Public TLS and ACME Reference

Public TLS is configured per HTTPS listener with certificate mappings.

In the management UI, choose TLS under Configure. Create an HTTPS listener under Proxy -> Listeners first, then choose Add certificate. The TLS page separates certificate mappings from reusable DNS credentials and shows summary counts for HTTPS listeners, mappings, certificate errors, and DNS credentials.

Exact Fields And Defaults

Mappings include:

• listener,
• hostname pattern,
• source,
• certificate/key material or ACME settings,
• enabled flag,
• status and renewal timestamps.

Hostname patterns support exact names and wildcards such as *.example.com.

The management UI's Manual method accepts uploaded PEM certificate/key material or generates a self-signed certificate. The management API also supports server file paths. ACME methods support:

Setting	Values
Challenge	HTTP-01, TLS-ALPN-01, DNS-01
CA	Let's Encrypt production or staging
DNS provider	Cloudflare for DNS-01

Statuses:

Status	Meaning
Pending	Waiting for initial issuance.
Renewing	Issuance or renewal is running.
Ready	Certificate material is available.
Error	Last issuance attempt failed; check last_error and the next retry time.

Validation Rules

• ACME hostnames must be public fully-qualified DNS names.
• ACME does not accept localhost, .local names (including the legacy p2pstream.local default), IP addresses, or internal-only names.
• Wildcard ACME certificates require DNS-01.
• DNS-01 currently requires an enabled Cloudflare DNS credential.
• Uploaded manual certificates require both PEM certificate and key.
• Manual file-path certificates require both paths.

Runtime Effects

Uploaded and generated public certificate material is written under ${CONFIG_DIR}/certs/public-listener-<listener-id>/. ACME certificates renew when missing, expired, or when one third of their lifetime remains, capped at 30 days before expiry (a 90-day certificate renews 30 days before expiry, a 45-day certificate 15 days before, a 6-day certificate 2 days before). Failed renewals are retried after 1 hour.

Fresh installations seed a manual self-signed mapping for localhost. Newly generated default and fallback certificates use only localhost as their subject/issuer CN and DNS SAN, plus 127.0.0.1 and ::1 IP SANs; they include no product organization or other product identity fields. Certificates generated for an explicit hostname or IP keep that requested SAN. Generic names remove explicit product identification from these certificates, but do not prevent TLS fingerprinting.

Upgrades preserve stored certificate mappings and files, including the legacy p2pstream.local default, uploaded certificates, and certificates referenced by server paths. Restarting replaces the in-memory fallback with a newly generated generic certificate, but does not replace a persisted default. To replace a legacy default, edit its mapping under TLS, change the hostname to localhost, select Manual -> Generate self-signed, choose the validity, and save. This generates new key/certificate material and applies it to new TLS handshakes. Keeping the old hostname while regenerating retains that hostname in the new CN/SAN. Alternatively, replace the mapping with a certificate for your intended public hostname. Manual certificates have no automatic renewal and cannot use the ACME Renew action. Management certificates and trust roots are separate and are unaffected.

For ready ACME certificates, next_renewal_at is the next planned renewal time. For failed ACME certificates, next_renewal_at is the next automatic retry time. While a renewal is running, the next schedule is cleared until the attempt succeeds or fails.

The certificate table uses Hostname, Status, Expires, and Renewal columns. Expand a row to see the served certificate's issuer, every DNS name and IP address, SHA-256 fingerprint, serial number, and validity; these are read from the certificate file and show a short reason when the file is missing, unreadable, or invalid. ACME certificates are flagged for attention when the last renewal failed, when a renewal is more than 24 hours overdue, or when less than one sixth of the lifetime (at most 14 days) remains. Manual certificates show an expiry warning when less than one third of the lifetime (at most 30 days) remains. Row actions renew ACME certificates, edit mappings, or delete mappings from the More menu. The separate DNS credentials table shows provider, zone ID, enabled/disabled state, and whether the secret is saved.

Server logs for ACME use component=public_acme. Renewal entries include fields such as cert_id, listener_id, hostname, challenge_type, ca, trigger, stage, attempt_at, duration, expires_at, next_renewal_at, and retry_at. Challenge tokens, DNS TXT values, DNS API tokens, and private key material are not logged.

The TLS page is the operational view for ACME status, manual certificate mappings, DNS credentials, renewal details, and certificate errors that need attention.

Examples

HTTP-01 mapping:

Listener: public-https
Hostname pattern: app.example.com
Method: HTTP-01
CA: Let's Encrypt staging, then production

DNS-01 wildcard mapping:

Listener: public-https
Hostname pattern: *.example.com
Method: DNS-01
DNS credential: cloudflare-example

The HTTP-01 and TLS-ALPN mapping form selects the listener, hostname pattern, ACME CA, validation method, account email, and enabled state.

DNS credentials are stored separately from certificate mappings so multiple DNS-01 mappings can reuse the same Cloudflare zone credential without exposing a saved secret in the UI.

The DNS-01 mapping form uses the saved Cloudflare credential and is the required ACME path for wildcard hostnames.

Related Tasks

• ACME HTTP/TLS-ALPN
• ACME Cloudflare DNS
• TLS