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.

This guide walks you through the full Certplane setup: running the broker, defining a certificate policy, enrolling a host with its identity certificate, and starting the agent renewal loop. By the end, your host will have a publicly trusted TLS certificate that renews automatically.
1

Prerequisites

Before you begin, make sure you have the following in place:
  • step-ca — A running step-ca instance reachable by your hosts. This is the internal CA that issues agent identity certificates.
  • Let’s Encrypt access — The broker uses ACME to obtain public certificates. You need a valid email address for the ACME account.
  • Cloudflare DNS token — Certplane uses the dns-01 challenge to prove domain ownership. Create an API token in your Cloudflare dashboard with Zone:DNS:Edit permission for the relevant zone.
  • The Certplane binaries — certplane-broker on your broker host and certplane-agent on each managed host.
2

Deploy the broker

The broker is the central server that enforces policy and obtains certificates from your public CA. Create /etc/certplane/broker.yml:
broker.yml
server:
  address: ":8443"
  tls:
    cert: /etc/certplane/broker.crt
    key: /etc/certplane/broker.key
    min_version: "1.2"
  mtls:
    agent_ca_bundle: /etc/certplane/agent-ca.crt

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

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

audit:
  enabled: true
  failure_mode: fail_open
  mirror_to_log: true

logging:
  level: info
  format: json
  destination: stdout

issuer:
  provider: acme
  acme:
    directory_url: https://acme-staging-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /etc/certplane/acme/account.key
    dns_provider: cloudflare

secrets:
  provider: env

rate_limits:
  per_identity_per_hour: 50
  per_identity_profile_per_hour: 20
Place your broker’s TLS certificate and key at the paths listed under server.tls. The server.mtls.agent_ca_bundle must be the CA certificate bundle that signed (or will sign) your agent identity certificates — this is the step-ca root.Once the config file is in place, start the broker:
certplane-broker --config /etc/certplane/broker.yml
The broker listens on :8443 by default and requires mTLS from every connecting agent. For a full configuration reference, see Broker Setup.
3

Create a policy file

The policy file defines which certificate profiles exist and which hosts are allowed to request each one. Create /etc/certplane/policy.yml:
policy.yml
version: 1

profiles:
  public_edge_main:
    cert_type: wildcard
    dns_names:
      - "*.example.com"
    acme_challenge: dns-01
    renew_before: 720h

hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main
  • profiles — Each named profile sets the certificate type (cert_type: wildcard or cert_type: multi), the DNS names to include, and the ACME challenge method (acme_challenge: dns-01 or acme_challenge: http-01).
  • hosts — Each host entry maps a human-readable key to a host identity (the CN of the identity certificate issued by step-ca) and lists which profiles that host may request. The broker rejects any request for a profile not listed here.
For a full policy reference, see Policy Overview.
4

Enroll your first host

Enrollment gives a host its identity certificate. The agent contacts step-ca once using a short-lived bootstrap token, generates a key pair locally, and stores the resulting identity.crt.Generate a bootstrap token on your step-ca instance:
step ca token edge01.h.int.example.com
Write the token to the host at the path you will reference in the agent config (e.g., /etc/certplane/agent/bootstrap-token).Create the agent config at /etc/certplane/agent.yml:
agent.yml
state_dir: /var/lib/certplane/agent

identity:
  name: edge01.h.int.example.com
  provider: step-ca
  cert: /var/lib/certplane/agent/identity.crt
  key: /var/lib/certplane/agent/identity.key
  issuer_ca_bundle: /var/lib/certplane/agent-ca.crt
  bootstrap_token: /etc/certplane/agent/bootstrap-token
  renew_before: 8h
  warn_before: 24h
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256-fingerprint"
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt

broker:
  url: https://certplane-broker.int.example.com:8443
  server_ca_bundle: /etc/certplane/broker-ca.crt
  timeout: 30s

logging:
  level: info
  format: text
  destination: stderr

certificates:
  - name: edge-wildcard
    profile: public_edge_main
    dns_names:
      - "*.example.com"
    key:       /var/lib/certplane/agent/service.key
    cert:      /var/lib/certplane/agent/service.crt
    chain:     /var/lib/certplane/agent/service.chain.crt
    fullchain: /var/lib/certplane/agent/service.fullchain.crt
    renew_before: 720h
    reload_command: ""
    reload_timeout: 30s
Run enrollment:
certplane-agent enroll --config /etc/certplane/agent.yml
The agent generates identity.key locally, creates a CSR, and submits it to step-ca along with the bootstrap token. On success, identity.crt is written to the path defined in identity.cert.
The bootstrap token is consumed during enrollment and cannot be reused. If enrollment fails and you need to retry, generate a new token from step-ca. See Agent Enrollment for troubleshooting.
5

Run the agent

Once the host is enrolled, start the renewal loop:
certplane-agent run --config /etc/certplane/agent.yml
On startup the agent:
  1. Generates a fresh service.key for each certificate entry.
  2. Constructs a CSR with the DNS names from your config.
  3. Connects to the broker over mTLS, presenting identity.crt as the client certificate.
  4. The broker verifies the identity, checks the policy, and either returns a cached certificate or requests a new one from Let’s Encrypt via ACME.
  5. The agent writes the certificate, chain, and full chain to the configured paths, then executes any reload_command you specified.
The agent continues running and re-checks expiry on each configured certificate. It renews a service certificate when less than renew_before time remains (default: 720 hours). For details on the renewal loop and systemd integration, see Running the Agent.