Regenerating certs for the Puppet Enterprise console

This version is no longer supported, maintained, or updated. For current versions, see Puppet Enterprise support lifecycle.

The major components of Puppet Enterprise (the Puppet master, PuppetDB, and PE console) contain SSL certificates and security credentials (private and public keys) that are generated by PE’s built-in certificate authority (CA). The following document provides instructions on regenerating the cert and security credentials for the PE console.

Regenerating certificates and security credentials for the PE console involves the following steps:

  1. Back up SSL directories on the PE console server.
  2. Shut down all PE-related services on the PE console server.
  3. Clear and regenerate the Puppet agent certs for the PE console server.
  4. Copy the new certs and security credentials to the appropriate PE console and services directories and set permissions.
  5. Restart all PE-related services on the PE console server.

Important: This document applies to the certs and security credentials for the PE console server only. If you’ve experienced an unforeseen security vulnerability and need to regenerate all the certificates and security credentials in your infrastructure, refer to Regenerating certs and security credentials in split Puppet Enterprise deployments for complete instructions.

In addition, this guide also applies to split installations only. On monolithic installs, PuppetDB shares an agent cert and security credentials with the Puppet master and the PE console. For a monolithic install, you must regenerate all certs and security credentials.

Clear and regenerate certs for the PE console

To clear and regenerate certs on your PE console server:


  • You must be logged in as a root, (or in the case of Windows agents, as an account with Administrator Privileges) to make these changes.

  • If you encounter any errors during steps that involve service stop/start, rm, cp, or chmod commands, you should diagnose these before continuing, as the success each step is very important to the success of the next step.

  • In the following instructions, when <CERTNAME> is used, it refers to the Puppet agent’s certname. To find this value, run puppet config print certname before starting. <CA SERVER HOSTNAME> refers to the server that is your certificate authority—depending on your PE configuration, this may or may not be the Puppet master.

  • Unless otherwise indicated, all commands are run on the PE console server.

  1. On the PE console, back up the following directories:

    • /etc/puppetlabs/puppet/ssl/

    • /opt/puppetlabs/server/data/console-services/certs

  2. On the PE console, shut down all PE-related services with the following commands:

     puppet resource service puppet ensure=stopped
     puppet resource service pe-console-services ensure=stopped
     puppet resource service pe-nginx ensure=stopped
     puppet resource service mcollective ensure=stopped
  3. On the PE console, delete the Puppet agent’s SSL cert and security credentials.

     rm -rf /etc/puppetlabs/puppet/ssl/*
  4. On the Puppet master, or CA server, remove the cert for the PE console node.

     puppet cert clean <CERTNAME>
  5. On the Puppet master, remove the cached catalog.

     rm -f /opt/puppetlabs/puppet/cache/client_data/catalog/<CERTNAME>.json
  6. On the PE console, generate security credentials and request a new certificate from the CA Puppet master. These certs will end up in /etc/puppetlabs/puppet/ssl.

     puppet agent --test --no-daemonize --noop

    Note: This agent run will not complete successfully, but it is necessary to set up the agent certificate for the node. You will see some errors about node definition and the inability to execute http requests due to the console being offline. You can ignore these.

  7. On the PE console, purge the console-services directory.

     rm -rf /opt/puppetlabs/server/data/console-services/certs/*
  8. On the PE console, copy the Puppet agent’s cert and security credentials to the console-services cert directory.

     cp /etc/puppetlabs/puppet/ssl/certs/<CERTNAME>.pem /opt/puppetlabs/server/data/console-services/certs/<CERTNAME>.cert.pem
     cp /etc/puppetlabs/puppet/ssl/public_keys/<CERTNAME>.pem /opt/puppetlabs/server/data/console-services/certs/<CERTNAME>.public_key.pem
     cp /etc/puppetlabs/puppet/ssl/private_keys/<CERTNAME>.pem /opt/puppetlabs/server/data/console-services/certs/<CERTNAME>.private_key.pem
  9. Create the console-services .pk8 cert.

     cd /opt/puppetlabs/server/data/console-services/certs/
     openssl pkcs8 -topk8 -inform PEM -outform DER -in /opt/puppetlabs/server/data/console-services/certs/<CERTNAME>.private_key.pem -out /opt/puppetlabs/server/data/console-services/certs/<CERTNAME>.private_key.pk8 -nocrypt
     chown -R pe-console-services:pe-console-services /opt/puppetlabs/server/data/console-services/certs/
  10. On the PE console, ensure the PE console can access the new credentials.

    chown -R pe-console-services:pe-console-services /opt/puppetlabs/server/data/console-services/certs
  11. On the PE console, restart all PE-related services with the following commands:

    puppet resource service puppet ensure=running
    puppet resource service pe-nginx ensure=running
    puppet resource service pe-console-services ensure=running
    puppet resource service mcollective ensure=running

Note: If you want to regenerate the DH param files, see Configuring the PE console to use a custom Diffie-Hellman file, which contains instructions on regenerating files. You will need to delete any DH param files that are in place (at /etc/puppetlabs/nginx/<PROXY-CUSTOM-dhparam>.pem) before regenerating them.

How helpful was this page?
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.