> ## 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.

# Run the broker

> Install certplane-broker, lay out its config and TLS material, and run it under systemd.

This page covers running `certplane-broker` on a single host. For the full schema reference, see [Broker configuration](/configuration/broker). To automate everything below with Ansible, see the [Ansible roles guide](/guides/ansible).

## Prerequisites

* A reachable [`step-ca`](https://smallstep.com/docs/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](/guides/ansible):

```
/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

```yaml /etc/certplane/broker.yml theme={null}
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](/configuration/broker) for every field. The full JSON Schema lives at [`schemas/broker.schema.json`](https://github.com/TaconeoMental/Certplane/blob/main/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`](/guides/ansible) role ships this unit. To run by hand:

```ini /etc/systemd/system/certplane-broker.service theme={null}
[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:

```bash theme={null}
systemctl daemon-reload
systemctl enable --now certplane-broker
```

## Verify it is running

```bash theme={null}
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](/setup/agent-enroll) — bring up your first host.
* [Policy overview](/policy/overview) — write the policy file.
* [Vault and OpenBao secrets](/guides/vault-secrets) — pull DNS credentials from Vault instead of env.