string

The URL to the CA's ACME directory endpoint. Default: https://acme-v02.api.letsencrypt.org/directory

string

The URL to the test CA's ACME directory endpoint. This endpoint is only used during retries if there is a failure using the primary CA. Default: https://acme-staging-v02.api.letsencrypt.org/directory

string

Your email address, so the CA can contact you if necessary. Not required, but strongly recommended to provide one so you can be reached if there is a problem. Your email is not sent to any Caddy mothership or used for any purpose other than ACME transactions.

string

Optionally select an ACME profile to use for certificate orders. Must be a profile name offered by the ACME server, which are listed at its directory endpoint.

EXPERIMENTAL: Subject to change. See https://datatracker.ietf.org/doc/draft-aaron-acme-profiles/

string

If you have an existing account with the ACME server, put the private key here in PEM format. The ACME client will look up your account information with this key first before trying to create a new one. You can use placeholders here, for example if you have it in an environment variable.

*acme.EAB

If using an ACME CA that requires an external account binding, specify the CA-provided credentials here.

caddy.Duration

Time to wait before timing out an ACME operation. Default: 0 (no timeout)

*ChallengesConfig

Configures the various ACME challenge types.

[]string

An array of files of CA certificates to accept when connecting to the ACME CA. Generally, you should only use this if the ACME CA endpoint is internal or for development/testing purposes.

*ChainPreference

Preferences for selecting alternate certificate chains, if offered by the CA. By default, the first offered chain will be selected. If configured, the chains may be sorted and the first matching chain will be selected.

caddy.Duration

The validity period to ask the CA to issue a certificate for. Default: 0 (CA chooses lifetime). This value is used to compute the "notAfter" field of the ACME order; therefore the system must have a reasonably synchronized clock. NOTE: Not all CAs support this. Check with your CA's ACME documentation to see if this is allowed and what values may be used. EXPERIMENTAL: Subject to change.

json.RawMessage

Forward proxy module

*x509.CertPool

*zap.Logger

certmagic.ACMEIssuer

*certmagic.Config

*certmagic.ACMEIssuer

[]string

[]*AutomationPolicy

The list of automation policies. The first policy matching a certificate or subject name will be applied.

*OnDemandConfig

On-Demand TLS defers certificate operations to the moment they are needed, e.g. during a TLS handshake. Useful when you don't know all the hostnames at config-time, or when you are not in control of the domain names you are managing certificates for. In 2015, Caddy became the first web server to implement this experimental technology.

Note that this field does not enable on-demand TLS; it only configures it for when it is used. To enable it, create an automation policy with on_demand.

caddy.Duration

Caddy staples OCSP (and caches the response) for all qualifying certificates by default. This setting changes how often it scans responses for freshness, and updates them if they are getting stale. Default: 1h

caddy.Duration

Every so often, Caddy will scan all loaded, managed certificates for expiration. This setting changes how frequently the scan for expiring certificates is performed. Default: 10m

caddy.Duration

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. 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).

*AutomationPolicy

*AutomationPolicy

[]string

Which subjects (hostnames or IP addresses) this policy applies to.

This list is a filter, not a command. In other words, it is used only to filter whether this policy should apply to a subject that needs a certificate; it does NOT command the TLS app to manage a certificate for that subject. To have Caddy automate a certificate or specific subjects, use the "automate" certificate loader module of the TLS app.

[]json.RawMessage

The modules that may issue certificates. Default: internal if all subjects do not qualify for public certificates; otherwise acme and zerossl.

[]json.RawMessage

Modules that can get a custom certificate to use for any given TLS handshake at handshake-time. Custom certificates can be useful if another entity is managing certificates and Caddy need only get it and serve it. Specifying a Manager enables on-demand TLS, i.e. it has the side-effect of setting the on_demand parameter to true.

TODO: This is an EXPERIMENTAL feature. Subject to change or removal.

bool

If true, certificates will be requested with MustStaple. Not all CAs support this, and there are potentially serious consequences of enabling this feature without proper threat modeling.

