docs: General updates for beta 18

src/docs/markdown/caddyfile/directives.md

@@ -23,12 +23,10 @@ Directive | Description
 **[rewrite](/docs/caddyfile/directives/rewrite)** | Rewrites the request internally
 **[root](/docs/caddyfile/directives/root)** | Set the path to the site root
 **[route](/docs/caddyfile/directives/route)** | A group of directives treated literally as single unit
-**[strip_prefix](/docs/caddyfile/directives/strip_prefix)** | Rewrite that strips path prefix
-**[strip_suffix](/docs/caddyfile/directives/strip_suffix)** | Rewrite that strips path suffix
 **[templates](/docs/caddyfile/directives/templates)** | Execute templates on the response
 **[tls](/docs/caddyfile/directives/tls)** | Customize TLS settings
 **[try_files](/docs/caddyfile/directives/try_files)** | Rewrite that depends on file existence
-**[uri_replace](/docs/caddyfile/directives/uri_replace)** | Rewrite that replaces substrings in URI
+**[uri](/docs/caddyfile/directives/uri)** | Manipulate the URI
 
 
 ## Syntax
@@ -73,9 +71,7 @@ root
 redir
 rewrite
 
-strip_prefix
-strip_suffix
-uri_replace
+uri
 try_files
 
 basicauth
