Puppet certificate management is a certificate-authority (CA) lifecycle: inspect a node’s certificate-signing request (CSR), approve and sign the expected identity, revoke certificates that must no longer authenticate, and clean CA and agent SSL files when a node is reissued or decommissioned. On Puppet 6 and later, use puppetserver ca on the primary server and puppet ssl on agents; the former puppet cert command was removed in Puppet 6.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
The safe sequence is to verify the certname and host ownership before signing, keep autosigning tightly controlled, revoke compromised credentials immediately, and clean both sides before regenerating an agent certificate. Puppet’s official documentation summarizes the purpose of this system: “Puppet uses certificates to verify the identity of nodes.”
As an Amazon Associate I earn from qualifying purchases.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →What Puppet certificates do
A Puppet agent does not simply identify itself with a hostname or a shared password. During its first check-in, it creates a private key and submits a CSR to the Puppet CA. After an administrator signs that request, the resulting certificate lets the agent prove its identity when it asks the primary server for a catalog. The CA therefore establishes which node name is allowed to act as that node.
The built-in CA is normally hosted by Puppet Server, although Puppet also supports an intermediate CA or an external CA when an organization needs a different trust boundary. Regardless of the CA design, the operational questions are the same: who controls the CA key, how requests are approved, how certificates are revoked, how long certificates live, and how renewal is automated.
#1 Best Overall
Current command split: server CA versus agent SSL
| Task | Run on | Command family | Purpose |
|---|---|---|---|
| List pending CSRs | Primary Puppet Server | puppetserver ca list |
Shows certificate requests waiting for approval. |
| Sign an approved request | Primary Puppet Server | puppetserver ca sign --certname <name> |
Issues a certificate for the exact certname after identity review. |
| Revoke a certificate | Primary Puppet Server | puppetserver ca revoke --certname <name> |
Invalidates the certificate so it can no longer authenticate. |
| Clean CA-side state | Primary Puppet Server | puppetserver ca clean --certname <name> |
Revokes listed certificates and removes their associated CA certificate files. |
| Remove local SSL material | Puppet agent node | puppet ssl clean |
Deletes the node’s local SSL material so the next run creates a new key and CSR. |
Keep the two command families distinct. puppetserver ca changes the CA’s records and trust decisions; puppet ssl changes the files held by one agent. Reissuing a node normally requires work on both sides.
Before changing a certificate
Certificate operations can disconnect an agent or invalidate a production identity. Establish the intended change before running a command.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11- Record the node’s current certname exactly, including capitalization and punctuation.
- Confirm that the request belongs to the expected host and owner. A familiar-looking name is not proof of ownership.
- Identify whether the node is new, being rebuilt, being renamed, decommissioned, or suspected of compromise.
- Schedule changes to a primary-server certificate because agents cannot connect while the server certificate is being replaced.
- Capture the current certificate and request state in your change record so an auditor can see what was approved, revoked, or reissued.
- Use a certificate lifetime that matches your rotation and incident-response policy rather than accepting an unexamined default.
How to sign a Puppet agent certificate
Signing is an approval step, not a routine cleanup command. Do it only after matching the CSR to a real node.
- Generate or locate the request. A new agent submits a CSR during its first check-in. If the node has just been cleaned, run the agent once to submit a fresh request, then stop and approve it before relying on a normal catalog run.
- List pending requests on the primary server. Run
puppetserver ca list. Read the certname and any request details shown by your Puppet Server release. - Validate the identity. Compare the certname with your inventory, the machine that initiated the request, and the change ticket. Reject or investigate an unexpected name; do not sign merely because a CSR is present.
- Sign the exact request. Run
puppetserver ca sign --certname <name>, replacing<name>with the reviewed certname. Puppet Server records the issued certificate in the CA state. - Set an intentional lifetime when required. The sign operation supports a TTL. A deployment with frequent rotation may choose a shorter lifetime than a stable, manually managed estate. Apply the value supported by the exact Puppet Server release and document the policy that justified it.
- Run the agent again. Once the certificate is signed, the node can authenticate and request its catalog. Check the run output and server logs for a successful TLS connection.
Why unrestricted autosigning is risky
Autosigning removes the manual approval gate. That can be acceptable only when a controlled enrollment policy, reliable inventory, and an independent way to authenticate the joining host are already in place. A broad autosign rule can turn possession of network access into permission to obtain a certificate for an arbitrary node name. Keep autosigning narrow, reviewable, and limited to names or workflows that your organization can verify.
Certificate lifetime, renewal, and rotation
A certificate’s TTL determines when the credential must be replaced; it does not replace an approval process. Align TTLs with the organization’s rotation schedule and incident-response requirements. Shorter lifetimes reduce the window in which a leaked key remains useful but increase renewal activity and the chance that an unavailable CA interrupts runs. Longer lifetimes reduce routine churn but leave more time for a compromised credential to be abused.
Rank #2
- Used Book in Good Condition
Document who monitors expiry, how renewal is triggered, and what happens if the primary server is unavailable. Test renewal before shortening lifetimes across a large fleet. A CA design that looks secure on paper can still cause outages if agents cannot reach it during renewal.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Revoke a certificate that must no longer authenticate
Use revocation when a key may be compromised, a node has been retired, or the identity must immediately lose trust. Revocation is a trust decision: it marks the certificate invalid for authentication.
- Confirm the affected certname and the reason for the emergency or retirement.
- On the primary server, run
puppetserver ca revoke --certname <name>. - Record the time, operator, certname, and incident or change reference.
- Remove or isolate the node itself if compromise is suspected; revoking the certificate does not clean the host or erase its private key.
- When the node will be rebuilt or reissued, continue with the CA-side and agent-side cleanup procedure below.
Revocation and cleanup are different. Revocation invalidates trust. It does not necessarily remove every CA-side file or delete the agent’s local key and certificate.
Clean CA files when decommissioning or reissuing a node
Use puppetserver ca clean --certname <name> when the CA-side certificate files should be removed as part of decommissioning or a controlled reissue. The clean operation revokes each listed certificate and deletes its associated CA certificate file. If a signed certificate does not exist, Puppet reports that condition instead of treating it as a fatal request error.
Cleaning is appropriate after you have confirmed that the old identity should not return. Do not use it as a substitute for investigating an unexpected CSR, and do not clean a production identity merely to silence an authentication error.
Regenerate an agent certificate
When an agent’s private key is lost, the node is rebuilt, its certname changes, or the old certificate must be replaced, clean the old identity on the server and then create a new request on the node.
- Decide whether the old certificate is still trusted. For a compromise or retirement, revoke it first. For a planned reissue, ensure no old process will continue using the identity.
- Clean the CA-side files. On the primary server, run
puppetserver ca clean --certname <name>. This removes the associated CA certificate file after revocation. - Clean the node’s SSL directory. On the agent, run
puppet ssl clean. This removes local SSL material, including the old certificate and key managed by Puppet. - Submit a new CSR. Run the Puppet agent so it generates fresh SSL material and requests a certificate. The run will remain unable to obtain a catalog until the request is approved.
- Inspect and sign the new request. On the primary server, run
puppetserver ca list, verify the new request’s identity, and sign it withpuppetserver ca sign --certname <name>. - Complete a normal run. Run the agent again and verify that it authenticates, receives its catalog, and completes without certificate errors.
Common reissue mistake: cleaning only one side
If the server still has the old CA record, a fresh agent request can conflict with the existing identity. If the agent still holds its old key and certificate, cleaning the server alone does not create a genuinely new credential. Treat reissue as a coordinated two-sided operation: CA-side cleanup followed by agent-side puppet ssl clean, a new CSR, approval, and a successful run.
Regenerate the primary Puppet Server certificate
Replacing the certificate used by the primary server affects every agent that connects to it. Puppet’s documented order is deliberate:
- Clean the primary server’s existing certificate from the CA state.
- Run
puppet ssl cleanon the primary server to remove its local SSL material. - Stop Puppet Server using the service manager for your installation.
- Generate a replacement certificate using the certificate-generation procedure for your Puppet release. If the server is reached through additional names, include the required DNS subject-alternative names (SANs) during generation.
- Start Puppet Server again.
- Verify the replacement certificate, certname, SANs, and service logs before allowing normal agent runs.
Agents cannot connect during the interruption, so perform this work in a maintenance window. A server certificate change is not the same as regenerating one agent: plan communication, confirm that the new name and trust chain match the deployment, and keep a recovery path if validation fails.
Free tools Windows power users keep installed
One-click scans. No signup required.
SANs and authorization extensions: security controls, not conveniences
Signing requests that contain SANs or authorization extensions is disabled by default. An administrator can enable these features in ca.conf, but doing so changes what a CSR can claim.
A SAN can let one certificate be accepted for another node name. Puppet warns that allowing SANs can enable an agent to impersonate another node. Enable SAN or authorization-extension signing only for a defined requirement, and review every CSR carrying those fields before signing. The review should establish why the extra identity is needed, who controls each name, and whether the certificate’s permissions are limited to that purpose.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting certificate operations
The CSR is not listed
Check that the agent actually ran after its SSL material was cleaned and that it is contacting the intended primary server. Confirm the certname used by the node and search the Puppet Server logs for the request. A request cannot be signed until it exists in the CA’s pending list.
The request has the wrong certname
Do not sign it and hope to correct the name later. An incorrect certname creates the wrong identity. Fix the node configuration or rebuild its SSL state, submit a new CSR with the intended name, and review that request before signing.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsThe agent still receives an authentication error after reissue
Check that the old certificate was revoked or cleaned on the CA, that puppet ssl clean removed the local material, and that the new CSR was signed. Verify that the agent is using the newly issued certificate rather than a stale copy and that Puppet Server has been restarted if the change involved the primary-server certificate.
Runs fail during a primary-server certificate change
That interruption is expected while Puppet Server is stopped. Wait until the replacement certificate has been generated, the service restarted, and the certificate and logs verified. Do not interpret connection failures during the maintenance window as evidence that every agent needs a new certificate.
Best Value
A clean command reports that a signed certificate does not exist
The clean operation reports nonexistent signed certificates rather than treating them as a fatal request error. Confirm the certname and inspect the remaining CA state. If the node still needs access, submit and approve a new CSR instead of assuming the absent file represents a valid credential.
Choosing a CA architecture
Puppet’s built-in CA is convenient when the Puppet Server team can own the CA key, approval workflow, availability, and renewal process. More regulated or segmented environments may use an intermediate CA or an external CA. The choice is architectural, not a command-line preference.
| Decision axis | Built-in Puppet CA | Intermediate CA | External CA |
|---|---|---|---|
| CA-key control | Managed with the Puppet Server deployment. | Root trust can remain separate while Puppet signs through an intermediate. | Held and governed by the external PKI owner. |
| Trust boundary | Centered on Puppet’s own CA state. | Separates root authority from Puppet’s issuing function. | Uses an organization-wide or service-specific PKI boundary. |
| Approval and revocation | Handled with Puppet Server CA commands and procedures. | Split between Puppet operations and the parent CA policy. | Must align Puppet enrollment and revocation with the external CA’s APIs and policy. |
| Lifetime and renewal | Configured around Puppet’s signing and agent workflows. | Requires coordination between intermediate and Puppet lifetimes. | Depends on the external CA’s automation and renewal interfaces. |
| Outage behavior | Depends on availability of the Puppet Server CA. | Adds dependencies on the parent trust chain. | Depends on external-CA availability, integration, and cached credentials. |
| Auditability | Use Puppet CA state, logs, and change records. | Correlate Puppet records with parent-CA records. | Use the external CA’s audit trail plus Puppet’s enrollment records. |
| SAN and authorization extensions | Disabled by default; enabling requires careful CSR review. | Must be allowed consistently across the chain. | Must be supported and constrained by the exact CA integration. |
Verify compatibility against the exact Puppet release before adopting an intermediate or external design. Key custody, certificate policy, renewal automation, availability, and incident response all change when the CA boundary moves outside Puppet Server.
Operational checklist
- Use
puppetserver ca listto inspect requests before signing. - Match every certname to an expected host and owner.
- Use
puppetserver ca sign --certname <name>only after that review. - Set certificate TTLs according to a documented rotation and response policy.
- Revoke compromised or retired certificates with
puppetserver ca revoke --certname <name>. - Use
puppetserver ca clean --certname <name>when CA files must be removed during decommissioning or reissue. - Run
puppet ssl cleanon the affected agent before requesting a replacement certificate. - Sign the new CSR before expecting a normal catalog run.
- Treat SAN and authorization-extension requests as exceptional and review them individually.
- Schedule primary-server certificate replacement and verify the service before resuming agents.
- Keep approvals, revocations, TTL decisions, and certificate changes in an auditable record.
What replaced puppet cert?
For Puppet 6 and later, the old puppet cert command is no longer the interface to use. Server-side CA administration moved to puppetserver ca, while agent-side certificate and SSL cleanup uses puppet ssl. Update runbooks, shell scripts, and operator training rather than attempting to install the removed command.
Quick Recap
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.
