Skip to main content
This page covers running certplane-broker on a single host. For the full schema reference, see Broker configuration. To automate everything below with Ansible, see the Ansible roles guide.

​
Prerequisites

  • A reachable step-ca (used to issue agent identities — the broker only needs its CA bundle, not credentials).
  • A TLS server certificate and key for the broker’s mTLS API. This can be issued by step-ca or any other CA your agents will trust.
  • The CA bundle that signs your agent identity certificates (typically the step-ca root or intermediate).
  • A supported ACME provider account email — the broker creates the ACME account on first use.
  • DNS provider credentials for dns-01 challenges, if you plan to issue wildcards. Supported: cloudflare, httpreq.

​
Filesystem layout

The recommended layout, matching the certplane_broker Ansible role: 
/etc/certplane/
├── broker.yml
├── policy.yml
├── tls/
│   ├── broker.crt
│   └── broker.key
└── ca/
    └── agent-identity-ca-bundle.crt
/var/lib/certplane/
├── acme/
│   └── account.key
└── broker.db
A dedicated certplane system user owns /var/lib/certplane and the ACME account key.

​
Minimum config

/etc/certplane/broker.yml
server:
  address: ":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

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

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

secrets:
  provider: env

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

audit:
  enabled: true
  failure_mode: fail_open

logging:
  level: info
  format: json
  destination: stdout
See Broker configuration for every field. The full JSON Schema lives at schemas/broker.schema.json.

​
CLI

The broker binary is a Cobra app with the global -c / --config flag and subcommands:
CommandPurpose
certplane-broker -c <config> serveRun the HTTPS/mTLS API.
certplane-broker -c <config> policy validate --policy <path>Compile and validate a policy file. Prints the policy hash plus profile and identity counts.
certplane-broker -c <config> certs listDump cached certificate bundles as JSON.
certplane-broker -c <config> audit tail [--limit N]Stream recent audit events as JSON lines.
-c is required for every subcommand.

​
systemd unit

The certplane_broker role ships this unit. To run by hand:
/etc/systemd/system/certplane-broker.service
[Unit]
Description=certplane broker
After=network.target

[Service]
Type=simple
User=certplane
Group=certplane
ExecStart=/usr/local/bin/certplane-broker -c /etc/certplane/broker.yml serve
Restart=on-failure
RestartSec=5s
ReadWritePaths=/var/lib/certplane

[Install]
WantedBy=multi-user.target
Enable and start: 
systemctl daemon-reload
systemctl enable --now certplane-broker

​
Verify it is running

curl --cacert /path/to/broker-server-ca.crt https://broker.example.com:8443/healthz
# ok

curl --cacert /path/to/broker-server-ca.crt https://broker.example.com:8443/readyz
# ready
/readyz returns 503 policy not loaded until the policy file is present and parses. The issuance endpoint (POST /v1/certificates) requires a valid agent client certificate and is normally only called by certplane-agent.

​
Policy hot reload

Set policy.watch: true to reload the policy file in place when its contents change on disk. No restart is needed. The broker logs the new policy hash, which you can correlate with the audit log.

​
Next steps