Global options

The Caddyfile has a way for you to specify options that apply globally. Some options act as default values; others customize HTTP servers and don't apply to just one particular site; while yet others customize the behavior of the Caddyfile adapter .

The very top of your Caddyfile can be a global options block . This is a block that has no keys:

There can only be one at most, and it must be the first block of the Caddyfile.

Possible options are (click on each option to jump to its documentation):

http_port

The port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: 80

https_port

The port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: 443

default_bind

The default bind address(es) to be used for all sites, if the bind directive is not used in the site. Default: empty, which binds to all interfaces.

Keep in mind that this will only apply to servers which are generated by the Caddyfile; this means that the HTTP server created by Automatic HTTPS for HTTP->HTTPS redirects will not inherit these bind addresses. To work around this, make sure to declare an http:// site (it can be empty, with no directives) so that it exists when the Caddyfile is adapted, to receive the bind addresses.

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 , 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 . Ordering can be described absolutely ( first or last ), or relatively ( before or after ) to another directive.

For example, to use the replace-response plugin , you'd want to make sure its directive is ordered after encode so that it can perform replacements before the response is encoded (because responses flow up the handler chain, not down):

order replace after encode

storage

Configures Caddy's storage mechanism. The default is file_system . There are many other available storage modules provided as plugins.

For example, to change the file system's storage location:

storage file_system /path/to/custom/location

Customizing the storage module is typically needed when syncing Caddy's storage across multiple instances of Caddy to make sure they all use the same certificates and keys. See the Automatic HTTPS section on storage for more details.

storage_clean_interval

How often to scan storage units for old or expired assets and remove them. These scans exert lots of reads (and list operations) on the storage module, so choose a longer interval for large deployments. The value is a duration value . Default: 24h .

Storage will always be cleaned when the process first starts. Then, a new cleaning will be started this duration after the previous cleaning started if the previous cleaning finished in less than half the time of this interval (otherwise next start will be skipped).

renew_interval

How often to scan all loaded, managed certificates for expiration, and trigger renewal if expired. Default: 10m .

ocsp_interval

How often to check if OCSP staples need updating. Default: 1h .

admin

Customizes the admin API endpoint . Accepts placeholders. If off , then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. Remember to use the --address CLI flag to specify the current admin endpoint when changing this value if the currently-running admin endpoint is not at the default address.

origins configures the list of remotes/origins that are allowed to connect to the endpoint.

enforce_origin enables enforcement of the Origin header. (This is different from enforcing origins generally, which is always done.)

persist_config

Controls whether the current JSON config should be persisted to the configuration directory , to avoid losing config changes performed via the admin API. Currently, only the off option is supported. By default, the config is persisted.

Configures named loggers. The name can be passed to indicate a specific logger for which to customize the behavior. If no name is specified, the behavior of the default logger is modified. Multiple loggers with different names can be configured by using the log multiple times. You can read more about the default logger and an explanation of how logging works in Caddy .

The differs from the log directive , which only configures HTTP request logging (also known as access logs). The log global option shares its configuration structure with the directive (except for include and exclude ), and complete documentation can be found on the directive's page.

The logger names that include and exclude accept depend on the modules used, and easiest way to discover them is from prior logs.

Here is an example logging as json all http access logs and admin logs to stdout:

