docs: Update for v2.2

src/docs/markdown/caddyfile/directives.md

@@ -21,6 +21,7 @@ Directive | Description
 **[log](/docs/caddyfile/directives/log)** | Enables access/request logging
 **[metrics](/docs/caddyfile/directives/metrics)** | Configures the Prometheus metrics exposition endpoint
 **[php_fastcgi](/docs/caddyfile/directives/php_fastcgi)** | Serve PHP sites over FastCGI
+**[push](/docs/caddyfile/directives/push)** | Push content to the client using HTTP/2 server push
 **[redir](/docs/caddyfile/directives/redir)** | Issues an HTTP redirect to the client
 **[request_header](/docs/caddyfile/directives/request_header)** | Manipulates request headers
 **[respond](/docs/caddyfile/directives/respond)** | Writes a hard-coded response to the client

src/docs/markdown/caddyfile/directives/file_server.md

@@ -22,7 +22,7 @@ file_server [<matcher>] [browse] {
 
 - **browse** enables file listings for requests to directories that do not have an index file.
 - **root** sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this directive. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective.
-- **hide** is a list of files to hide; if requested, the file server will pretend they do not exist. The active configuration file will be added by default.
+- **hide** is a list of files to hide; if requested, the file server will pretend they do not exist. The active configuration file will be added by default. Specifying a file name without path will hide all files with that name; otherwise, a prefix match will be attempted, and then a globular match.
 - **index** is a list of filenames to look for as index files. Default: `index.html index.txt`
 - **<template_file>** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code <img src="/resources/images/external-link.svg">](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go).
 

src/docs/markdown/caddyfile/directives/log.md

@@ -126,14 +126,6 @@ Formats each log entry as a JSON object.
 format json
 ```
 
-#### logfmt
-
-Formats each log entry as [logfmt](https://brandur.org/logfmt).
-
-```caddy-d
-format logfmt
-```
-
 #### single_field
 
 Writes only a single field from the structure log entry. Useful if one of the fields has all the information you need.

src/docs/markdown/caddyfile/directives/push.md

@@ -0,0 +1,66 @@
+---
+title: push (Caddyfile directive)
+---
+
+# push
+
+Configures the server to pre-emptively send resources to the client using HTTP/2 server push.
+
+Resources can be linked for server push by specifying the Link header(s) of the response. This directive will automatically push resources described by upstream Link headers in these formats:
+
+- `<resource>; as=script`
+- `<resource>; as=script,<resource>; as=style`
+- `<resource>; nopush`
+- `<resource>;<resource2>;...`
+
+where `<resource>` begins with a forward slash `/` (i.e. is a URI path with the same host). Only same-host resources can be pushed. If a linked resource is external or if it has the `nopush` attribute, it will not be pushed.
+
+By default, push requests will include some headers deemed safe to copy from the original request:
+
+- Accept-Encoding
+- Accept-Language
+- Accept
+- Cache-Control
+- User-Agent
+
+as it is assumed many requests would fail without these headers; these do not need to be configured manually.
+
+Push requests are virtualized internally, so they are very lightweight.
+
+
+## Syntax
+
+```caddy-d
+push [<matcher>] [<resource>] {
+	[GET|HEAD] <resource>
+	headers {
+		[+]<field> [<value|regexp> [<replacement>]]
+		-<field>
+	}
+}
+```
+
+- **&lt;resource&gt;** is the target URI path to push. If used within the block, may optionally be preceeded by the method (GET or POST; GET is default).
+- **&lt;headers&gt;** manipulates the headers of the push request using the same syntax as the [`header` directive](/docs/caddyfile/directives/header). Some headers are carried over by default and do not need to be explicitly configured (see above).
+
+
+
+## Examples
+
+Push any resources described by `Link` headers in the response:
+
+```caddy-d
+push
+```
+
+Same, but also push `/resources/style.css` for all requests:
+
+```caddy-d
+push * /resources/style.css
+```
+
+Push `/foo.jpg` only when `/foo.html` is requested by the client:
+
+```caddy-d
+push /foo.html /foo.jpg
+```

src/docs/markdown/caddyfile/directives/reverse_proxy.md

@@ -109,7 +109,7 @@ Passive health checks happen inline with actual proxied requests:
 
 The proxy **buffers responses** by default for wire efficiency:
 
-- **flush_interval** is a [duration value](/docs/conventions#durations) that defines how often Caddy should flush the buffered response body to the client. Set to -1 to disable buffering.
+- **flush_interval** is a [duration value](/docs/conventions#durations) that defines how often Caddy should flush the buffered response body to the client. Set to -1 to disable buffering. It is set to -1 automatically for requests that have a `text/event-stream` response or for HTTP/2 requests where the Content-Length is unspecified.
 
 ### Headers
 
@@ -146,7 +146,9 @@ transport http {
     tls_server_name <sni>
 	keepalive [off|<duration>]
 	keepalive_idle_conns <max_count>
+    versions <versions...>
     compression off
+    buffer_requests
 }
 ```
 
