Skip to main content
The HTTP Server module is the foundation of Caddy’s HTTP functionality. It describes the configuration for individual HTTP servers, including listeners, protocols, routing, TLS settings, and various server-level behaviors.

​
Module ID

http.servers.<name> Each server is defined by a unique name in the configuration.

​
Server Configuration

​
Listen Addresses

​
listen
array of strings
Socket addresses to bind listeners to. Accepts network addresses that may include port ranges. Listener addresses must be unique across all defined servers.
"listen": [":443", ":80"]

​
Protocol Settings

​
protocols
array of strings
default:"[h1, h2, h3]"
Specifies which HTTP protocols to enable. Supported values:
  • h1 - HTTP/1.1
  • h2 - HTTP/2 over TLS
  • h2c - Cleartext HTTP/2
  • h3 - HTTP/3 over QUIC
If enabling h2 or h2c, h1 must also be enabled due to Go standard library limitations.
HTTP/2 operates only over TLS (HTTPS). HTTP/3 opens a UDP socket to serve QUIC connections.
​
listen_protocols
array of arrays
Overrides protocols for each parallel address in listen. A nil value or element indicates that protocols will be used instead.

​
Timeouts

​
read_timeout
duration
How long to allow a read from a client’s upload. Setting this to a short, non-zero value can mitigate slowloris attacks, but may affect legitimately slow clients.
​
read_header_timeout
duration
default:"1 minute"
Like read_timeout but specifically for request headers.
​
write_timeout
duration
How long to allow a write to a client. Setting this to a small value when serving large files may negatively affect legitimately slow clients.
​
idle_timeout
duration
default:"5 minutes"
Maximum time to wait for the next request when keep-alives are enabled. If zero, a default timeout of 5m is applied to help avoid resource exhaustion.

​
TCP Keep-Alive

​
keepalive_interval
duration
default:"15 seconds"
Interval at which TCP keepalive packets are sent to keep the connection alive at the TCP layer when no other data is being transmitted. If negative, keepalive packets are not sent.
​
keepalive_idle
duration
default:"15 seconds"
Time that the connection must be idle before the first TCP keep-alive probe is sent when no other data is being transmitted. If negative, underlying socket value is unchanged.
​
keepalive_count
integer
default:"9"
Maximum number of TCP keep-alive probes that should be sent before dropping a connection. If negative, underlying socket value is unchanged.

​
Request Limits

​
max_header_bytes
integer
Maximum size to parse from a client’s HTTP request headers.
​
enable_full_duplex
boolean
default:"false"
Enable full-duplex communication for HTTP/1 requests. Only has an effect if Caddy was built with Go 1.21 or later.
This is an EXPERIMENTAL feature and subject to change. Test thoroughly with your HTTP clients, as some older clients may not support full-duplex HTTP/1 which can cause them to deadlock.

​
Routes and Handlers

​
routes
array
Describes how this server will handle requests. Routes are executed sequentially. Each route’s matchers are evaluated first, then its grouping. If it matches and has not been mutually-excluded by its grouping, its handlers are executed sequentially.By default, all unrouted requests receive a 200 OK response to indicate the server is working.
​
named_routes
object
Mapping of reusable routes that can be invoked by their name. This optimizes memory usage when the same route is needed for many subroutes, by having handlers and matchers provisioned once but used from many places.
EXPERIMENTAL: Subject to change or removal.
​
errors
object
How this server will handle errors returned from any of the handlers in the primary routes. If the primary handler chain returns an error, the error along with its recommended status code are bubbled back to the HTTP server which executes a separate error route.

​
TLS Configuration

​
tls_connection_policies
array
How to handle TLS connections. At least one policy is required to enable HTTPS on this server if automatic HTTPS is disabled or does not apply.
​
automatic_https
object
Configures or disables automatic HTTPS within this server. HTTPS is enabled automatically and by default when qualifying names are present in a Host matcher and/or when the server is listening only on the HTTPS port.
​
strict_sni_host
boolean
If true, requires that a request’s Host header match the value of the ServerName sent by the client’s TLS ClientHello. Often a necessary safeguard when using TLS client authentication.

​
Trusted Proxies

​
trusted_proxies
module
A module which provides a source of IP ranges from which requests should be trusted. By default, no proxies are trusted.This can be used as a default set of ranges for handlers or matchers in routes to pick up, instead of needing to configure each of them. For example, the reverse_proxy handler uses this to trust sensitive incoming X-Forwarded-* headers.Module namespace: http.ip_sources
​
client_ip_headers
array of strings
default:"['X-Forwarded-For']"
Headers from which the client IP address could be read from. These will be considered in order, with the first good value being used as the client IP.This depends on trusted_proxies being configured and the request being validated as coming from a trusted proxy.
​
trusted_proxies_strict
integer
default:"0"
If greater than zero, enables strict ClientIPHeaders parsing. The headers will be parsed from right to left, and the first value that is both valid and doesn’t match the trusted proxy list will be used as client IP.If zero, the headers will be parsed from left to right, and the first value that is a valid IP address will be used.
​
trusted_proxies_unix
boolean
default:"false"
If true, enables trusting socket connections (e.g. Unix domain sockets) as coming from a trusted proxy.

​
Logging

​
logs
object
Enables access logging and configures how access logs are handled in this server. To minimally enable access logs, simply set this to a non-null, empty struct.

​
Advanced Settings

​
listener_wrappers
array
List of listener wrapper modules, which can modify the behavior of the base listener. They are applied in the given order.Module namespace: caddy.listeners
​
packet_conn_wrappers
array
List of packet conn wrapper modules, which can modify the behavior of the base packet conn. They are applied in the given order.Module namespace: caddy.packetconns
​
allow_0rtt
boolean
If set, overrides whether QUIC listeners allow 0-RTT (early data). If nil, the default behavior is used (currently allowed).
One reason to disable 0-RTT is if a remote IP matcher is used, which introduces a dependency on the remote address being verified if routing happens before the TLS handshake completes.

​
Configuration Example

{
  "apps": {
    "http": {
      "servers": {
        "example": {
          "listen": [":443"],
          "protocols": ["h1", "h2", "h3"],
          "routes": [
            {
              "match": [{"host": ["example.com"]}],
              "handle": [{"handler": "file_server"}]
            }
          ],
          "idle_timeout": "5m",
          "read_header_timeout": "30s"
        }
      }
    }
  }
}

​
Context Values

The server sets the following context values on requests:
  • ServerCtxKey - Reference to the server instance
  • VarsCtxKey - Request’s variable table
  • OriginalRequestCtxKey - Partial copy of the unmodified request

​
Methods

​
ServeHTTP

The entry point for all HTTP requests. This method:
  1. Enables full-duplex for HTTP/1 if configured
  2. Sets the Server header
  3. Advertises HTTP/3 if enabled
  4. Prepares the request with a replacer and context
  5. Handles ACME HTTP challenges
  6. Executes the primary handler chain
  7. Invokes error handler chain if needed

​
PrepareRequest

Fills the request for use in a Caddy HTTP handler chain. Sets up:
  • Replacer context
  • Server reference
  • Trusted proxy detection
  • Client IP determination
  • Request variables
  • Original request copy
The server enforces strict host matching when strict_sni_host is enabled, ensuring the TLS ServerName matches the Host header.

Build docs developers (and LLMs) love

Get started for freeTalk to us