SSL directory (ssldir)

Puppet stores its certificate infrastructure in the SSL directory (ssldir) which has a similar structure on all Puppet nodes, whether they are agent nodes, primary Puppet servers, or the certificate authority (CA) server.

Location

By default, the ssldir is a subdirectory of the confdir.

You can change its location using the ssldir setting in the puppet.conf file. See the Configuration reference for more information.
Note: The content of the ssldir is generated, grows over time, and is relatively difficult to replace. Some third-party Puppet packages for Linux place the ssldir in the cache directory (vardir) instead of the confdir. When a distro changes the ssldir location, it sets ssldir in the $confdir/puppet.conf file, usually in the [main] section.

To see the location of the ssldir on one of your nodes, run: puppet config print ssldir

Contents

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

The ssldir on an agent or primary server contains:

  • A private key: private_keys/<certname>.pem

  • A signed certificate: certs/<certname>.pem

  • A copy of the CA certificate: certs/ca.pem

  • A copy of the certificate revocation list (CRL): crl.pem

  • A copy of its sent CSR: certificate_requests/<certname>.pem

Tip: Puppet does not save its public key to disk, because the public key is derivable from its private key and is contained in its certificate. If you need to extract the public key, use $ openssl rsa -in $(puppet config print hostprivkey) -pubout

If these files don’t exist on a node, it's because they are generated locally or requested from the CA server.

Agent and primary server credentials are identified by certname, so an agent process and a primary server process running on the same server can use the same credentials.

The ssldir for the Puppet CA, which runs on the CA server, contains similar credentials: private and public keys, a certificate, and a primary server copy of the CRL. It maintains a list of all signed certificates in the deployment, a copy of each signed certificate, and an incrementing serial number for new certificates. To keep it separated from general Puppet credentials on the same server, all of the CA’s data is stored in the ca subdirectory.

The ssldir directory structure

All of the files and directories in the ssldir directory have corresponding Puppet settings, which can be used to change their locations. Generally, though, don't change the default values unless you have a specific problem to work around.

Ensure the permissions mode of the ssldir is 0771. The directory and each file in it is owned by the user that Puppet runs as: root or Administrator on agents, and defaulting to puppet or pe-puppet on a primary server. Set up automated management for ownership and permissions on the ssldir.

The ssldir has the following structure. See the Configuration reference for details about each puppet.conf setting listed:
  • ca directory (on the CA server only): Contains the files used by Puppet’s certificate authority. Mode: 0755. Setting: cadir.
    • ca_crl.pem: The primary server 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 a primary server or agent certificate; it can only be used to sign certificates. Mode: 0644. Setting: cacert.
    • ca_key.pem: The CA’s private key, and one of the most security-critical files in the Puppet certificate infrastructure. Mode: 0640. Setting: cakey.
    • ca_pub.pem: The CA’s public key. Mode: 0644. Setting: capub.
    • inventory.txt: A list of the certificates the CA signed, along with their serial numbers and validity periods. Mode: 0644. Setting: cert_inventory.
    • requests (directory): Contains the certificate signing requests (CSRs) that have been received but not yet signed. The CA deletes CSRs from this directory after signing them. Mode: 0755. Setting: csrdir.
      • <name>.pem: CSR files awaiting signing.
    • serial: A file containing the serial number for the next certificate the CA signs. 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: Signed certificate files.
  • certificate_requests (directory): Contains CSRs generated by this node in preparation for submission to the CA. CSRs stay 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 signed certificates present on the node. This includes the node’s own certificate, and a copy of the CA certificate for 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 agents or primary servers. 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 the node's private key and, on the CA, private keys created by the puppetserver ca generate command. It never contains 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 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.