Puppet Server CA commands

We've updated our documentation to remove harmful terminology.

Puppet Server has a puppetserver ca command that performs certificate authority (CA) tasks like signing and revoking certificates. Most of its actions are performed by making HTTP requests to Puppet Server’s CA API, specifically the certificate_status endpoint. You must have Puppet Server running in order to sign or revoke certs.

CA subcommands

The following actions are available as subcommands for the puppetserver ca command:

  • clean: Revoke certificates and remove related files from the CA.

  • generate: Create a certificate signed by the CA.

  • import: Import the CA’s key, certificates, and certificate revocation lists (CRLs).

  • list: List all certificate requests.

  • migrate: Migrate the contents of the CA directory from its current location to /etc/puppetlabs/puppetserver/ca. Adds a symlink at the old location for backwards compatibility.

  • revoke: Revoke a certificate.

  • setup: Generate a root and intermediate signing CA for Puppet Server.

  • sign: Sign a certificate.

    • Use the -ttl flag with sign subcommand to send the ttl to the CA. The signed certificate's notAfter value is the current time and the ttl. The values are valid puppet.conf ttl values, for example, 1y = 1 year, 31d = 31 days.
puppetserver ca <action> [options]
Most commands require a target to be specified with the --certname flag. For example:
puppetserver ca sign --certname cert.example.com
The target is a comma separated list of names that act on multiple certificates at one time.

You can supply a custom configuration file to all subcommands using the --config option. This allows you to point the command at a custom puppet.conf, instead of the default one. You can use this option to configure ad hoc actions when you do not want the values in your usual puppet.conf.

Some actions have additional options. Run puppetserver ca help for details.

These commands are shipped as a gem alongside Puppet Server. It can be updated between releases to pick up improvements and bug fixes. To update the gem, run:
/opt/puppetlabs/puppet/bin/gem install -i /opt/puppetlabs/puppet/lib/ruby/vendor_gems puppetserver-ca

API authentication

For security, access to the certificate_status API endpoint that is issued to sign and revoke certificates is tightly restricted. In Puppet 6, the primary server’s certificate is generated with a special extension which is added to the allowlist in the auth.conf entries for the certificate_status and certificate_statuses endpoint. This extension is reserved, and Puppet Server refuses to sign other CSRs requesting it, even with allow-authorization-extensions set to true. If you need a certificate with this extension, you can generate it offline by stopping Puppet Server and running puppetserver ca generate --ca-client --certname <name>. API authentication is required for regenerating the primary server cert. For details on cert regeneration, see Regenerating certificates in a Puppet deployment.


The Puppet CA commands are available in Puppet 5, but to use them, you must update Puppet Server’s auth.conf to include a rule allowing the primary server’s certname to access the certificate_status and certificate_statuses endpoints. If you’re upgrading from Puppet 5 to Puppet 6 and you are not regenerating your CA, you must allow the primary server’s certname in your auth.conf file. See Puppet Server configuration files: auth.conf for details on how to use auth.conf.

The following example shows how to allow the CA commands to access the certificate_status endpoint:
  match-request: {
 path: "/puppet-ca/v1/certificate_status"  
     type: path        
     method: [get, put, delete]    
   allow: primaryserver.example.com  
   sort-order: 500    
   name: "puppetlabs cert status"

Signing certificates with subject alternative names or auth extensions

With the removal of puppet cert sign, Puppet Server’s CA API can sign certificates with subject alternative names (SANs) or auth extensions, which was previously disallowed. This option is disabled by default for security reasons, but you can turn it on by setting allow-subject-alt-names or allow-authorization-extensions to true in the certificate-authority section of Puppet Server’s config (usually located in ca.conf). After these have been configured, you can use puppetserver ca sign --certname <name> to sign certificates with these additions.

How helpful was this page?

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.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.