@@ -161,7 +163,10 @@ transport http {
 - **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.
+- **versions** allows customizing which versions of HTTP to support. As a special case, "h2c" is a valid value which will enable cleartext HTTP/2 connections to the upstream (however, this is a non-standard feature that does not use Go's default HTTP transport, so it is exclusive of other features; subject to change or removal). Default: `1.1 2`
 - **compression** can be used to disable compression to the backend by setting it to `off`.
+- **buffer_requests** will cause the proxy to read the entire request body into a buffer before sending it upstream. This is very inefficient and should only be done if the upstream requires reading request bodies without delay (which is something the upstream application should fix).
+
 
 #### The `fastcgi` transport
 
@@ -170,12 +175,14 @@ transport fastcgi {
 	root  <path>
 	split <at>
 	env   <key> <value>
+    resolve_root_symlink
 }
 ```
 
 - **root** is the root of the site. Default: `{http.vars.root}` or current working directory.
 - **split** is where to split the path to get PATH_INFO at the end of the URI.
 - **env** sets custom environment variables.
+- **resolve_root_symlink** The declared root directory will be resolved to its actual value by evaluating any symbolic links.
 
 
 ## Examples

src/docs/markdown/caddyfile/directives/tls.md

@@ -32,6 +32,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 		trusted_leaf_cert      <base64_der>
 		trusted_leaf_cert_file <filename>
 	}
+	issuer <issuer_name> [<params...>]
 }
 ```
 
@@ -90,6 +91,70 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 
 	Multiple `trusted_*` directives may be specified as a way to chain multiple CA or leaf certificates.
 
+- **issuer** configures a custom certificate issuer, or a source from which to obtain certificates. Which issuer is used and the options that follow in this segment depend on the issuer modules that are available (see below for the standard issuers). Some of the other subdirectives such as `ca` and `dns` are actually shortcuts for configuring the `acme` issuer (and this subdirective was added later), so specifying this directive and some of the others is confusing and thus prohibited.
+
+### Issuers
+
+These issuers come standard with the `tls` directive:
+
+#### acme
+
+Obtains certificates using the ACME protocol.
+
+```caddy
+... acme {
+	dir      <directory_url>
+	test_dir <test_directory_url>
+	email    <email>
+	timeout  <duration>
+	disable_http_challenge
+	disable_tlsalpn_challenge
+	alt_http_port    <port>
+	alt_tlsalpn_port <port>
+	eab <key_id> <mac_key>
+	trusted_roots <pem_files...>
+	dns <provider_name> [<options>]
+	resolvers <dns_servers...>
+}
+```
+
+- **dir** is the URL to the ACME CA's directory. Default: `https://acme-v02.api.letsencrypt.org/directory`
+- **test_dir** is an optional fallback directory to use when retrying challenges; if all challenges fail, this endpoint will be used during retries; useful if a CA has a staging endpoint where you want to avoid rate limits on their production endpoint. Default: `https://acme-staging-v02.api.letsencrypt.org/directory`
+- **email** is the ACME account contact email address.
+- **timeout** is how long to wait before timing out an ACME operation.
+- **disable_http_challenge** will disable the HTTP challenge.
+- **disable_tlsalpn_challenge** will disable the TLS-ALPN challenge.
+- **alt_http_port** is an alternate port on which to serve the HTTP challenge; it has to happen on port 80 so you must forward packets to this alternate port.
+- **alt_tlsalpn_port** is an alternate port on which to serve the TLS-ALPN challenge; it has to happen on port 443 so you must forward packets to this alternate port.
+- **eab** specifies an External Account Binding which may be required with some ACME CAs.
+- **trusted_roots** is one or more root certificates (as PEM filenames) to trust when connecting to the ACME CA server.
+- **dns** configures the DNS challenge.
+- **resolvers** customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones.
+
+
+#### zerossl
+
+Obtains certificates using the ACME protocol, specifically with ZeroSSL.
+
+The config for `zerossl` is exactly the same as the config for `acme`, except that its name is `zerossl`, it will use ZeroSSL's directory, and it will automatically negotiate EAB credentials. In other words, simply specifying this issuer (with no other configuration) is enough to use ZeroSSL.
+
+Its default directory endpoint is `https://acme.zerossl.com/v2/DV90`.
+
+Note that ZeroSSL is RFC-8555-compliant and can be used with the `acme` issuer module instead, but this module is more convenient because it handles the EAB credentials under the hood for you.
+
+
+#### internal
+
+Obtains certificates from an internal certificate authority.
+
+```caddy
+... internal {
+	ca <name>
+}
+```
+
+- **ca** is the name of the internal CA to use. Default: `local`
+
 
 
 ## Examples

src/docs/markdown/caddyfile/options.md

@@ -31,8 +31,13 @@ Possible options are:
 	}
 	acme_ca <directory_url>
 	acme_ca_root <pem_file>
+	acme_eab <key_id> <mac_key>
+	acme_dns <provider>
 	email   <yours>
-	admin   off|<addr>
+	admin   off|<addr> {
+		origins <origins...>
+		enforce_origin
+	}
 	on_demand_tls {
 		ask      <endpoint>
 		interval <duration>
@@ -41,6 +46,7 @@ Possible options are:
 	local_certs
 	key_type ed25519|p256|p384|rsa2048|rsa4096
 	auto_https off|disable_redirects
+	cert_issuer <name> ...
 }
 ```
 
@@ -53,11 +59,16 @@ Possible options are:
 - **storage** configures Caddy's storage mechanism. Default: `file_system`
 - **acme_ca** specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: Let's Encrypt's production endpoint.
 - **acme_ca_root** specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.
+- **acme_eab** specifies an External Account Binding to use for all ACME transactions.
+- **acme_dns** configures the DNS challenge to use for all ACME transactions.
 - **email** is your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.
 - **admin** customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server.
+	- **origins** configures the list of remotes/origins that are allowed to connect to the endpoint.
+	- **enforce_origin** enables enforcement of the Origin header. (This is different from enforcing origins generally, which is always done.)
 - **on_demand_tls** configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse.
 	- **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns 200 OK, Caddy will be authorized to obtain a certificate for that name.
 	- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval.
 - **local_certs** causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments.
 - **key_type** specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.
 - **auto_https** configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`). See the [Automatic HTTPS](/docs/automatic-https) page for more details.
