Puppet is usually deployed in a simple client-server model (Figure 1-2). The server is called a "Puppet master", the Puppet client software is called an agent and the host itself is defined as a node.

The Puppet master runs as a daemon on a host and contains the configuration required for your environment. The Puppet agents connect to the Puppet master via an encrypted and authenticated connection using standard SSL, and retrieve or "pull" any configuration to be applied.

Importantly, if the Puppet agent has no configuration available or already has the required configuration then Puppet will do nothing. This means that Puppet will only make changes to your environment if they are required. The whole process is called a configuration run.

Each agent can run Puppet as a daemon via a mechanism such as cron, or the connection can be manually triggered. The usual practice is to run Puppet as a daemon and have it periodically check with the master to confirm that its configuration is up-to-date or to retrieve any new configuration. However, many people find being able to trigger Puppet via a mechanism such as cron, or manually, better suits their needs. By default, the Puppet agent will check the master for new or changed configuration once every 30 minutes. You can configure this period to suit your environment.

Figure 1.2. Puppet client-server model

Other deployment models also exist. For example, Puppet can also run in a stand-alone mode where no Puppet master is required. Configuration is installed locally on the host and the puppet binary is run to execute and apply that configuration. We discuss this mode later in the book.

Puppet uses a declarative language to define your configuration items, which Puppet calls "resources." This declarative nature creates an important distinction between Puppet and many other configuration tools. A declarative language makes statements about the state of your configuration - for example, it declares that a package should be installed or a service should be started.

Most configuration tools, such as a shell or Perl script, are imperative or procedural. They describe HOW things should be done rather than the desired end state - for example, most custom scripts used to manage configuration would be considered imperative.

This means Puppet users just declare what the state of their hosts should be: what packages should be installed, what services should be running, etc. With Puppet, the system administrator doesn't care HOW this state is achieved – that's Puppet's problem. Instead, we abstract our host's configuration into resources.

package { "vim":
    ensure => present,
}

type { title:
    attribute => value,
}

operatingsystem => Ubuntu
ipaddress => 10.0.0.10

Puppet's transactional layer is its engine. A Puppet transaction encompasses the process of configuring each host including:

The first step Puppet takes is to analyze your configuration and calculate how to apply it to your agent. To do this, Puppet creates a graph showing all resources, their relationships to each other and to each agent. This allows Puppet to work out in what order, based on relationships you create, to apply each resource to your host. This model is one of Puppet's most powerful features.

Puppet then takes the resources and compiles them into a "catalog" for each agent. The catalog is sent to the host and applied by the Puppet agent. The results of this application are then sent back to the master in the form of a report.

The transaction layer allows configurations to be created and applied repeatedly on the host. Puppet calls this idempotent, meaning multiple applications of the same operation will yield the same results. Puppet configuration can be safely run multiple times with the same outcome on your host and hence ensuring your configuration stays consistent.

Puppet is not fully transactional though; your transactions aren't logged (other than informative logging) and hence you can't roll back transactions as you can with some databases. You can, however, model transactions in a "noop," or no operation mode, that allows you to test the execution of your changes without making any actual changes.

On Red Hat Enterprise Linux and Red Hat based-derivatives, you need to install some prerequisites (such as the Ruby programming language, the Ruby libraries and the Ruby Shadow library) to allow Puppet to manage users and groups. You can do this with Red Hat's package management tool, Yum.

# yum install ruby ruby-libs ruby-shadow

Next, to get the latest releases of Puppet, you will need to add the EPEL repository (see sidebar) to your host and then install packages from that repository. You can add the EPEL repository by adding the epel-release RPM (.rpm package manager).

# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/

epel-release-5-3.noarch.rpm

On the master, you need to install the puppet, puppet-server, and facter packages from the EPEL repository.

# yum install puppet puppet-server facter

The puppet package contains the agent, the puppet-server package contains the master, and the facter package contains the system inventory tool Facter. As mentioned earlier, Facter gathers information, or "facts," about your hosts that are used to help customize your Puppet configuration.

On the agent, you only need to install the prerequisites and the puppet and facter packages.

# yum install puppet facter

# gem install puppet facter

On Debian and Ubuntu we also need to install the Ruby packages as a prerequisite:

# apt-get install ruby libshadow-ruby1.8

Then you can install the required packages for Puppet: puppet, puppetmaster, and facter. The puppet package contains the Puppet agent, the puppetmaster package contains the master, and the facter package contains the Facter system inventory tool.

On the master, you need to install this:

