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 is the central component of Certplane. It validates agent identity certificates over mTLS, enforces your issuance policy, requests certificates from Let’s Encrypt via ACME, and returns signed bundles to agents. This page walks you through configuring and starting the broker from scratch.
1

Prerequisites

Before you configure the broker, have the following ready:
  • Internal CA — a running step-ca instance that will issue machine identity certificates to agents.
  • Broker TLS certificate and key — a certificate issued by your internal CA for the broker’s HTTPS listener (e.g. broker.int.example.com), along with its private key.
  • Agent CA bundle — the internal CA root certificate (PEM) that signed, and will sign, agent identity certificates. The broker uses this to verify mTLS connections from agents.
  • ACME account email — the email address to register with Let’s Encrypt.
  • ACME account key — a PEM-encoded EC or RSA private key for the ACME account. Generate one with openssl ecparam -name prime256v1 -genkey -noout -out account.key.
  • DNS provider credentials — API credentials for your DNS provider (currently cloudflare), used for the dns-01 ACME challenge. Make these available as environment variables on the broker host.
2

Create broker.yml

Create /etc/certplane/broker.yml with the following content. Every field shown here corresponds to a real configuration key — do not add fields not listed below.
# broker.yml

server:
  # Address and port the broker listens on. Defaults to :8443.
  address: ":8443"
  tls:
    # Path to the broker's TLS server certificate (PEM), issued by your internal CA.
    cert: /etc/certplane/broker.crt
    # Path to the broker's TLS private key (PEM).
    key: /etc/certplane/broker.key
    # Minimum TLS version accepted. Must be "1.2" or "1.3". Defaults to "1.2".
    min_version: "1.2"
  mtls:
    # Path to the CA bundle (PEM) used to validate incoming agent identity certificates.
    agent_ca_bundle: /etc/certplane/agent-ca.crt

policy:
  # Path to your policy.yml file.
  path: /etc/certplane/policy.yml
  # Set to true to reload policy.yml automatically when the file changes.
  watch: false

store:
  # Persistence driver. Only "sqlite" and "file" are supported.
  driver: sqlite
  # Path to the SQLite database file. Created automatically if it does not exist.
  path: /var/lib/certplane/broker.db

audit:
  # Enable audit logging. Defaults to true.
  enabled: true
  # What to do if the audit subsystem fails. "fail_open" continues issuing;
  # "fail_closed" rejects all requests until the audit system recovers.
  failure_mode: fail_open
  # Mirror audit events to the structured log stream.
  mirror_to_log: true

logging:
  # Log level: debug | info | warn | error. Defaults to info.
  level: info
  # Log format: json | text. Defaults to json.
  format: json
  # Log destination. Defaults to stdout.
  destination: stdout

issuer:
  # The only supported provider is "acme".
  provider: acme
  acme:
    # ACME directory URL. Use the staging URL while testing (see warning below).
    directory_url: https://acme-staging-v02.api.letsencrypt.org/directory
    # Email address registered with the ACME CA.
    account_email: admin@example.com
    # Path to the ACME account private key (PEM).
    account_key: /etc/certplane/acme/account.key
    # DNS provider for the dns-01 challenge. Currently only "cloudflare" is supported.
    dns_provider: cloudflare

secrets:
  # How the broker resolves secret references in the config.
  # "env"  — secret names are environment variable names (default).
  # "file" — secret names are file paths.
  # "vault" / "openbao" — secret names are Vault KV paths.
  provider: env

rate_limits:
  # Maximum certificate requests per agent identity per hour. Defaults to 50.
  per_identity_per_hour: 50
  # Maximum requests per agent identity per certificate profile per hour. Defaults to 20.
  per_identity_profile_per_hour: 20
The broker listens on :8443 by default. To bind to a specific interface, set server.address to a full address such as 0.0.0.0:8443 or 192.168.1.10:8443.
Use the staging ACME directory (https://acme-staging-v02.api.letsencrypt.org/directory) when testing your setup. Staging certificates are not trusted by browsers or the OS but are otherwise identical to production certificates. Switch to https://acme-v02.api.letsencrypt.org/directory only after you have confirmed that the broker can complete the dns-01 challenge successfully.
3

Create a policy file

The broker requires a policy file at the path set in policy.path. The policy file defines which certificate profiles exist and which agent identities are allowed to request them.Create /etc/certplane/policy.yml to get started. See Policy overview for the full policy reference.
If you set policy.watch: true, the broker reloads policy.yml automatically whenever the file changes on disk — no restart required. This is useful when you manage policy with a configuration management tool that writes the file in place.
4

Start the broker

Run the broker, passing the path to your config file:
certplane-broker --config /etc/certplane/broker.yml
The broker starts listening on the configured address and logs startup events to stdout in JSON format. If any required fields are missing or invalid, the broker exits immediately with a descriptive error.For a full reference of every configuration field and its accepted values, see Broker configuration.