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

> Execute certplane-agent run on a systemd timer to renew identity and service certificates.

`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

| Command                              | Purpose                                                                                                              |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `certplane-agent -c <config> enroll` | One-time enrollment. See [Agent enrollment](/setup/agent-enroll).                                                    |
| `certplane-agent -c <config> run`    | Renew the identity certificate if needed, then renew every service certificate that is in its `renew_before` window. |
| `certplane-agent -c <config> check`  | Validate config and on-disk files without contacting any server.                                                     |

`-c` / `--config` is required.

## What `run` does

For full detail see [How it works](/how-it-works#phase-2-renewal-loop). 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`](/guides/ansible) Ansible role installs both. By hand:

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

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

```bash theme={null}
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](/guides/reload-commands).

## Logs

The agent logs to `stderr` by default (configurable under `logging`). The `systemd` unit captures that into the journal:

```bash theme={null}
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

```bash theme={null}
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.