Certificate policies

A certificate policy is a standing rule attached to an agent group. It is not a job itself - it hands one out. For as long as an agent is in the policy's group, the policy makes sure that agent has the certificate the policy describes.

What it creates is entirely ordinary. Every certificate and every job a policy produces is a normal certificate and a normal job: renewal, revocation, deployment and reseller order polling behave exactly as they do for something you created by hand.

Certificate policies build on agent groups and require the Standard plan or higher.

The rollout it makes possible

This is the order the feature is built around, and it works even though the policy is written before any of the servers exist.

1. Write the policy on the group. The group can be completely empty. The policy is stored and applies to nobody yet.
2. Roll a server out. Under Manage > Agents, pick the group in the enrollment wizard's Platform section. The enrollment token carries it, so the agent joins the group the moment it registers.
3. The policy applies itself. The agent's certificate is created and its issue job queued before its first ordinary check-in.

Moving an already-enrolled agent into the group - from the group's Members tab, or from the agent's own settings - does exactly the same thing.

Modes

"Every member gets this certificate" can mean two different things, so a policy picks one when it is created. The mode cannot be changed afterwards: the two produce structurally different certificates, and switching would strand whatever the policy has already created.

Per agent

Each member gets its own certificate, with its own common name and its own order at the authority. The common name is a template resolved against each agent:

So {{hostname_short}}.example.com gives web-01.example.com on one host and web-02.example.com on the next. The form previews the result as you type.

A per-agent policy must contain a placeholder. Without one every member would resolve to the same name, and the form rejects it.

An agent controls the hostname it reports, so a substituted value is treated as untrusted input: anything that is not a plausible DNS label is replaced with a hyphen, and the whole result is re-checked as an RFC 1123 hostname before it becomes a certificate subject. A member whose hostname cannot produce a valid name is reported as not applied rather than ordering a nonsense certificate.

Shared

What a policy carries

The policy form has five sections. What is in them is the specification its certificates are built from.

Deploy target fields accept the same three placeholders as the common name, so a path, a script name or a certificate object name can vary per host. In a deploy target field they are not restricted to hostname-safe characters, and an unknown {{...}} is left in place rather than rejected.

What a policy edit does

Editing a policy changes what future applications produce. It does not rewrite certificates the policy has already created. Members pick the new specification up at their next issuance; to push it out now, reissue the affected certificates from the certificate list.

When a policy stops applying

A policy stops applying to an agent when the agent leaves the group, or the policy is disabled or deleted. Each policy decides in advance what happens to the certificate it created:

Either way, jobs that were queued but had not started are cancelled. Work already in progress, and certificates already deployed, are never retracted.

PSW Group certificates under retire stop renewing but must be revoked at PSW by hand

• PSW revocation is a server-side API call rather than an agent job.

Rollout state

A policy's page shows how far it has been applied across the group's current members, and what each member's certificate is doing. Applying is idempotent, so Apply now is always safe to press: members already covered are left alone.

A member can legitimately show as not applied, with the reason on the row:

Fix the cause and press Apply now.

Policy or certificate job?

Both exist and they answer different questions.