Agent configuration

This page documents every field in agent.yml. The authoritative source is schemas/agent.schema.json. Required top-level keys: identity, broker, certificates.

`state_dir`

state_dir: /var/lib/certplane/agent

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

`identity`

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`

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.

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.

`logging`

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.

Get Started

Setup

Policy

Configuration

Guides

Agent configuration

`state_dir`

`identity`

`broker`

`certificates`

`logging`

Validation

​state_dir

​identity

​broker

​certificates

​logging

​Validation

`state_dir`

`identity`

`broker`

`certificates`

`logging`

Validation