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.

Enrollment is the one-time process that establishes a host’s machine identity within Certplane. During enrollment, the agent contacts your step-ca instance with a short-lived bootstrap token, obtains a long-lived identity certificate, and writes the certificate and private key to the configured paths. Every subsequent interaction between the agent and the broker is authenticated with that identity certificate over mTLS. You only need to run enrollment once per host.
1

Generate a bootstrap token

The bootstrap token is issued on the CA side by an operator with access to your step-ca instance. Generating it is outside the scope of this page — refer to the step-ca documentation for how to create a one-time-use token for your chosen provisioner.The token is a signed JWT that step-ca will accept exactly once to issue an identity certificate.
2

Write the bootstrap token to the host

Copy the bootstrap token to the host that will run the agent and write it to a file. The path must match identity.bootstrap_token in your agent.yml (see next step).
echo "YOUR_BOOTSTRAP_TOKEN" > /etc/certplane/agent/bootstrap-token
chmod 600 /etc/certplane/agent/bootstrap-token
Treat the bootstrap token as a secret. It grants one-time access to your internal CA. Restrict file permissions to the user that will run certplane-agent, and delete the file after enrollment succeeds.
3

Create agent.yml

Create /etc/certplane/agent.yml with the following content. Every field shown here corresponds to a real configuration key.
# agent.yml

# Directory where the agent stores its runtime state.
# Defaults to /var/lib/certplane/agent.
state_dir: /var/lib/certplane/agent

identity:
  # Unique name for this host's identity. Typically the host's FQDN.
  # This value must match the identity registered in your policy file.
  name: pvvl-edge01.h.int.example.com

  # Identity CA provider. Only "step-ca" is currently supported.
  provider: step-ca

  # Path where the agent writes and reads its identity certificate (PEM).
  cert: /var/lib/certplane/agent/identity.crt

  # Path where the agent writes and reads its identity private key (PEM).
  key: /var/lib/certplane/agent/identity.key

  # Path to the CA bundle (PEM) that issued agent identity certificates.
  # The broker uses this CA to verify mTLS connections from this agent.
  issuer_ca_bundle: /var/lib/certplane/agent-ca.crt

  # Path to the bootstrap token file written in the previous step.
  # Only required during initial enrollment. Can be deleted afterwards.
  bootstrap_token: /etc/certplane/agent/bootstrap-token

  # Renew the identity certificate when less than this time remains before expiry.
  # Defaults to 8h.
  renew_before: 8h

  # Emit a warning log when less than this time remains before expiry.
  # Should be greater than renew_before. Defaults to 24h.
  warn_before: 24h

  step_ca:
    # URL of your step-ca API.
    url: https://ca.int.example.com
    # SHA256 fingerprint of the step-ca root CA certificate.
    fingerprint: "sha256-fingerprint-of-your-root-ca"
    # Path to the step-ca root CA certificate (PEM).
    # Required if fingerprint is not provided; optional if fingerprint is set.
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt

broker:
  # URL of the certplane-broker API.
  url: https://certplane-broker.int.example.com:8443
  # Path to the CA bundle (PEM) used to verify the broker's TLS certificate.
  server_ca_bundle: /etc/certplane/ca/broker-ca.crt
  # Timeout for broker API calls. Defaults to 30s.
  timeout: 30s

logging:
  # Log level: debug | info | warn | error. Defaults to info.
  level: info
  # Log format: json | text. Defaults to text for the agent.
  format: text
  # Log destination. Defaults to stderr.
  destination: stderr

certificates:
  - # A unique name for this certificate entry. Used in logs and state tracking.
    name: edge-wildcard
    # The certificate profile to request. Must be listed for this host in policy.yml.
    profile: public_edge_main
    # DNS names to include in the certificate SAN.
    dns_names:
      - "*.example.com"
    # Path where the agent writes the service private key (PEM).
    key: /var/lib/certplane/agent/service.key
    # Path where the agent writes the service certificate (PEM).
    cert: /var/lib/certplane/agent/service.crt
    # Path where the agent writes the intermediate chain (PEM).
    chain: /var/lib/certplane/agent/service.chain.crt
    # Path where the agent writes the full certificate chain (PEM).
    fullchain: /var/lib/certplane/agent/service.fullchain.crt
    # Request a new certificate when less than this time remains before expiry.
    # Defaults to 720h (30 days).
    renew_before: 720h
    # Shell command to run after the certificate is written or renewed.
    # Leave empty to skip. See configuration/agent for details.
    reload_command: ""
    # Timeout for the reload_command. Defaults to 30s.
    reload_timeout: 30s
4

Run enrollment

With the config file in place, run the enrollment command:
certplane-agent enroll --config /etc/certplane/agent.yml
The agent reads the bootstrap token from identity.bootstrap_token, contacts your step-ca instance, and obtains a signed identity certificate. Enrollment is complete when the command exits with status 0.
5

Verify the identity certificate was written

After successful enrollment, the agent writes two files to the paths configured under identity:
ls -l /var/lib/certplane/agent/
# identity.crt   — the signed machine identity certificate
# identity.key   — the corresponding private key
Confirm that both files exist and are non-empty. If either file is missing, check the error output from the enroll command for details.
The bootstrap token file (identity.bootstrap_token) is consumed once by step-ca and becomes invalid after enrollment. You can safely delete it from the host:
rm /etc/certplane/agent/bootstrap-token
With enrollment complete, the host has a valid machine identity certificate. Proceed to Run the agent to start the renewal loop and begin requesting service certificates from the broker. For a full reference of every agent configuration field, see Agent configuration.