From fa3b5f6699333ed6f0699e10e99a20b1f6d20afc Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Mon, 11 May 2020 17:13:32 -0600 Subject: [PATCH 1/4] docs: Update a variety of docs for upcoming 2.1 betas --- src/docs/markdown/caddyfile/concepts.md | 14 ++++++++ .../caddyfile/directives/reverse_proxy.md | 4 ++- src/docs/markdown/caddyfile/matchers.md | 32 ++++++++++++++++--- src/docs/markdown/command-line.md | 4 +-- src/docs/markdown/conventions.md | 4 ++- 5 files changed, 50 insertions(+), 8 deletions(-) diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index d63526b..31b2a7e 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -141,6 +141,14 @@ directive "\"abc def\"" Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. +You can also use a backtick (`\``) to quote tokens: + +``` +directive `"foo bar"` +``` + +Backtick strings are convenient when tokens contain quote literals. + ## Addresses @@ -219,11 +227,16 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd |-----------------|---------------------------------| | `{dir}` | `{http.request.uri.path.dir}` | | `{file}` | `{http.request.uri.path.file}` | +| `{header.*}` | `{http.request.header.*}` | | `{host}` | `{http.request.host}` | +| `{labels.*}` | `{http.request.host.labels.*}` | | `{hostport}` | `{http.request.hostport}` | | `{method}` | `{http.request.method}` | | `{path}` | `{http.request.uri.path}` | +| `{path.*}` | `{http.request.uri.path.*}` | | `{query}` | `{http.request.uri.query}` | +| `{query.*}` | `{http.request.uri.query.*}` | +| `{re.*.*}` | `{http.regexp.*.*}` | | `{remote}` | `{http.request.remote}` | | `{remote_host}` | `{http.request.remote.host}` | | `{remote_port}` | `{http.request.remote.port}` | @@ -237,6 +250,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd | `{tls_client_subject}` | `{http.request.tls.client.subject}` | + ## Snippets You can define special blocks called snippets by giving them a name surrounded in parentheses: diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 09726a6..e2c0cca 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -62,7 +62,7 @@ Upstream addresses can take the form of a conventional [Caddy network address](/ - `unix//var/php.sock` - `srv+http://internal:5099` -Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Specifying ports 80 and 443 are the same as specifying the HTTP and HTTPS schemes, respectively. Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport. Additionally, schemes cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. +Note: Schemes cannot be mixed, since they modify the common transport configuration (a TLS-enabled transport cannot carry both HTTPS and plaintext HTTP). Specifying ports 80 and 443 are the same as specifying the HTTP and HTTPS schemes, respectively. Any explicit transport configuration will not be overwritten, and omitting schemes or using other ports will not assume a particular transport. Additionally, schemes cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. If the address is not a URL (i.e. does not have a scheme), then placeholders can be used, but this makes the upstream dynamic. **Load balancing** is used whenever more than one upstream is defined. @@ -128,6 +128,7 @@ transport http { tls_insecure_skip_verify tls_timeout tls_trusted_ca_certs + tls_server_name keepalive [off|] keepalive_idle_conns } @@ -141,6 +142,7 @@ transport http { - **tls_insecure_skip_verify** turns off security. _Do not use in production._ - **tls_timeout** is a [duration value](/docs/conventions#durations) that specifies how long to wait for the TLS handshake to complete. - **tls_trusted_ca_certs** is a list of PEM files that specify CA public keys to trust when connecting to the backend. +- **tls_server_name** sets the ServerName (SNI) to put in the ClientHello; only needed if the remote server it. - **keepalive** is either `off` or a [duration value](/docs/conventions#durations) that specifies how long to keep connections open. - **keepalive_idle_conns** defines the maximum number of connections to keep alive. diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index 93229a8..7686b73 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -62,10 +62,11 @@ reverse_proxy /api/* localhost:9000 To match on anything other than a path, define a [named matcher](#named-matchers) and refer to it using `@name`: ```caddy-d -@post { +@postfoo { method POST + path /foo/* } -reverse_proxy @post localhost:9000 +reverse_proxy @postfoo localhost:9000 ``` @@ -73,7 +74,7 @@ reverse_proxy @post localhost:9000 ### Wildcard matchers -The wildcard matcher `*` matches all requests, and is only needed if a matcher token is required. For example, if the first argument you want to give a directive also happens to be a path, it would look exactly like a path matcher! So you can use a wildcard matcher to disambiguate, for example: +The wildcard (or "catch-all") matcher `*` matches all requests, and is only needed if a matcher token is required. For example, if the first argument you want to give a directive also happens to be a path, it would look exactly like a path matcher! So you can use a wildcard matcher to disambiguate, for example: ```caddy-d root * /home/www/mysite @@ -97,6 +98,8 @@ Path matcher tokens must start with a forward slash `/`. ### Named matchers +All matchers that are not comprised of a single path matcher or a wildcard matcher must be named matchers. This is a matcher that is defined outside of any particular directive, and can be reused. + Defining a matcher with a unique name gives you more flexibility, allowing you to combine [any available matchers](#standard-matchers) into a set: ```caddy-d @@ -105,6 +108,12 @@ Defining a matcher with a unique name gives you more flexibility, allowing you t } ``` +or, if there is only one matcher in the set: + +``` +@name ... +``` + Then you can use the matcher like so: `@name` For example: @@ -119,6 +128,15 @@ reverse_proxy @websockets localhost:6001 This proxies only the requests that have a header field named "Connection" containing the word "Upgrade", and another field named "Upgrade" with a value of "websocket". +If the matcher set consists of only one matcher, a one-liner syntax also works: + +``` +@post method POST +reverse_proxy @post localhost:6001 +``` + +(One-liner named matchers cannot open a block.) + Like directives, named matcher definitions must go inside the site blocks that use them. A named matcher definition constitutes a _matcher set_. Matchers in a set are AND'ed together; i.e. all must match. For example, if you have both a `header` and `path` matcher in the set, both must match. @@ -185,7 +203,13 @@ By files. - `most_recent_modified` chooses the file that was most recently modified. - `split_path` will cause the path to be split at the first delimiter in the list that is found in each filepath to try. For each split value, the left-hand side of the split including the delimiter itself will be the filepath that is tried. For example, `/remote.php/dav/` using a delimiter of `.php` would try the file `/remote.php`. Each delimiter must appear at the end of a URI path component in order to be used as a split delimiter. This is a niche setting and is mostly used when serving PHP sites. -An empty `file` matcher will see if the requested file (verbatim from the URI, relative to the [site root](/docs/caddyfile/directives/root)) exists. +Because `try_files` with a policy of `first_exist` is so common, there is a one-line shortcut for that: + +```caddy-d +file +``` + +An empty `file` matcher (one with no files listed after it) will see if the requested file—verbatim from the URI, relative to the [site root](/docs/caddyfile/directives/root)—exists. Since rewriting based on the existence of a file on disk is so common, there is also a [`try_files` directive](/docs/caddyfile/directives/try_files) which is a shortcut of the `file` matcher and a [`rewrite` handler](/docs/caddyfile/directives/rewrite). diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index a932f8c..8df54b1 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -172,13 +172,13 @@ Formats or prettifies a Caddyfile, then exits. The result is printed to stdout u ### `caddy hash-password` 
caddy hash-password
-	--plaintext <password>
+	[--plaintext <password>]
 	[--algorithm <name>]
 	[--salt <string>]
