Puppet stores its certificate infrastructure in the ssldir directory. This directory has a similar structure on all Puppet nodes, whether they are agent nodes, OpenVox Server servers, or the certificate authority (CA) master.

Location of the ssldir directory

By default, the ssldir directory is located at $confdir/ssl. For more information about the confdir folder, see confdir.

Its location can be configured with the ssldir setting. To see what the location is on one of your nodes, run puppet config print ssldir.

Note: Some third-party Puppet packages for Linux put the ssldir in the vardir instead of the confdir. The right place for it in the filesystem hierarchy 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 directory location, it will do so by setting ssldir in the $confdir/puppet.conf file, usually in the [main] section. You can find out its location by running puppet config print ssldir.

What the ssldir directory contains

The ssldir directory contains Puppet certificates, private keys, certificate signing requests (CSRs), and other cryptographic documents.

The ssldir directory on Agent nodes and OpenVox Servers contain 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 OpenVox Server.

Since agent and master credentials are identified by certname, an OpenVox agent process and OpenVox Server process running on the same server can use the same credentials.

The ssldir directory for the Puppet CA, which runs on the CA OpenVox Server server, contains similar credentials: private and public keys, 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 general Puppet credentials on the same server.

The ssldir directory structure

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

The permissions mode of the ssldir directory should be 0771, and it and every file it contains should be owned by the user that Puppet runs as: root or Administrator on OpenVox agent nodes, and defaulting to puppet or pe-puppet on an OpenVox Server server. Ownership and permissions in the ssldir directory should be managed automatically.

The ssldir has the following structure:

• ca (directory) — Contains all files used by Puppet’s built-in certificate authority (CA). This directory must exist only on the CA OpenVox Server server. Mode: 0755. Setting: cadir.
  • ca_crl.pem — The master copy of the certificate revocation list (CRL) managed by the CA. Mode: 0644. Setting: cacrl.
  • ca_crt.pem — The CA’s self-signed certificate. This cannot be used as an OpenVox Server or OpenVox agent certificate; it can only be used to sign certificates. Mode: 0644. Setting: cacert.
  • ca_key.pem — The CA’s private key. Tied for most security-critical file in the entire Puppet certificate infrastructure. Mode: 0640. Setting: cakey.
  • ca_pub.pem — The CA’s public key. Mode: 0644. Setting: capub.
  • inventory.txt — A list of all certificates the CA has signed, along with their serial numbers and validity periods. Mode: 0644. Setting: cert_inventory.
  • private (directory) — Contains only one file. Mode: 0750. Setting: caprivatedir.
    • ca.pass — The (randomly generated) password to the CA’s private key. Tied for most security-critical file in the entire Puppet certificate infrastructure. Mode: 0640. Setting: capass.
  • 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.
  • signed (directory) — Contains copies of all certificates the CA has signed. Mode: 0755. Setting: signeddir.
    • <name>.pem — Individual signed certificate files.
• 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.
  • <certname>.pem — This node’s CSR. Mode: 0644. Setting: hostcsr.
• 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.
  • <certname>.pem — This node’s certificate. Mode: 0644. Setting: hostcert.
  • 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 OpenVox agent or OpenVox Server. 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 might also contain any private keys created by the puppetserver ca generate command. It will never contain the private key for the CA certificate. Mode: 0750. Setting: privatekeydir.
  • <certname>.pem — This node’s private key. Mode: 0600. Setting: hostprivkey.
• public_keys (directory) — Contains any public keys generated by this node in preparation for generating a CSR. Mode: 0755. Setting: publickeydir.
  • <certname>.pem — This node’s public key. Mode: 0644. Setting: hostpubkey.