Skip to main content
Enrollment runs once per host and produces the (identity.key, identity.cert) pair the agent uses for every subsequent broker call.

​
What enrollment does

certplane-agent -c <config> enroll:
  1. Acquires a file lock at <state_dir>/agent.lock.
  2. Refuses to run if identity.cert already exists.
  3. Generates an ECDSA P-256 key at identity.key (mode 0600) if missing, otherwise reuses it.
  4. Reads the bootstrap token at identity.bootstrap_token.
  5. Builds a CSR with CN = identity.name and submits it to step-ca at identity.step_ca.url, verifying the server using identity.step_ca.fingerprint or identity.step_ca.root_ca_bundle.
  6. Writes the returned identity certificate to identity.cert and removes the bootstrap token file.
The lock and the existence check make enroll safe to run from Ansible — re-runs against an already-enrolled host fail fast.

​
Generate a bootstrap token

On your step-ca host: 
step ca token edge01.h.int.example.com
The CN you pass must match identity.name in the agent config. Tokens are single-use and short-lived.

​
Place the token on the host

install -o certplane -g certplane -m 0600 /dev/stdin /etc/certplane/bootstrap-token <<< "$TOKEN"
The Ansible role does this with no_log: true and only when the identity certificate is missing.

​
Agent identity config

The minimum fields needed for enrollment: 
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: /etc/certplane/ca/agent-identity-ca-bundle.crt
  bootstrap_token: /etc/certplane/bootstrap-token
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256:aabbcc..."
    # OR root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
    timeout: 10s
You need either step_ca.fingerprint or step_ca.root_ca_bundle. The full schema is in Agent configuration.

​
Run enrollment

certplane-agent -c /etc/certplane/agent.yml enroll
On success, the agent writes identity.crt and deletes the bootstrap token. The host is now ready to run the renewal loop.

​
Validate the config without enrolling

certplane-agent -c /etc/certplane/agent.yml check
check validates the YAML, applies defaults, runs the same Validate() logic the agent uses at startup, and confirms expected files are reachable. It does not contact step-ca or the broker.

​
Troubleshooting

Enrollment is one-shot. To re-enroll, delete identity.cert and identity.key, generate a fresh bootstrap token, and run enroll again.
The token file at identity.bootstrap_token is missing. With Ansible, this means the certplane_agent_bootstrap_token variable was not set on this host.
The token file exists but is whitespace-only. Regenerate it with step ca token ....
The step-ca server cert is not trusted. Either set identity.step_ca.fingerprint to the SHA-256 of the step-ca root, or set identity.step_ca.root_ca_bundle to a PEM file containing it.
The broker’s server.mtls.agent_ca_bundle must trust the CA that signed identity.cert. If you rotated the step-ca intermediate after deploying the broker, redeploy the bundle.

​
Next: run the agent

Running the agent covers the run subcommand, the systemd timer, and the renewal model.