Setting up the server
For the most part, the Puppet server is preconfigured for reporting and is simply waiting for clients to start sending information to it. By default, the Puppet master will use the store report processor, and this will simply store the data that is sent to the Puppet master in the YAML format on the filesystem.
Note
YAML is a data serialization format that is designed to be both machine and human readable. It's widely used and seems to have found considerable favor among open source projects. YAML has a simple layout but still has the ability to hold complex configurations that are easily accessible with relatively simple code. A nice side effect of its popularity is that it has gained first-class support in many languages and for those languages without such support, there are many libraries that allow you to easily work with them.
It's worth taking some time to become familiar with YAML; you can find the YAML specifications at http://yaml.org, and Wikipedia has an excellent entry that can ease you into understanding how this simple yet exceedingly powerful format is used.
Although the store processor is simple, it gives us an excellent starting point to ensure that our Puppet master and agent are configured correctly. The YAML files it produces hold a complete record of the Puppet agent's interactions with the client. This record includes a complete record of which resources were applied, how long it took, what value they were earlier, and much more. In later chapters, we will fully explore the wealth of data that both the Puppet reports and Puppet metrics offer us.
Tip
We're going to spend some time looking at various settings, both in this chapter and others. While you can look in the raw configuration files (and I highly encourage you to), you can also use the puppet master –configprint command to find out what Puppet believes a particular setting to be set at. This is extremely useful in finding out how a default setting may be configured, as it may not even be present in the configuration file but will still be applied!
Out of the box, the only real Puppet master setting that may require some care and attention is the reportdir setting. This defines where the Puppet agent reports are stored, and it is important that this points to a directory that has plenty of space. I've routinely seen installations of Puppet where the disk is consumed within a matter of days via a reportdir setting that points at a relatively diminutive partition. By default, the reportdir setting is set to the /var/lib/puppet/reports directory. So at the very least, make sure that your /var partition is fairly roomy. If your Puppet agents are set to run every thirty minutes and you have a healthy number of hosts, then whatever partition you have this directory in is going to become full very quickly. It's worth bearing in mind that there is no inbuilt rotation or compression of these log files, and you may want to consider adding one using your tool of choice. Alternatively, there is a Puppet module to manage the log rotate on the Puppet Forge at https://forge.puppetlabs.com/rodjek/logrotate.
Tip
If you do relocate the reports directory, then ensure that the permissions are set correctly so that the user who runs the Puppet master process has access to both read/write to the reporting directory. If the permissions aren't set correctly, then it can lead to some very weird and wonderful error messages on both the Puppet master and agent.
Now that we understand some of the basics of Puppet reporting, it's time to take a look at the configuration. Let's take another look at the basic configuration that comes out of the box. The configuration file is as follows:
[main] logdir=/var/log/puppet vardir=/var/lib/puppet ssldir=/var/lib/puppet/ssl rundir=/var/run/puppet factpath=$vardir/lib/facter templatedir=$confdir/templates [master] # These are needed when the Puppetmaster is run by passenger # and can safely be removed if webrick is used. ssl_client_header = SSL_CLIENT_S_DN ssl_client_verify_header = SSL_CLIENT_VERIFY
At this point, no further changes are required on the Puppet master, and it will store client reports by default. However, as mentioned, it will store reports in the /var/lib/Puppet/reports directory by default . This isn't ideal in some cases; sometimes, it's impossible to create a /var directory that would be big enough (for instance, on hosts that use small primary storage such as SSD drives), or you may wish to place your logs onto a centralized storage space such as an NFS share. This is very easy to change, so let's take a look at changing our default configuration to point to a new location. This is described in the following code:
[main]
logdir=/var/log/puppet
vardir=/var/lib/puppet
ssldir=/var/lib/puppet/ssl
rundir=/var/run/puppet
factpath=$vardir/lib/facter
templatedir=$confdir/templates
[master]
reportdir = /mnt/puppetreports
# These are needed when the puppetmaster is run by passenger
# and can safely be removed if webrick is used.
ssl_client_header = SSL_CLIENT_S_DN
ssl_client_verify_header = SSL_CLIENT_VERIFYMake sure that once you have created your Puppet's reports directory, you change the permissions to match your Puppet user (normally, puppet:puppet for Unix and Linux systems) and restart the Puppet master. Go ahead and run the client again, and you should see the report appear in your new reporting directory.
If you're using Puppet Enterprise, then none of this applies; the installer has taken care of this for you. If you take a look at the configuration directory (normally /etc/Puppetlabs/master), you can see that the Puppet.conf file has the same changes. Puppet Enterprise is configured out of the box to use the HTTP and PuppetDB storage method. This is a far more scalable way of doing things than the standard reportdir directory and store method, and it is a good example of where Puppet Enterprise is designed with scale in mind. This doesn't mean that you can't do this in the open source version, though; in the following chapters, we will go through setting up Puppet Open Source to use these report processors and more.