float64

How long before a certificate's expiration to try renewing it, as a function of its total lifetime. As a general and conservative rule, it is a good idea to renew a certificate when it has about 1/3 of its total lifetime remaining. This utilizes the majority of the certificate's lifetime while still saving time to troubleshoot problems. However, for extremely short-lived certs, you may wish to increase the ratio to ~1/2.

string

The type of key to generate for certificates. Supported values: ed25519, p256, p384, rsa2048, rsa4096.

json.RawMessage

Optionally configure a separate storage module associated with this manager, instead of using Caddy's global/default-configured storage.

bool

If true, certificates will be managed "on demand"; that is, during TLS handshakes or when needed, as opposed to at startup or config load. This enables On-Demand TLS for this policy.

bool

If true, private keys already existing in storage will be reused. Otherwise, a new key will be created for every new certificate to mitigate pinning and reduce the scope of key compromise. TEMPORARY: Key pinning is against industry best practices. This property will likely be removed in the future. Do not rely on it forever; watch the release notes.

bool

Disables OCSP stapling. Disabling OCSP stapling puts clients at greater risk, reduces their privacy, and usually lowers client performance. It is NOT recommended to disable this unless you are able to justify the costs. EXPERIMENTAL. Subject to change.

map[string]string

Overrides the URLs of OCSP responders embedded in certificates. Each key is a OCSP server URL to override, and its value is the replacement. An empty value will disable querying of that server. EXPERIMENTAL. Subject to change.

[]certmagic.Issuer

Issuers and Managers store the decoded issuer and manager modules; they are only used to populate an underlying certmagic.Config's fields during provisioning so that the modules can survive a re-provisioning.

[]certmagic.Manager

[]string

*certmagic.Config

certmagic.Storage

any

int

Maximum number of certificates to allow in the cache. If reached, certificates will be randomly evicted to make room for new ones. Default: 10,000

string

Path to the certificate (public key) file.

string

Path to the private key file.

string

The format of the cert and key. Can be "pem". Default: "pem"

[]string

Arbitrary values to associate with this certificate. Can be useful when you want to select a particular certificate when there may be multiple valid candidates.

string

The certificate (public key) in PEM format.

string

The private key in PEM format.

[]string

Arbitrary values to associate with this certificate. Can be useful when you want to select a particular certificate when there may be multiple valid candidates.

tls.Certificate

[]string

any

*bool

Prefer chains with the fewest number of bytes.

[]string

Select first chain having a root with one of these common names.

[]string

Select first chain that has any issuer with one of these common names.

*HTTPChallengeConfig

HTTP configures the ACME HTTP challenge. This challenge is enabled and used automatically and by default.

*TLSALPNChallengeConfig

TLSALPN configures the ACME TLS-ALPN challenge. This challenge is enabled and used automatically and by default.

*DNSChallengeConfig

Configures the ACME DNS challenge. Because this challenge typically requires credentials for interfacing with a DNS provider, this challenge is not enabled by default. This is the only challenge type which does not require a direct connection to Caddy from an external server.

NOTE: DNS providers are currently being upgraded, and this API is subject to change, but should be stabilized soon.

string

Optionally customize the host to which a listener is bound if required for solving a challenge.

json.RawMessage

Certificate authority module which provides the certificate pool of trusted certificates

CA

[]string

Deprecated: Use the ca field with the tls.ca_pool.source.inline module instead. A list of base64 DER-encoded CA certificates against which to validate client certificates. Client certs which are not signed by any of these CAs will be rejected.

[]string

Deprecated: Use the ca field with the tls.ca_pool.source.file module instead. TrustedCACertPEMFiles is a list of PEM file names from which to load certificates of trusted CAs. Client certificates which are not signed by any of these CA certificates will be rejected.

[]string

Deprecated: This field is deprecated and will be removed in a future version. Please use the validators field instead with the tls.client_auth.verifier.leaf module instead.

A list of base64 DER-encoded client leaf certs to accept. If this list is not empty, client certs which are not in this list will be rejected.

