From aea9c986d1e37c036fd26f52bd3d3508378c6766 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Fri, 28 Feb 2020 11:16:45 -0700 Subject: [PATCH] docs: Update for beta 15 --- src/docs/markdown/caddyfile/concepts.md | 2 +- src/docs/markdown/caddyfile/directives.md | 1 + src/docs/markdown/caddyfile/directives/log.md | 186 ++++++++++++++++++ .../caddyfile/directives/reverse_proxy.md | 29 ++- src/docs/markdown/caddyfile/directives/tls.md | 2 + src/docs/markdown/caddyfile/options.md | 8 +- src/docs/markdown/command-line.md | 7 +- src/docs/markdown/install.md | 4 +- 8 files changed, 226 insertions(+), 13 deletions(-) create mode 100644 src/docs/markdown/caddyfile/directives/log.md diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 3575454..7b948fd 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -163,7 +163,7 @@ By default, a directive that injects an HTTP handler applies to all requests (un **Request matchers** can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a directive applies to. -To limit a directive's scope, use a **matcher token** immediately after the directive, [if the directive supports matchers](/docs/caddyfile/directives#matchers). The matcher token can be one of these forms: +To limit a directive's scope, use a **matcher token** immediately following the directive, [if the directive supports matchers](/docs/caddyfile/directives#matchers). The matcher token can be one of these forms: 1. **`*`** to match all requests (wildcard; default). 2. **`/path`** start with a forward slash to match a request path. diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 4ccf2e5..eaad178 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -14,6 +14,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 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers +**[log](/docs/caddyfile/directives/log)** | Enables access/request logging **[php_fastcgi](/docs/caddyfile/directives/php_fastcgi)** | Serve PHP sites over FastCGI **[redir](/docs/caddyfile/directives/redir)** | Issues an HTTP redirect to the client **[request_header](/docs/caddyfile/directives/request_header)** | Manipulates request headers diff --git a/src/docs/markdown/caddyfile/directives/log.md b/src/docs/markdown/caddyfile/directives/log.md new file mode 100644 index 0000000..12c67e9 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/log.md @@ -0,0 +1,186 @@ +--- +title: log (Caddyfile directive) +--- + +# log + +Enables and configures HTTP request logging (also known as access logs). + +## Syntax + +``` +log { + output ... + format ... + level +} +``` + +- **output** configures a where to write the logs to. See [Output modules](#output-modules) below. Default: `stderr` +- **format** describes how to encode, or format, the logs. See [Format modules](#format-modules) below. Default `console` +- **level** is the minimum entry level to log. Default: `INFO` + +### Output modules + +The **output** subdirective lets you customize where logs get written. It appears within a `log` block. + +#### stderr + +Standard error (console, default). + +``` +output stderr +``` + +#### stdout + +Standard output (console). + +``` +output stderr +``` + +#### discard + +No output. + +``` +output discard +``` + +#### file + +A file. By default, log files are rotated ("rolled") to prevent disk space exhaustion. + +``` +output file { + roll_disabled + roll_size + roll_keep + roll_keep_for +} +``` + +- **<filename>** is the path to the log file. +- **roll_disabled** disables log rolling. This can lead to disk space depletion, so only use this if your log files are maintained some other way. +- **roll_size** is the size at which to roll the log file. Default: `100MiB` +- **roll_keep** is how many log files to keep before deleting the oldest ones. Default: `10` +- **roll_keep_for** is how long to keep rolled files. Default: 90 days + + +#### net + +A network socket. + +``` +output net
+``` + +- **<address>** is the [address](/docs/conventions#network-addresses) to write logs to. + + + +### Format modules + +The **format** subdirective lets you customize how logs get encoded (formatted). It appears within a `log` block. + +In addition to the syntax for each individual encoder, these common properties can be set on most encoders: + +``` +{ + message_key + level_key + time_key + name_key + caller_key + stacktrace_key + line_ending + time_format + level_format +} +``` + +- **message_key** The key for the message field of the log entry. Default: `message` +- **level_key** The key for the level field of the log entry. Default: `level` +- **time_key** The key for the time field of the log entry. Default: `time` +- **name_key** The key for the name field of the log entry (i.e. the name of the logger itself). Default: `name` +- **caller_key** The key for the caller field of the log entry. +- **stacktrace_key** The key for the stacktrace field of the log entry. +- **line_ending** The line endings to use. +- **time_format** The format for timestamps. +- **level_format** The format for levels. + +#### console + +The console encoder formats the log entry for human readability while preserving some structure. + +``` +output console +``` + +#### json + +Formats each log entry as a JSON object. + +``` +output json +``` + +#### logfmt + +Formats each log entry as [logfmt](https://brandur.org/logfmt). + +``` +output 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. + +``` +output single_field +``` + +- **<field_name>** is the name of the field whose value to use as the log entry. + + + + + + + +## Examples + +Enable access logging (to the console): + +``` +log +``` + +Write logs to a file (with log rolling, which is enabled by default): + +``` +log { + output file /var/log/access.log +} +``` + +Customize log rolling: + +``` +log { + output file /var/log/access.log { + roll_size 1gb + roll_keep 5 + } +} +``` + +Use common log format (deprecated, but can be useful for older setups): + +``` +log { + format single_field common_log +} +``` diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 19b1b60..16e583e 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -52,6 +52,17 @@ reverse_proxy [] [] { - **<upstreams...>** is a list of upstreams (backends) to which to proxy. - **to** is an alternate way to specify the list of upstreams, one (or more) per line. +Upstream addresses can take the form of a conventional [Caddy network address](/docs/conventions#network-addresses) or a URL that contains only scheme and host/port. Valid examples: + +- `localhost:4000` +- `127.0.0.1:4000` +- `http://localhost:4000` +- `https://example.com` +- `example.com` +- `unix//var/php.sock` + +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. + **Load balancing** is used whenever more than one upstream is defined. - **lb_policy** is the name of the load balancing policy, along with any options. Default: `random`. Can be: @@ -93,6 +104,8 @@ It can also **manipulate headers** between itself and the backend: - **header_up** Sets, adds, removes, or performs a replacement in a request header going upstream to the backend. - **header_down** Sets, adds, removes, or performs a replacement in a response header coming downstream from the backend. +By default, Caddy passes thru incoming headers to the backend—including the `Host` header—without modifications, with one exception: it adds or augments the [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) header field as is standard for well-mannered proxies. + Caddy's proxy **transport** is pluggable: - **transport** defines how to communicate with the backend. Default is `http`. @@ -119,7 +132,7 @@ The `http_ntlm` transport is identical to the `http` transport, but the HTTP ver - **read_buffer** is the size of the read buffer in bytes. - **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. +- **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_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. @@ -164,13 +177,17 @@ reverse_proxy /api/* node1:80 node2:80 node3:80 { } ``` -Preserve original request Host and add common proxying headers: +Set the upstream Host header to the address of the upstream (by default, it will retain its original, incoming value): ``` reverse_proxy localhost:9000 { - header_up Host {host} - header_up X-Real-IP {remote_host} - header_up X-Forwarded-For {remote_host} - header_up X-Forwarded-Proto {scheme} + header_up Host {http.reverse_proxy.upstream.hostport} } ``` + +Reverse proxy to an HTTPS endpoint: + +``` +reverse_proxy https://example.com +``` + diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index e0db1a9..680a143 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -21,6 +21,7 @@ tls |[ ] { alpn load ca + ca_root } ``` @@ -55,6 +56,7 @@ tls |[ ] { - **alpn** is the list of values to advertise in the ALPN extension of the TLS handshake. - **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. diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 98ed50d..2c7bbd2 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -28,8 +28,10 @@ Possible options are: } experimental_http3 acme_ca + acme_ca_root email - admin + admin off| + debug } ``` @@ -39,5 +41,7 @@ Possible options are: - **storage** configures Caddy's storage mechanism. Default: `file_system` - **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._ - **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. +- **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). diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 0b67d5d..6bf8b40 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -200,7 +200,8 @@ Gives the running Caddy instance a new configuration. This has the same effect a 
caddy reverse-proxy
 	--from <addr>
-	--to <addr>
+ --to <addr> + --change-host-header Spins up a simple but production-ready reverse proxy. @@ -208,7 +209,9 @@ Spins up a simple but production-ready reverse proxy. `--to` is the address to proxy to. -Both from and to parameters can be URLs, as scheme, domain name, and URI rewrite information will be inferred from the provided URL. Or they can be a simple network address and not a complete URL. +`--change-host-header` will cause Caddy to change the Host header from the incoming value to the address of the upstream. + +Both `--from` and `--to` parameters can be URLs, as scheme, domain name, and URI rewrite information will be inferred from the provided URL (paths and query strings ignored). Or they can be a simple network address and not a complete URL. This command disables the admin API, making it easier to run multiple instances on a local development machine. diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md index 438e1bf..969b431 100644 --- a/src/docs/markdown/install.md +++ b/src/docs/markdown/install.md @@ -49,7 +49,7 @@ Create a user named `caddy`, with a writeable home folder: Next, take [this systemd unit file](https://github.com/caddyserver/dist/blob/master/init/caddy.service) and save it to `/etc/systemd/system/caddy.service`. Double-check the **ExecStart** and **ExecReload** directives---make sure the binary's location and command line arguments are correct for your installation. -Double-check that both your systemd and Caddy configs are correct before continuing. +Double-check that both your systemd and Caddy configs are correct before continuing. Make sure your config file is in the location specified in the command. To start the service for the first time, do the usual systemctl dance: @@ -73,7 +73,7 @@ You can stop the service with: Requirements: -- [Go](https://golang.org/dl) 1.13 or newer +- [Go](https://golang.org/dl) 1.14 or newer - [Go modules](https://github.com/golang/go/wiki/Modules) enabled Download the `v2` branch source code: