Directories: The SSLdir

Puppet stores its certificate infrastructure in the ssldir. This directory is used with a similar layout on all Puppet nodes, whether they are acting as agent nodes, Puppet master servers, or the CA Puppet master.

Note: Some third-party Puppet packages for Linux put the ssldir in the vardir instead of the confdir. (The right place for it under the FHS is debatable; the contents are automatically generated and will tend to grow, but are also important, relatively difficult to replace, and can be considered configuration.)

If a distro changes the ssldir location, it will do so by setting ssldir in the $confdir/puppet.conf file, usually in the [main] section. You can find out for sure by printing the ssldir setting value.

Summary of Contents

Agent nodes and Puppet masters require a private key (private_keys/<certname>.pem), a public key (public_keys/<certname.pem>), a signed certificate (certs/<certname>.pem), a copy of the CA certificate (certs/ca.pem), and a copy of the certificate revocation list (CRL) (crl.pem). They usually also retain a copy of their CSR after submitting it (certificate_requests/<certname>.pem). If these files don’t exist, they are either generated locally or requested from the CA Puppet master.

Since agent and master credentials are identified by certname, a Puppet agent process and Puppet master process running on the same server may use the same credentials.

The Puppet CA, which runs on the CA Puppet master server, requires similar credentials (private/public key, certificate, master copy of the CRL). It also maintains a list of all signed certificates in the deployment, a copy of each signed certificate, and an incrementing serial number for new certificates. All of the CA’s data is stored in the ca subdirectory, to keep it separated from any normal Puppet credentials on the same server.

All of the files and directories in the ssldir have corresponding Puppet settings, which can be used to individually change their locations. However, this is generally not recommended.

Detailed Contents

The permissions mode of the ssldir should be 0771, and it and every file it contains should be owned by the user Puppet runs as (i.e., root or Administrator on Puppet agent nodes and defaulting to puppet or pe-puppet on a Puppet master server). Ownership and permissions in the ssldir are generally managed automatically.

requests(directory) — Contains certificate signing requests (CSRs) that were received but have not yet been signed. The CA deletes CSRs from this directory after signing them. Mode: 0755. Setting: csrdir.

<name>.pem — Individual CSR files.

serial — A file containing the serial number for the next certificate the CA will sign. This is incremented with each new certificate signed. Mode: 0644. Setting: serial.

certificate_requests(directory) — Contains any CSRs generated by this node in preparation for submission to the CA. CSRs persist in this directory even after they have been submitted and signed. Mode: 0755. Setting: requestdir.

certs(directory) — Contains any signed certificates present on this node. This includes the node’s own certificate, as well as a copy of the CA certificate (for use when validating certificates presented by other nodes). Mode: 0755. Setting: certdir.

ca.pem — A local copy of the CA certificate. Mode: 0644. Setting: localcacert.

crl.pem — A copy of the certificate revocation list (CRL) retrieved from the CA, for use by Puppet agent or Puppet master. Mode: 0644. Setting: hostcrl.

private(directory) — Usually does not contain any files. Mode: 0750. Setting: privatedir.

password — The password to a node’s private key. Usually not present. The conditions in which this file would exist are not defined. Mode: 0640. Setting: passfile.

private_keys(directory) — Contains any private keys present on this node. This should generally only include the node’s own private key, although on the CA it may also contain any private keys created by the puppet cert generate command. It will never contain the private key for the CA certificate. Mode: 0750. Setting: privatekeydir.