Regenerating certificates in a Puppet deployment

In some cases, you might need to regenerate the certificates and security credentials (private and public keys) that are generated by Puppet’s built-in PKI systems.

For example, you might have a Puppet primary server you need to move to a different network in your infrastructure, or you might have experienced a security vulnerability that makes existing credentials untrustworthy.

Note: There are other, more automated ways of doing this. We recommend using Bolt to regenerate certs when needed. See the Bolt documentation for more information. There is also a


                    puppetlabs-certregen

module but is not supported with Puppet Server 6.

Important: The information on this page describes the steps for regenerating certs in an open source Puppet deployment. If you use Puppet Enterprise do not use the information on this page, as it leaves you with an incomplete replacement and non-functional deployment. Instead, PE customers must refer to one of the following pages:


If your goal is to...	Do this...
Regenerate an agent’s certificate	Clear and regenerate certs for Puppet agents
Fix a compromised or damaged certificate authority	Regenerate the CA and all certificates
Completely regenerate all Puppet deployment certificates	Regenerate the CA and all certificates
Add DNS alt-names or other certificate extensions to your existing Puppet primary server	Regenerate the agent certificate of your Puppet primary server and add DNS alt-names or other certificates

Regenerate the agent certificate of your Puppet primary server and add DNS alt-names or other certificate extensions

This option preserves the primary server/agent relationship and lets you add DNS alt-names or certificate extensions to your existing primary server.

Revoke the Puppet primary server’s certificate and clean the CA files pertaining to it. Note that the agents won’t be able to connect to the primary server until all of the following steps are finished.
```
puppetserver ca clean --certname <CERTNAME_OF_YOUR_SERVER>
```
Remove the agent-specific copy of the public key, private key, and certificate-signing request pertaining to the certificate:
```
puppet ssl clean
```
Stop the Puppet primary server service:
```
puppet resource service puppetserver ensure=stopped
```
Note: The CA and server run in the same primary server so this also stops the CA.
After you’ve stopped the primary server and CA service, create a certificate signed by the CA and add DNS alt names (comma separated):
```
 puppetserver ca generate --certname <CERTNAME> --subject-alt-names <DNS ALT NAMES> --ca-client
```
Note:
- If you don’t want to add DNS alt names to your primary server, omit the --subject-alt-names <DNS ALT NAMES> option from the command above.
- Although this particular use of the generate command requires you to stop puppetserver service, all other uses of this command require the service to be running.

Restart the Puppet primary server service:

puppet resource service puppetserver ensure=running

Regenerate the CA and all certificates

CAUTION: This process destroys the certificate authority and all other certificates. It is meant for use in the event of a total compromise of your site, or some other unusual circumstance. If you want to preserve the primary server/agent relationship, regenerate the agent certificate of your Puppet primary server. If you just need to replace a few agent certificates, clear and regenerate certs for Puppet agents.

Step 1: Clear and regenerate certs on your primary Puppet server

On the primary server hosting the CA:

Back up the SSL directory, which is in /etc/puppetlabs/puppet/ssl/. If something goes wrong, you can restore this directory so your deployment can stay functional. However, if you needed to regenerate your certs for security reasons and couldn’t, get some assistance as soon as possible so you can keep your site secure.

Stop the agent service:

sudo puppet resource service puppet ensure=stopped

Stop the primary server service.

For Puppet Server, run:

sudo puppet resource service puppetserver ensure=stopped

Delete the SSL directory:
```
sudo rm -r /etc/puppetlabs/puppet/ssl
```
Regenerate the CA and primary server's cert:
```
sudo puppetserver ca setup
```
You will see this message: Notice: Signed certificate request for ca.

Start the primary server service by running:

sudo puppet resource service puppetserver ensure=running

Start the Puppet agent service by running this command:
```
sudo puppet resource service puppet ensure=running
```

Results

At this point:

You have a new CA certificate and key.
Your primary server has a certificate from the new CA, and it can field new certificate requests.
The primary server rejects any requests for configuration catalogs from nodes that haven’t replaced their certificates. At this point, it is all of them except itself.
When using any extensions that rely on Puppet certificates, like PuppetDB, the primary server won’t be able to communicate with them. Consequently, it might not be able to serve catalogs, even to agents that do have new certificates.

Step 2: Clear and regenerate certs for any extension

You might be using an extension, like PuppetDB or MCollective, to enhance Puppet. These extensions probably use certificates from Puppet’s CA in order to communicate securely with the primary Puppet server. For each extension like this, you’ll need to regenerate the certificates it uses.

Many tools have scripts or documentation to help you set up SSL, and you can often just re-run the setup instructions.

PuppetDB

We recommend PuppetDB users first follow the instructions in Step 3: Clear and regenerate certs for agents, below, because PuppetDB re-uses Puppet agents’ certificates. After that, restart the PuppetDB service. See Redo SSL setup after changing certificates for more information.

Step 3: Clear and regenerate certs for Puppet agents

To replace the certs on agents, you’ll need to log into each agent node and do the following steps.

Stop the agent service. On *nix:
```
sudo puppet resource service puppet ensure=stopped
```
On Windows, with Administrator privileges:
```
puppet resource service puppet ensure=stopped
```
Locate Puppet’s SSL directory and delete its contents.
The SSL directory can be determined by running puppet config print ssldir --section agent
Restart the agent service. On *nix:
```
sudo puppet resource service puppet ensure=running
```
On Windows, with Administrator privileges:
```
puppet resource service puppet ensure=running
```
When the agent starts, it generates keys and requests a new certificate from the CA primary server.
If you are not using autosigning, log in to the CA primary server and sign each agent node’s certificate request.
To view pending requests, run:
```
sudo puppetserver ca list
```
To sign requests, run:
```
sudo puppetserver ca sign --certname <NAME>
```
After an agent node’s new certificate is signed, it's retrieved within a few minutes and a Puppet run starts.

Results

After you have regenerated all agents’ certificates, everything will be fully functional under the new CA.

Note: You can achieve the same results by turning these steps into Bolt tasks or plans. See the Bolt documentation for more information.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.