Configuration: ACME automatic TLS

This page documents the ACME TLS provider (tls-acme module), which automatically obtains TLS certificates from ACME-compatible Certificate Authorities (CAs) such as Let’s Encrypt. It supports both eager (startup-time) and on-demand (lazy, first-connection) certificate issuance, with three challenge types:

• HTTP-01 — serves a token at /.well-known/acme-challenge/ (default)
• TLS-ALPN-01 — responds with a self-signed cert during the TLS handshake
• DNS-01 — creates a TXT record at _acme-challenge.<domain>

Certificates are cached (both in-memory and file-based) and automatically renewed before expiration.

Automatic TLS via ACME is enabled by default in Ferron for public hosts:

example.com {
    # Automatic TLS is enabled by default, no explicit TLS directive needed
}

Directives

Challenge types

HTTP-01 (default)

The simplest challenge type. The server listens on port 80 to serve /.well-known/acme-challenge/<token>.

example.com {
    tls {
        provider acme
        challenge http-01
        contact "admin@example.com"
    }
}

Requirements: The server must be reachable on port 80 for the ACME CA to validate the challenge.

TLS-ALPN-01

Responds with a self-signed certificate when the CA connects with the acme-tls/1 ALPN protocol. No additional port is needed.

example.com {
    tls {
        provider acme
        challenge tls-alpn-01
        contact "admin@example.com"
    }
}

Requirements: The server must be reachable on port 443. Does not support wildcard domains.

DNS-01 (required for wildcard domains)

Creates a _acme-challenge TXT record via a DNS provider. The only challenge type that supports wildcard certificates.

*.example.com {
    tls {
        provider acme
        challenge dns-01
        contact "admin@example.com"
        dns {
            provider cloudflare
            api_key "EXAMPLE_API_KEY"
        }
    }
}

Requirements: A DNS provider module must be configured. Wildcard domains are supported. The dns block must specify the provider name and any provider-specific credentials. See DNS providers for the full list of supported providers and their directives.

Configuration parameters

Configuration example:

example.com {
    tls {
        provider acme
        challenge http-01
        contact "admin@example.com"

        directory "https://acme-v02.api.letsencrypt.org/directory"
        cache "/var/cache/ferron-acme"

        save "/etc/ssl/certs/example.com.pem" "/etc/ssl/private/example.com.pem"
        # `post_obtain_command` arg is a script/binary name + args, separated by spaces.
        post_obtain_command "/var/lib/post_obtain_command.sh"

        ocsp {
            enabled true
        }
    }
}

Eager mode (recommended for known domains)

Eager mode obtains certificates at server startup, before any client traffic is received. This is ideal for static configurations where all domain names are known in advance.

On-demand mode

On-demand mode defers certificate issuance until the first TLS handshake for a hostname. This is useful for wildcard domains, multi-tenant hosting, or when domains are not known at startup.

*.example.com {
    tls {
        provider acme
        challenge dns-01
        contact "admin@example.com"
        on_demand
    }
}

On-demand approval endpoint

To prevent abuse, you can configure an approval endpoint. Before issuing a certificate, Ferron sends an HTTP GET request to the endpoint with ?domain=<sni> as a query parameter. If the response is 200, the certificate is issued.

*.example.com {
    tls {
        provider acme
        challenge http-01
        contact "admin@example.com"
        on_demand
        on_demand_ask "https://internal-api.example.com/check-cert"
    }
}

Certificate caching

In-memory cache (default)

When no cache path is specified, certificates and account data are stored in memory.

File-based cache

Setting a cache path persists certificates and accounts to disk, surviving restarts:

example.com {
    tls {
        provider acme
        challenge http-01
        contact "admin@example.com"
        cache "/var/cache/ferron-acme"
    }
}

The cache directory structure:

/var/cache/ferron-acme/
├── account_<hash>          # ACME account credentials
└── certificate_<hash>      # Certificate chain + private key (JSON)

Cache key derivation

• Account cache key: hash of contact emails + directory URL
• Certificate cache key: hash of sorted domains + profile name

Certificate renewal

Certificates are automatically renewed before expiration. The renewal check runs every 10 seconds in the background. Ferron uses the ACME renewalInfo endpoint (RFC 9773) when available, falling back to a heuristic of 50% of certificate lifetime (capped at 24 hours before expiry).

External Account Binding (EAB)

Some CAs (especially enterprise/internal ACME servers) require External Account Binding. Provide the key ID and HMAC secret:

tls {
    provider acme
    challenge http-01
    contact "admin@example.com"
    eab "my-key-id" "SMq9KpHkR7z..."
    directory "https://acme.internal.example.com/directory"
}

The HMAC secret must be base64url-encoded (without padding).

Saving certificates to disk

To persist obtained certificates for use by other tools or backup:

tls {
    provider acme
    challenge http-01
    contact "admin@example.com"
    save "/etc/ssl/certs/example.com.pem" "/etc/ssl/private/example.com.pem"
}

If only one path is given, the key path defaults to the certificate path with a .key extension. After a certificate is obtained, the private key is written with 0600 permissions on Unix.

Security considerations

• Private keys are never logged or exposed in error messages.
• When saved to disk, keys are written with 0600 permissions on Unix.
• When using on-demand mode, always configure an on_demand_ask endpoint in production to prevent certificate issuance for arbitrary hostnames.

Troubleshooting

”ACME certificate provisioning error: …”

Certificate issuance failed. The log message includes the affected domains. Check the error message for details (DNS resolution, ACME server errors, etc.). At debug log level (--verbose), you’ll also see per-step messages for account loading, order creation, challenge solving, and certificate installation.

DNS-01 issues

• Ensure the DNS provider is configured correctly with valid credentials.
• Check that the provider has permission to create TXT records for the domain.
• DNS propagation may take longer than 60 seconds for some providers — the ACME CA will retry validation.

Verifying certificates

# Check the certificate served by Ferron
echo | openssl s_client -connect example.com -servername example.com 2>/dev/null | openssl x509 -noout -subject -dates -issuer

# Verify OCSP stapling
openssl s_client -connect example.com -status -servername example.com </dev/null 2>/dev/null | grep -A 5 "OCSP response"

Observability

The ACME background task emits log events and metrics through the configured observability pipeline:

Logs

Structured logs

In OTLP log_style modern, the summary field is used as the log body and attributes are emitted as typed OpenTelemetry log record attributes.

Metrics

See also

• DNS providers — all supported DNS-01 provider backends and their configuration
• Security and TLS — cipher suites, ECDH curves, mTLS
• TLS session ticket keys — session resumption
• OCSP stapling — OCSP response stapling
• HTTP host directives — per-host TLS configuration

Best practices

The following best-practice checks are reported by ferron doctor for directives on this page.

• no_verification for ACME directory — Disabling TLS verification for the ACME directory should only be used for testing.
• on_demand without on_demand_ask — On-demand certificate issuance without an approval endpoint allows certificate issuance for arbitrary hostnames. Configure on_demand_ask to approve requests.
• on_demand_ask_no_verification — Disabling TLS verification for the approval endpoint should only be used for strictly internal and otherwise authenticated endpoints.
• Missing contact — Without an ACME account email, the certificate authority cannot send expiry or account notices.
• Non-public domain — Domains using non-public TLDs (.local, .internal, .home, .lan, .test, .localhost) or bare IP addresses are unlikely to be publicly resolvable. Certificate issuance via ACME will fail because the CA cannot complete domain validation. This check applies to both explicit domains directives and to the host block’s hostname when on_demand TLS is used.