docs: Changes for v2.5.1 release (#228)

* docs: Changes for v2.5.1 release

* Remove path from addresses doc

* Fix www redirect pattern

src/docs/markdown/caddyfile/concepts.md

@@ -169,7 +169,6 @@ These are examples of valid addresses:
 - `localhost:8080`
 - `127.0.0.1`
 - `[::1]:2015`
-- `example.com/foo/*`
 - `*.example.com`
 - `http://`
 
@@ -177,7 +176,7 @@ These are examples of valid addresses:
 	<a href="/docs/automatic-https">Automatic HTTPS</a> is enabled if your site's address contains a hostname or IP address. This behavior is purely implicit, however, so it never overrides any explicit configuration. For example, if the site's address is <code>http://example.com</code>, auto-HTTPS will not activate because the scheme is explicitly <code>http://</code>.
 </aside>
 
-From the address, Caddy can potentially infer the scheme, host, port, and path of your site. If the address is without a port, the Caddyfile will choose the port matching the scheme if specified, or the default port of 443 will be assumed.
+From the address, Caddy can potentially infer the scheme, host and port of your site. If the address is without a port, the Caddyfile will choose the port matching the scheme if specified, or the default port of 443 will be assumed.
 
 If you specify a hostname, only requests with a matching Host header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`.
 
@@ -257,6 +256,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd
 | `{tls_client_certificate_pem}` | `{http.request.tls.client.certificate_pem}` |
 | `{tls_client_certificate_der_base64}` | `{http.request.tls.client.certificate_der_base64}` |
 | `{upstream_hostport}` | `{http.reverse_proxy.upstream.hostport}` |
+| `{rp.*}` | `{http.reverse_proxy.*}` |
 | `{vars.*}` | `{http.vars.*}` |
 
 

src/docs/markdown/caddyfile/directives.md

@@ -42,6 +42,7 @@ Directive | Description
 **[encode](/docs/caddyfile/directives/encode)** | Encodes (usually compresses) responses
 **[error](/docs/caddyfile/directives/error)** | Trigger an error
 **[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk
+**[forward_auth](/docs/caddyfile/directives/forward_auth)** | Delegate authentication to an external service
 **[handle](/docs/caddyfile/directives/handle)** | A mutually-exclusive group of directives
 **[handle_errors](/docs/caddyfile/directives/handle_errors)** | Defines routes for handling errors
 **[handle_path](/docs/caddyfile/directives/handle_path)** | Like handle, but strips path prefix
@@ -126,6 +127,7 @@ try_files
 
 # middleware handlers; some wrap responses
 basicauth
+forward_auth
 request_header
 encode
 push

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

@@ -0,0 +1,101 @@
+---
+title: forward_auth (Caddyfile directive)
+---
+
+# forward_auth
+
+An opinionated directive which proxies a clone of the request to an authentication gateway, which can decide whether handling should continue, or needs to be sent to a login page.
+
+- [Syntax](#syntax)
+- [Expanded Form](#expanded-form)
+- [Examples](#examples)
+
+Caddy's [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) is capable of performing "pre-check requests" to an external service, but this directive is tailored specifically for the authentication usecase. This directive is actually just a convenient way to use a longer, more common configuration (below).
+
+This directive makes a `GET` request to the configured upstream with the `uri` rewritten:
+- If the upstream responds with a `2xx` status code, then access is granted and the header fields in `copy_headers` are copied to the original request, and handling continues.
+- Otherwise, if the upstream responds with any other status code, then the upstream's response is copied back to the client. This response should typically involve a redirect to login page of the authentication gateway.
+
+If this behaviour is not exactly what you want, you may take the [expanded form](#expanded-form) below as a basis and customize it to your needs.
+
+All the subdirectives of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) are supported, and passed through to the underlying `reverse_proxy` handler.
+
+
+## Syntax
+
+```caddy-d
+forward_auth [<matcher>] [<upstreams...>] {
+	uri          <to>
+	copy_headers <fields...>
+}
+```
+
+- **&lt;upstreams...&gt;** is a list of upstreams (backends) to which to send auth requests.
+- **uri** is the URI (path and query) to set on the request sent to the upstream. This will usually be the verification endpoint of the authentication gateway.
+- **copy_headers** is a list of HTTP header fields to copy from the response to the original request, when the request has a success status code.
+
+Since this directive is an opinionated wrapper over a reverse proxy, you can use any of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#syntax)'s subdirectives to customize it.
+
+
+## Expanded form
+
+The `forward_auth` directive is the same as the following configuration. Auth gateways like [Authelia](https://www.authelia.com/) work well with this preset. If yours does not, feel free to borrow from this and customize it as needed instead of using the `forward_auth` shortcut.
+
+```caddy-d
+reverse_proxy <upstreams...> {
+	# Always GET, so that the incoming
+	# request's body is not consumed
+	method GET
+
+	# Change the URI to the auth gateway's
+	# verification endpoint
+	rewrite <to>
+
+	# Forward the original method and URI,
+	# since they get rewritten above; this
+	# is in addition to other X-Forwarded-*
+	# headers already set by reverse_proxy
+	header_up X-Forwarded-Method {method}
+	header_up X-Forwarded-Uri {uri}
+
+	# On a successful response, copy response headers
+	@good status 2xx
+	handle_response @good {
+		request_header {
+			# for example, for each copy_headers field...
+			Remote-User {rp.header.Remote-User}
+			Remote-Email {rp.header.Remote-Email}
+		}
+	}
+
+	# On a failed response, copy the response back to
+	# the client, with some hop-by-hop headers removed
+	handle_response {
+		copy_response_headers {
+			exclude Connection Keep-Alive Te Trailers Transfer-Encoding Upgrade
+		}
+		copy_response
+	}
+}
+```
+
+## Examples
+
+Delegating authentication to [Authelia](https://www.authelia.com/), before serving your app via a reverse proxy:
+
+```caddy
+# Serve the authentication gateway itself
+auth.example.com {
+	reverse_proxy authelia:9091
+}
+
+# Serve your app
+app1.example.com {
+	forward_auth authelia:9091 {
+		uri /api/verify?rd=https://auth.example.com
+		copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
+	}
+
+	reverse_proxy app1:8080
+}
+```

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

@@ -31,6 +31,7 @@ The `log` directive applies to the host/port of the site block it appears in, no
   - [json](#json)
   - [filter](#filter)
     - [delete](#delete)
+	- [rename](#rename)
 	- [replace](#replace)
 	- [ip_mask](#ip-mask)
 	- [query](#query)
@@ -223,6 +224,14 @@ Marks a field to be skipped from being encoded.
 <field> delete
 ```
 
+##### rename
+
+Rename the key of a log field.
+
+```caddy-d
+<field> rename <key>
+```
+
 ##### replace
 
 Marks a field to be replaced with the provided string at encoding time.

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

@@ -15,7 +15,7 @@ Caddy's [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) is capable o
 
 It expects that any `index.php` at the site root acts as a router. If that is not desirable, either reconfigure the `try_files` option to modify the default rewrite behaviour, or take the [expanded form](#expanded-form) below as a basis and customize it to your needs.
 
-It supports all the subdirectives of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) and passes them through to the underlying reverse_proxy handler, plus a few subdirectives that customize the FastCGI transport specifically.
+It supports all the subdirectives of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) and passes them through to the underlying `reverse_proxy` handler, plus a few subdirectives that customize the FastCGI transport specifically.
 
 **Most modern PHP apps work fine without extra subdirectives or customization.** Subdirectives are usually only used in certain edge cases or with legacy PHP apps.
 
