Puppet Server CA commands

Sections

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 certificates.

CA subcommands

See Subcommands to view the subcommands for the puppetserver ca command.

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

The puppetserver-ca CLI tool is 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.

Upgrading

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.