Run the broker

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:

Command	Purpose
`certplane-broker -c <config> serve`	Run 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 list`	Dump 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

Agent enrollment — bring up your first host.
Policy overview — write the policy file.
Vault and OpenBao secrets — pull DNS credentials from Vault instead of env.

Get Started

Setup

Policy

Configuration

Guides

Prerequisites

Filesystem layout

Minimum config

CLI

systemd unit

Verify it is running

Policy hot reload

Next steps

​Prerequisites

​Filesystem layout

​Minimum config

​CLI

​systemd unit

​Verify it is running

​Policy hot reload

​Next steps

Prerequisites

Filesystem layout

Minimum config

CLI

systemd unit

Verify it is running

Policy hot reload

Next steps