mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-24 14:06:17 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Big Caddyfile docs update (#374)

Browse source
This commit is contained in:
Francis Lavoie 2024-02-20 06:49:30 -05:00 • committed by GitHub
parent 3ec3033602
commit 22301d6a81
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 1732 additions and 512 deletions
Download patch file Download diff file Expand all files Collapse all files

253
src/docs/markdown/caddyfile/directives/log.md
View file

@ -4,6 +4,16 @@ title: log (Caddyfile directive)
<script>
window.$(function() {
// Fix > in code blocks
window.$('pre.chroma .k:contains(">")')
.each(function() {
const e = window.$(this);
// Skip if ends with >
if (e.text().trim().endsWith('>')) return;
// Replace > with <span class="p">&gt;</span>
e.html(e.html().replace(/&gt;/g, '<span class="p">&gt;</span>'));
});
// We'll add links to all the subdirectives if a matching anchor tag is found on the page.
addLinksToSubdirectives();
});
@ -15,14 +25,14 @@ Enables and configures HTTP request logging (also known as access logs).
<aside class="tip">
If you're looking to configure Caddy's runtime logs, you're looking for the [`log` global option](/docs/caddyfile/options#log) instead.
To configure Caddy's runtime logs, see the [`log` global option](/docs/caddyfile/options#log) instead.
</aside>
The `log` directive applies to the host/port of the site block it appears in, not any other part of the site address (e.g. path).
The `log` directive applies to the hostnames of the site block it appears in, unless overridden with the `hostnames` subdirective.
When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`skip_log` directive](/docs/caddyfile/directives/skip_log).
When configured, by default all requests to the site will be logged. To conditionally skip some requests from logging, use the [`skip_log` directive](skip_log).
- [Syntax](#syntax)
@ -60,25 +70,35 @@ log [<logger_name>] {
}
```
- **logger_name** is an optional override of the logger name for this site. By default, a logger name is generated automatically, e.g. `log0`, `log1`, and so on depending on the order of the sites in the Caddyfile. This is only useful if you wish to reliably refer to the output of this logger from another logger defined in global options. See [an example](#multiple-outputs) below.
- **logger_name** is an optional override of the logger name for this site.
- **hostnames** overrides the hostnames that this logger applies to. By default, the logger applies to the hostnames of the site block it appears in, i.e. the site addresses. This is useful if you wish to define different loggers per subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates). See [an example](#wildcard-logs) below.
By default, a logger name is generated automatically, e.g. `log0`, `log1`, and so on depending on the order of the sites in the Caddyfile. This is only useful if you wish to reliably refer to the output of this logger from another logger defined in global options. See [an example](#multiple-outputs) below.
- **output** configures where to write the logs. See [Output modules](#output-modules) below. Default: `stderr`.
- **hostnames** is an optional override of the hostnames that this logger applies to.
- **format** describes how to encode, or format, the logs. See [Format modules](#format-modules) below. Default: `console` if `stderr` is detected to be a terminal, `json` otherwise.
By default, the logger applies to the hostnames of the site block it appears in, i.e. the site addresses. This is useful if you wish to define different loggers per subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates). See [an example](#wildcard-logs) below.
- **level** is the minimum entry level to log. Default: `INFO`. Note that access logs currently only emit `INFO` and `ERROR` level logs.
- **output** configures where to write the logs. 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` if `stderr` is detected to be a terminal, `json` otherwise.
- **level** is the minimum entry level to log. Default: `INFO`.
Note that access logs currently only emit `INFO` and `ERROR` level logs.
### Output modules
The **output** subdirective lets you customize where logs get written. It appears within a `log` block.
The **output** subdirective lets you customize where logs get written.
#### stderr
Standard error (console, default).
Standard error (console, is the default).
```caddy-d
output stderr
@ -104,6 +124,8 @@ output discard
A file. By default, log files are rotated ("rolled") to prevent disk space exhaustion.
Log rolling is provided by [lumberjack <img src="/old/resources/images/external-link.svg" class="external-link">](https://github.com/natefinch/lumberjack)
```caddy-d
output file <filename> {
roll_disabled
@ -116,11 +138,25 @@ output file <filename> {
```
- **&lt;filename&gt;** 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. The current implementation supports megabyte resolution; fractional values are rounded up to the next whole megabyte. For example, `1.1MiB` is rounded up to `2MiB`. Default: `100MiB`
- **roll_uncompressed** turns off gzip log compression. Default: gzip compression is enabled.
- **roll_local_time** sets the rolling to use local timestamps in filenames. Default: uses UTC time.
- **roll_keep** is how many log files to keep before deleting the oldest ones. Default: `10`
- **roll_size** is the size at which to roll the log file. The current implementation supports megabyte resolution; fractional values are rounded up to the next whole megabyte. For example, `1.1MiB` is rounded up to `2MiB`.
Default: `100MiB`
- **roll_uncompressed** turns off gzip log compression.
Default: gzip compression is enabled.
- **roll_local_time** sets the rolling to use local timestamps in filenames.
Default: uses UTC time.
- **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 as a [duration string](/docs/conventions#durations). The current implementation supports day resolution; fractional values are rounded up to the next whole day. For example, `36h` (1.5 days) is rounded up to `48h` (2 days). Default: `2160h` (90 days)
@ -136,7 +172,9 @@ output net <address> {
```
- **&lt;address&gt;** is the [address](/docs/conventions#network-addresses) to write logs to.
- **dial_timeout** is how long to wait for a successful connection to the log socket. Log emissions may be blocked for up to this long if the socket goes down.
- **soft_start** will ignore errors when connecting to the socket, allowing you to load your config even if the remote log service is down. Logs will be emitted to stderr instead.
@ -171,33 +209,57 @@ format <encoder_module> {
```
- **message_key** The key for the message field of the log entry. Default: `msg`
- **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: `ts`
- **name_key** The key for the name field of the log entry (i.e. the name of the logger itself). Default: `name`
- **name_key** The key for the name field of the log entry. 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. May be one of:
- **unix_seconds_float** Floating-point number of seconds since the Unix epoch; this is the default.
- **unix_milli_float** Floating-point number of milliseconds since the Unix epoch.
- **unix_nano** Integer number of nanoseconds since the Unix epoch.
- **iso8601** Example: `2006-01-02T15:04:05.000Z0700`
- **rfc3339** Example: `2006-01-02T15:04:05Z07:00`
- **rfc3339_nano** Example: `2006-01-02T15:04:05.999999999Z07:00`
- **wall** Example: `2006/01/02 15:04:05`
- **wall_milli** Example: `2006/01/02 15:04:05.000`
- **wall_nano** Example: `2006/01/02 15:04:05.000000000`
- **common_log** Example: `02/Jan/2006:15:04:05 -0700`
- **time_format** The format for timestamps.
Default: `wall_milli` if the format defaulted to `console`, `unix_seconds_float` otherwise.
May be one of:
- `unix_seconds_float` Floating-point number of seconds since the Unix epoch.
- `unix_milli_float` Floating-point number of milliseconds since the Unix epoch.
- `unix_nano` Integer number of nanoseconds since the Unix epoch.
- `iso8601` Example: `2006-01-02T15:04:05.000Z0700`
- `rfc3339` Example: `2006-01-02T15:04:05Z07:00`
- `rfc3339_nano` Example: `2006-01-02T15:04:05.999999999Z07:00`
- `wall` Example: `2006/01/02 15:04:05`
- `wall_milli` Example: `2006/01/02 15:04:05.000`
- `wall_nano` Example: `2006/01/02 15:04:05.000000000`
- `common_log` Example: `02/Jan/2006:15:04:05 -0700`
- Or, any compatible time layout string; see the [Go documentation](https://pkg.go.dev/time#pkg-constants) for full details.
Note that the parts of the format string are special constants for the layout; so `2006` is the year, `01` is the month, `Jan` is the month as a string, `02` is the day. Do not use the actual current date numbers in the format string.
- **time_local** Logs with the local system time rather than the default of UTC time.
- **duration_format** The format for durations. May be one of:
- **seconds** Floating-point number of seconds elapsed; this is the default.
- **nano** Integer number of nanoseconds elapsed.
- **string** Using Go's built-in string format, for example `1m32.05s` or `6.31ms`.
- **level_format** The format for levels. May be one of:
- **lower** Lowercase; this is the default.
- **upper** Uppercase.
- **color** Uppercase, with console colors.
- **duration_format** The format for durations.
Default: `seconds`.
May be one of:
- `seconds` Floating-point number of seconds elapsed.
- `nano` Integer number of nanoseconds elapsed.
- `string` Using Go's built-in string format, for example `1m32.05s` or `6.31ms`.
- **level_format** The format for levels.
Default: `color` if the format defaulted to `console`, `lower` otherwise.
May be one of:
- `lower` Lowercase.
- `upper` Uppercase.
- `color` Uppercase, with ANSI colors.
#### console
@ -244,6 +306,7 @@ Marks a field to be skipped from being encoded.
<field> delete
```
##### rename
Rename the key of a log field.
@ -252,6 +315,7 @@ Rename the key of a log field.
<field> rename <key>
```
##### replace
Marks a field to be replaced with the provided string at encoding time.
@ -260,13 +324,17 @@ Marks a field to be replaced with the provided string at encoding time.
<field> replace <replacement>
```
##### ip_mask
Masks IP addresses in the field using a CIDR mask, i.e. the number of bits from the IP to retain, starting from the left side. If the field is an array of strings (e.g. HTTP headers), each value in the array is masked. The value may be a comma separated string of IP addresses.
There is separate configuration for IPv4 and IPv6 addresses, since they have a different total number of bits.
Most commonly, the fields to filter would be `request>remote_ip` for the directly connecting client, `request>client_ip` for the parsed "real client" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured, or `request>headers>X-Forwarded-For` if behind a reverse proxy.
Most commonly, the fields to filter would be:
- `request>remote_ip` for the directly connecting client
- `request>client_ip` for the parsed "real client" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured
- `request>headers>X-Forwarded-For` if behind a reverse proxy
```caddy-d
<field> ip_mask {
@ -275,9 +343,10 @@ Most commonly, the fields to filter would be `request>remote_ip` for the directl
}
```
##### query
Marks a field to have one or more actions performed, to manipulate the query part of a URL field. Most commonly, the field to filter would be `request>uri`. The available actions are:
Marks a field to have one or more actions performed, to manipulate the query part of a URL field. Most commonly, the field to filter would be `request>uri`.
```caddy-d
<field> query {
@ -287,13 +356,18 @@ Marks a field to have one or more actions performed, to manipulate the query par
}
```
The available actions are:
- **delete** removes the given key from the query.
- **replace** replaces the value of the given query key with **replacement**. Useful to insert a redaction placeholder; you'll see that the query key was in the URL, but the value is hidden.
- **hash** replaces the value of the given query key with the first 4 bytes of the SHA-256 hash of the value, lowercase hexadecimal. Useful to obscure the value if it's sensitive, while being able to notice whether each request had a different value.
##### cookie
Marks a field to have one or more actions performed, to manipulate a `Cookie` HTTP header's value. Most commonly, the field to filter would be `request>headers>Cookie`. The available actions are:
Marks a field to have one or more actions performed, to manipulate a `Cookie` HTTP header's value. Most commonly, the field to filter would be `request>headers>Cookie`.
```caddy-d
<field> cookie {
@ -303,12 +377,17 @@ Marks a field to have one or more actions performed, to manipulate a `Cookie` HT
}
```
The available actions are:
- **delete** removes the given cookie by name from the header.
- **replace** replaces the value of the given cookie with **replacement**. Useful to insert a redaction placeholder; you'll see that the cookie was in the header, but the value is hidden.
- **hash** replaces the value of the given cookie with the first 4 bytes of the SHA-256 hash of the value, lowercase hexadecimal. Useful to obscure the value if it's sensitive, while being able to notice whether each request had a different value.
If many actions are defined for the same cookie name, only the first action will be applied.
##### regexp
Marks a field to have a regular expression replacement applied at encoding time. If the field is an array of strings (e.g. HTTP headers), each value in the array has replacements applied.
@ -321,6 +400,7 @@ The regular expression language used is RE2, included in Go. See the [RE2 syntax
In the replacement string, capture groups can be referenced with `${group}` where `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.
##### hash
Marks a field to be replaced with the first 4 bytes (8 hex characters) of the SHA-256 hash of the value at encoding time. If the field is a string array (e.g. HTTP headers), each value in the array is hashed.
@ -337,30 +417,36 @@ Useful to obscure the value if it's sensitive, while being able to notice whethe
Enable access logging to the default logger.
In other words, by default this logs to the console or stderr, but this can be changed by reconfiguring the default logger with the [`log` global option](/docs/caddyfile/options#log):
In other words, by default this logs to `stderr`, but this can be changed by reconfiguring the `default` logger with the [`log` global option](/docs/caddyfile/options#log):
```caddy-d
log
```caddy
example.com {
log
}
```
Write logs to a file (with log rolling, which is enabled by default):
```caddy-d
log {
output file /var/log/access.log
```caddy
example.com {
log {
output file /var/log/access.log
}
}
```
Customize log rolling:
```caddy-d
log {
output file /var/log/access.log {
roll_size 1gb
roll_keep 5
roll_keep_for 720h
```caddy
example.com {
log {
output file /var/log/access.log {
roll_size 1gb
roll_keep 5
roll_keep_for 720h
}
}
}
```
@ -368,12 +454,14 @@ log {
Delete the `User-Agent` request header from the logs:
```caddy-d
log {
format filter {
wrap console
fields {
request>headers>User-Agent delete
```caddy
example.com {
log {
format filter {
wrap console
fields {
request>headers>User-Agent delete
}
}
}
}
@ -382,14 +470,16 @@ log {
Redact multiple sensitive cookies. (Note that some sensitive headers are logged with empty values by default; see the [`log_credentials` global option](/docs/caddyfile/options#log-credentials) to enable logging `Cookie` header values):
```caddy-d
log {
format filter {
wrap console
fields {
request>headers>Cookie cookie {
replace session REDACTED
delete secret
```caddy
example.com {
log {
format filter {
wrap console
fields {
request>headers>Cookie cookie {
replace session REDACTED
delete secret
}
}
}
}
@ -401,14 +491,16 @@ Mask the remote address from the request, keeping the first 16 bits (i.e. 255.25
Note that as of Caddy v2.7, both `remote_ip` and `client_ip` are logged, where `client_ip` is the "real IP" when [`trusted_proxies`](/docs/caddyfile/options#trusted-proxies) is configured:
```caddy-d
log {
format filter {
wrap console
fields {
request>remote_ip ip_mask {
ipv4 16
ipv6 32
```caddy
example.com {
log {
format filter {
wrap console
fields {
request>remote_ip ip_mask {
ipv4 16
ipv6 32
}
}
}
}
@ -416,23 +508,24 @@ log {
```
<span id="wildcard-logs" /> To write separate log files for each subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates), by overriding `hostnames` for each logger:
<span id="wildcard-logs" /> To write separate log files for each subdomain in a [wildcard site block](/docs/caddyfile/patterns#wildcard-certificates), by overriding `hostnames` for each logger. This uses a [snippet](/docs/caddyfile/concepts#snippets) to avoid repetition:
```caddy
*.example.com {
(subdomain-log) {
log {
hostnames foo.example.com
output file /var/log/foo.example.com.log
hostnames {args[0]}
output file /var/log/{args[0]}.log
}
@foo host foo.example.com
}
*.example.com {
import subdomain-log foo.example.com
@foo host foo.example.com
handle @foo {
respond "foo"
}
log {
hostnames bar.example.com
output file /var/log/bar.example.com.log
}
import subdomain-log bar.example.com
@bar host bar.example.com
handle @bar {
respond "bar"