Manage Puppet certificates as a certificate-authority (CA) lifecycle. On the primary server, inspect pending requests with puppetserver ca list, approve a verified node with puppetserver ca sign --certname <name>, invalidate a certificate with puppetserver ca revoke --certname <name>, and remove its CA-side files with puppetserver ca clean --certname <name>. On an agent, puppet ssl clean removes local SSL material so the next agent run can create a new request.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
This command split applies to Puppet 6 and later: puppetserver ca handles server-side CA work, while puppet ssl handles agent-side SSL files. The older puppet cert command was removed in Puppet 6.
As an Amazon Associate I earn from qualifying purchases.
What Puppet certificates do
Puppet uses certificates to verify the identity of nodes. The built-in CA on Puppet Server issues a certificate to an agent after the agent submits a certificate-signing request (CSR). Once the CSR is signed, the certificate identifies that agent when it requests catalogs from the primary server.
The certificate is tied to the agent’s Puppet certname. That name is an identity, not merely a display label: changing it can make the server treat the machine as a different node. Before approving a request, compare the requested certname with your inventory, DNS and ownership records, and the machine that is expected to use it.
#1 Best Overall
A normal first-connection sequence is:
- The agent starts with no signed certificate and creates a private key and CSR.
- The CSR reaches the primary server and appears as a pending request.
- An administrator verifies the identity and signs the CSR.
- The agent receives its certificate and uses it for authenticated catalog requests.
Puppet can also operate with an intermediate CA or an external CA. Those designs change who controls keys and policy, but the agent still needs a certificate that the Puppet Server trust chain accepts.
Current command map
| Task | Run on | Command | Effect |
|---|---|---|---|
| List pending CSRs | Primary server | puppetserver ca list |
Shows certificate requests waiting for approval. |
| Sign an approved CSR | Primary server | puppetserver ca sign --certname <name> |
Issues a certificate for the specified certname. |
| Revoke a certificate | Primary server | puppetserver ca revoke --certname <name> |
Invalidates the certificate for future authentication. |
| Revoke and remove CA files | Primary server | puppetserver ca clean --certname <name> |
Revokes each listed certificate and deletes its associated CA certificate file. |
| Remove local agent SSL material | Agent node | puppet ssl clean |
Deletes local SSL state so the next agent run generates a new key and CSR. |
Run these commands with the account and service permissions required by your Puppet installation. If your deployment uses a custom configuration directory or an external CA, confirm the exact command behavior against the Puppet release and CA integration in use.
Free tools Windows power users keep installed
One-click scans. No signup required.
How to sign a Puppet certificate
1. Find pending requests
On the primary server, list unsigned requests:
puppetserver ca listRecord the exact certname shown. Do not sign every request simply because it is present. A pending CSR proves that a key was generated and submitted; it does not, by itself, prove that the requester is an authorized machine.
2. Verify the node identity
Use your inventory and change records to confirm the machine, owner, environment and intended certname. Check for spelling differences, stale hosts and duplicate identities. If the request is unexpected, leave it unsigned while you investigate. Signing the wrong CSR gives that key a trusted identity and can allow the wrong machine to request catalogs as another node.
3. Sign the request
After approval, sign only the named request:
puppetserver ca sign --certname node01.example.netReplace the example with the certname printed by puppetserver ca list. The agent can use the certificate on its next run. If the agent is waiting for approval, run the normal agent command again after signing it.
Rank #2
- Used Book in Good Condition
4. Choose certificate lifetime deliberately
The CA sign operation supports a time-to-live (TTL). Set a lifetime that matches your rotation schedule and incident-response policy rather than choosing a long period by habit. Shorter lifetimes reduce the window of exposure after a key compromise but require dependable renewal automation and monitoring. Longer lifetimes reduce renewal frequency but leave a stolen key trusted for longer. Document the policy and test renewal before adopting a short TTL across production.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
5. Keep autosigning narrow
Autosigning can remove manual approval from bootstrap workflows, but an unrestricted policy may sign any CSR that reaches the CA. Use it only when you have a controlled provisioning process, an authoritative inventory and a way to prevent an unauthorized host from choosing a trusted certname. Manual review is safer for ad hoc or internet-exposed enrollment.
How to revoke or clean a certificate
Revoke when the certificate must no longer authenticate
For a compromised key, retired node or identity that must immediately lose trust, revoke the certificate on the primary server:
puppetserver ca revoke --certname node01.example.netRevocation is the trust decision. It tells Puppet that the certificate is no longer valid for authentication. Treat a suspected private-key disclosure as an incident: revoke the certificate, preserve relevant logs, and investigate where the key may have been copied.
Clean CA files when decommissioning or reissuing
Use clean when you also need to remove the CA-side certificate files associated with a certname:
puppetserver ca clean --certname node01.example.netThe clean operation revokes each listed certificate and deletes its associated CA certificate file. If a signed certificate does not exist, Puppet reports that condition rather than treating it as a fatal request error. Cleaning is therefore useful when retiring a node or preparing a complete reissue, but it is not a substitute for deciding whether the identity should be revoked.
Keep the distinction clear:
- Revoke: invalidate trust for a certificate.
- Clean: perform revocation as applicable and remove the related CA-side certificate file.
- Agent cleanup: remove the node’s local key, certificate and related SSL state so it can enroll again.
How to regenerate an agent certificate
Reissuing an agent normally requires cleanup on both sides. Cleaning only the server can leave the node presenting an old private key; cleaning only the node can leave an old CA record that complicates enrollment.
- Identify the exact certname. Confirm which node is being reissued and stop automated runs if necessary.
- Clean the CA-side record. On the primary server, run
puppetserver ca clean --certname <name>. Use a separatepuppetserver ca revokefirst if you need an explicit incident-response action or want the event recorded independently. - Log in to the agent. Run
puppet ssl cleanon the node. This removes its local SSL material, including the credentials needed to present the old identity. - Submit a new CSR. Run the agent normally. Because no usable local certificate remains, Puppet generates a new key and submits a certificate request.
- Review the new request. On the primary server, run
puppetserver ca listand verify that the new CSR has the expected certname and ownership. - Sign it. Run
puppetserver ca sign --certname <name>only after that review. - Run the agent again. The node should now retrieve its signed certificate and request a catalog. Check the agent and Puppet Server logs if the run does not complete.
Do not copy a private key from another node to “fix” enrollment. A certificate and its private key form one identity; sharing them defeats node authentication and creates an audit problem.
Regenerating the primary server certificate
A primary-server certificate change affects every agent connection. Puppet documents a specific order to avoid leaving the server with mismatched local SSL state:
- Clean the primary server certificate using the CA procedure appropriate to your Puppet installation.
- Run
puppet ssl cleanon the primary server to remove its local SSL material. - Stop Puppet Server.
- Generate the replacement certificate. If required by your topology, include the server’s DNS subject-alternative names (SANs) during generation.
- Start Puppet Server again.
- Verify that the replacement certificate contains the expected name and that the server presents the intended trust chain.
- Test an agent connection before restoring the normal run schedule.
Agents cannot connect while Puppet Server is stopped or while its certificate is being replaced. Schedule the interruption, communicate the maintenance window and keep a rollback plan for the server’s CA and SSL state. A server certificate that omits a name used by agents can cause connection failures even when the private key and CA are otherwise correct.
SANs and authorization extensions: security controls, not convenience flags
Subject-alternative-name (SAN) and authorization-extension signing are disabled by default. If an administrator enables them in ca.conf, every CSR containing those fields requires deliberate review.
Puppet warns that permitting SANs can allow an agent to impersonate another node name. A requester could present an alternate name that belongs to a more privileged or differently classified node. Enable SAN or authorization-extension signing only for a defined requirement, and document who reviews the requested values.
- Confirm why the extra name is needed and which service will use it.
- Check that the requested SAN does not identify another managed node.
- Limit who can change the CA configuration that enables these extensions.
- Record the approved names and the administrator who signed the CSR.
- Revisit the setting after the special deployment; leave it disabled when the requirement ends.
A certificate can be cryptographically valid and still be operationally unsafe if its identity fields authorize the wrong name.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteChoosing a CA architecture
Puppet’s built-in CA is not the only design. Compare the options by control, policy and failure behavior rather than by certificate issuance alone.
| Architecture | CA-key control | Intermediate CA | Approval and revocation | Renewal and outage considerations | Best fit |
|---|---|---|---|---|---|
| Puppet built-in CA | Controlled by the Puppet Server deployment. | Not required for the basic setup. | Managed with puppetserver ca; straightforward manual or controlled automated approval. |
Simple operational path, but the Puppet Server and its CA storage become important availability and backup dependencies. | Teams that want Puppet-native enrollment and a small operational boundary. |
| Intermediate CA under an organizational root | Root key can remain outside Puppet while Puppet uses a delegated intermediate. | Yes, by design. | Approval and revocation follow the organization’s PKI policy while Puppet handles node use of the issued chain. | Requires coordination among root, intermediate and Puppet operators; renewal and chain rollover need testing. | Organizations that centralize root trust but delegate issuance to infrastructure teams. |
| External CA | Owned by a separate PKI service or team. | May be required by that service’s hierarchy. | Defined by the external CA’s APIs and policy, with Puppet compatibility to verify for the exact release. | Availability, API access, key custody and renewal dependencies extend beyond Puppet Server. | Environments with an established enterprise PKI or a requirement to keep CA keys outside Puppet. |
Before selecting an external or intermediate design, decide who owns the CA key, which policy approves and revokes nodes, how certificate lifetime and renewal are automated, what happens during a CA outage, how events are audited, and whether SAN or authorization extensions are supported safely. Verify compatibility against the exact Puppet release; an architecture that works for one integration or version is not automatically supported for another.
Best Value
Certificate renewal and rotation planning
Certificate management is more reliable when renewal is treated as a scheduled lifecycle instead of an emergency command. Maintain an inventory containing each certname, owner, environment, issuance date, expiry or TTL policy, and current status. Monitor for approaching expiry and for requests that remain pending longer than the normal enrollment window.
When rotating a healthy node, choose a maintenance sequence that preserves one valid identity until the replacement is ready. For a full reissue, clean the CA-side record and the agent’s local SSL state, submit a CSR, review it, sign it and test a catalog run. For a suspected compromise, revoke first and investigate before allowing a new enrollment.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Back up CA material according to your security policy. A backup that exposes the CA private key is itself a trust risk, while a backup that omits necessary CA state may prevent recovery. Restrict access, record restoration procedures and test them in a non-production environment.
Troubleshooting certificate operations
The request is not listed
- Confirm that the agent is contacting the intended primary server and that its certname is the one you expect.
- Check network connectivity and Puppet Server logs for a rejected CSR.
- On the node, verify that
puppet ssl cleanwas not followed by a failed run that never reached the server. - Run the agent again only after correcting the underlying hostname, configuration or connectivity issue.
The request has the wrong certname
Do not sign it and do not attempt to rename it after issuance. Correct the agent’s certname configuration, remove the local SSL material with puppet ssl clean, submit a new CSR and review the new name. If the incorrect certificate was already signed, revoke or clean it on the primary server before reissuing.
The agent still presents an old certificate
Check that the node’s local SSL directory was actually cleaned and that the agent is running as the account and configuration you expect. Confirm that the server-side certificate was revoked or cleaned, then run the agent to create a new CSR. A new request should have a new key; never solve the problem by copying credentials from another node.
The agent cannot connect after the primary certificate change
Verify that Puppet Server is running, that the replacement certificate includes the server name agents use, and that the issuing CA is trusted by the agents. Check for DNS or hostname mismatches and inspect both server and agent logs. During a planned replacement, keep the outage window open until a test agent has completed authentication and a catalog request.
A SAN or authorization-extension request is rejected
These fields are disabled by default. Confirm whether the CA configuration permits them, whether the CSR contains the expected values, and whether the request has gone through the required identity review. Do not enable the feature merely to bypass a rejection; determine why the additional identity is needed and whether it creates an impersonation risk.
Quick Recap
Production checklist
- Use Puppet 6-and-later commands:
puppetserver caon the primary server andpuppet sslon agents. - Verify certname, ownership and expected host identity before signing any CSR.
- Keep autosigning restricted to a controlled provisioning policy.
- Choose TTLs that match renewal capability and incident-response requirements.
- Use revoke to invalidate trust and clean to remove associated CA-side files.
- For a complete agent reissue, clean the CA record and run
puppet ssl cleanon the node before submitting a new CSR. - Treat SAN and authorization-extension signing as exceptional, reviewed operations.
- Plan primary-server certificate changes as outages and test the replacement before normal runs resume.
- Document CA ownership, key custody, approval, revocation, renewal, backup and recovery procedures.
- For intermediate or external CAs, validate the full trust chain and integration against the exact Puppet release.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
