Want to improve your security posture? The 2019 State of DevOps Report tells you how.
Get the report

Regenerate certificates in monolithic installations

Puppet Enterprise 2019.1

Expand menu Collapse menu
Open menu Close menu
  1. Delete and recreate the certificate authority
  2. Regenerate compiler certificates
  3. Regenerate agent certificates
  4. Regenerate master certificates

Regenerating certificates and security credentials—both private and public keys—created by the built-in PE certificate authority can help ensure the security of your installation in certain cases.

The process for regenerating certificates varies depending on your goal.
If your goal is to...Do this...
Upgrade to the intermediate certificate architecture introduced in Puppet 6.0.
Complete these tasks in order:

  1. Delete and recreate the certificate authority

  2. Regenerate compiler certificates, if applicable

  3. Regenerate agent certificates

Fix a compromised or damaged certificate authority.
Fix a compromised compiler certificate or troubleshoot SSL errors on compilers.Regenerate compiler certificates
Fix a compromised agent certificate or troubleshoot SSL errors on agent nodes.Regenerate agent certificates
Specify a new DNS alt name or other trusted data.Regenerate master certificates

Delete and recreate the certificate authority

Recreate the certificate authority only if you're upgrading to the new certificate architecture introduced in Puppet 6.0, or if your certificate authority was compromised or damaged beyond repair.

Before you begin

The puppet infrastructure run command leverages built-in Bolt plans to automate certain management tasks. To use this command, you must be able to connect using SSH from your master to any nodes that the command modifies. You can establish an SSH connection using key forwarding, a local key file, or by specifying keys in .ssh/config on your master. For more information, see Bolt OpenSSH configuration options.

CAUTION: Replacing your certificate authority invalidates all existing certificates in your environment. Complete this task only if and when you're prepared to regenerate certificates for both your infrastructure nodes and your entire agent fleet.
On your master logged in as root, run puppet infrastructure run rebuild_certificate_authority caserver=<CA_SERVER_HOSTNAME>
Tip: If your master operates as your CA server, specify caserver=localhost. Running the command with localhost avoids the requirement to set up SSH between your master and itself.
The SSL and cert directories on your CA server are backed up with "_bak" appended to the end, CA files are removed and certificates are rebuilt, and a Puppet run completes.

Regenerate compiler certificates

Regnerate compiler certificates to fix a compromised certificate or troubleshoot SSL errors on compilers, or if you recreated your certificate authority.

Before you begin

Configure Puppet Server with allow-subject-alt-names in the certificate-authority section of ca.conf.

  1. If you did not recreate your certificate authority, you must log into your master as root and remove the compiler certificate: puppetserver ca clean --certname <COMPILE_MASTER_HOSTNAME>
  2. Log into the compiler as root and back up the /etc/puppetlabs/puppet/ssl/ directory: 
    cp -r /etc/puppetlabs/puppet/ssl/ /etc/puppetlabs/puppet/ssl_bak/
  3. Stop the Puppet agent, Puppet Server, and PXP agent services.
    puppet resource service puppet ensure=stopped
puppet resource service pe-puppetserver ensure=stopped
puppet resource service pxp-agent ensure=stopped
  4. Delete the compiler SSL directory: rm -rf /etc/puppetlabs/puppet/ssl
  5. Remove the compiler cached catalog: rm -f /opt/puppetlabs/puppet/cache/client_data/catalog/<CERTNAME>.json
  6. Adjust DNS alt names and trusted data, as needed.
  7. Re-start the Puppet agent service: puppet resource service puppet ensure=running

    After the agent starts, it automatically generates keys and request a new certificate from the Puppet CA.

  8. Log into your master as root and sign the compiler's certificate request: puppetserver ca sign --certname <COMPILE_MASTER_HOSTNAME>
  9. Log into your compiler as root and run Puppet: puppet agent -t

PE performs a full catalog run, and the compiler resumes its role in your deployment.

Regenerate agent certificates

Regenerate agent certificates to fix a compromised certificate or troubleshoot SSL errors on agents, or if you recreated your certificate authority.

Before you begin

The puppet infrastructure run command leverages built-in Bolt plans to automate certain management tasks. To use this command, you must be able to connect using SSH from your master to any nodes that the command modifies. You can establish an SSH connection using key forwarding, a local key file, or by specifying keys in .ssh/config on your master. For more information, see Bolt OpenSSH configuration options.

On your master logged in as root, run puppet infrastructure run regenerate_agent_certificate agent=<AGENT_HOSTNAME> caserver=<CA_SERVER_HOSTNAME>
Note: Your CA server is usually your master.
You can specify this optional parameter:
  • dns_alt_names – Comma-separated list of alternate DNS names to be added to the certificates generated for your agents.
    Important: To use the dns_alt_names parameter, you must configure Puppet Server with allow-subject-alt-names in the certificate-authority section of ca.conf.
The agent's SSL directory is backed up to /etc/puppetlabs/puppet/ssl_bak, its certificate is regenerated and signed, a Puppet run completes, and the agent resumes its role in your deployment.

Regenerate master certificates

Regenerate master certificates to specify a new DNS alt name or other trusted data.

Before you begin

The puppet infrastructure run command leverages built-in Bolt plans to automate certain management tasks. To use this command, you must be able to connect using SSH from your master to any nodes that the command modifies. You can establish an SSH connection using key forwarding, a local key file, or by specifying keys in .ssh/config on your master. For more information, see Bolt OpenSSH configuration options.

On your master logged in as root, run puppet infrastructure run regenerate_master_certificate.
You can specify this optional parameter:
  • dns_alt_names – Comma-separated list of alternate DNS names to be added to the certificates generated for your master.
    Important: To use the dns_alt_names parameter, you must configure Puppet Server with allow-subject-alt-names in the certificate-authority section of ca.conf.
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.