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

# Agent configuration

> Complete reference for agent.yml — identity, broker, certificates, and logging.

This page documents every field in `agent.yml`. The authoritative source is [`schemas/agent.schema.json`](https://github.com/TaconeoMental/Certplane/blob/main/schemas/agent.schema.json).

Required top-level keys: `identity`, `broker`, `certificates`.

## `state_dir`

```yaml theme={null}
state_dir: /var/lib/certplane/agent
```

Base directory for agent state. The lock file `agent.lock` lives here. Default: `/var/lib/certplane/agent`.

## `identity`

```yaml theme={null}
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: /etc/certplane/ca/agent-identity-ca-bundle.crt
  bootstrap_token: /etc/certplane/bootstrap-token  # only required for enroll
  renew_before: 8h
  warn_before: 24h
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256:aabbcc..."
    # OR
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
    timeout: 10s
```

| Field                    | Type            | Default   | Notes                                                                             |
| ------------------------ | --------------- | --------- | --------------------------------------------------------------------------------- |
| `name`                   | string          | —         | **Required.** CN to issue the identity certificate with.                          |
| `provider`               | enum: `step-ca` | `step-ca` | Only `step-ca` is currently supported.                                            |
| `cert`                   | string          | —         | **Required.** Path the agent writes/reads the identity certificate at.            |
| `key`                    | string          | —         | **Required.** Path the agent writes/reads the identity key at (mode `0600`).      |
| `issuer_ca_bundle`       | string          | —         | **Required.** CA bundle used to verify the issuer of the identity cert.           |
| `bootstrap_token`        | string          | —         | Required only for `enroll`. Deleted after a successful enrollment.                |
| `renew_before`           | duration        | `8h`      | Renew the identity certificate when less than this remains.                       |
| `warn_before`            | duration        | `24h`     | Log a warning when less than this remains. Must be greater than `renew_before`.   |
| `step_ca.url`            | string          | —         | URL of the `step-ca` API.                                                         |
| `step_ca.fingerprint`    | string          | —         | SHA-256 fingerprint of the `step-ca` root. Required if `root_ca_bundle` is unset. |
| `step_ca.root_ca_bundle` | string          | —         | PEM bundle for the `step-ca` root. Required if `fingerprint` is unset.            |
| `step_ca.timeout`        | duration        | `10s`     |                                                                                   |

You must set exactly one of `step_ca.fingerprint` or `step_ca.root_ca_bundle`.

## `broker`

```yaml theme={null}
broker:
  url: https://certplane-broker.int.example.com:8443
  server_ca_bundle: /etc/certplane/ca/broker-server-ca-bundle.crt
  timeout: 30s
```

| Field              | Type     | Default | Notes                                                               |
| ------------------ | -------- | ------- | ------------------------------------------------------------------- |
| `url`              | string   | —       | **Required.** Broker HTTPS endpoint.                                |
| `server_ca_bundle` | string   | —       | **Required.** CA bundle that signs the broker's server certificate. |
| `timeout`          | duration | `30s`   | Per-request timeout to the broker.                                  |

## `certificates`

A list with **at least one** entry. Each entry is a managed service certificate.

```yaml theme={null}
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
    reload_command: "systemctl reload traefik"
    reload_timeout: 30s
    renew_before: 720h
```

| Field            | Type      | Default | Notes                                                                                            |
| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------ |
| `name`           | string    | —       | **Required.** Unique label for this entry; appears in logs.                                      |
| `profile`        | string    | —       | **Required.** Broker profile to request. Must be allowed for this host's identity in the policy. |
| `dns_names`      | string\[] | —       | **Required.** Non-empty. Must satisfy the profile's allowed DNS names.                           |
| `key`            | string    | —       | **Required.** Path to the service private key. Generated if missing.                             |
| `cert`           | string    | —       | **Required.** Output path for the leaf certificate.                                              |
| `chain`          | string    | —       | **Required.** Output path for the intermediate chain.                                            |
| `fullchain`      | string    | —       | **Required.** Output path for `leaf + intermediates`.                                            |
| `reload_command` | string    | —       | Shell command run after a successful install.                                                    |
| `reload_timeout` | duration  | `30s`   | Hard timeout for `reload_command`.                                                               |
| `renew_before`   | duration  | `720h`  | Request a new certificate when less than this remains.                                           |

For more on reload commands and how the agent privileges work, see [Reload commands](/guides/reload-commands).

## `logging`

```yaml theme={null}
logging:
  level: info        # debug | info | warn | error
  format: text       # text | json
  destination: stderr  # stdout | stderr
```

Agent defaults: `info`, `text`, `stderr` (so `journalctl` shows readable lines out of the box).

## Validation

`certplane-agent ... check` (and every other subcommand at startup) validates that:

* All required fields are present.
* Every `certificates[].dns_names` entry is a valid DNS name.
* `step_ca.url` and `broker.url` are valid URLs.
* Exactly one of `step_ca.fingerprint` and `step_ca.root_ca_bundle` is set.
* Output paths under `certificates` are absolute.

The full list lives in [`config/agent.go`](https://github.com/TaconeoMental/Certplane/blob/main/config/agent.go).