Broker configuration

This page documents every field in broker.yml. The authoritative source is schemas/broker.schema.json. Most editors (VS Code, JetBrains) will load it automatically if you reference the schema with a YAML # yaml-language-server: $schema=... comment or via your editor’s schema mapping. Required top-level keys: server, policy, issuer.

`server`

server:
  address: "0.0.0.0:8443"
  tls:
    cert: /etc/certplane/tls/broker.crt
    key:  /etc/certplane/tls/broker.key
    min_version: "1.2"
  mtls:
    agent_ca_bundle: /etc/certplane/ca/agent-identity-ca-bundle.crt
  read_header_timeout: 5s
  read_timeout: 10s
  write_timeout: 60s
  idle_timeout: 120s

Field	Type	Default	Notes
`address`	string	`:8443`	Listen address.
`tls.cert`	string	—	Required. Path to PEM server certificate.
`tls.key`	string	—	Required. Path to PEM server key.
`tls.min_version`	enum: `1.2`, `1.3`	`1.2`	Minimum TLS version.
`mtls.agent_ca_bundle`	string	—	Required. CA bundle used to verify agent identity certificates.
`read_header_timeout`	duration	`5s`
`read_timeout`	duration	`10s`
`write_timeout`	duration	`60s`
`idle_timeout`	duration	`120s`

address accepts any Go net.Listen syntax. Use :8443 to bind all interfaces; use 127.0.0.1:8443 and front with a reverse proxy if you need a custom termination model — keep in mind the broker requires mTLS on the connection that reaches it.

`policy`

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

Field	Type	Default	Notes
`path`	string	—	Required. Policy YAML file.
`watch`	bool	`false`	Reload the policy on disk changes without restart.

The schema and semantics are in Policy overview.

`issuer`

Currently acme is the only provider.

issuer:
  provider: acme
  acme:
    directory_url: https://acme-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /var/lib/certplane/acme/account.key
    dns_provider: cloudflare
    preferred_chain: "ISRG Root X1"

Field	Type	Default	Notes
`provider`	enum: `acme`	`acme`
`acme.directory_url`	string	—	Required. Use the staging directory while testing: `https://acme-staging-v02.api.letsencrypt.org/directory`.
`acme.account_email`	string	—	Required.
`acme.account_key`	string	—	Required. Path to ACME account private key. Created by the broker on first run if missing.
`acme.dns_provider`	enum: `cloudflare`, `httpreq`	—	Required. DNS provider used for `dns-01` challenges.
`acme.preferred_chain`	string	—	Optional; defaults to the CA’s preferred chain.

DNS provider credentials are resolved through secrets — see below and Let’s Encrypt + dns-01.

`secrets`

secrets:
  provider: env       # env | file | vault | openbao
  vault:
    address: https://vault.int.example.com:8200
    token_file: /etc/certplane/vault-token
    mount_path: secret
    kv_version: 2
    key: value
    timeout: 10s
    namespace: ""

Field	Type	Default	Notes
`provider`	enum: `env`, `file`, `vault`, `openbao`	`env`
`vault.address`	string	—	Required when `provider` is `vault` or `openbao`.
`vault.token`	string	—	Inline token. Prefer `token_file`.
`vault.token_file`	string	—	Path containing the Vault token.
`vault.mount_path`	string	`secret`	KV engine mount.
`vault.kv_version`	enum: `1`, `2`	`2`
`vault.key`	string	`value`	Key inside the secret to read.
`vault.timeout`	duration	`10s`
`vault.namespace`	string	—	Vault Enterprise only.

See Vault and OpenBao secrets for the credential reference format.

`store`

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

The store caches issued certificates (to avoid hitting Let’s Encrypt rate limits) and audit events when audit is enabled.

Field	Type	Default	Notes
`driver`	enum: `sqlite`, `file`	`sqlite`
`path`	string	`/var/lib/certplane/broker.db`	SQLite DB or JSON cache file.

`audit`

audit:
  enabled: true
  failure_mode: fail_open     # fail_open | fail_closed
  mirror_to_log: false

Field	Type	Default	Notes
`enabled`	bool	`true`
`failure_mode`	enum	`fail_open`	If audit recording fails, `fail_closed` rejects the issuance request; `fail_open` permits it.
`mirror_to_log`	bool	`false`	Also emit each audit event as a structured log line.

Inspect events with certplane-broker -c <config> audit tail [--limit N].

`rate_limits`

rate_limits:
  per_identity_per_hour: 50
  per_identity_profile_per_hour: 20

0 disables the corresponding limit. Negative values are invalid.

`logging`

logging:
  level: info        # debug | info | warn | error
  format: json       # text | json
  destination: stdout  # stdout | stderr

Broker defaults: info, json, stdout.

Validation

certplane-broker rejects the config on startup if:

Any required field is missing.
tls.min_version is not 1.2 or 1.3.
An ACME field required by provider: acme is missing.
secrets.provider is vault/openbao without vault.address or with an invalid kv_version.
store.driver is not sqlite or file.
audit.failure_mode is not fail_open or fail_closed.
Either rate-limit value is negative.

Errors are accumulated and reported together so you can fix everything in one pass.

​server

​policy

​issuer

​secrets

​store

​audit

​rate_limits

​logging

​Validation