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 policy file is the central control document in Certplane. It defines which certificate profiles exist and which hosts are permitted to request each profile. Every certificate request the broker receives is evaluated against this file — if a host or profile is not declared here, the request is rejected before any ACME interaction takes place.

​
Where the policy file lives

The broker reads the policy file from the path you set in broker.yml under policy.path:
broker.yml
policy:
  path: /etc/certplane/policy.yml
  watch: true
policy.path is a required field. The broker will refuse to start if it is not set.

​
Top-level sections

The policy file has two top-level sections:
SectionPurpose
profilesNamed certificate policies that define what kind of cert is issued and how
hostsRegistered host entries that map a host identity CN to the profiles it may request
Both sections are required and must contain at least one entry each.

​
Minimal working example

The following is a complete, valid policy file with one profile and one host:
policy.yml
version: 1

profiles:
  public_edge_main:
    cert_type: wildcard
    dns_names:
      - "*.example.com"
    acme_challenge: dns-01
    renew_before: 720h

hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main

​
Automatic reloads with policy.watch

Set watch: true in the broker config and the broker watches the policy file for changes using filesystem events. When you save an updated policy file, the broker reloads it in place without requiring a restart.
broker.yml
policy:
  path: /etc/certplane/policy.yml
  watch: true
If watch is omitted or set to false, you must restart the broker for policy changes to take effect.

​
Applying policy changes

1

Edit the policy file

Add, remove, or modify profiles and host entries in policy.yml.
2

Save the file

Write the file to disk. If watch: true is set, the broker picks up the change immediately.
3

Restart the broker if watch is disabled

If you are not using watch: true, restart the broker process to load the updated policy.
A host whose identity CN is not listed in the hosts section will be rejected by the broker regardless of what the agent requests. Adding a host to the hosts section is a prerequisite for it to receive any certificate.

​
Next steps

  • Profiles — full field reference for defining certificate profiles
  • Hosts — full field reference for registering hosts and controlling profile access