Open source Puppet documentation

This information describes the supported and tested configurations for external CAs in this version of Puppet. If you have an external CA use case that isn’t listed here, contact Puppet so we can learn more about it.

Supported external CA configurations

This version of Puppet supports some external CA configurations, however not every possible configuration is supported.

We fully support the following setup options:
  • Single CA which directly issues SSL certificates.

  • Puppet Server functioning as an intermediate CA.

Fully supported by Puppet means:
  • If issues arise that are considered bugs, we'll fix them as soon as possible.

  • If issues arise in any other external CA setup that are considered feature requests, we’ll consider whether to expand our support.

Option 2: Single CA

When Puppet uses its internal CA, it defaults to a single CA configuration. A single externally issued CA can also be used in a similar manner.



This is an all or nothing configuration rather than a mix-and-match. When using an external CA, the built-in Puppet CA service must be disabled and cannot be used to issue SSL certificates.

Note: Puppet cannot automatically distribute certificates in this configuration.

Puppet Server

Configure Puppet Server in three steps:
  • Disable the internal CA service.

  • Ensure that the certname will not change.

  • Put certificates and keys in place on disk.

  1. To disable the internal CA, edit the Puppet Server /etc/puppetlabs/puppetserver/services.d/ca.cfg file to comment and uncomment the appropriate settings:
    # To enable the CA service, leave the following line uncommented 
    puppetlabs.services.ca.certificate-authority-service/certificate-authority-service
    # To disable the CA service, comment out the above line and uncomment the line below
    #puppetlabs.services.ca.certificate-authority-disabled-service/certificate-authority-disabled-service
    puppetlabs.trapperkeeper.services.watcher.filesystem-watch-service/filesystem-watch-service
  2. Set a static value for the certname setting in puppet.conf:
    [master]
    certname = puppetserver.example.com
    
    Setting a static value prevents any confusion if the machine's hostname changes. The value must match the certname you’ll use to issue the server's certificate, and it must not be blank.
  3. Put the credentials from your external CA on disk in the correct locations. These locations must match what’s configured in your webserver.conf file.
    If you haven’t changed those settings, run the following commands to find the default locations.
    CredentialFile location
    Server SSL certificate puppet config print hostcert --section master
    Server SSL certificate private key puppet config print hostprivkey --section master
    Root CA certificate puppet config print localcacert --section master
    Root certificate revocation list puppet config print hostcrl --section master

    If you’ve put the credentials in the correct locations, you shouldn’t need to change any additional settings.

Puppet agent

You don’t need to change any settings. Put the external credentials into the correct filesystem locations. You can run the following commands to find the appropriate locations.

CredentialFile location
Agent SSL certificatepuppet config print hostcert --section agent
Agent SSL certificate private keypuppet config print hostprivkey --section agent
Root CA certificatepuppet config print localcacert --section agent
Root certificate revocation listpuppet config print hostcrl --section agent

General notes and requirements

PEM encoding of credentials is mandatory

Puppet expects its SSL credentials to be in .pem format.

Normal Puppet certificate requirements still apply

Any Puppet Server certificate must contain the DNS name, either as the Subject Common Name (CN) or as a Subject Alternative Name (SAN), that agent nodes use to attempt contact with the server.

Client DN Authentication

Puppet Server is hosted by a Jetty web server; therefore. For client authentication purposes, Puppet Server can extract the distinguished name (DN) from a client certificate provided during SSL negotiation with the Jetty web server.

The use of an X-Client-DN request header is supported for cases where SSL termination of client requests needs to be done on an external server. See External SSL Termination with Puppet Server for details.

Web Server Configuration

The webserver.conf file for Puppet Server can be used to configure Jetty.  Several ssl- settings should be added to the webserver.conf file to enable the web server to use the correct SSL configuration:

  • ssl-cert: The value of puppet master --configprint hostcert. Equivalent to the ‘SSLCertificateFile’ Apache config setting.

  • ssl-key: The value of puppet master --configprint hostprivkey. Equivalent to the ‘SSLCertificateKeyFile’ Apache config setting.

  • ssl-ca-cert: The value of puppet master --configprint localcacert. Equivalent to the ‘SSLCACertificateFile’ Apache config setting.

  • ssl-cert-chain: Equivalent to the ‘SSLCertificateChainFile’ Apache config setting. Optional.

  • ssl-crl-path: The path to the CRL file to use. Optional.

An example webserver.conf file might look something like this:
webserver: { 
 client-auth : want  
 ssl-host    : 0.0.0.0  
 ssl-port    : 8140  
 ssl-cert    : /path/to/master.pem  
 ssl-key     : /path/to/master.key  
 ssl-ca-cert : /path/to/ca_bundle.pem  
 ssl-cert-chain : /path/to/ca_bundle.pem  
 ssl-crl-path : /etc/puppetlabs/puppet/ssl/crl.pem
}
For more information on these settings, see Configuring the Web Server Service.

Restart Required

After the above changes are made to Puppet Server’s configuration files, you’ll have to restart the Puppet Server service for the new settings to take effect.

Back to top