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

CommandPurpose
certplane-agent -c <config> enrollOne-time enrollment. See Agent enrollment.
certplane-agent -c <config> runRenew the identity certificate if needed, then renew every service certificate that is in its renew_before window.
certplane-agent -c <config> checkValidate config and on-disk files without contacting any server.
-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
[Unit]
Description=certplane agent run
After=network.target

[Service]
Type=oneshot
User=certplane
Group=certplane
ExecStartPre=/usr/local/bin/certplane-agent -c /etc/certplane/agent.yml check
ExecStart=/usr/local/bin/certplane-agent -c /etc/certplane/agent.yml run
/etc/systemd/system/certplane-agent.timer
[Unit]
Description=certplane agent renewal timer

[Timer]
OnBootSec=1min
OnUnitActiveSec=6h
RandomizedDelaySec=5min
Unit=certplane-agent.service

[Install]
WantedBy=timers.target
Enable the timer (the timer triggers the service — do not enable the service unit itself): 
systemctl daemon-reload
systemctl enable --now certplane-agent.timer
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: 
journalctl -u certplane-agent --since "1 hour ago"
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

openssl x509 -in /var/lib/certplane/agent/service.crt -noout -subject -issuer -ext subjectAltName -dates
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.