Setting up the Puppet agent

As was explained earlier, the master mainly serves instructions to agents in the form of catalogs that are compiled from the manifest. You have also prepared a node block for your first agent in the master manifest.

Installing the agent software is easy; you did this at the start of Chapter 1, Writing Your First Manifests. The plain Puppet package that allows you to apply a local manifest contains all the required parts in order to operate a proper agent.

If you are using Puppet Labs packages, use the instructions from earlier in this chapter. On agent machines, you need not install the puppetserver package. Just get puppet-agent instead.

After a successful package installation, one needs to specify where puppet agent can find the puppet server:

root@puppetmaster # puppet config set –-section agent server pup-petmaster.example.net 

Afterwards, the following invocation is sufficient for an initial test:

root@agent# puppet agent --test
Info: Creating a new SSL key for agent
Error: Could not request certificate: getaddrinfo: Name or service not known
Exiting; failed to retrieve certificate and waitforcert is disabled

Puppet first created a new SSL certificate key for itself. For its own name, it picked agent, which is the machine's hostname. That's fine for now. An error occurred because the puppet name cannot be currently resolved to anything. Add this to /etc/hosts so that Puppet can contact the master:

root@agent# puppet agent --test
Info: Caching certificate for ca
Info: csr_attributes file loading from /etc/puppetlabs/puppet/csr_attributes.yaml
Info: Creating a new SSL certificate request for agent
Info: Certificate Request fingerprint (SHA256): 52:65:AE:24:5E:2A:C6:17:E2:5D:0A:C9: 86:E3:52:44:A2:EC:55:AE:3D:40:A9:F6:E1:28:31:50:FC:8E:80:69
Exiting; failed to retrieve certificate and waitforcert is disabled

Puppet created a certificate request and sent it to the master. It then immediately tried to download the signed certificate. This is expected to fail the master won't just sign a certificate for any request it receives. This behavior is important for proper security.
There is a configuration setting that enables such automatic signing, but users are generally discouraged from using this setting because it allows the creation of arbitrary numbers of signed (and therefore, trusted) certificates to any user who has network access to the master.

To authorize the agent, look for the CSR on the master using the puppet cert command:

root@puppetmaster# puppet cert --list
"agent" (SHA256) 52:65:AE:24:5E:2A:C6:17:E2:5D:0A:C9:86:E3:52:44:A2:EC:55:AE: 3D:40:A9:F6:E1:28:31:50:FC:8E:80:69  

This looks alright, so now you can sign a new certificate for the agent:

root@puppetmaster# puppet cert --sign agent
Notice: Signed certificate request for agent
Notice: Removing file Puppet::SSL::CertificateRequest agent at '/etc/puppetlabs/ puppet/ssl/ca/requests/agent.pem'  

Now the agent can receive its certificate for its catalog run as follows:

root@agent# puppet agent --test
Info: Caching certificate for agent
Info: Caching certificate_revocation_list for ca
Info: Caching certificate for agent
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Caching catalog for agent
Info: Applying configuration version '1437065761'
Notice: Applied catalog in 0.11 seconds

The agent is now fully operational. It received a catalog and applied all resources found within. Before you read on to learn how the agent usually operates, there is a note that is especially important for the users of Puppet 3.

Since this is the common name in the master's certificate, the preceding command will not even work with a Puppet 3.x master. It works with puppetserver and Puppet 4 because the default puppet name is now included in the certificate's Subject Alternative Names by default.

It is tidier to not rely on this alias name, though. After all, in production, you will probably want to make sure that the master has a fully qualified name that can be resolved, at least inside your network. You should, therefore, add the following to the main section of puppet.conf on each agent machine:

[agent] 
server=master.example.net 

In the absence of DNS to resolve this name, your agent will need an appropriate entry in its hosts file or a similar alternative way of address resolution.

These steps are necessary in a Puppet 3.x setup. If you have been following along with a Puppet 4 agent, you might notice that after this change, it generates a new certificate signing request:

root@agent# puppet agent –test
Info: Creating a new SSL key for agent.example.net
Info: csr_attributes file loading from /etc/puppetlabs/puppet/csr_attributes.yaml
Info: Creating a new SSL certificate request for agent.example.net
Info: Certificate Request fingerprint (SHA256): 85:AC:3E:D7:6E:16:62:BD:28:15:B6:18: 12:8E:5D:1C:4E:DE:DF:C3:4E:8F:3E:20:78:1B:79:47:AE:36:98:FD
Exiting; no certificate found and waitforcert is disabled

If this happens, you will have to use puppet cert sign on the master again. The agent will then retrieve a new certificate.