# apt-get install puppet puppetmaster facter

On the agent, you only need to install the following packages:

# apt-get install puppet facter

Installing Puppet on OpenSolaris requires installing Ruby first. Then install Puppet and Facter via a RubyGem. Start by using the pkg command to install Ruby.

# pkg install -q SUNWruby18

Once Ruby is installed (it can take a little while to download and install), there are two ways to install Puppet. The first is to use the RubyGems packaging system. RubyGems is installed by default when the SUNWruby18 package is installed. You can use the gem command to install the required Gems.

# gem install puppet facter

Alternatively, if you use Blastwave packages, Puppet and Facter are also available from the Blastwave repositories at http://www.blastwave.org and can be added using the pkgutil command. Further instructions are available on the Puppet wiki at http://projects.puppetlabs.com/projects/puppet/wiki/Puppet_Solaris.

You can also install Puppet and Facter from source tarballs. We don't recommend this approach because it makes upgrading, uninstalling and generally managing Puppet across a lot of hosts difficult. To do this you'll need to ensure some prerequisites are installed, for example Ruby and its libraries, using the appropriate packages for your host or via source again. First, download the Facter tarball from the Puppet Labs site.

$ cd /tmp
$ wget http://puppetlabs.com/downloads/facter/facter-1.5.7.tar.gz

Unpack the tarball and run the install.rb script to install Facter.

$ tar -zxf facter-1.5.7.tar.gz
$ cd facter-1.5.7
# ./install.rb

This will install Facter into the default path for Ruby libraries on your host, for example /usr/lib/ruby/ on many Linux distributions.

Next, we need to download and install Puppet using the same process:

$ cd /tmp
$ wget http://puppetlabs.com/downloads/puppet/puppet-2.6.1.tar.gz
$ tar -zxf puppet-2.6.1.tar.gz
$ cd puppet-2.6.1
# ./install.rb

Like the Facter steps, this will install Puppet into the default path for Ruby libraries on your host.

Since version 2.6.0, Puppet has supported running on Microsoft Windows. For the 2.6.0 release Puppet only manages a limited subset of configuration, primarily managing files, but other configuration types should be available in later releases.

Installing Puppet on Microsoft Windows can be achieved a couple of different ways, but the first step of both methods is to install Ruby. The easiest way to do this is with the Ruby One-Click Installer available at http://rubyinstaller.rubyforge.org/wiki/wiki.pl?RubyInstaller. You can also download binaries at http://www.ruby-lang.org/en/downloads/ if you wish.

We're going to use the One-Click installer. Download the latest version, which at the time of writing is at http://rubyforge.org/frs/download.php/47082/ruby186-27_rc2.exe. Run the downloaded executable and install Ruby. During the installation, select the Use RubyGems tick box.

Once Ruby is installed, start the RubyGems Package Manager from the start menu:

Programs -> Ruby-186-27 -> RubyGems -> RubyGems Package Manager

From the command window that opens, you can then install the Facter and Puppet gems.

C:gem install puppet facter

We've just explained how to install Puppet on some popular platforms. Puppet can also be installed on a wide variety of other platforms. Puppet is also available in varying versions on:

Puppet's tarball also contains some packaging artifacts in the conf directory, for example an RPM spec file and OS X build scripts, that can allow you to create your own packages for compatible operating systems. Now you've installed Puppet on your chosen platform, we can start configuring it.

The site.pp file tells Puppet where and what configuration to load for our clients. We're going to store this file in a directory called manifests under the /etc/puppet directory.

This directory and file is often already created when the Puppet packages are installed. If it hasn't already been created, then create this directory and file now:

# mkdir /etc/puppet/manifests
# touch /etc/puppet/manifests/site.pp

We'll add some configuration to this file later in this chapter, but now we just need the file present.

The Puppet master runs on TCP port 8140. This port needs to be open on your master's firewall (and any intervening firewalls and network devices), and your client must be able to route and connect to the master. To do this, you need to have an appropriate firewall rule on your master, such as the following rule for the Netfilter firewall:

-A INPUT -p tcp -m state --state NEW --dport 8140 -j ACCEPT

The preceding line allows access from everywhere to TCP port 8140. If possible, you should lock this down to only networks that require access to your Puppet master. For example:

-A INPUT -p tcp -m state --state NEW -s 192.168.0.0/24 --dport 8140 -j ACCEPT

Here we've restricted access to port 8140 to the 192.168.0.0/24 subnet.

The Puppet master can be started via an init script on most Linux distributions. On Red Hat, we would run the init script with the service command, like so:

