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.

The agent reads a single YAML configuration file, passed at startup with the --config flag. This page documents every supported field, its type, default value, and when it is required.

​
Full example

state_dir: /var/lib/certplane/agent

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: /var/lib/certplane/agent-ca.crt
  bootstrap_token: /etc/certplane/agent/bootstrap-token
  renew_before: 8h
  warn_before: 24h
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256-fingerprint"
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt

broker:
  url: https://certplane-broker.int.example.com:8443
  server_ca_bundle: /etc/certplane/broker-ca.crt
  timeout: 30s

logging:
  level: info
  format: text
  destination: stderr

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
    renew_before: 720h
    reload_command: "systemctl reload nginx"
    reload_timeout: 30s

​
Top level

​
state_dir
string
default:"/var/lib/certplane/agent"
Base directory where the agent writes its state files. All relative paths used internally by the agent are resolved against this directory.

​
identity

The identity section controls how the agent enrolls and renews its own mTLS identity certificate. This certificate is presented to the broker on every API call.
​
identity.name
string
required
Common name (CN) for this host’s identity certificate. Use a fully qualified hostname that uniquely identifies the machine, for example edge01.h.int.example.com.
​
identity.provider
string
default:"step-ca"
CA provider used to enroll and renew the identity certificate. The only supported value is step-ca.
​
identity.cert
string
required
Path where the agent writes and reads its identity certificate (PEM). The file is created on first enrollment and overwritten on each renewal.
​
identity.key
string
required
Path where the agent writes and reads the identity private key (PEM).
​
identity.issuer_ca_bundle
string
required
Path to the internal CA bundle (PEM) used to verify the identity certificate issued by step-ca. The agent uses this bundle when validating its own certificate chain after renewal.
​
identity.bootstrap_token
string
Path to the bootstrap token file. This token is only consumed during initial enrollment. You can remove it from the config after the agent has enrolled for the first time.
​
identity.renew_before
duration
default:"8h"
The agent requests a new identity certificate when less than this duration remains before expiry. Accepts Go duration strings such as 8h or 30m.
​
identity.warn_before
duration
default:"24h"
The agent writes a warning to its log when less than this duration remains before the identity certificate expires. Set this to a value greater than renew_before so you have time to investigate if automated renewal fails.

​
identity.step_ca

These fields are required when identity.provider is step-ca.
​
identity.step_ca.url
string
required
URL of the step-ca API, for example https://ca.int.example.com:9000. The agent contacts this endpoint to enroll and renew the identity certificate.
​
identity.step_ca.fingerprint
string
SHA-256 fingerprint of the step-ca root CA certificate. Either fingerprint or root_ca_bundle must be provided so the agent can bootstrap trust in step-ca.
​
identity.step_ca.root_ca_bundle
string
Path to the step-ca root CA certificate (PEM). Either this field or fingerprint must be set. If both are provided, root_ca_bundle takes precedence.
​
identity.step_ca.timeout
duration
default:"10s"
Timeout for each step-ca API call. Accepts Go duration strings such as 10s or 1m.

​
broker

​
broker.url
string
required
URL of the certplane-broker API, for example https://broker.internal.example.com:8443. The agent sends certificate requests to this endpoint.
​
broker.server_ca_bundle
string
required
Path to the CA bundle (PEM) used to verify the broker’s TLS server certificate. This is typically your internal root CA.
​
broker.timeout
duration
default:"30s"
Timeout for broker API calls. Accepts Go duration strings such as 30s or 1m.

​
certificates

certificates is a required array. At least one entry must be present. Each entry describes one service certificate that the agent manages on behalf of a local process.
​
certificates[].name
string
required
A unique name for this certificate entry. Names are used in log messages and must not be duplicated within the same config file.
​
certificates[].profile
string
required
The profile name to request from the broker. The profile must be listed under this host in the broker’s policy file, otherwise the request is rejected.
​
certificates[].dns_names
string[]
required
Array of DNS names to include in the certificate’s Subject Alternative Names. Wildcard names such as *.example.com are supported.
​
certificates[].key
string
required
Path where the agent writes the service private key (PEM). This path must differ from cert.
​
certificates[].cert
string
required
Path where the agent writes the service certificate (PEM).
​
certificates[].chain
string
required
Path where the agent writes the intermediate certificate chain (PEM), without the end-entity certificate.
​
certificates[].fullchain
string
required
Path where the agent writes the full chain (PEM): the end-entity certificate followed by all intermediates. Use this file with most web servers.
​
certificates[].reload_command
string
Shell command to run after the certificate is written to disk. Use this to reload the process that consumes the certificate, for example systemctl reload nginx.
​
certificates[].reload_timeout
duration
default:"30s"
Maximum time allowed for the reload_command to complete. If the command exceeds this timeout, the agent logs an error but does not retry automatically.
​
certificates[].renew_before
duration
default:"720h"
The agent requests a new service certificate when less than this duration remains before expiry. The default of 720h (30 days) is suitable for 90-day certificates issued by Let’s Encrypt.

​
logging

​
logging.level
string
default:"info"
Minimum log level to emit. Accepted values: debug, info, warn, error.
​
logging.format
string
default:"text"
Output format for log lines. Accepted values: text for human-readable output, json for structured logging.
​
logging.destination
string
default:"stderr"
Where logs are written. Accepted values: stdout or stderr.