Skip to main content
Version: 0.16

Configuration

ACME providers are registered as AcmeProvider objects (found in the WebUI under Settings › TLS › ACME Providers). Each provider describes where to talk to the CA, which challenge to use, and which contacts are notified. The relevant fields are:

  • directory: the directory URL of the ACME provider. Let's Encrypt's production directory is https://acme-v02.api.letsencrypt.org/directory (the default); the staging directory https://acme-staging-v02.api.letsencrypt.org/directory is used for test runs that do not consume production rate-limit budget.
  • challengeType: the challenge type used to validate control of each domain. One of TlsAlpn01 (default), Dns01, DnsPersist01, or Http01. DNS-PERSIST-01 is a variant of the DNS-01 challenge that keeps the validation TXT record in place after the initial issuance so that subsequent renewals do not have to republish it; use it with DNS providers where propagation is slow or where keeping the record simplifies automation.
  • contact: one or more contact email addresses. Used by the CA for expiry warnings and security notices.
  • renewBefore: how early renewal starts, expressed as a fraction of the remaining lifetime. Default R23 (two thirds of the remaining validity period has elapsed).
  • maxRetries: number of attempts before giving up on a failed challenge. Default 10.
  • eabKeyId / eabHmacKey: External Account Binding (EAB) credentials when the CA requires them.
  • memberTenantId: tenant scope of the provider (Enterprise deployments only).

An AcmeProvider does not list the domains it covers. Instead, each Domain that needs an automatically managed certificate sets its certificateManagement to the Automatic variant, which carries an acmeProviderId reference to the AcmeProvider and an optional subjectAlternativeNames list (leave empty to request a wildcard or the default set of SANs). A single AcmeProvider can be referenced from any number of Domain records, so one ACME account issues certificates for many domains. ACME account keys and state are stored in the data store and need no filesystem path.

Default-certificate selection is made on the SystemSettings singleton through defaultCertificateId: whichever Certificate is pointed to there is served to clients that do not send SNI in their ClientHello. The AcmeProvider itself has no "default" flag; a provider becomes the default implicitly by issuing the Certificate selected via defaultCertificateId. This setting is optional, since clients negotiating with SNI pick their certificate from the domain records directly.

Note
  • Regularly check the contact email for messages from the ACME provider.
  • Point a new provider at the staging directory first to verify the configuration; switching to production afterwards avoids consuming the production rate-limit budget on failed runs.

DNS-01 configuration​

When challengeType is set to Dns01, Stalwart publishes the validation record through a configured DNS provider. DNS providers are stored as DnsServer objects (found in the WebUI under Settings › Network › DNS › DNS Providers). Each DnsServer carries its own variant (Tsig, Sig0, or Cloudflare) with the fields needed to talk to that provider. Common timing fields that apply to every DNS variant are:

  • pollingInterval: how often to check whether the TXT record has propagated. Default "15s".
  • propagationTimeout: maximum time to wait for propagation. Default "1m".
  • ttl: TTL applied to new records. Default "5m".
  • timeout: per-request timeout against the DNS API. Default "30s".

The DNS zone used for record updates is no longer carried on the DnsServer itself. It is set per domain on the Domain object: when dnsManagement is the Automatic variant, dnsServerId picks the DnsServer to drive and origin names the zone that carries the records (for example, example.com for a domain sub.example.com). Leaving origin empty uses the domain name itself as the zone. This lets several domains share one DnsServer while each pins its own zone for DNS-01 and DNS-PERSIST-01 validation.

RFC2136 (TSIG)​

The Tsig variant of DnsServer speaks RFC 2136 dynamic update with TSIG authentication. Its fields are:

  • host: IP address of the authoritative DNS server.
  • port: port used to reach the server. Default 53.
  • protocol: udp or tcp. Default udp.
  • tsigAlgorithm: TSIG HMAC algorithm. Default hmac-sha512.
  • keyName: TSIG key name.
  • key: TSIG key secret.

Cloudflare​

The Cloudflare variant of DnsServer drives the Cloudflare DNS API. Its fields are:

  • secret: Cloudflare API token, or API key when email is set.
  • email: account email used with the legacy X-Auth-Email / X-Auth-Key flow. Leave unset to authenticate with an API token.
  • timeout: HTTP request timeout. Default "30s".

Example​

An ACME provider pointing at the Let's Encrypt production directory and using TLS-ALPN-01:

{
  "directory": "https://acme-v02.api.letsencrypt.org/directory",
  "challengeType": "TlsAlpn01",
  "contact": ["[email protected]"],
  "renewBefore": "R23"
}