+- **cert_issuer** defines the issuer (or source) of TLS certificates.

src/docs/markdown/command-line.md

@@ -165,9 +165,9 @@ This command disables the admin API, making it easier to run multiple instances
 
 Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used.
 
-`<path>` specifies the path to the Caddyfile. If omitted, a file named Caddyfile in the current directory is assumed instead.
+`<path>` specifies the path to the Caddyfile. If `-`, the input is read from stdin. If omitted, a file named Caddyfile in the current directory is assumed instead.
 
-`--overwrite` causes the result to be written to the input file instead of being printed to the terminal.
+`--overwrite` causes the result to be written to the input file instead of being printed to the terminal. If the input is not a regular file, this flag has no effect.
 
 
 

src/docs/markdown/logging.md

@@ -94,7 +94,7 @@ Now compare an equivalent structured log message from Caddy, encoded as JSON and
 
 You can see how the structured log is much more useful and contains much more information. The abundance of information in this log message is not only useful, but it comes at virtually no performance overhead: Caddy's logs are zero-allocation. Structured logs have no restrictions on data types or context: they can be used in any code path and include any kind of information.
 
-Because the logs are structured and strongly-typed, they can be encoded into any format. So if you don't want to work with JSON, logs can be encoded into any other representation. Caddy supports [logfmt](https://brandur.org/logfmt) and others through [log encoder modules](/docs/json/logging/logs/encoder/), and even more can be added.
+Because the logs are structured and strongly-typed, they can be encoded into any format. So if you don't want to work with JSON, logs can be encoded into any other representation. Caddy supports others through [log encoder modules](/docs/json/logging/logs/encoder/), and even more can be added.
 
 **Most importantly** in the distinction between structured logs and legacy formats, a structured log can be encoded as Common Log Format (or anything else!), but not the other way around. It is non-trivial (or at least inefficient) to go from CLF to structured formats, and impossible considering the lack of information.
 

src/resources/css/docs.css

@@ -84,7 +84,7 @@ header nav .button {
 
 main {
 	display: flex;
-	justify-content: center;
+	justify-content: space-between;
 }
 
 main > .sidebar {
@@ -104,7 +104,8 @@ main > nav.sidebar {
 	font-size: 16px;
 }
 
-main nav li img {
+main nav li img,
+article li img {
 	max-height: .9em;
 }
 

src/resources/js/docs.js

@@ -44,7 +44,7 @@ $(function() {
 				? '/docs/caddyfile/directives'
 				: '/docs/caddyfile/directives/' + text;
 			$(item)
-				.html('<a href="' + url + '" style="color: inherit;"></a>')
+				.html('<a href="' + url + '" style="color: inherit;" title="Directive"></a>')
 				.find('a')
 				.text(text);
 		});
@@ -57,7 +57,7 @@ $(function() {
 		.map(function(k, item) {
 			let text = item.innerText;
 			$(item)
-				.html('<a href="/docs/caddyfile/matchers" style="color: inherit;"></a>')
+				.html('<a href="/docs/caddyfile/matchers" style="color: inherit;" title="Matcher token"></a>')
 				.find('a')
 				.text(text);
 		});