mirror of
https://github.com/caddyserver/website.git
synced 2025-04-23 13:36:16 -04:00
Docs for v2.7.0 (#322)
* Docs for v2.7.0 * Document named-routes & invoke, polish reverse_proxy * Storage import/export CLI docs * Header replacement defer * Proxy stream closing options, weighted round robin LB policy
This commit is contained in:
Francis Lavoie
GitHub
parent
0a8e6ef86b
commit
194beebc7c
15 changed files with 454 additions and 105 deletions
|
|
@ -12,10 +12,12 @@ caddy <command> [<args...>]
|
|||
|
||||
The `<carets>` indicate parameters that get replaced by your input.
|
||||
|
||||
The`[brackets]` indicate optional parameters.
|
||||
The`[brackets]` indicate optional parameters. The `(brackets)` indicate required parameters.
|
||||
|
||||
The ellipses `...` indicates a continuation, i.e. one or more parameters.
|
||||
|
||||
The `--flags` may have a single-letter shortcut like `-f`.
|
||||
|
||||
**Quick start: `caddy`, `caddy help`, or `man caddy` (if installed)**
|
||||
|
||||
---
|
||||
|
|
@ -71,6 +73,12 @@ The ellipses `...` indicates a continuation, i.e. one or more parameters.
|
|||
- **[caddy stop](#caddy-stop)**
|
||||
Stops the running Caddy process
|
||||
|
||||
- **[caddy storage export](#caddy-storage)**
|
||||
Exports the contents of the configured storage to a tarball
|
||||
|
||||
- **[caddy storage import](#caddy-storage)**
|
||||
Imports a previously exported tarball to the configured storage
|
||||
|
||||
- **[caddy trust](#caddy-trust)**
|
||||
Installs a certificate into local trust store(s)
|
||||
|
||||
|
|
@ -104,9 +112,9 @@ The ellipses `...` indicates a continuation, i.e. one or more parameters.
|
|||
### `caddy adapt`
|
||||
|
||||
<pre><code class="cmd bash">caddy adapt
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[--pretty]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[-p, --pretty]
|
||||
[--validate]</code></pre>
|
||||
|
||||
Adapts a configuration to Caddy's native JSON config structure and writes the output to stdout, along with any warnings to stderr, then exits.
|
||||
|
|
@ -178,13 +186,13 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin
|
|||
### `caddy file-server`
|
||||
|
||||
<pre><code class="cmd bash">caddy file-server
|
||||
[--root <path>]
|
||||
[-r, --root <path>]
|
||||
[--listen <addr>]
|
||||
[--domain <example.com>]
|
||||
[--browse]
|
||||
[--templates]
|
||||
[-d, --domain <example.com>]
|
||||
[-b, --browse]
|
||||
[-t, --templates]
|
||||
[--access-log]
|
||||
[--debug]</code></pre>
|
||||
[-v, --debug]</code></pre>
|
||||
|
||||
Spins up a simple but production-ready static file server.
|
||||
|
||||
|
|
@ -213,7 +221,9 @@ Exports the default file browsing template to stdout
|
|||
|
||||
### `caddy fmt`
|
||||
|
||||
<pre><code class="cmd bash">caddy fmt [--overwrite] [--diff] [<path>]</code></pre>
|
||||
<pre><code class="cmd bash">caddy fmt [<path>]
|
||||
[-w, --overwrite]
|
||||
[-d, --diff]</code></pre>
|
||||
|
||||
Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used, and will exit with code `1` if there are any differences.
|
||||
|
||||
|
|
@ -229,17 +239,19 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u
|
|||
### `caddy hash-password`
|
||||
|
||||
<pre><code class="cmd bash">caddy hash-password
|
||||
[--plaintext <password>]
|
||||
[--algorithm <name>]
|
||||
[--salt <string>]</code></pre>
|
||||
[-p, --plaintext <password>]
|
||||
[-a, --algorithm <name>]
|
||||
[-s, --salt <string>]</code></pre>
|
||||
|
||||
Hashes a password and writes the output to stdout, then exits.
|
||||
Convenient way to hash a plaintext password. The resulting hash is written to stdout as a format usable directly in your Caddy config.
|
||||
|
||||
`--plaintext` is the plaintext form of the password. If omitted, interactive mode will be assumed and the user will be shown a prompt to enter the password manually.
|
||||
|
||||
`--algorithm` may be bcrypt or any installed hash algorithm. Default is bcrypt.
|
||||
`--algorithm` may be `bcrypt` or any installed hash algorithm. Default is `bcrypt`.
|
||||
|
||||
`--salt` is used only if the algorithm requires an external salt (like scrypt).
|
||||
`--salt` is used only if the algorithm requires an external salt (like `scrypt`).
|
||||
|
||||
Note that `scrypt` is deprecated. Please use `bcrypt` instead.
|
||||
|
||||
|
||||
|
||||
|
|
@ -257,7 +269,7 @@ Prints CLI help text, optionally for a specific subcommand, then exits.
|
|||
<pre><code class="cmd bash">caddy list-modules
|
||||
[--packages]
|
||||
[--versions]
|
||||
[--skip-standard]</code></pre>
|
||||
[-s, --skip-standard]</code></pre>
|
||||
|
||||
Prints the Caddy modules that are installed, optionally with package and/or version information from their associated Go modules, then exits.
|
||||
|
||||
|
|
@ -270,7 +282,7 @@ NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version i
|
|||
### `caddy manpage`
|
||||
|
||||
<pre><code class="cmd bash">caddy manpage
|
||||
--directory <path></code></pre>
|
||||
(-o, --directory <path>)</code></pre>
|
||||
|
||||
Generates manual/documentation pages for Caddy commands and writes them to the directory at the specified path. The output of this command can be read by the `man` command.
|
||||
|
||||
|
|
@ -290,13 +302,14 @@ Manual pages are separate documentation from what is on our website. Our website
|
|||
|
||||
|
||||
|
||||
|
||||
### `caddy reload`
|
||||
|
||||
<pre><code class="cmd bash">caddy reload
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--address <interface>]
|
||||
[--force]</code></pre>
|
||||
[-f, --force]</code></pre>
|
||||
|
||||
Gives the running Caddy instance a new configuration. This has the same effect as POSTing a document to the [/load endpoint](/docs/api#post-load), but this command is convenient for simple workflows revolving around config files. Compared to the `stop`, `start`, and `run` commands, this single command is the correct, semantic way to change/reload the running configuration.
|
||||
|
||||
|
|
@ -311,15 +324,17 @@ Because this command uses the API, the admin endpoint must not be disabled.
|
|||
`--force` will cause a reload to happen even if the specified config is the same as what Caddy is already running. Can be useful to force Caddy to reprovision its modules, which can have side-effects, for example: reloading manually-loaded TLS certificates.
|
||||
|
||||
|
||||
|
||||
|
||||
### `caddy respond`
|
||||
|
||||
<pre><code class="cmd bash">caddy respond
|
||||
[--status <code>]
|
||||
[--header "<Field>: <value>"]
|
||||
[--body <content>]
|
||||
[--listen <addr>]
|
||||
[-s, --status <code>]
|
||||
[-H, --header "<Field>: <value>"]
|
||||
[-b, --body <content>]
|
||||
[-l, --listen <addr>]
|
||||
[-v, --debug]
|
||||
[--access-log]
|
||||
[--debug]
|
||||
[<status|body>]</code></pre>
|
||||
|
||||
|
||||
|
|
@ -333,9 +348,9 @@ Starts one or more simple, hard-coded HTTP servers that are useful for developme
|
|||
|
||||
`--listen` is the listener address, which can be any [network address](/docs/conventions#network-addresses) recognized by Caddy, and may include a port range to start multiple servers.
|
||||
|
||||
`--access-log` enables access/request logging.
|
||||
`--debug` enables verbose debug logging.
|
||||
|
||||
`--debug` enables more verbose debug logging.
|
||||
`--access-log` enables access/request logging.
|
||||
|
||||
With no options specified, this command listens on a random available port and answers HTTP requests with an empty 200 response. The listen address can be customized with the `--listen` flag and will always be printed to stdout. If the listen address includes a port range, multiple servers will be started.
|
||||
|
||||
|
|
@ -377,45 +392,62 @@ Pipe in a maintenance page:
|
|||
--header "Content-Type: text/html"</code></pre>
|
||||
|
||||
|
||||
|
||||
|
||||
### `caddy reverse-proxy`
|
||||
|
||||
<pre><code class="cmd bash">caddy reverse-proxy
|
||||
[--from <addr>]
|
||||
--to <addr>
|
||||
[--change-host-header]
|
||||
[--disable-redirects]
|
||||
[--internal-certs]
|
||||
[--debug]</code></pre>
|
||||
[-f, --from <addr>]
|
||||
(-t, --to <addr>)
|
||||
[-H, --header-up "<Field>: <value>"]
|
||||
[-d, --header-down "<Field>: <value>"]
|
||||
[-c, --change-host-header]
|
||||
[-r, --disable-redirects]
|
||||
[-i, --internal-certs]
|
||||
[-v, --debug]
|
||||
[--access-log]
|
||||
[--insecure]</code></pre>
|
||||
|
||||
Spins up a simple but production-ready HTTP(S) reverse proxy.
|
||||
A simple but production-ready reverse proxy. Useful for quick deployments, demos, and development.
|
||||
|
||||
`--from` is the address to proxy from.
|
||||
Simply shuttles HTTP(S) traffic from the `--from` address to the `--to` address. Multiple `--to` addresses may be specified by repeating the flag. At least one `--to` address is required. The `--to` address may have a port range as a shortcut to expand to multiple upstreams.
|
||||
|
||||
`--to` is the address(es) to proxy to. Can be repeated to load balance between multiple upstreams.
|
||||
Unless otherwise specified in the addresses, the `--from` address will be assumed to be HTTPS if a hostname is given, and the `--to` address will be assumed to be HTTP.
|
||||
|
||||
`--change-host-header` will cause Caddy to change the Host header from the incoming value to the address of the upstream.
|
||||
If the `--from` address has a host or IP, Caddy will attempt to serve the proxy over HTTPS with a certificate (unless overridden by the HTTP scheme or port).
|
||||
|
||||
`--disable-redirects` prevents Automatic HTTPS from enabling the HTTP->HTTPS redirects, if the `--from` address would enable HTTPS.
|
||||
If serving HTTPS:
|
||||
- `--disable-redirects` can be used to avoid binding to the HTTP port.
|
||||
|
||||
`--internal-certs` will cause Caddy to issue certificates using its internal issuer (effectively self-signed) for the domain specified in the `--from` address.
|
||||
- `--internal-certs` can be used to force issuance certs using the internal CA instead of attempting to issue a public certificate.
|
||||
|
||||
`--debug` enables verbose logging.
|
||||
For proxying:
|
||||
- `--header-up` can be used to set a request header to send to the upstream.
|
||||
|
||||
- `--header-down` can be used to set a response header to send back to the client.
|
||||
|
||||
- `--change-host-header` sets the Host header on the request to the address of the upstream, instead of defaulting to the incoming Host header.
|
||||
|
||||
Both `--from` and `--to` parameters can be URLs, as scheme and domain name will be inferred from the provided URL (paths and query strings ignored). Or they can be a simple network address and not a complete URL.
|
||||
This is a shortcut for `--header-up "Host: {http.reverse_proxy.upstream.hostport}"`
|
||||
|
||||
- `--insecure` disables TLS verification with the upstream. WARNING: THIS DISABLES SECURITY BY NOT VERIFYING THE UPSTREAM'S CERTIFICATE.
|
||||
|
||||
- `--debug` enables verbose logging.
|
||||
|
||||
This command disables the admin API so it is easier to run multiple instances on a local development machine.
|
||||
|
||||
|
||||
|
||||
### `caddy run`
|
||||
|
||||
<pre><code class="cmd bash">caddy run
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--pidfile <file>]
|
||||
[--environ]
|
||||
[-e, --environ]
|
||||
[--envfile <file>]
|
||||
[--resume]
|
||||
[--watch]</code></pre>
|
||||
[-r, --resume]
|
||||
[-w, --watch]</code></pre>
|
||||
|
||||
Runs Caddy and blocks indefinitely; i.e. "daemon" mode.
|
||||
|
||||
|
|
@ -442,15 +474,15 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode.
|
|||
### `caddy start`
|
||||
|
||||
<pre><code class="cmd bash">caddy start
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--envfile <file>]
|
||||
[--pidfile <file>]
|
||||
[--watch]</code></code></pre>
|
||||
[-w, --watch]</code></code></pre>
|
||||
|
||||
Same as [`caddy run`](#caddy-run), but in the background. This command only blocks until the background process is running successfully (or fails to run), then returns.
|
||||
|
||||
Note: the flag `--config` doesn't support `-` to read the config from stdin.
|
||||
Note: the flag `--config` does _not_ support `-` to read the config from stdin.
|
||||
|
||||
Use of this command is discouraged with system services or on Windows. On Windows, the child process will remain attached to the terminal, so closing the window will forcefully stop Caddy, which is not obvious. Consider running Caddy [as a service](/docs/running) instead.
|
||||
|
||||
|
|
@ -462,7 +494,7 @@ Once started, you can use [`caddy stop`](#caddy-stop) or the [`POST /stop`](/doc
|
|||
|
||||
<pre><code class="cmd bash">caddy stop
|
||||
[--address <interface>]
|
||||
[--config <path> [--adapter <name>]]</code></pre>
|
||||
[-c, --config <path> [-a, --adapter <name>]]</code></pre>
|
||||
|
||||
<aside class="tip">
|
||||
|
||||
|
|
@ -478,12 +510,57 @@ The address of this request can be customized using the `--address` flag, or fro
|
|||
If you want to stop the current configuration but do not want to exit the process, use [`caddy reload`](#caddy-reload) with a blank config, or the [`DELETE /config/`](/docs/api#delete-configpath) endpoint.
|
||||
|
||||
|
||||
### `caddy storage`
|
||||
|
||||
Allows export and import of the contents of Caddy's configured data storage.
|
||||
|
||||
This is useful when needing to transition from one [storage module](/docs/json/storage/) to another, by exporting from your old one, updating your config, then importing into the new one.
|
||||
|
||||
The following command can be used to do this all in one shot, using and old and new config with different configured storage modules, piping the export output into the
|
||||
|
||||
```
|
||||
$ caddy storage export -c Caddyfile.old -o- |
|
||||
caddy storage import -c Caddyfile.new -i-
|
||||
```
|
||||
|
||||
<aside class="advice">
|
||||
|
||||
Please note that when using [filesystem storage](/docs/conventions#data-directory), you must run the export command as the same user that Caddy normally runs as, otherwise the wrong storage location may be used.
|
||||
|
||||
For example, when running Caddy as a [systemd service](/docs/running#linux-service), it will run as the `caddy` user, so you should run the export or import commands as that user. This can typically be done with `sudo -u caddy <command>`.
|
||||
|
||||
</aside>
|
||||
|
||||
|
||||
#### `caddy storage export`
|
||||
|
||||
<pre><code class="cmd bash">caddy storage export
|
||||
-c, --config <path>
|
||||
[-o, --output <path>]</code></pre>
|
||||
|
||||
`--config` is the config file load. This is required, so that the correct storage module is connected to.
|
||||
|
||||
`--output` is the filename to write the tarball. If `-`, the output is written to stdout.
|
||||
|
||||
|
||||
|
||||
#### `caddy storage import`
|
||||
|
||||
<pre><code class="cmd bash">caddy storage import
|
||||
-c, --config <path>
|
||||
-i, --input <path></code></pre>
|
||||
|
||||
`--config` is the config file load. This is required, so that the correct storage module is connected to.
|
||||
|
||||
`--input` is the filename of the tarball to read from. If `-`, the input is read from stdin.
|
||||
|
||||
|
||||
### `caddy trust`
|
||||
|
||||
<pre><code class="cmd bash">caddy trust
|
||||
[--ca <id>]
|
||||
[--address <interface>]
|
||||
[--config <path> [--adapter <name>]]</code></pre>
|
||||
[-c, --config <path> [-a, --adapter <name>]]</code></pre>
|
||||
|
||||
Installs a root certificate for a CA managed by Caddy's [PKI app](/docs/json/apps/pki/) into local trust stores.
|
||||
|
||||
|
|
@ -499,10 +576,10 @@ You may also use the `caddy` binary with this command to install certificates on
|
|||
### `caddy untrust`
|
||||
|
||||
<pre><code class="cmd bash">caddy untrust
|
||||
[--cert <path>]
|
||||
[-p, --cert <path>]
|
||||
[--ca <id>]
|
||||
[--address <interface>]
|
||||
[--config <path> [--adapter <name>]]</code></pre>
|
||||
[-c, --config <path> [-a, --adapter <name>]]</code></pre>
|
||||
|
||||
Untrusts a root certificate from the local trust store(s).
|
||||
|
||||
|
|
@ -520,7 +597,7 @@ If the admin API is used, then the CA ID defaults to "local". You may specify th
|
|||
### `caddy upgrade`
|
||||
|
||||
<pre><code class="cmd bash">caddy upgrade
|
||||
[--keep-backup]</code></pre>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Replaces the current Caddy binary with the latest version from [our download page](https://caddyserver.com/download) with the same modules installed, including all third-party plugins that are registered on the Caddy website.
|
||||
|
||||
|
|
@ -535,7 +612,7 @@ This command may require elevated privileges if your user does not have permissi
|
|||
### `caddy add-package`
|
||||
|
||||
<pre><code class="cmd bash">caddy add-package <packages...>
|
||||
[--keep-backup]</code></pre>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, _plus_ the packages listed as arguments included in the new binary. Find the list of packages you can install from [our download page](https://caddyserver.com/download). Each argument should be the full package name.
|
||||
|
||||
|
|
@ -548,7 +625,7 @@ For example:
|
|||
### `caddy remove-package`
|
||||
|
||||
<pre><code class="cmd bash">caddy remove-package <packages...>
|
||||
[--keep-backup]</code></pre>
|
||||
[-k, --keep-backup]</code></pre>
|
||||
|
||||
Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest version with the same modules installed, but _without_ the packages listed as arguments, if they existed in the current binary. Run `caddy list-modules --packages` to see the list of package names of non-standard modules included in the current binary.
|
||||
|
||||
|
|
@ -557,8 +634,8 @@ Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest
|
|||
### `caddy validate`
|
||||
|
||||
<pre><code class="cmd bash">caddy validate
|
||||
[--config <path>]
|
||||
[--adapter <name>]
|
||||
[-c, --config <path>]
|
||||
[-a, --adapter <name>]
|
||||
[--envfile <file>]</code></pre>
|
||||
|
||||
Validates a configuration file, then exits. This command deserializes the config, then loads and provisions all of its modules as if to start the config, but the config is not actually started. This exposes errors in a configuration that arise during loading or provisioning phases and is a stronger error check than merely serializing a config as JSON.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue