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.

certplane-agent run starts the agent’s long-running renewal loop. On each iteration the agent checks whether any managed certificate is approaching its renew_before threshold. If renewal is due, the agent generates a private key, builds a certificate signing request, and submits it to the broker over mTLS using the identity certificate obtained during enrollment. The broker validates the request against policy, issues or returns a cached certificate from Let’s Encrypt, and the agent writes the certificate, chain, and full chain to the configured paths. If a reload_command is configured for that certificate entry, the agent runs it after writing the files.

​
Start the agent

Run the following command on the enrolled host: 
certplane-agent run --config /etc/certplane/agent.yml
The agent logs to stderr in text format at info level by default. You can override both with logging.format and logging.level in agent.yml.
The agent logs to stderr by default (logging.destination: stderr, logging.format: text, logging.level: info). When running under systemd, stderr is captured by the journal automatically — no additional log configuration is needed.

​
What happens on the first run

When the agent starts and a certificate does not yet exist at the configured cert path, it treats the certificate as immediately due for renewal and proceeds with the full issuance flow:
  1. Key generation — the agent generates a new private key and writes it to certificates[].key.
  2. CSR creation — a certificate signing request is built from the configured dns_names and profile.
  3. mTLS request to broker — the CSR is sent to the broker. The agent authenticates with its identity certificate (identity.cert / identity.key) over mutual TLS.
  4. Broker issues certificate — the broker validates the request against the host’s policy entry, then requests a certificate from Let’s Encrypt (or returns a cached one if still valid).
  5. Files written — the agent writes the signed certificate to cert, the intermediate chain to chain, and the full chain to fullchain.
  6. Reload command — if reload_command is set, the agent runs it within reload_timeout seconds.
Set reload_command to the command that signals your service to reload its TLS configuration without a full restart. For example:
certificates:
  - name: edge-wildcard
    # ...
    reload_command: "systemctl reload nginx"
    reload_timeout: 30s
Other common examples: systemctl reload traefik, systemctl reload vault.

​
Steady-state behavior

After the initial issuance, the agent runs a renewal check loop. On each tick it compares the remaining validity of each certificate against the certificate’s renew_before value. When the remaining validity falls below that threshold, the agent repeats the same issuance flow described above. The broker caches the most recently issued certificate for each profile. If the cached certificate still has more than the broker’s own renewal threshold remaining, the broker returns the cached bundle instead of placing a new ACME order. This avoids unnecessary requests to Let’s Encrypt.

​
Run as a systemd service

For production use, manage the agent with systemd so it starts on boot and is restarted on failure. Create /etc/systemd/system/certplane-agent.service: 
[Unit]
Description=Certplane agent renewal loop
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/certplane-agent run --config /etc/certplane/agent.yml
Restart=on-failure
RestartSec=10s
# Run as a dedicated user if your deployment creates one.
# User=certplane
# Group=certplane

[Install]
WantedBy=multi-user.target
Enable and start the service: 
systemctl daemon-reload
systemctl enable --now certplane-agent.service
systemctl status certplane-agent.service
Check the journal for agent output: 
journalctl -u certplane-agent.service -f
For a full reference of every configuration field accepted by the agent, see Agent configuration.