# service puppetmaster start

On Debian or Ubuntu, we run it using the invoke-rc.d command:

# invoke-rc.d puppetmaster start

Other platforms should use their appropriate service management tools.

Starting the daemon will initiate your Puppet environment, create a local Certificate Authority, certificates and keys for the master, and open the appropriate network socket to await client connections. You can see Puppet's SSL information and certificates in the /etc/puppet/ssl directory.

# ls -l /etc/puppet/ssl
drwxrwx--- 5 puppet puppet 4096 2009-11-16 22:36 ca

drwxr-xr-x 2 puppet root   4096 2009-11-16 22:36 certificate_requests
drwxr-xr-x 2 puppet root   4096 2009-11-16 22:36 certs
-rw-r--r-- 1 puppet root    361 2009-11-16 22:36 crl.pem
drwxr-x--- 2 puppet root   4096 2009-11-16 22:36 private
drwxr-x--- 2 puppet root   4096 2009-11-16 22:36 private_keys
drwxr-xr-x 2 puppet root   4096 2009-11-16 22:36 public_keys

The directory on the master contains your Certificate Authority, certificate requests from your clients, a certificate for your master and certificates for all your clients.

You can also run the Puppet master from the command line to help test and debug issues. I recommend doing this when testing Puppet initially. To do this we start the Puppet master daemon like so:

# puppet master --verbose --no-daemonize

The --verbose option outputs verbose logging and the --no-daemonize option keeps the daemon in the foreground and redirects output to standard out. You can also add the --debug option to produce more verbose debug output from the daemon.

# puppet master

# puppetmasterd

# puppet agent

# puppetd

$ puppet --help

To complete the connection and authenticate our agent we now need to sign the certificate the agent has sent to the master. We do this using puppet cert (or the puppetca binary) on the master.

puppet# puppet cert --list
node1.example.com

The --list option displays all the certificates waiting to be signed. We can then sign our certificate using the --sign option.

puppet# puppet cert --sign node1.example.com
Signed node1.example.com

You can sign all waiting certificates with the puppet cert --sign --all command.

On the client, two minutes after we've signed our certificate, we should see the following entries (or you can stop and restart the Puppet agent rather than waiting two minutes):

notice: Got signed certificate
notice: Starting Puppet client version 2.6.1

The agent is now authenticated with the master, but we have another message present:

err: Could not retrieve catalog: Could not find default node or by name with 

'node1.example.com, node1' on node node1.example.com

The agent has connected and our signed certificate has authenticated the session with the master. The master, however, doesn't have any configuration available for our puppet node, node1.example.com, and hence we have received an error message. We now have to add some configuration for this agent on the master.

Our first step in creating our first agent configuration is defining and extending the site.pp file. See an example of this file in Listing 1-3.

import 'nodes.pp'
$puppetserver = 'puppet.example.com'

The import directive tells Puppet to load a file called nodes.pp. This directive is used to include any Puppet configuration we want to load. For example, if we specify resources in a file called resources.pp, we would need to import it this way:

import 'resources.pp'

When Puppet starts, it will now load the nodes.pp file and process the contents. In this case, this file will contain the node definitions we create for each agent we connect. You can also import multiple files like so:

import 'nodes/*'
import 'classes/*'

The import statement will load all files with a suffix of .pp in the directories nodes and classes.

The $puppetserver statement sets a variable. In Puppet, configuration statements starting with a dollar sign are variables used to specify values that you can use in Puppet configuration.

In Listing 1-3, we've created a variable that contains the fully qualified domain name of our Puppet master, enclosed in double quotes.

Let's add our first agent definition to the nodes.pp file we've just asked Puppet to import. In Puppet manifests, agents are defined using node statements.

# touch /etc/puppet/manifests/nodes.pp.

You can see the node definition we're going to add in Listing 1-4.

node 'node1.example.com' {
    include sudo
}

For a node definition we specify the node name, enclosed in single quotes, and then specify the configuration that applies to it inside curly braces { }. The client name can be the hostname or the fully qualified domain name of the client. At this stage, you can't specify nodes with wildcards (e.g., *.example.com) but you can use regular expressions, such as:

node /^wwwd+.example.com/ {
    include sudo
}

This example will match all nodes from the domain example.com with the hostname www1, www12, www123, etc.

Next, we specify an include directive in our node definition. The include directive specifies a collection of configuration that we want to apply to our host. There are two types of collections we can include in a node:

You can include multiple collections by using multiple include directives or separating each collection with commas.

