Troubleshooting SSL issues

Among the most frustrating issues, especially for new users, are problems with the agent's SSL handshake. Such errors are especially troublesome because Puppet cannot always offer very helpful analysis in its logs—the problems occur in the SSL library functions, and the application cannot examine the circumstances.

Consider the following output for the --test command:

root@agent# puppet agent --testWarning: Unable to fetch my node definition, but the agent run will continue:
Warning: SSL_connect returned=1 errno=0 state=unknown state: certificate verify failed: [CRL is not yet valid for /CN=Puppet CA: puppet.example.net]

The agent opines that the CRL it receives from the master is not yet valid. Errors such as these can happen whenever the agent's clock gets reset to a very early date. This can also result from but a slight clock skew, when the CRL has recently been updated through a revocation action on the master. If the system clock on the agent machine returns a time far in the future, it will consider certificates to be expired.

These clock-related issues are best avoided by running an ntp service on all Puppet agents and masters.

Errors will generally result if the data in the agent's $ssldir becomes inconsistent. This can happen when the agent interacts with an alternate master (a testing instance, for example). The first piece of advice you will most likely receive when asking the community what to do about such problems is to create a new agent certificate from scratch. This works as described in the The agent's life cycle section:

This approach will indeed remedy most issues. Be careful not to leave any old files in the relevant location on the agent machine. If the problems persist, a more involved solution is required. The openssl command-line tool is helpful to analyze the certificates and related files. The details of such an analysis are beyond the scope of this book, though.