Skip to main content
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
FieldTypeDefaultNotes
namestring—Required. CN to issue the identity certificate with.
providerenum: step-castep-caOnly step-ca is currently supported.
certstring—Required. Path the agent writes/reads the identity certificate at.
keystring—Required. Path the agent writes/reads the identity key at (mode 0600).
issuer_ca_bundlestring—Required. CA bundle used to verify the issuer of the identity cert.
bootstrap_tokenstring—Required only for enroll. Deleted after a successful enrollment.
renew_beforeduration8hRenew the identity certificate when less than this remains.
warn_beforeduration24hLog a warning when less than this remains. Must be greater than renew_before.
step_ca.urlstring—URL of the step-ca API.
step_ca.fingerprintstring—SHA-256 fingerprint of the step-ca root. Required if root_ca_bundle is unset.
step_ca.root_ca_bundlestring—PEM bundle for the step-ca root. Required if fingerprint is unset.
step_ca.timeoutduration10s
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
FieldTypeDefaultNotes
urlstring—Required. Broker HTTPS endpoint.
server_ca_bundlestring—Required. CA bundle that signs the broker’s server certificate.
timeoutduration30sPer-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
FieldTypeDefaultNotes
namestring—Required. Unique label for this entry; appears in logs.
profilestring—Required. Broker profile to request. Must be allowed for this host’s identity in the policy.
dns_namesstring[]—Required. Non-empty. Must satisfy the profile’s allowed DNS names.
keystring—Required. Path to the service private key. Generated if missing.
certstring—Required. Output path for the leaf certificate.
chainstring—Required. Output path for the intermediate chain.
fullchainstring—Required. Output path for leaf + intermediates.
reload_commandstring—Shell command run after a successful install.
reload_timeoutduration30sHard timeout for reload_command.
renew_beforeduration720hRequest 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.