include sudo
include sshd
include vim, syslog-ng

In addition to including collections of resources, you can also specify individual resources to a node, like so:

node 'node1.example.com' {

include sudo
    package { 'vim': ensure => present }
}

In this case however, as we've seen in Listing 1-4, we're just going to add a single collection of resources: the sudo module.

Let's start by creating a module directory and file structure in Listing 1-5. We're going to create this structure under the directory /etc/puppet/modules. We will name the module sudo. Modules (and classes) must be normal words containing only letters, numbers, underscores and dashes.

# mkdir -p /etc/puppet/modules/sudo/{files,templates,manifests}
# touch /etc/puppet/modules/sudo/manifests/init.pp

The manifests directory will hold our init.pp file and any other configuration. The init.pp file is the core of your module and every module must have one. The files directory will hold any files we wish to serve as part of our module. The templates directory will contain any templates that our module might use.

Now let's look inside our sudo module, starting with the init.pp file, which we can see in Listing 1-6.

class sudo {
    package { sudo:
         ensure => present,
    }

    if $operatingsystem == "Ubuntu" {
         package { "sudo-ldap":
            ensure => present,
            require => Package["sudo"],
        }
    }

    file { "/etc/sudoers":
        owner => "root",
        group => "root",
        mode => 0440,
        source => "puppet://$puppetserver/modules/sudo/etc/sudoers",
        require => Package["sudo"],
    }
}

Our sudo module's init.pp file contains a single class, also called sudo. There are three resources in the class, two packages and a file resource.

The first package resource ensures that the sudo package is installed, ensure => present. The second package resource uses Puppet's if/else syntax to set a condition on the installation of the sudo-ldap package.

Puppet will check the value of the operatingsystem fact for each connecting client. If the value of the $operatingsystem fact is Ubuntu, then Puppet should install the sudo-ldap package.

Lastly, in this resource we've also specified a new attribute, require. The require attribute is a metaparameter. Metaparameters are resource attributes that are part of Puppet's framework rather than belonging to a specific type. They perform actions on resources and can be specified for any type of resource.

The require metaparameter creates a dependency relationship between the Package["sudo-ldap"] resource and the Package["sudo"] resource. In this case, adding the require metaparameter to the resource tells Puppet that the Package["sudo"] is required by the Package["sudo-ldap"] resource. Hence, the Package["sudo"] resource must and will be installed first.

Relationships are an important part of Puppet. They allow you to instantiate real world relationships between configuration components on your hosts. A good example of this is networking. A number of resources on your hosts, for example a Web server or an MTA (Mail Transfer Agent), would rely on your network being configured and active before they can be activated. Relationships allow you to specify that certain resources, for example those configuring your network, are processed before those resources that configure your Web server or MTA.

The usefulness of relationships does not end there. Puppet can also build triggering relationships between resources. For example, if a file resource changes, then you can tell Puppet to restart a service resource. This means you can change a service's configuration file and have that change trigger a restart of that service to ensure it is running with the updated configuration. We'll see a lot more of these relationships and other metaparameters in Chapter 3.

The last resource in the sudo class is a file resource, File["/etc/sudoers"], which manages the /etc/sudoers file. Its first three attributes allow us to specify the owner, group and permissions of the file. In this case, the file is owned by the root user and group and has its mode set to 0440 (currently the mode can only be set using octal notation).

The next attribute, source, allows Puppet to retrieve a file from the Puppet file server and deliver it to the client. The value of this attribute is the name of the Puppet file server and the location and name of the file to retrieve.

puppet://$puppetserver/modules/sudo/etc/sudoers

Let's break down this value. The puppet:// part specifies that Puppet will use the Puppet file server protocol to retrieve the file.

The $puppetserver variable contains the hostname of our Puppet server. Remember that we created this variable and placed it in our site.pp file earlier? Instead of the variable, you could also specify the host name of the file server here.

puppet://puppet.example.com/modules/sudo/etc/sudoers

The next portion of our source value tells Puppet where to look for the file. This is the equivalent of the path to a network file share. The first portion of this share is modules, which tells us that the file is stored in a module. Next we specify the name of the module the file is contained in, in this case sudo. Finally, we specify the path inside that module to find the file.

All files in modules are stored under the files directory; this is considered the "root" of the module's file "share." In our case, we would create the directory etc under the files directory and create the sudoers file in this directory.

puppet$ mkdir -p /etc/puppet/modules/sudo/files/etc
puppet$ cp /etc/sudoers /etc/puppet/manifests/files/etc/sudoers