log default {
	output stdout
	format json
	include http.log.access admin.api

grace_period

Defines the grace period for shutting down HTTP servers (i.e. during config changes or when Caddy is stopping). During the grace period, no new connections are accepted, idle connections are closed, and active connections are impatiently waited upon to finish their requests. If clients do not finish their requests within the grace period, the server will be forcefully terminated to allow the reload to complete and free up resources. Accepts duration values . By default, the grace period is eternal, which means connections are never forcefully closed.

shutdown_delay

Defines a duration before the grace period during which a server that is going to be stopped continues to operate normally, except the {http.shutting_down} placeholder evaluates to true and {http.time_until_shutdown} gives the time until the grace period begins. This causes a delay if any server is being shut down as part of a config change and effectively schedules the change for a later time. It is useful for announcing to health checkers of this server's impending doom and to give time for a load balancer to move it out of the rotation; for example:

handle /health-check {
	@goingDown vars {http.shutting_down} true
	respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
	respond 200

TLS Options

auto_https

Configure automatic HTTPS. There are a few modes to choose from:

See the Automatic HTTPS page for more details.

email

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.

Keep in mind that Let's Encrypt may send you emails about your certificate nearing expiry, but this may be misleading because Caddy may have chosen to use a different issuer (e.g. ZeroSSL) when renewing. Check your logs and/or the certificate itself (in your browser for example) to see which issuer was used, and that its expiry is still valid; if so, you may safely ignore the email from Let's Encrypt.

default_sni

Sets a default TLS ServerName for when clients do not use SNI in their ClientHello.

fallback_sni

If configured, the fallback becomes the TLS ServerName in the ClientHello if the original ServerName doesn't match any certificates in the cache. The uses for this are very niche; typically if a client is a CDN and passes through the ServerName of the downstream handshake but can accept a certificate with the origin's hostname instead, then you would set this as your origin's hostname. Note that Caddy must be managing a certificate for this name. ⚠️ Experimental

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.

skip_install_trust

Skips the attempts to install the local CA's root into the system trust store, as well as into Java and Mozilla Firefox trust stores.

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 for testing or development. Default: ZeroSSL and Let's Encrypt's production endpoints.

Note that a globally-configured ACME CA may not apply to all sites; see the hostname requirements for using the default ACME issuer(s).

acme_ca_root

Specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.

acme_eab

Specifies an External Account Binding to use for all ACME transactions.

acme_dns

Configures the ACME DNS challenge provider to use for all ACME transactions. The tokens following the name of the provider set up the provider the same as if specified in the tls directive's acme issuer .

on_demand_tls

Configures On-Demand TLS where it is enabled, but does not enable it (to enable it, use the on_demand subdirective of the tls directive ). Required for use in production environments, to prevent abuse.

The ask endpoint should return as fast as possible , in a few milliseconds, ideally. Typically, your endpoint should do a constant-time lookup in an database with an index by domain name; avoid loops. Avoid making DNS queries or other network requests.

key_type

Specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it. The possible values are: ed25519 , p256 , p384 , rsa2048 , rsa4096 .

cert_issuer

Defines the issuer (or source) of TLS certificates. The tokens following the name of the issuer set up the issuer the same as if specified in the tls directive . May be repeated if you wish to configure more than one issuer to try. They will be tried in the order they are defined.

ocsp_stapling

Can be set to off to disable OCSP stapling. Useful in environments where responders are not reachable due to firewalls.

preferred_chains

If your CA provides multiple certificate chains, you can use this option to specify which chain Caddy should prefer. Set one of the following options:

Note that specifying preferred_chains as a global option will affect all issuers if there isn't any overriding issuer level config .

Server Options

Customizes HTTP servers with settings that potentially span multiple sites and thus can't be rightly configured in site blocks. These options affect the listener/socket or other facilities beneath the HTTP layer.

Can be specified more than once with different listener_address values to configure different options per server. For example, servers :443 will only apply to the server that is bound to the listener address :443 . Omitting the listener address will apply the options to any remaining server.

Use the caddy adapt command to find the listen address for the servers in your Caddyfile.

For example, to configure different options for the servers on ports :80 and :443 , you would specify two servers blocks:

listener_wrappers {
	http_redirect

listener_wrappers {
	proxy_protocol {
		timeout 2s
		allow 192.168.86.1/24 192.168.86.1/24

trusted_proxies static [private_ranges] <ranges...>

Events

These standard events are emitted by Caddy:

tls events

Plugins may also emit events, so check their documentation for details.