Hashes a password and writes the output to stdout in base64 encoding, then exits. -`--plaintext` is the plaintext form of the password. +`--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 scrypt. Default is bcrypt. diff --git a/src/docs/markdown/conventions.md b/src/docs/markdown/conventions.md index fcd56d0..9ed15fe 100644 --- a/src/docs/markdown/conventions.md +++ b/src/docs/markdown/conventions.md @@ -140,7 +140,7 @@ It is crucial that this directory is persistent and writeable by Caddy. ## Durations -Duration strings are commonly used throughout Caddy's configuration. They take on the same format as [Go's time.ParseDuration syntax](https://golang.org/pkg/time/#ParseDuration). Valid units are: +Duration strings are commonly used throughout Caddy's configuration. They take on the same format as [Go's time.ParseDuration syntax](https://golang.org/pkg/time/#ParseDuration) except you can also use `d` for day (we assume 1 day = 24 hours for simplicity). Valid units are: - `ns` (nanosecond) - `us`/`µs` (microsecond) @@ -148,6 +148,7 @@ Duration strings are commonly used throughout Caddy's configuration. They take o - `s` (second) - `m` (minute) - `h` (hour) +- `d` (day) Examples: @@ -155,5 +156,6 @@ Examples: - `5s` - `1.5h` - `2h45m` +- `90d` In the [JSON config](/docs/json/), duration values can also be integers which represent nanoseconds. \ No newline at end of file From f655da2c2e6b33df0d2f44c905becc44193747ba Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Thu, 14 May 2020 10:19:14 -0600 Subject: [PATCH 2/4] docs: --pidfile flag --- src/docs/markdown/command-line.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 8df54b1..ed7bacd 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -250,6 +250,7 @@ This command disables the admin API so it is easier to run multiple instances on 
caddy run
 	[--config <path>]
 	[--adapter <name>]
+	[--pidfile <file>]
 	[--environ]
 	[--resume]
 	[--watch]
@@ -260,6 +261,8 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode. `--adapter` is the name of the config adapter to use when loading the initial config, if any. This flag is not necessary if the `--config` filename starts with "Caddyfile" which assumes the `caddyfile` adapter. Otherwise, this flag is required if the provided config file is not in Caddy's native JSON format. Any warnings will be printed to the log, but beware that any adaptation without errors will immediately be used, even if there are warnings. If you want to review the results of the adaptation first, use the [`caddy adapt`](#caddy-adapt) subcommand. +`--pidfile` writes the PID to the specified file. + `--environ` prints out the environment before starting. This is the same as the `caddy environ` command, but does not exit after printing. `--resume` uses the last loaded configuration, overriding the `--config` flag (if present) if a previous config was saved. Using this flag guarantees config durability through machine reboots or process restarts. It is most useful in [API](/docs/api)-heavy deployments. @@ -277,6 +280,7 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode. 
caddy start
 	[--config <path>]
 	[--adapter <name>]
+	[--pidfile <file>]
 	[--watch]
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. From 1367aebe20f9f17d1b52d981c760decab165e9db Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sun, 17 May 2020 16:46:23 -0400 Subject: [PATCH 3/4] docs: Add a few code lang labels, minor cleanup --- src/docs/markdown/caddyfile/concepts.md | 7 ++++--- src/docs/markdown/caddyfile/directives/reverse_proxy.md | 2 +- src/docs/markdown/caddyfile/matchers.md | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 31b2a7e..fb5d824 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -141,13 +141,13 @@ directive "\"abc def\"" Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. -You can also use a backtick (`\``) to quote tokens: +You can also use a backtick ` to quote tokens: -``` +```caddy-d directive `"foo bar"` ``` -Backtick strings are convenient when tokens contain quote literals. +Backtick strings are convenient when tokens contain quote literals, e.g. JSON text. @@ -231,6 +231,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd | `{host}` | `{http.request.host}` | | `{labels.*}` | `{http.request.host.labels.*}` | | `{hostport}` | `{http.request.hostport}` | +| `{port}` | `{http.request.port}` | | `{method}` | `{http.request.method}` | | `{path}` | `{http.request.uri.path}` | | `{path.*}` | `{http.request.uri.path.*}` | diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index e2c0cca..fb51c51 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -142,7 +142,7 @@ transport http { - **tls_insecure_skip_verify** turns off security. _Do not use in production._ - **tls_timeout** is a [duration value](/docs/conventions#durations) that specifies how long to wait for the TLS handshake to complete. - **tls_trusted_ca_certs** is a list of PEM files that specify CA public keys to trust when connecting to the backend. -- **tls_server_name** sets the ServerName (SNI) to put in the ClientHello; only needed if the remote server it. +- **tls_server_name** sets the ServerName (SNI) to put in the ClientHello; only needed if the remote server requires it. - **keepalive** is either `off` or a [duration value](/docs/conventions#durations) that specifies how long to keep connections open. - **keepalive_idle_conns** defines the maximum number of connections to keep alive. diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index 7686b73..ca1f4d3 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -110,7 +110,7 @@ Defining a matcher with a unique name gives you more flexibility, allowing you t or, if there is only one matcher in the set: -``` +```caddy-d @name ... ``` @@ -130,7 +130,7 @@ This proxies only the requests that have a header field named "Connection" conta If the matcher set consists of only one matcher, a one-liner syntax also works: -``` +```caddy-d @post method POST reverse_proxy @post localhost:6001 ``` From f30a5456257aabef72c0b3ad6a1bbf738ae2d3b5 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Mon, 8 Jun 2020 12:27:26 -0600 Subject: [PATCH 4/4] docs: Add docs for acme_server Caddyfile directive --- src/docs/markdown/caddyfile/directives.md | 1 + .../caddyfile/directives/acme_server.md | 21 +++++++++++++++++++ 2 files changed, 22 insertions(+) create mode 100644 src/docs/markdown/caddyfile/directives/acme_server.md diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 585e6d8..56c6af7 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -8,6 +8,7 @@ The following directives come standard with Caddy, and can be used in the HTTP C Directive | Description ----------|------------ +**[acme_server](/docs/caddyfile/directives/acme_server)** | An embedded ACME server **[basicauth](/docs/caddyfile/directives/basicauth)** | Enforces HTTP Basic Authentication **[bind](/docs/caddyfile/directives/bind)** | Customize the server's socket address **[encode](/docs/caddyfile/directives/encode)** | Encodes (usually compresses) responses diff --git a/src/docs/markdown/caddyfile/directives/acme_server.md b/src/docs/markdown/caddyfile/directives/acme_server.md new file mode 100644 index 0000000..7e5aaf1 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/acme_server.md @@ -0,0 +1,21 @@ +--- +title: acme_server (Caddyfile directive) +--- + +# acme_server + +An embedded [ACME protocol](https://tools.ietf.org/html/rfc8555) server handler. This allows a Caddy instance to issue certificates for any other ACME-compatible software (including other Caddy instances). + +When enabled, requests matching the path `/acme/*` will be handled by the ACME server. + + +## Client configuration + +Using ACME server defaults, ACME clients should simply be configured to use `https://localhost/acme/directory` as their ACME endpoint. + + +## Syntax + +```caddy-d +acme_server [] +```