@@ -93,4 +89,4 @@ php_fastcgi
 file_server
 ```
 
-You can override or customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).
+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/rewrite.md

@@ -8,6 +8,8 @@ Rewrites the request internally. A rewrite changes some or all of the request UR
 
 The `rewrite` directive implies the intent to accept the request, but with modifications. It is mutually exclusive to other `rewrite` directives in the same block, so it is safe to define rewrites that would otherwise cascade into each other; only the first matching rewrite will be executed.
 
+Because `rewrite` essentially performs an internal redirect, the Caddyfile adapter will not fold any subsequent, adjacent handlers into the same route if their matchers happen to be exactly the same. This allows the matchers of the next handlers to be deferred until after the rewrite. In other words, a matcher that matches a request before the `rewrite` might not match the same request after the `rewrite`. If you want your `rewrite` to share a route with other handlers, use the [`route`](route) or [`handle`](handle) directives.
+
 
 ## Syntax
 
@@ -49,7 +51,5 @@ rewrite * /index.php?{query}&p={path}
 
 There are other directives that perform rewrites, but imply a different intent or do the rewrite without a complete replacement of the URI:
 
-- [`strip_prefix`](/docs/caddyfile/directives/strip_prefix) strips a prefix from the request path.
-- [`strip_suffix`](/docs/caddyfile/directives/strip_suffix) strips a suffix from the request path.
-- [`uri_replace`](/docs/caddyfile/directives/uri_replace) performs a substring replacement on the request path.
-- [`try_files`](/docs/caddyfile/directives/try_files) rewrites the request based on the existence of files.
+- [`uri`](uri) manipulates a URI (strip prefix, suffix, or substring replacement).
+- [`try_files`](try_files) rewrites the request based on the existence of files.

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

@@ -70,7 +70,7 @@ Strip `api/` prefix from request path just before proxying all API requests to a
 
 ```
 route /api/* {
-	strip_prefix  api/
+	uri strip_prefix api/
 	reverse_proxy localhost:9000
 }
 ```

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

@@ -1,31 +0,0 @@
----
-title: strip_prefix (Caddyfile directive)
----
-
-# strip_prefix
-
-Strips a given prefix from the request URI's path. If a matched request does not have the given path prefix, this directive is a no-op.
-
-
-## Syntax
-
-```
-strip_prefix [<matcher>] <prefix>
-```
-
-- **&lt;prefix&gt;** is the prefix to strip from the request path. This value may omit the leading forward slash `/` and it will be assumed.
-
-
-## Examples
-
-Strip `api/` from the beginning of all request paths:
-
-```
-strip_prefix api/
-```
-
-An alternate way to describe the same thing, using a matcher:
-
-```
-strip_prefix /api/* /api
-```

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

@@ -1,25 +0,0 @@
----
-title: strip_suffix (Caddyfile directive)
----
-
-# strip_suffix
-
-Strips a given suffix from the request URI's path. If a matched request does not have the given path suffix, this directive is a no-op.
-
-
-## Syntax
-
-```
-strip_suffix [<matcher>] <suffix>
-```
-
-- **&lt;suffix&gt;** is the suffix to strip from the request path.
-
-
-## Examples
-
-Strip `.html` from the end of all request paths:
-
-```
-strip_suffix .html
-```

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

@@ -22,6 +22,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 	load      <paths...>
 	ca        <ca_dir_url>
 	ca_root   <pem_file>
+	on_demand
 }
 ```
 
@@ -58,20 +59,34 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 - **load** specifies a list of folders from which to load PEM files that are certificate+key bundles.
 - **ca** changes the ACME CA endpoint. This is most often used to use [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) 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.
+- **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es).
 
 
 
 ## Examples
 
-Specify an email address for your ACME account:
-
-```
-tls your@email.com
-```
-
 Use a custom certificate and key:
 
 ```
 tls cert.pem key.pem
 ```
 
+Use locally-trusted certificates for all hosts on the current site block, rather than public certificates via ACME / Let's Encrypt (useful in dev environments):
+
+```
+tls internal
+```
+
+Use locally-trusted certificates, but managed on-demand intead of in the background:
+
+```
+tls internal {
+	on_demand
+}
+```
+
+Specify an email address for your ACME account (but if only one email is used for all sites, we recommend the `email` [global option](/docs/caddyfile/options) instead):
+
+```
+tls your@email.com
+```

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

@@ -0,0 +1,47 @@
+---
+title: uri (Caddyfile directive)
+---
+
+# uri
+
+Manipulates a request's URI. It can strip path prefix/suffix or replace substrings on the whole URI.
+
+This directive is distinct from [`rewrite`](rewrite) in that `uri` _partially_ changes the URI, rather than setting it to something completely different as `rewrite` does. While `rewrite` is treated specially as an internal redirect, `uri` is just another handler.
+
+
+## Syntax
+
+```
+uri [<matcher>] strip_prefix|strip_suffix|replace \
+	<target> \
+	[<replacement> [<limit>]]
+```
+
+- The first (non-matcher) argument specifies the operation:
+	- **strip_prefix** strips a prefix from the path, if it has the prefix.
+	- **strip_suffix** strips a suffix from the path, if it has the suffix.
+	- **replace** performs a substring replacement across the whole URI.
+- **&lt;target&gt;** is the prefix, suffix, or search string/regular expression. If a prefix, the leading forward slash may be omitted, since paths always start with a forward slash.
+- **&lt;replacement&gt;** is the replacement string (only valid with `replace`).
+- **&lt;limit&gt;** is an optional limit to the maximum number of replacements (only valid with `replace`).
+
+
+## Examples
+
+Strip `api/` from the beginning of all request paths:
+
+```
+uri strip_prefix api/
+```
+
+Strip `.php` from the end of all request paths:
+
+```
+uri strip_suffix .php
+```
+
+Replace "/docs/" with "/v1/docs/" in any request URI:
+
+```
+uri replace /docs/ /v1/docs/
+```

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

@@ -1,27 +0,0 @@
----
-title: uri_replace (Caddyfile directive)
----
-
-# uri_replace
-
-Performs a substring or regular expression replacement in the request URI.
-
-
-## Syntax
-
-```
-uri_replace [<matcher>] <find> <replace> [<limit>]
-```
-
-- **&lt;find&gt;** is the substring or regular expression to search for.
-- **&lt;replace&gt;** is the replacement value.
-- **&lt;limit&gt;** is an optional limit to the number of replacements.
-
-
-## Examples
-
-Replace "/docs/" with "/v1/docs/" in any request URI:
-
-```
-uri_replace * /docs/ /v1/docs/
-```

src/docs/markdown/caddyfile/options.md

@@ -20,30 +20,40 @@ Possible options are:
 
 ```
 {
-	http_port  <port>
-	https_port <port>
+	debug
+	http_port   <port>
+	https_port  <port>
+	default_sni <name>
 	order <dir1> first|last|[before|after <dir2>]
+	experimental_http3
 	storage <module_name> {
 		<options...>
 	}
-	experimental_http3
-	default_sni <name>
 	acme_ca <directory_url>
 	acme_ca_root <pem_file>
 	email   <yours>
 	admin   off|<addr>
-	debug
+	on_demand_tls {
+		ask      <endpoint>
+		interval <duration>
+		burst    <n>
+	}
+	local_certs
 }
 ```
 
+- **debug** enables debug mode, which sets all log levels to debug (unless otherwise specified).
 - **http_port** is the port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: 80
 - **https_port** is the port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: 443
-- **order** sets or changes the standard order of HTTP handler directive(s). Can set directives to be `first` or `last`, or `before` or `after` another directive.
-- **storage** configures Caddy's storage mechanism. Default: `file_system`
 - **default_sni** sets a default TLS ServerName for when clients do not use SNI in their ClientHello.
+- **order** sets or changes the standard order of HTTP handler directive(s). Can set directives to be `first` or `last`, or `before` or `after` another directive.
 - **experimental_http3** enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._
+- **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.
 - **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.
-- **debug** enables debug mode, which sets all log levels to debug (unless otherwise specified).
+- **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.