diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 56c6af7..b47e5d6 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -15,6 +15,7 @@ Directive | Description **[file_server](/docs/caddyfile/directives/file_server)** | Serve files from disk **[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 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers **[import](/docs/caddyfile/directives/import)** | Include snippets or files **[log](/docs/caddyfile/directives/log)** | Enables access/request logging @@ -85,12 +86,14 @@ encode templates handle +handle_path route respond reverse_proxy php_fastcgi file_server +acme_server ``` You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route). \ No newline at end of file diff --git a/src/docs/markdown/caddyfile/directives/basicauth.md b/src/docs/markdown/caddyfile/directives/basicauth.md index 6ee56cc..059d158 100644 --- a/src/docs/markdown/caddyfile/directives/basicauth.md +++ b/src/docs/markdown/caddyfile/directives/basicauth.md @@ -8,7 +8,7 @@ Enables HTTP Basic Authentication, which can be used to protect directories and **Note that basic auth is not secure over plain HTTP.** Use discretion when deciding what to protect with HTTP Basic Authentication. -When a user requests a resource that is protected, the browser will prompt the user for a username and password if they have not already supplied one. If the proper credentials are present in the Authorization header, the server will grant access to the resource. If the header is missing or the credentials are incorrect, the server will respond with HTTP 401 Unauthorized. +When a user requests a resource that is protected, the browser will prompt the user for a username and password if they have not almdy supplied one. If the proper credentials are present in the Authorization header, the server will grant access to the resource. If the header is missing or the credentials are incorrect, the server will respond with HTTP 401 Unauthorized. Caddy configuration does not accept plaintext passwords; you MUST hash them before putting them into the configuration. The [`caddy hash-password`](/docs/command-line#caddy-hash-password) command can help with this. @@ -16,13 +16,14 @@ Caddy configuration does not accept plaintext passwords; you MUST hash them befo ## Syntax ```caddy-d -basicauth [] [] { +basicauth [] [ []] { [] ... } ``` - **<hash_algorithm>** is the name of the password hashing algorithm (or KDF) used for the hashes in this configuration. Can be `bcrypt` (default) or `scrypt`. +- **<realm>** is a custom realm name. - **<username>** is a username or user ID. - **<hashed_password_base64>** is the base-64 encoding of the hashed password. - **<salt_base64>** is the base-64 encoding of the password salt, if an external salt is required. diff --git a/src/docs/markdown/caddyfile/directives/handle_path.md b/src/docs/markdown/caddyfile/directives/handle_path.md new file mode 100644 index 0000000..8812cab --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/handle_path.md @@ -0,0 +1,43 @@ +--- +title: handle_path (Caddyfile directive) +--- + +# handle_path + +Same as the [`handle` directive](/docs/caddyfile/directives/handle), but implicitly strips the matched path prefix. + +Handling a request matching a certain path (while stripping that path from the request URI) is a common enough use case that it has its own directive for convenience. + + +## Syntax + +```caddy-d +handle_path { + +} +``` + +- **** is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a handle_path block. + +Note that only a single path matcher is accepted and required; you cannot use other kinds of matchers with handle_path. + +## Examples + +This configuration: + +```caddy-d +handle_path /prefix/* { + ... +} +``` + +is effectively the same as this: + +```caddy-d +handle /prefix/* { + uri strip_prefix /prefix + ... +} +``` + +but the `handle_path` form is slightly more succinct. diff --git a/src/docs/markdown/caddyfile/directives/php_fastcgi.md b/src/docs/markdown/caddyfile/directives/php_fastcgi.md index fa9ae83..aee0a57 100644 --- a/src/docs/markdown/caddyfile/directives/php_fastcgi.md +++ b/src/docs/markdown/caddyfile/directives/php_fastcgi.md @@ -10,16 +10,30 @@ Caddy's [reverse_proxy](/docs/caddyfile/directives/reverse_proxy) is capable of It expects that any `index.php` at the site root acts as a router. If that is not desirable, either perform your own URI rewrite or use something like the [expanded form](#expanded-form) below 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. + +**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. ## Syntax ```caddy-d -php_fastcgi [] +php_fastcgi [] { + split + env [ ] + root + index + + +} ``` -- **** is the address of the FastCGI server. +- **** are the [addresses](/docs/conventions#network-addresses) of the FastCGI servers. +- **split** sets the substrings for splitting the URI into two parts. The first matching substring will be used to split the "path info" from the path. The first piece is suffixed with the matching substring and will be assumed as the actual resource (CGI script) name. The second piece will be set to PATH_INFO for the CGI script to use. Default: `.php` +- **env** sets an extra environment variable to the given value. +- **root** sets the root folder to the site. Default: [`root` directive](/docs/caddyfile/directives/root). +- **index** specifies the list of filenames to treat as directory index files. This affects the file matcher in the [expanded form](#expanded-form). -Since this directive is an opinionated wrapper over a reverse proxy, you can open a block and 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's subdirectives to customize it. ## Expanded form diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index fb51c51..a23d89e 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -124,7 +124,7 @@ transport http { write_buffer dial_timeout tls - tls_client_auth + tls_client_auth | tls_insecure_skip_verify tls_timeout tls_trusted_ca_certs @@ -138,7 +138,7 @@ transport http { - **write_buffer** is the size of the write buffer in bytes. - **dial_timeout** is how long to wait when connecting to the upstream socket. - **tls** uses HTTPS with the backend. This will be enabled automatically if you specify backends using the `https://` scheme or port `:443`. -- **tls_client_auth** specifies a certificate and key file to present for TLS client authentication with the backend. +- **tls_client_auth** enables TLS client authentication one of two ways: (1) by specifying a domain name for which Caddy should obtain a certificate and keep it renewed, or (2) by specifying a certificate and key file to present for TLS client authentication with the backend. - **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. diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index ca1f4d3..c046641 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -93,7 +93,7 @@ redir /old.html /new.html Path matcher tokens must start with a forward slash `/`. -[Path matching](/docs/caddyfile/matchers#path) is an exact match by default; you must append a `*` for a fast prefix match. Note that `/foo*` will match `/foo` and `/foo/` as well as `/foobar`; you might actually want `/foo/*` instead. +**[Path matching](/docs/caddyfile/matchers#path) is an exact match by default;** you must append a `*` for a fast prefix match. Note that `/foo*` will match `/foo` and `/foo/` as well as `/foobar`; you might actually want `/foo/*` instead. ### Named matchers @@ -135,8 +135,6 @@ If the matcher set consists of only one matcher, a one-liner syntax also works: 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. diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 388a48b..a74b6f9 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -40,6 +40,7 @@ Possible options are: } local_certs key_type ed25519|p256|p384|rsa2048|rsa4096 + auto_https off|disable_redirects } ``` @@ -59,3 +60,4 @@ Possible options are: - **interval** and **burst** allows `` certificate operations within `` 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`). diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index ed7bacd..37bf8dc 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -136,7 +136,8 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin [--listen <addr>] [--domain <example.com>] [--browse] - [--templates] + [--templates] + [--access-log] Spins up a simple but production-ready static file server. @@ -150,6 +151,8 @@ Spins up a simple but production-ready static file server. `--templates` will enable template rendering. +`--access-log` enables the request/access log. + This command disables the admin API, making it easier to run multiple instances on a local development machine. @@ -252,6 +255,7 @@ This command disables the admin API so it is easier to run multiple instances on [--adapter <name>] [--pidfile <file>] [--environ] + [--envfile <file>] [--resume] [--watch] @@ -265,6 +269,8 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode. `--environ` prints out the environment before starting. This is the same as the `caddy environ` command, but does not exit after printing. +`--envfile` loads environment variables from the specified file. + `--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. `--watch` will watch the config file and automatically reload it after it changes. ⚠️ This feature is intended for use only in local development environments! diff --git a/src/docs/markdown/extending-caddy/namespaces.md b/src/docs/markdown/extending-caddy/namespaces.md index cf96716..7356bc7 100644 --- a/src/docs/markdown/extending-caddy/namespaces.md +++ b/src/docs/markdown/extending-caddy/namespaces.md @@ -21,7 +21,7 @@ caddy.storage | [`caddy.StorageConverter`](https://pkg.go.dev/github.com/caddyse http.authentication.hashes | [`caddyauth.Comparer`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth?tab=doc#Comparer) | Password hashers/comparers http.authentication.providers | [`caddyauth.Authenticator`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth?tab=doc#Authenticator) | HTTP authentication providers http.handlers | [`caddyhttp.MiddlewareHandler`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#MiddlewareHandler) | HTTP handlers -http.matchers | [`caddyhttp.RequestMatcher`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#RequestMatcher) | HTTP request matchers +http.matchers | [`caddyhttp.RequestMatcher`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#RequestMatcher) | HTTP request matchers
⚠️ Subject to change http.reverse_proxy.circuit_breakers | [`reverseproxy.CircuitBreaker`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy?tab=doc#CircuitBreaker) | Reverse proxy circuit breakers http.reverse_proxy.selection_policies | [`reverseproxy.Selector`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy?tab=doc#Selector) | Load balancing selection policies
⚠️ Subject to change http.reverse_proxy.transport | [`http.RoundTripper`](https://pkg.go.dev/net/http?tab=doc#RoundTripper) | HTTP reverse proxy transports