[]json.RawMessage

Client certificate verification modules. These can perform custom client authentication checks, such as ensuring the certificate is not revoked.

[]ClientCertificateVerifier

string

The mode for authenticating the client. Allowed values are:

Mode | Description -----|--------------- request | Ask clients for a certificate, but allow even if there isn't one; do not verify it require | Require clients to present a certificate, but do not verify it verify_if_given | Ask clients for a certificate; allow even if there isn't one, but verify it if there is require_and_verify | Require clients to present a valid certificate that is verified

The default mode is require_and_verify if any TrustedCACerts or TrustedCACertPEMFiles or TrustedLeafCerts are provided; otherwise, the default mode is require.

func([][]byte, [][]*x509.Certificate) error

any

any

any

[]*ConnectionPolicy

caddy.ModuleMap

How to match this policy with a TLS ClientHello. If this policy is the first to match, it will be used.

[]ConnectionMatcher

*CustomCertSelectionPolicy

How to choose a certificate if more than one matched the given ServerName (SNI) value.

[]string

The list of cipher suites to support. Caddy's defaults are modern and secure.

[]string

The list of elliptic curves to support. Caddy's defaults are modern and secure.

[]string

Protocols to use for Application-Layer Protocol Negotiation (ALPN) during the handshake.

string

Minimum TLS protocol version to allow. Default: tls1.2

string

Maximum TLS protocol version to allow. Default: tls1.3

bool

Reject TLS connections. EXPERIMENTAL: May change.

*ClientAuthentication

Enables and configures TLS client authentication.

string

DefaultSNI becomes the ServerName in a ClientHello if there is no policy configured for the empty SNI value.

string

FallbackSNI becomes the ServerName in a ClientHello if the original ServerName doesn't match any certificates in the cache. The use cases 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 to your origin's hostname. Note that Caddy must be managing a certificate for this name.

This feature is EXPERIMENTAL and subject to change or removal.

string

Also known as "SSLKEYLOGFILE", TLS secrets will be written to this file in NSS key log format which can then be parsed by Wireshark and other tools. This is INSECURE as it allows other programs or tools to decrypt TLS connections. However, this capability can be useful for debugging and troubleshooting. ENABLING THIS LOG COMPROMISES SECURITY!

This feature is EXPERIMENTAL and subject to change or removal.

json.RawMessage

A module that can manipulate the context passed into CertMagic's certificate management functions during TLS handshakes. EXPERIMENTAL - subject to change or removal.

HandshakeContext

*tls.Config

TLSConfig is the fully-formed, standard lib TLS config used to serve TLS connections. Provision all ConnectionPolicies to populate this. It is exported only so it can be minimally adjusted after provisioning if necessary (like to adjust NextProtos to disable HTTP/2), and may be unexported in the future.

[]bigInt

The certificate must have one of these serial numbers.

[]string

The certificate must have one of these organization names.

PublicKeyAlgorithm

The certificate must use this public key algorithm.

[]string

The certificate must have at least one of the tags in the list.

[]string

The certificate must have all of the tags in the list.

json.RawMessage

The DNS provider module to use which will manage the DNS records relevant to the ACME challenge. Required.

caddy.Duration

The TTL of the TXT record used for the DNS challenge.

caddy.Duration

How long to wait before starting propagation checks. Default: 0 (no wait).

caddy.Duration

Maximum time to wait for temporary DNS record to appear. Set to -1 to disable propagation checks. Default: 2 minutes.

[]string

Custom DNS resolvers to prefer over system/built-in defaults. Often necessary to configure when using split-horizon DNS.

string

Override the domain to use for the DNS challenge. This is to delegate the challenge to a different domain, e.g. one that updates faster or one with a provider API.

acmez.Solver

[]ECHConfiguration

The list of ECH configurations for which to automatically generate and rotate keys. At least one is required to enable ECH.

It is strongly recommended to use as few ECH configs as possible to maximize the size of your anonymity set (see the ECH specification for a definition). Typically, each server should have only one public name, i.e. one config in this list.