@@ -49,7 +49,7 @@ php_fastcgi [<matcher>] <php-fpm_gateways...> {
 - **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 
 
-Since this directive is an opinionated wrapper over a reverse proxy, you can use any of reverse_proxy's subdirectives to customize it.
+Since this directive is an opinionated wrapper over a reverse proxy, you can use any of [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy#syntax)'s subdirectives to customize it.
 
 
 ## Expanded form

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

@@ -17,10 +17,11 @@ redir [<matcher>] <to> [<code>]
 
 - **&lt;to&gt;** is the target location. Becomes the response's Location header.
 - **&lt;code&gt;** is the HTTP status code to use for the redirect. Can be:
-	- A positive integer in the 3xx range
+	- A positive integer in the 3xx range, or 401
 	- `temporary` for a temporary redirect (302; default)
 	- `permanent` for a permanent redirect (301)
 	- `html` to use an HTML document to perform the redirect (useful for redirecting browsers but not API clients)
+	- A placeholder with a status code value
 
 
 
@@ -43,3 +44,9 @@ Same, but permanent:
 ```caddy-d
 redir https://example.com{uri} permanent
 ```
+
+Redirect your old `/about-us` page to your new `/about` page:
+
+```caddy-d
+redir /about-us /about
+```

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

@@ -26,7 +26,7 @@ $(function() {
 
 # reverse_proxy
 
-Proxies requests to one or more backends with configurable transport, load balancing, health checking, header manipulation, and buffering options.
+Proxies requests to one or more backends with configurable transport, load balancing, health checking, request manipulation, and buffering options.
 
 - [Syntax](#syntax)
 - [Upstreams](#upstreams)
@@ -39,6 +39,7 @@ Proxies requests to one or more backends with configurable transport, load balan
   - [Passive health checks](#passive-health-checks)
 - [Streaming](#streaming)
 - [Headers](#headers)
+- [Rewrites](#rewrites)
 - [Transports](#transports)
   - [The `http` transport](#the-http-transport)
   - [The `fastcgi` transport](#the-fastcgi-transport)
@@ -84,10 +85,12 @@ reverse_proxy [<matcher>] [<upstreams...>] {
 	buffer_responses
 	max_buffer_size <size>
 
-    # header manipulation
+	# request manipulation
 	trusted_proxies [private_ranges] <ranges...>
 	header_up   [+|-]<field> [<value|regexp> [<replacement>]]
 	header_down [+|-]<field> [<value|regexp> [<replacement>]]
+	method <method>
+	rewrite <to>
 
 	# round trip
 	transport <name> {
@@ -317,6 +320,23 @@ reverse_proxy https://example.com {
 
 
 
+### Rewrites
+
+By default, Caddy performs the upstream request with the same HTTP method and URI as the incoming request, unless a rewrite was performed in the middleware chain before it reaches `reverse_proxy`.
+
+Before proxying it, the request is cloned; this ensures that any modifications done to the request during the handler do not leak to other handlers. This is useful in situations where the handling needs to continue after the proxy.
+
+In addition to [header manipulations](#headers), the request's method and URI may be changed before it is sent to the upstream:
+
+- **method** <span id="method"/> changes the HTTP method of the cloned request. If the method is changed to `GET` or `HEAD`, then the incoming request's body will _not_ be sent upstream by this handler. This is useful if you wish to allow a different handler to consume the request body.
+- **rewrite** <span id="rewrite"/> changes the URI (path and query) of the cloned request. This is similar to the [`rewrite` directive](/docs/caddyfile/directives/rewrite), except that it doesn't persist the rewrite past the scope of this handler.
+
+These rewrites are often useful for a pattern like "pre-check requests", where a request is sent to another server to help make a decision on how to continue handling the current request.
+
+For example, the request could be sent to an authentication gateway to decide whether the request was from an authenticated user (e.g. the request has a session cookie) and should continue, or should instead be redirected to a login page. For this pattern, Caddy provides a shortcut directive [`forward_auth`](/docs/caddyfile/directives/forward_auth) to skip most of the config boilerplate.
+
+
+
 
 ### Transports
 
@@ -399,27 +419,32 @@ transport fastcgi {
 - **read_timeout** <span id="read_timeout"/> is how long to wait when reading from the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 - **write_timeout** <span id="write_timeout"/> is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 
+<aside class="tip">
+	If you're trying to serve a modern PHP application, you may be looking for the <a href="/docs/caddyfile/directives/php_fastcgi"><code>php_fastcgi</code> directive</a>, which is a shortcut for a proxy using the `fastcgi` directive, with the necessary rewrites for using `index.php` as the routing entrypoint.
+</aside>
 
 
 
 ### Intercepting responses
 
-The reverse proxy can be configured to intercept responses from the backend. To facilitate this, response matchers can be defined (similar to the syntax for request matchers) and the first matching `handle_response` route will be invoked. When this happens, the response from the backend is not written to the client, and the configured `handle_response` route will be executed instead, and it is up to that route to write a response.
+The reverse proxy can be configured to intercept responses from the backend. To facilitate this, response matchers can be defined (similar to the syntax for request matchers) and the first matching `handle_response` route will be invoked.
+
+When a response handler is invoked, the response from the backend is not written to the client, and the configured `handle_response` route will be executed instead, and it is up to that route to write a response. If the route does _not_ write a response, then request handling will continue with any handlers that are ordered after this `reverse_proxy`.
 
 - **@name** is the name of a [response matcher](#response-matcher). As long as each response matcher has a unique name, multiple matchers can be defined. A response can be matched on the status code and presence or value of a response header.
 - **replace_status** <span id="replace_status"/> simply changes the status code of response when matched by the given matcher.
-- **handle_response** <span id="handle_response"/> defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used.
+- **handle_response** <span id="handle_response"/> defines the route to execute when matched by the given matcher (or, if a matcher is omitted, all responses). The first matching block will be applied. Inside a `handle_response` block, any other [directives](/docs/caddyfile/directives) can be used. During 
 
 Additionally, inside `handle_response`, two special handler directives may be used:
 
-- **copy_response** <span id="copy_response"/> copies the response from the backend back to the client. Optionally allows changing the status code of the response while doing so. This directive is [ordered before `respond`](/docs/caddyfile/directives#directive-order).
+- **copy_response** <span id="copy_response"/> copies the response body received from the backend back to the client. Optionally allows changing the status code of the response while doing so. This directive is [ordered before `respond`](/docs/caddyfile/directives#directive-order).
 - **copy_response_headers** <span id="copy_response_headers"/> copies the response headers from the backend to the client, optionally including _OR_ excluding a list of headers fields (cannot specify both `include` and `exclude`). This directive is [ordered after `header`](/docs/caddyfile/directives#directive-order).
 
 Three placeholders will be made available within the `handle_response` routes:
 
-- `{http.reverse_proxy.status_code}` The status code from the backend's response.
+- `{rp.status_code}` The status code from the backend's response.
-- `{http.reverse_proxy.status_text}` The status text from the backend's response.
+- `{rp.status_text}` The status text from the backend's response.
-- `{http.reverse_proxy.header.*}` The headers from the backend's response.
+- `{rp.header.*}` The headers from the backend's response.
 
 
 #### Response matcher
@@ -486,7 +511,6 @@ Reverse proxy to an HTTPS endpoint:
 ```caddy-d
 reverse_proxy https://example.com {
 	header_up Host {upstream_hostport}
-	header_up X-Forwarded-Host {host}
 }
 ```
 
@@ -510,14 +534,23 @@ handle_path /old-prefix/* {
 ```
 
 
-X-Accel-Redirect support:
+When Caddy is behind another proxy or load balancer whose IP is `123.123.123.123`, which may set `X-Forwarded-*` headers to identify details about the original client request, that downstream proxy must be listed as trusted, otherwise Caddy will ignore those incoming headers:
+
+```caddy-d
+reverse_proxy localhost:8080 {
+	trusted_proxies 123.123.123.123
+}
+```
+
+
+X-Accel-Redirect support, i.e. serving static files as requested by the proxy upstream:
 
 ```caddy-d
 reverse_proxy localhost:8080 {
 	@accel header X-Accel-Redirect *
 	handle_response @accel {
 		root    * /path/to/private/files
-		rewrite * {http.reverse_proxy.header.X-Accel-Redirect}
+		rewrite * {rp.header.X-Accel-Redirect}
 		file_server
 	}
 }
@@ -531,12 +564,13 @@ reverse_proxy localhost:8080 {
 	@error status 500 503
 	handle_response @error {
 		root    * /path/to/error/pages
-		rewrite * /{http.reverse_proxy.status_code}.html
+		rewrite * /{rp.status_code}.html
 		file_server
 	}
 }
 ```
 
+
 Get backends dynamically from A/AAAA record DNS queries:
 
 ```caddy-d
@@ -545,6 +579,7 @@ reverse_proxy {
 }
 ```
 
+
 Get backends dynamically from SRV record DNS queries:
 
 ```caddy-d

src/docs/markdown/caddyfile/matchers.md

@@ -192,13 +192,13 @@ As a special case, Caddy [placeholders](/docs/conventions#placeholders) (or [Cad
 
 #### Examples:
 
-Match requests whose methods start with `P`, e.g. `PUT` or `POST`.
+Match requests whose methods start with `P`, e.g. `PUT` or `POST`:
 
 ```caddy-d
 expression {method}.startsWith("P")
 ```
 
-Match requests where handler returned error status code `404`, would be used in conjunction with the [`handle_errors` directive](/docs/caddyfile/directives/handle_errors).
+Match requests where handler returned error status code `404`, would be used in conjunction with the [`handle_errors` directive](/docs/caddyfile/directives/handle_errors):
 
 ```caddy-d
 expression {http.error.status_code} == 404
@@ -246,13 +246,13 @@ Upon matching, two new placeholders will be made available:
 
 #### Examples:
 
-Match requests where the path is a file that exists.
+Match requests where the path is a file that exists:
 
 ```caddy-d
 file
 ```
 
-Match requests where the path followed by `.html` is a file that exists, or if not, where the path is a file that exists.
+Match requests where the path followed by `.html` is a file that exists, or if not, where the path is a file that exists:
 
 ```caddy-d
 file {
@@ -260,7 +260,7 @@ file {
 }
 ```
 
-Same as above, except using the one-line shortcut, and falling back to emitting a 404 error if a file is not found.
+Same as above, except using the one-line shortcut, and falling back to emitting a 404 error if a file is not found:
 
 ```caddy-d
 file {path}.html {path} =404
@@ -289,13 +289,13 @@ Different header fields within the same set are AND-ed. Multiple values per fiel
 
 #### Example:
 
-Match requests with the `Connection` header containing `Upgrade`.
+Match requests with the `Connection` header containing `Upgrade`:
 
 ```caddy-d
 header Connection *Upgrade*
 ```
 
-Match requests with the `Foo` header containing `bar` OR `baz`.
+Match requests with the `Foo` header containing `bar` OR `baz`:
 ```caddy-d
 @foo {
 	header Foo bar
@@ -367,13 +367,13 @@ Multiple `method` matchers will be OR'ed together.
 
 #### Examples:
 
-Match requests with the `GET` method.
+Match requests with the `GET` method:
 
 ```caddy-d
 method GET
 ```
 
-Match requests with the `PUT` or `DELETE` methods.
+Match requests with the `PUT` or `DELETE` methods:
 
 ```caddy-d
 method PUT DELETE
@@ -469,7 +469,7 @@ There can only be one `path_regexp` matcher per named matcher.
 
 #### Example:
 
-Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups that can be accessed with `{re.static.1}` and `{re.static.2}` for each part enclosed in `( )`, respectively.
+Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups that can be accessed with `{re.static.1}` and `{re.static.2}` for each part enclosed in `( )`, respectively:
 
 ```caddy-d
 path_regexp static \.([a-f0-9]{6})\.(css|js)$
@@ -503,7 +503,7 @@ There can be multiple `query` matchers per named matcher, and pairs with the sam
 
 #### Example:
 
-Match requests with a `sort` query parameter with the value `asc`
+Match requests with a `sort` query parameter with the value `asc`:
 
 ```caddy-d
 query sort=asc
@@ -520,14 +520,23 @@ remote_ip [forwarded] <ranges...>
 
 By remote (client) IP address. Accepts exact IPs or CIDR ranges. If the first argument is `forwarded`, then the first IP in the `X-Forwarded-For` request header, if present, will be preferred as the reference IP, rather than the immediate peer's IP, which is the default. IPv6 zones are supported.
 
-Multiple `remote_ip` matchers will be OR'ed together.
+As a shortcut, `private_ranges` can be used to match all private IPv4 and IPv6 ranges. It's the same as specifying all of these ranges: `192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1`
+
+There can be multiple `remote_ip` matchers per named matcher, and their ranges will be merged and OR'ed together.
 
 #### Example:
 
-Match requests from private IPv4 addresses.
+Match requests from private IPv4 addresses:
 
 ```caddy-d
-remote_ip 192.168.0.0/16 172.16.0.0/12 10.0.0.0/8
+remote_ip 192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8
+```
+
+This matcher is commonly paired with the [`not`](#not) matcher to invert the match. For example, to abort all connections from _public_ IPv4 and IPv6 addresses (which is the inverse of all private ranges):
+
+```caddy-d
+@denied not remote_ip private_ranges
+abort @denied
 ```
 
 
@@ -545,7 +554,7 @@ This matcher is most useful when paired with the [`map` directive](/docs/caddyfi
 
 #### Example:
 
-Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for the values `3`, or `5`.
+Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for the values `3`, or `5`:
 
 ```caddy-d
 vars {magic_number} 3 5
@@ -568,7 +577,7 @@ There can only be one `vars_regexp` matcher per named matcher.
 
 #### Example:
 
-Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for a value starting with `4`, capturing the value in a capture group.
+Match an output of the [`map` directive](/docs/caddyfile/directives/map) named `magic_number` for a value starting with `4`, capturing the value in a capture group:
 
 ```caddy-d
 vars_regexp magic {magic_number} ^(4.*)

src/docs/markdown/caddyfile/patterns.md

@@ -100,7 +100,7 @@ To remove it for **multiple domains** at once:
 
 ```caddy
 www.example-one.com, www.example-two.com {
-	redir https://{labels.1}{labels.0}{uri}
+	redir https://{labels.1}.{labels.0}{uri}
 }
 
 example-one.com, example-two.com {