diff --git a/src/docs/markdown/caddyfile/directives/bind.md b/src/docs/markdown/caddyfile/directives/bind.md index 151ed051..e2e49f3e 100644 --- a/src/docs/markdown/caddyfile/directives/bind.md +++ b/src/docs/markdown/caddyfile/directives/bind.md @@ -16,10 +16,13 @@ Note that binding sites inconsistently may result in unintended consequences. Fo ## Syntax ```caddy-d -bind +bind { + protocols +} ``` - **<hosts...>** is the list of host interfaces to bind which to bind the listener. +- **<protocols...>** is an optional override of the HTTP protocols to enable for the listener, see the [server options](/docs/caddyfile/options#protocols) for its accepted values and their meanings. ## Examples @@ -64,6 +67,39 @@ example.com { } ``` +To bind to a Unix domain socket at `/run/caddy/stream.sock` that serves h1 and h2, and another at `/run/caddy/dgram.sock` that serves h3: + +```caddy +example.com { + bind unix//run/caddy/stream.sock { + protocols h1 h2 + } + bind unixgram//run/caddy/dgram.sock { + protocols h3 + } +} +``` + +To bind to inherited file descriptors specified with [environment placeholders](/docs/conventions#placeholders): + +```caddy +http://example.com { + bind fd/{env.CADDY_HTTP_FD} { + protocols h1 + } + redir https://example.com{uri} permanent +} + +https://example.com { + bind fd/{env.CADDY_HTTPS_FD} { + protocols h1 h2 + } + bind fdgram/{env.CADDY_HTTP3_FD} { + protocols h3 + } +} +``` + To bind one domain to two different interfaces, with different responses: ```caddy diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index f57fb37d..75693c33 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -56,7 +56,9 @@ Possible options are (click on each option to jump to its documentation): debug http_port https_port - default_bind + default_bind { + protocols + } order first|last|[before|after ] storage { @@ -192,7 +194,7 @@ Default: `443` ##### `default_bind` -The default bind address(es) to be used for all sites, if the [`bind` directive](/docs/caddyfile/directives/bind) is not used in the site. Default: empty, which binds to all interfaces. +The default bind address(es) and optional HTTP protocol(s) (`h1|h2|h2c|h3`) to serve with them for all sites, if the [`bind` directive](/docs/caddyfile/directives/bind) is not used in the site. If multiple `default_bind` directives are present, each will be applied to servers with no `bind` directive in the order they were given. Default: empty, which binds to all interfaces, and serves the default protocols (`h1 h2 h3`) on them. +For example, to bind to `10.0.0.1` when no other address(es) are specified: + ```caddy { default_bind 10.0.0.1 } ``` +To disable HTTP/3 unless otherwise specified: + +```caddy +{ + default_bind { + protocols h1 h2 + } +} +``` +To create default listeners from file descriptors `3` and `4`: + +```caddy +{ + default_bind fd/3 { + protocols h1 h2 + } + default_bind fdgram/4 { + protocols h3 + } +} +``` ##### `order` Assigns an order to HTTP handler directive(s). As HTTP handlers execute in a sequential chain, it is necessary for the handlers to be executed in the right order. Standard directives have [a pre-defined order](/docs/caddyfile/directives#directive-order), but if using third-party HTTP handler modules, you'll need to define the order explicitly by either using this option or placing the directive in a [`route` block](/docs/caddyfile/directives/route). Ordering can be described absolutely (`first` or `last`), or relatively (`before` or `after`) to another directive. diff --git a/src/docs/markdown/conventions.md b/src/docs/markdown/conventions.md index 4ddef28d..9f880d53 100644 --- a/src/docs/markdown/conventions.md +++ b/src/docs/markdown/conventions.md @@ -32,6 +32,7 @@ The network can be any of the following; ones suffixed with `4` or `6` are IPv4 - UDP: `udp`, `udp4`, `udp6` - IP: `ip`, `ip4`, `ip6` - Unix: `unix`, `unixgram`, `unixpacket` +- File descriptors: `fd`, `fdgram` The address part may be any of these forms: @@ -42,10 +43,12 @@ The address part may be any of these forms: - `/path/to/unix/socket` - `/path/to/unix/socket|0200` -The host may be any hostname, resolvable domain name, or IP address. +The host may be any hostname, resolvable domain name, IP address, or file descriptor number. In the case of IPv6 addresses, the address must be enclosed in square brackets `[]`. The zone identifier (starting with `%`) is optional (often used for link-local addresses). +In the case of file descriptors, the host must be an unsigned [integer literal](https://go.dev/ref/spec#Integer_literals). + The port may be a single value (`:8080`) or an inclusive range (`:8080-8085`). A port range will be multiplied into singular addresses. Not all config fields accept port ranges. The special port `:0` means any available port. A unix socket path is only acceptable when using a `unix*` network type. The forward slash that separates the network and address is not considered part of the path.