[]*ECHPublication

Publication describes ways to publish ECH configs for clients to discover and use. Without publication, most clients will not use ECH at all, and those that do will suffer degraded performance.

Most major browsers support ECH by way of publication to HTTPS DNS RRs. (This also typically requires that they use DoH or DoT.)

map[string][]echConfig

map of public_name to list of configs

string

The public server name (SNI) that will be used in the outer ClientHello. This should be a domain name for which this server is authoritative, because Caddy will try to provision a certificate for this name. As an outer SNI, it is never used for application data (HTTPS, etc.), but it is necessary for enabling clients to connect securely in some cases. If this field is empty or missing, or if Caddy cannot get a certificate for this domain (e.g. the domain's DNS records do not point to this server), client reliability becomes brittle, and you risk coercing clients to expose true server names in plaintext, which compromises both the privacy of the server and makes clients more vulnerable.

any

json.RawMessage

The DNS provider module which will establish the HTTPS record(s).

ECHDNSProvider

*zap.Logger

[]string

The list of ECH configurations to publish, identified by public name. If not set, all configs will be included for publication by default.

It is generally advised to maximize the size of your anonymity set, which implies using as few public names as possible for your sites. Usually, only a single public name is used to protect all the sites for a server

EXPERIMENTAL: This field may be renamed or have its structure changed.

[]string

The list of ("inner") domain names which are protected with the associated ECH configurations.

If not set, all server names registered with the TLS module will be added to this list implicitly. (This registration is done automatically by other Caddy apps that use the TLS module. They should register their configured server names for this purpose. For example, the HTTP server registers the hostnames for which it applies automatic HTTPS. This is not something you, the user, have to do.) Most servers

Names in this list should not appear in any other publication config object with the same publishers, since the publications will likely overwrite each other.

NOTE: In order to publish ECH configs for domains configured for On-Demand TLS that are not explicitly enumerated elsewhere in the config, those domain names will have to be listed here. The only time Caddy knows which domains it is serving with On-Demand TLS is handshake-time, which is too late for publishing ECH configs; it means the first connections would not protect the server names, revealing that information to observers, and thus defeating the purpose of ECH. Hence the need to list them here so Caddy can proactively publish ECH configs before clients connect with those server names in plaintext.

caddy.ModuleMap

How to publish the ECH configurations so clients can know to use ECH to connect more securely to the server.

[]ECHPublisher

any

[]string

TrustedCACertPEMFiles is a list of PEM file names from which to load certificates of trusted CAs. Client certificates which are not signed by any of these CA certificates will be rejected.

*x509.CertPool

[]CertKeyFilePair

[]string

string

The URL from which to download the certificate. Required.

The URL will be augmented with query string parameters taken from the TLS handshake:

• server_name: The SNI value
• signature_schemes: Comma-separated list of hex IDs of signatures
• cipher_suites: Comma-separated list of hex IDs of cipher suites

To be valid, the response must be HTTP 200 with a PEM body consisting of blocks for the certificate chain and the private key.

To indicate that this manager is not managing a certificate for the described handshake, the endpoint should return HTTP 204 (No Content). Error statuses will indicate that the manager is capable of providing a certificate but was unable to.

context.Context

[]string

the list of URLs that respond with PEM-encoded certificates to trust.

*TLSConfig

Customize the TLS connection knobs to used during the HTTP call

*x509.CertPool

bool

If true, the HTTP challenge will be disabled.

int

An alternate port on which to service this challenge. Note that the HTTP challenge port is hard-coded into the spec and cannot be changed, so you would have to forward packets from the standard HTTP challenge port to this one.

any

[]string

A list of base64 DER-encoded CA certificates against which to validate client certificates. Client certs which are not signed by any of these CAs will be rejected.

*x509.CertPool

string

The ID of the CA to use for signing. The default CA ID is "local". The CA can be configured with the pki app.

caddy.Duration

The validity period of certificates.

bool

If true, the root will be the issuer instead of the intermediate. This is NOT recommended and should only be used when devices/clients do not properly validate certificate chains.

*caddypki.CA

*zap.Logger

[]json.RawMessage

[]*x509.Certificate

any

[]string

[]string

[]string

[]string

A list of certificate file names to be loaded from storage.

json.RawMessage

The storage module where the trusted leaf certificates are stored. Absent explicit storage implies the use of Caddy default storage.

certmagic.Storage

Reference to the globally configured storage module.

caddy.Context

[]string

The IPs or CIDR ranges to match.

[]netip.Prefix

*zap.Logger

string

A unique name for this regular expression. Optional, but useful to prevent overwriting captures from other regexp matchers.

string

The regular expression to evaluate, in RE2 syntax, which is the same general syntax used by Go, Perl, and Python. For details, see Go's regexp package. Captures are accessible via placeholders. Unnamed capture groups are exposed as their numeric, 1-based index, while named capture groups are available by the capture group name.

*regexp.Regexp

[]string

The IPs or CIDR ranges to match.

[]string

The IPs or CIDR ranges to NOT match.

[]netip.Prefix

[]netip.Prefix

*zap.Logger

[]string

MatchRegexp

string

Deprecated. WILL BE REMOVED SOON. Use 'permission' instead with the http module.

json.RawMessage

REQUIRED. A module that will determine whether a certificate is allowed to be loaded from storage or obtained from an issuer on demand.

OnDemandPermission

any

[]CertKeyPEMPair

[]string

List of the Authority names that are configured in the pki app whose intermediate certificates are trusted

[]*caddypki.CA

*x509.CertPool

[]string

List of the Authority names that are configured in the pki app whose root certificates are trusted

[]*caddypki.CA

*x509.CertPool

string

The endpoint to access. It should be a full URL. A query string parameter "domain" will be added to it, containing the domain (or IP) for the desired certificate, like so: ?domain=example.com. Generally, this endpoint is not exposed publicly to avoid a minor information leak (which domains are serviced by your application).

The endpoint must return a 200 OK status if a certificate is allowed; anything else will cause it to be denied. Redirects are not followed.

*zap.Logger

*caddy.Replacer

x509.PublicKeyAlgorithm

any

json.RawMessage

KeySource is the method by which Caddy produces or obtains TLS session ticket keys (STEKs). By default, Caddy generates them internally using a secure pseudorandom source.

caddy.Duration

How often Caddy rotates STEKs. Default: 12h.

int

The maximum number of keys to keep in rotation. Default: 4.

bool

Disables STEK rotation.

bool

Disables TLS session resumption by tickets.

STEKProvider

map[*tls.Config]struct{}

chan struct{}

[][]byte

*sync.Mutex

[]CertKeyFilePair

A list of pairs of certificate and key file names along with their encoding format so that they can be loaded from storage.

certmagic.Storage

Reference to the globally configured storage module.

caddy.Context

json.RawMessage

The storage module where the trusted root certificates are stored. Absent explicit storage implies the use of Caddy default storage.

[]string

The storage key/index to the location of the certificates

certmagic.Storage

*x509.CertPool

caddy.ModuleMap

Certificates to load into memory for quick recall during TLS handshakes. Each key is the name of a certificate loader module.

The "automate" certificate loader module can be used to specify a list of subjects that need certificates to be managed automatically, including subdomains that may already be covered by a managed wildcard certificate. The first matching automation policy will be used to manage automated certificate(s).

All loaded certificates get pooled into the same cache and may be used to complete TLS handshakes for the relevant server names (SNI). Certificates loaded manually (anything other than "automate") are not automatically managed and will have to be refreshed manually before they expire.

*AutomationConfig

Configures certificate automation.

*SessionTicketService

Configures session ticket ephemeral keys (STEKs).

*CertCacheOptions

Configures the in-memory certificate cache.

bool

Disables OCSP stapling for manually-managed certificates only. To configure OCSP stapling for automated certificates, use an automation policy instead.

Disabling OCSP stapling puts clients at greater risk, reduces their privacy, and usually lowers client performance. It is NOT recommended to disable this unless you are able to justify the costs.

EXPERIMENTAL. Subject to change.

bool

Disables checks in certmagic that the configured storage is ready and able to handle writing new content to it. These checks are intended to prevent information loss (newly issued certificates), but can be expensive on the storage.

Disabling these checks should only be done when the storage can be trusted to have enough capacity and no other problems.

EXPERIMENTAL. Subject to change.

bool

Disables the automatic cleanup of the storage backend. This is useful when TLS is not being used to store certificates and the user wants run their server in a read-only mode.

Storage cleaning creates two files: instance.uuid and last_clean.json. The instance.uuid file is used to identify the instance of Caddy in a cluster. The last_clean.json file is used to store the last time the storage was cleaned.

EXPERIMENTAL. Subject to change.

*ECH

Enable Encrypted ClientHello (ECH). ECH protects the server name (SNI) and other sensitive parameters of a normally-plaintext TLS ClientHello during a handshake.

EXPERIMENTAL: Subject to change.

json.RawMessage

The default DNS provider module to use when a DNS module is needed.

EXPERIMENTAL: Subject to change.

any

[]CertificateLoader

map[string]struct{}

caddy.Context

*time.Ticker

chan struct{}

*zap.Logger

*caddyevents.App

map[string]struct{}

*sync.Mutex

map[string]string

set of subjects with managed certificates, and hashes of manually-loaded certificates (managing's value is an optional issuer key, for distinction)

bool

If true, the TLS-ALPN challenge will be disabled.

int

An alternate port on which to service this challenge. Note that the TLS-ALPN challenge port is hard-coded into the spec and cannot be changed, so you would have to forward packets from the standard TLS-ALPN challenge port to this one.

json.RawMessage

Provides the guest module that provides the trusted certificate authority (CA) certificates

bool

If true, TLS verification of server certificates will be disabled. This is insecure and may be removed in the future. Do not use this option except in testing or local development environments.

caddy.Duration

The duration to allow a TLS handshake to a server. Default: No timeout.

string

The server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part. You only need to override this if your upstream address does not match the certificate the upstream is likely to use. For example if the upstream address is an IP address, then you would need to configure this to the hostname being served by the upstream server. Currently, this does not support placeholders because the TLS config is not provisioned on each connection, so a static value must be used.

string

TLS renegotiation level. TLS renegotiation is the act of performing subsequent handshakes on a connection after the first. The level can be:

• "never": (the default) disables renegotiation.
• "once": allows a remote server to request renegotiation once per connection.
• "freely": allows a remote server to repeatedly request renegotiation.

*zap.Logger

string

The API key (or "access key") for using the ZeroSSL API. REQUIRED.

int

How many days the certificate should be valid for. Only certain values are accepted; see ZeroSSL docs.

string

The host to bind to when opening a listener for verifying domain names (or IPs).

int

If HTTP is forwarded from port 80, specify the forwarded port here.

*DNSChallengeConfig

Use CNAME validation instead of HTTP. ZeroSSL's API uses CNAME records for DNS validation, similar to how Let's Encrypt uses TXT records for the DNS challenge.

*zap.Logger

certmagic.Storage

*certmagic.ZeroSSLIssuer

big.Int

time.Duration

*os.File

uint16

"The version of ECH for which this configuration is used. The version is the same as the code point for the encrypted_client_hello extension. Clients MUST ignore any ECHConfig structure with a version they do not support."

uint8

HpkeKeyConfig fields:

hpke.KEM

kem.PublicKey

[]hpkeSymmetricCipherSuite

uint8

ECHConfigContents fields:

string

[]byte

[]byte

these fields are not part of the spec, but are here for our use when setting up TLS servers or maintenance

[]byte

echConfigMeta

bool

[]echConfig

time.Time

publicationHistory

hpke.KDF

hpke.AEAD

map[string]map[string]time.Time

string

*net.TCPConn

testAddr