Open source Puppet documentation

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.

Syntax:
puppetserver ca <action> [options]
Most commands require a target to be specified with the --certname flag. For example:
puppetserver ca sign --certname foo.example.com
The target is a comma separated list of names that act on multiple certificates at once. 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 isused to sign and revoke certificates is tightly restricted. In Puppet 6, the Puppet 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 specially reserved, and Puppet Server will refuse to sign other CSRs requesting it, even with allow-authorization-extensions set to true. If you need a certificate with this extension, it can be generated 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.

Upgrading

The Puppet CA commands are available in Puppet 5, but to use it, 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.

Back to top