Skip to main content

Documentation Index

Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt

Use this file to discover all available pages before exploring further.

The broker reads a single YAML configuration file, passed at startup with the --config flag. This page documents every supported field, its type, default value, and when it is required.

​
Full example

server:
  address: ":8443"
  tls:
    cert: /etc/certplane/broker.crt
    key: /etc/certplane/broker.key
    min_version: "1.2"
  mtls:
    agent_ca_bundle: /etc/certplane/agent-ca.crt

policy:
  path: /etc/certplane/policy.yml
  watch: false

issuer:
  provider: acme
  acme:
    directory_url: https://acme-staging-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /etc/certplane/acme/account.key
    dns_provider: cloudflare

secrets:
  provider: env

store:
  driver: sqlite
  path: /var/lib/certplane/broker.db

audit:
  enabled: true
  failure_mode: fail_open
  mirror_to_log: true

rate_limits:
  per_identity_per_hour: 50
  per_identity_profile_per_hour: 20

logging:
  level: info
  format: json
  destination: stdout

​
server

​
server.address
string
default:":8443"
Address and port the broker listens on, in the form host:port. Use :8443 to listen on all interfaces on port 8443.

​
server.tls

​
server.tls.cert
string
required
Path to the broker’s TLS server certificate (PEM). This certificate is presented to agents and any other clients connecting to the broker API.
​
server.tls.key
string
required
Path to the broker’s TLS server private key (PEM).
​
server.tls.min_version
string
default:"1.2"
Minimum TLS version the broker accepts. Accepted values: "1.2" or "1.3". Set to "1.3" to disable TLS 1.2 in high-security environments.

​
server.mtls

​
server.mtls.agent_ca_bundle
string
required
Path to the internal CA bundle (PEM) used to validate agent identity certificates during the mTLS handshake. Only agents whose certificates chain up to a CA in this bundle are allowed to connect.

​
Server timeouts

These fields tune the HTTP server’s connection-level timeouts. Defaults are conservative values suitable for most deployments.
​
server.read_header_timeout
duration
default:"5s"
Maximum time allowed to read the request headers.
​
server.read_timeout
duration
default:"10s"
Maximum time allowed to read the full request body.
​
server.write_timeout
duration
default:"60s"
Maximum time allowed to write the response. Set this higher than any expected ACME round-trip time.
​
server.idle_timeout
duration
default:"120s"
Maximum time an idle keep-alive connection is kept open.

​
policy

​
policy.path
string
required
Path to the policy YAML file. The policy file defines which hosts are allowed to request which certificate profiles.
​
policy.watch
boolean
default:"false"
When true, the broker watches the policy file for changes and reloads it automatically without a restart. Useful in environments where policy is managed by configuration management tools.

​
issuer

​
issuer.provider
string
default:"acme"
Certificate issuer provider. The only supported value is acme.

​
issuer.acme

These fields are required when issuer.provider is acme.
Use the staging directory while you are testing to avoid hitting Let’s Encrypt rate limits:
  • Staging: https://acme-staging-v02.api.letsencrypt.org/directory
  • Production: https://acme-v02.api.letsencrypt.org/directory
Switch to the production directory only when your setup is verified and working end-to-end.
​
issuer.acme.directory_url
string
required
ACME directory URL for the CA you want to use. See the note above for the Let’s Encrypt staging and production URLs.
​
issuer.acme.account_email
string
required
Email address registered with the ACME account. Let’s Encrypt uses this address to send expiry warnings and policy notifications.
​
issuer.acme.account_key
string
required
Path to the ACME account private key (PEM). If the file does not exist, the broker generates a new key and registers a new account on first startup.
​
issuer.acme.dns_provider
string
required
DNS provider used to complete dns-01 challenges, for example cloudflare. The broker uses the corresponding provider credentials from the configured secrets provider.
​
issuer.acme.preferred_chain
string
Preferred certificate chain name when the ACME CA offers multiple chains. For Let’s Encrypt this is typically "ISRG Root X1". If omitted, the CA’s default chain is used.

​
store

​
store.driver
string
default:"sqlite"
Storage driver for broker state. Accepted values: sqlite or file.
​
store.path
string
default:"/var/lib/certplane/broker.db"
Path to the storage file. For the sqlite driver this is the SQLite database file. The broker creates the file if it does not exist.

​
audit

​
audit.enabled
boolean
default:"true"
Enable audit logging. When enabled, the broker records an audit event for every certificate request, including the requesting identity, the requested profile, and the outcome.
​
audit.failure_mode
string
default:"fail_open"
Controls broker behavior when the audit log cannot be written. Accepted values:
  • fail_open — the broker continues to issue certificates even if audit logging fails.
  • fail_closed — the broker refuses to issue certificates until audit logging is restored.
​
audit.mirror_to_log
boolean
default:"false"
When true, audit events are written to the main application log in addition to the dedicated audit log. Useful for development and troubleshooting.

​
rate_limits

​
rate_limits.per_identity_per_hour
integer
default:"50"
Maximum number of certificate requests a single host identity may make in any rolling one-hour window, across all profiles. Set to 0 to disable this limit.
​
rate_limits.per_identity_profile_per_hour
integer
default:"20"
Maximum number of certificate requests a single host identity may make for a specific profile in any rolling one-hour window. Set to 0 to disable this limit.

​
logging

​
logging.level
string
default:"info"
Minimum log level to emit. Accepted values: debug, info, warn, error.
​
logging.format
string
default:"json"
Output format for log lines. Accepted values: json for structured logging (recommended for log aggregation), text for human-readable output.
​
logging.destination
string
default:"stdout"
Where logs are written. Accepted values: stdout or stderr.