Puppet Server CA commands

This version is out of date. For current versions, see Puppet packages and versions.

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.

  • revoke: Revoke a certificate.

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

  • sign: Sign a certificate.

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 with the --config option. 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 master’s certificate is generated with a special extension which is whitelisted 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 master 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 master’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 whitelist the master’s certname. 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: master.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.

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