Skip to main content
certplane-agent is a one-shot binary. Each run invocation does the minimum work needed to keep certificates current, then exits. Schedule it with a systemd timer (or any scheduler).

​
CLI

-c / --config is required.

​
What run does

For full detail see How it works. In short, every invocation:
  1. Acquires <state_dir>/agent.lock.
  2. Fails fast if identity.cert is missing — you must enroll first.
  3. Renews the identity certificate if it expires within identity.renew_before (default 8h).
  4. For each entry under certificates[]:
    • Generates the service key at key if missing, reuses it otherwise.
    • Skips the entry if the existing certificate matches the key and is not within renew_before of expiry.
    • Otherwise builds a CSR, requests a new bundle from the broker, validates the bundle against the local key and configured DNS names, writes cert/chain/fullchain, and runs reload_command (subject to reload_timeout, default 30s).
The lock ensures two timer firings cannot race.

​
systemd unit + timer

The certplane_agent Ansible role installs both. By hand:
/etc/systemd/system/certplane-agent.service
/etc/systemd/system/certplane-agent.timer
Enable the timer (the timer triggers the service — do not enable the service unit itself):
The RandomizedDelaySec spreads load across a fleet — a desirable property when many agents would otherwise renew at the same time.

​
When does the agent actually call the broker?

Only when a certificate is within its renew_before window or missing. On a healthy fleet with renew_before: 720h (30 days) and a 90-day Let’s Encrypt certificate, each host calls the broker roughly once every 60 days. Other timer firings parse the local certificate, see it is not yet due, log certificate skipped, not in renewal window, and exit.

​
Reload hooks

If a certificate entry sets reload_command, the agent runs it after a successful install — for example systemctl reload nginx. The command runs as the agent’s user (typically certplane), so it usually needs a sudoers rule to reload a system service. See Reload commands.

​
Logs

The agent logs to stderr by default (configurable under logging). The systemd unit captures that into the journal:
Key log lines:
  • agent run started
  • service key generated / service key reused
  • certificate skipped, not in renewal window
  • requesting certificate
  • certificate installed
  • reload started / reload completed / reload failed
  • agent run completed

​
Verifying installed certificates

The agent already verifies that the broker’s bundle matches the local key and that the SAN list matches the configured dns_names. If you ever see a mismatch, the agent refuses to install the bundle.