docs: Some cleanup, some v2.4.0 additions (#139)

* docs: Some cleanup, some v2.4.0 additions

- Add `abort` directive docs
- Add a note in `handle` to cross-link to `handle_path`
- Add another example in `handle_errors` that shows how an `expression` matcher can be used to pair with it
- Add a cat emoji to handle_errors because 😸
- Add `file_server` to one of the `php_fastcgi` examples, it's rare that you'll ever use it without `file_server` so might as well include it there
- Add a TOC to `reverse_proxy` cause it's such a long page. Maybe we'll add one to other pages as well, but TBD
- Clarify the upstream address stuff a bit after some discussion in https://caddy.community/t/reverse-proxy-with-multiple-different-upstreams-with-paths/11512/12 and mention `rewrite` as the alternative
- Use the `{re.*.*}` shortcut in the Caddyfile matcher docs, links to the placeholder mapping to let people trace where that comes from

* docs: Revise the `handle` cross-linking, add another example

* docs: Bump minimum Go version to 1.15

* docs: A bunch more additions since v2.3.0

I went through the whole list of commits here: https://github.com/caddyserver/caddy/compare/v2.3.0...ec3ac84

* docs: Review feedback

* docs: Link to https://golang.org/doc/install, better instructions

src/docs/markdown/build.md

@@ -6,7 +6,7 @@ title: "Build from source"
 
 Requirements:
 
-- [Go](https://golang.org/dl) 1.14 or newer
+- [Go](https://golang.org/doc/install) 1.15 or newer
 
 Clone the repository:
 

src/docs/markdown/caddyfile/directives.md

@@ -103,6 +103,7 @@ reverse_proxy
 php_fastcgi
 file_server
 acme_server
+abort
 ```
 
 You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).

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

@@ -15,8 +15,18 @@ abort [<matcher>]
 
 ## Examples
 
-Abort all requests for paths starting with `/foo`:
+Forcefully close a connection received for unknown domains when using a wildcard certificate:
 
-```caddy-d
-abort /foo*
-```
+```caddy
+*.example.com {
+    @foo host foo.example.com
+    handle @foo {
+        respond "This is foo!" 200
+    }
+
+    # Unhandled domains fall through to here, but we don't want to accept their requests
+    handle {
+        abort
+    }
+}
+```

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

@@ -23,6 +23,14 @@ handle [<matcher>] {
 
 If you prefer crafting HTTP handler logic in a more inheritence-based way like nginx location blocks, you may prefer the use of `handle` blocks rather than defining mutually-exclusive matchers for your directives. If inheritence is a desired characteristic of your HTTP handler configurations, then the `handle` directive may suit you well.
 
+## Similar directives
+
+There are other directives that can wrap HTTP handler directives, but each has its use depending on the behavior you want to convey:
+
+- [`handle_path`](handle_path) does the same as `handle`, but it strips a prefix from the request before running its handlers.
+- [`handle_errors`](handle_errors) is like `handle`, but is only invoked when Caddy encounters an error during request handling.
+- [`route`](route) wraps other directives like `handle` does, but with two distinctions: 1) route blocks are not mutually exclusive to each other, and 2) directives within a route are not [re-ordered]([directive order](/docs/caddyfile/directives#directive-order), giving you more control if needed.
+
 ## Examples
 
 Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy:
@@ -35,3 +43,15 @@ handle {
 	reverse_proxy 127.0.0.1:8080
 }
 ```
+
+You can mix `handle` and [`handle_path`](handle_path) directives in the same site, and they will still be mutually exclusive from each other:
+
+```caddy-d
+handle_path /foo/* {
+	# The path has the "/foo" prefix stripped
+}
+
+handle /bar/* {
+	# The path still retains "/bar"
+}
+```

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

@@ -26,7 +26,7 @@ handle_errors {
 
 Custom error pages based on the status code (i.e. a page called `404.html` for 404 errors):
 
-```caddy
+```caddy-d
 handle_errors {
 	rewrite * /{http.error.status_code}.html
 	file_server
@@ -35,7 +35,7 @@ handle_errors {
 
 A single error page that uses [`templates`](/docs/caddyfile/directives/templates) to write a custom error message:
 
-```caddy
+```caddy-d
 handle_errors {
 	rewrite * /error.html
 	templates
@@ -43,9 +43,9 @@ handle_errors {
 }
 ```
 
-Reverse proxy to a professional server that is highly qualified for handling HTTP errors and improving your day:
+Reverse proxy to a professional server that is highly qualified for handling HTTP errors and improving your day 😸:
 
-```caddy
+```caddy-d
 handle_errors {
 	rewrite * /{http.error.status_code}
 	reverse_proxy https://http.cat {
@@ -56,8 +56,19 @@ handle_errors {
 
 Simply use [`respond`](/docs/caddyfile/directives/respond) to return the error code and name
 
-```caddy
+```caddy-d
 handle_errors {
 	respond "{http.error.status_code} {http.error.status_text}"
 }
 ```
+
+To handle specific error codes differently, use an [`expression`](/docs/caddyfile/matchers#expression) matcher:
+
+```caddy-d
+handle_errors {
+	@4xx expression `{http.error.status_code} >= 400 && {http.error.status_code} < 500`
+	respond @4xx "It's a 4xx error!"
+
+	respond "It's not a 4xx error."
+}
+```

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

@@ -97,9 +97,10 @@ When using php-fpm listening via a unix socket:
 php_fastcgi unix//run/php/php7.4-fpm.sock
 ```
 
-The [`root` directive](/docs/caddyfile/directives/root) is often used to specify the directory containing the PHP scripts:
+The [`root` directive](/docs/caddyfile/directives/root) is often used to specify the directory containing the PHP scripts, and the [`file_server` directive](/docs/caddyfile/directives/file_server) to serve static files:
 
 ```caddy-d
 root * /var/www/html
 php_fastcgi 127.0.0.1:9000
+file_server
 ```

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

@@ -6,6 +6,19 @@ title: reverse_proxy (Caddyfile directive)
 
 Proxies requests to one or more backends with configurable transport, load balancing, health checking, header manipulation, and buffering options.
 
+- [Syntax](#syntax)
+- [Upstreams](#upstreams)
+- [Load balancing](#load-balancing)
+  - [Active health checks](#active-health-checks)
+  - [Passive health checks](#passive-health-checks)
+- [Streaming](#streaming)
+- [Headers](#headers)
+- [Transports](#transports)
+  - [The `http` transport](#the-http-transport)
+  - [The `fastcgi` tranport](#the-fastcgi-transport)
+- [Examples](#examples)
+
+
 
 ## Syntax
 
@@ -27,6 +40,9 @@ reverse_proxy [<matcher>] [<upstreams...>] {
     health_timeout  <duration>
     health_status   <status>
     health_body     <regexp>
+	health_headers {
+		<field> [<values...>]
+	}
 
     # passive health checking
     fail_duration     <duration>
@@ -38,6 +54,8 @@ reverse_proxy [<matcher>] [<upstreams...>] {
     # streaming
     flush_interval <duration>
     buffer_requests
+	buffer_responses
+	max_buffer_size <size>
 
     # header manipulation
     header_up   [+|-]<field> [<value|regexp> [<replacement>]]
@@ -50,6 +68,8 @@ reverse_proxy [<matcher>] [<upstreams...>] {
 }
 ```
 
+
+
 ### Upstreams
 
 - **&lt;upstreams...&gt;** is a list of upstreams (backends) to which to proxy.
@@ -67,7 +87,13 @@ Upstream addresses can take the form of a conventional [Caddy network address](/
 - `srv+http://internal.service.consul`
 - `srv+https://internal.service.consul`
 
-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.
+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, upstream addresses cannot contain paths or query strings, as that would imply simultaneous rewriting the request while proxying, which behavior is not defined or supported. You may use the [`rewrite`](/docs/caddyfile/directives/rewrite) directive should you need this.
+
+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, meaning that the potentially many different backends act as one upstream in terms of health checks and load balancing.
+
+
 
 ### Load balancing
 
@@ -87,6 +113,8 @@ Load balancing is used whenever more than one upstream is defined.
 - **lb_try_duration** is a [duration value](/docs/conventions#durations) that defines how long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients will wait for up to this long while the load balancer tries to find an available upstream host.
 - **lb_try_interval** is a [duration value](/docs/conventions#durations) that defines how long to wait between selecting the next host from the pool. Default is `250ms`. Only relevant when a request to an upstream host fails. Be aware that setting this to 0 with a non-zero `lb_try_duration` can cause the CPU to spin if all backends are down and latency is very low.
 
+
+
 #### Active health checks
 
 Active health checks perform health checking in the background on a timer:
@@ -97,6 +125,9 @@ Active health checks perform health checking in the background on a timer:
 - **health_timeout** is a [duration value](/docs/conventions#durations) that defines how long to wait for a reply before marking the backend as down.
 - **health_status** is the HTTP status code to expect from a healthy backend. Can be a 3-digit status code or a status code class ending in `xx`, for example: `200` (default) or `2xx`.
 - **health_body** is a substring or regular expression to match on the response body of an active health check. If the backend does not return a matching body, it will be marked as down.
+- **health_headers** allows specifying headers to set on the active health check requests. This is useful if you need to change the `Host` header, or if you need to provide some authentication to your backend as part of your health checks.
+
+
 
 #### Passive health checks
 
@@ -108,12 +139,18 @@ Passive health checks happen inline with actual proxied requests:
 - **unhealthy_latency** is a [duration value](/docs/conventions#durations) that counts a request as failed if it takes this long to get a response.
 - **unhealthy_request_count** is the permissible number of simultaneous requests to a backend before marking it as down.
 
+
+
 ### Streaming
 
 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. 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.
 - **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).
+- **buffer_responses** will cause the entire response body to be read and buffered in memory before being proxied to the client. This should be avoided if at all possible for performance reasons, but could be useful if the backend has tighter memory constraints.
+- **max_buffer_size** if body buffering is enabled, this sets the maximum size of the buffers used for the requests and responses. This accepts all size formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go).
+
+
 
 ### Headers
 
@@ -129,6 +166,8 @@ By default, Caddy passes thru incoming headers to the backend&mdash;including th
 
 Since these header fields are only de-facto standards, Caddy may stop setting them implicitly in the future if the standardized [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) header field becomes more widely adopted.
 
+
+
 ### Transports
 
 Caddy's proxy **transport** is pluggable:
@@ -207,6 +246,7 @@ transport fastcgi {
 - **write_timeout** is how long to wait when sending to the FastCGI server. Accepts [duration values](/docs/conventions#durations). Default: no timeout.
 
 
+
 ## Examples
 
 Reverse proxy all requests to a local backend:

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

@@ -63,6 +63,13 @@ route {
 
 And now `file_server` will be chained in before `redir` because the order is taken literally.
 
+## Similar directives
+
+There are other directives that can wrap HTTP handler directives, but each has its use depending on the behavior you want to convey:
+
+- [`handle`](route) wraps other directives like `route` does, but with two distinctions: 1) handle blocks are mutually exclusive to each other, and 2) directives with a handle are [re-ordered]([directive order](/docs/caddyfile/directives#directive-order) normally.
+- [`handle_path`](handle_path) does the same as `handle`, but it strips a prefix from the request before running its handlers.
+- [`handle_errors`](handle_errors) is like `handle`, but is only invoked when Caddy encounters an error during request handling.
 
 ## Examples
 

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

@@ -23,6 +23,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 	ca        <ca_dir_url>
 	ca_root   <pem_file>
 	dns       <provider_name> [<params...>]
+	resolvers <dns_servers...>
 	eab       <key_id> <mac_key>
 	on_demand
 	client_auth {
@@ -70,6 +71,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 - **ca** changes the ACME CA endpoint. This is most often used to set [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) when testing, or an internal ACME server. (To change this value for the whole Caddyfile, use the `acme_ca` [global option](/docs/caddyfile/options) instead.)
 - **ca_root** specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store.
 - **dns** enables the [DNS challenge](/docs/automatic-https#dns-challenge) using the specified provider plugin, which must be plugged in from one of the [caddy-dns](https://github.com/caddy-dns) repositories. Each provider plugin may have their own syntax following their name; refer to their docs for details. Maintaining support for each DNS provider is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148)
+- **resolvers** customizes the DNS resolvers used when performing the DNS challenge; these take precedence over system resolvers or any default ones. If set here, the resolvers will propagate to all configured certificate issuers.
 - **eab** configures ACME external account binding (EAB) for this site, using the key ID and MAC key provided by your CA.
 - **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es).
 - **client_auth** enables and configures TLS client authentication:
@@ -102,7 +104,7 @@ These issuers come standard with the `tls` directive:
 Obtains certificates using the ACME protocol.
 
 ```caddy
-... acme {
+... acme [<directory_url>] {
 	dir      <directory_url>
 	test_dir <test_directory_url>
 	email    <email>

src/docs/markdown/caddyfile/matchers.md

@@ -283,13 +283,13 @@ Match requests that do not have the `Foo` header field at all:
 header_regexp [<name>] <field> <regexp>
 ```
 
-Like `header`, but supports regular expressions. Capture groups can be accessed via placeholder like `{http.regexp.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
+Like `header`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
 Only one regular expression is supported per header field. Multiple different fields will be AND'ed.
 
 #### Example:
 
-Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{http.regexp.login.1}`.
+Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{re.login.1}`.
 
 ```caddy-d
 header_regexp login Cookie login_([a-f0-9]+)
@@ -414,13 +414,13 @@ Multiple `path` matchers will be OR'ed together.
 path_regexp [<name>] <regexp>
 ```
 
-Like `path`, but supports regular expressions. Capture groups can be accessed via placeholder like `{http.regexp.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
+Like `path`, but supports regular expressions. Capture groups can be accessed via [placeholder](/docs/caddyfile/concepts#placeholders) like `{re.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
 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 `{http.regexp.static.1}` and `{http.regexp.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)$

src/docs/markdown/caddyfile/options.md

@@ -49,6 +49,7 @@ Possible options are:
 	}
 	key_type ed25519|p256|p384|rsa2048|rsa4096
 	cert_issuer <name> ...
+	ocsp_stapling off
 
 	# Server Options
 	servers [<listener_address>] {
@@ -134,7 +135,10 @@ Configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enab
 Specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.
 
 ##### `cert_issuer`
-Defines the issuer (or source) of TLS certificates. The tokens following the name of the issuer set up the issuer the same as if specified in the [`tls` directive](/docs/caddyfile/directives/tls#issuer).
+Defines the issuer (or source) of TLS certificates. The tokens following the name of the issuer set up the issuer the same as if specified in the [`tls` directive](/docs/caddyfile/directives/tls#issuer). May be repeated if you wish to configure more than one issuer to try. They will be tried in the order they are defined.
+
+##### `ocsp_stapling`
+Can be set to `off` to disable OCSP stapling. Useful in environments where responders are not reachable due to firewalls.
 
 
 

src/docs/markdown/command-line.md

@@ -222,7 +222,8 @@ NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version i
 <pre><code class="cmd bash">caddy reload
 	[--config &lt;path&gt;]
 	[--adapter &lt;name&gt;]
-	[--address &lt;interface&gt;]</code></pre>
+	[--address &lt;interface&gt;]
+	[--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.
 
@@ -234,6 +235,8 @@ Because this command uses the API, the admin endpoint must not be disabled.
 
 `--address` needs to be used if the admin endpoint is not listening on the default address and if it is different from the address in the provided config file. Note that only TCP addresses are supported at this time.
 
+`--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 reverse-proxy`

src/docs/markdown/extending-caddy.md

@@ -9,7 +9,7 @@ Caddy is easy to extend because of its modular architecture. Most kinds of Caddy
 **Prerequisites:**
 - Basic understanding of [Caddy's architecture](/docs/architecture)
 - Go language proficiency
-- [`go`](https://golang.org/dl)
+- [`go`](https://golang.org/doc/install)
 - [`xcaddy`](https://github.com/caddyserver/xcaddy)