Getting Started with a Simple Puppet Recipe

Using Puppet is largely about developing the Puppet manifests, which describe the configuration of your system.

Once you have Puppet installed (see Installation Guide ) on at least one server (the Puppetmaster), and at least one client, you're ready to set up a minimal configuration and get started using Puppet.

A Simple Manifest: Managing Ownership of a File

For our first manifest, we'll manage a single element (in this case, a file) on all of our hosts.

Step one: Create /etc/puppet/manifests/classes/sudo.pp

First, we'll create a class, which we'll call sudo, in the sudo.pp manifest. We'll use this appropriately-named manifest for all configuration information related to sudo, so next time we'll be able to find the sudo stuff quickly. We'll start simple, and just manage the sudoers file for now:

# /etc/puppet/manifests/classes/sudo.pp

class sudo {
    file { "/etc/sudoers":
        owner => "root",
        group => "root",
        mode  => 440,
    }
}

So now we have a class which will ensure that the owner, group, and mode of the /etc/sudoers file will be set consistently across all systems that belong to that class (but we haven't chosen which computers belong in that class, yet).

Step two: Create /etc/puppet/manifests/site.pp

Now we'll create the site.pp manifest which is the master manifest. Puppet will search for a manifest by this name by default. Here's our file:

# /etc/puppet/manifests/site.pp

import "classes/*"

node default {
    include sudo
}

With the import statement on the first line, we import all of the class files located in the classes subdirectory of the Puppet home directory (/etc/puppet/manifests/classes in this case). Since we only have one other manifest (our sudo.pp), this will be the only file imported. Later, if we add more manifests in the classes subdirectory, we won't have to edit site.pp again to add them to the import statement.

After we've imported our classes, we create a default node definition. In essence, the default node definition will be applied to any node that doesn't fall into any other node definition's scope. In this case, since we have no other node definitions, all nodes will follow this node definition and so any node will include our sudo class.

Step three: Start the Puppetmaster

Now that we have a basic manifest configuration laid out, we can start the Puppetmaster daemon. We'll start the server with the --mkusers option, so it creates the puppet user and group:

master % sudo puppetmasterd --mkusers

This will background the daemon and send all of its logs to the syslog facility. If you would prefer, you can add --verbose and the daemon will stay in the foreground and its messages will go to the terminal.

On Ubuntu and other Debian based distributions, starting the Puppetmaster daemon works like this:

master % sudo /etc/init.d/puppetmaster restart

Step four: Run a client

It's usually best to start with your first client being Puppetmaster server itself. However, since the Puppetmaster will be talking to itself, that client will already have a certificate, so no signing will be necessary to establish trust between the Puppetmaster server and itself. In this example, we'll configure a client that isn't the Puppetmaster server so we can demonstrate how to establish cryptographic trust between the Puppetmaster server and its new clients:

First, start puppetd on the client in verbose mode:

client% sudo puppetd --verbose

You should see a message about not receiving a certificate, and on the server you should get a message about a request waiting for you. On the server, we'll list the certificates waiting for signatures:

master% sudo puppetca --list

You should see our client's name listed, so we can give the Puppetmaster the command to sign its certificate (thus creating a trust relationship that client):

master% sudo puppetca --sign <client>

Within two minutes (the default value for --waitforcert), the client should connect again and receive its signed certificate. Once the signed cert is in place, the client should ask for its configuration; the server will compile it (and log that it has done so) and pass the compiled configuration to the client.

Then, if the sudoers file had incorrect permissions, we should see one or more messages indicating the corrections; but if everything about the sudoers file is already correct, you'll just see messages about starting and ending the configuration run.

If you restart puppetd without the --verbose option, it will background itself and run periodically thereafter, checking with the Puppetmaster server to see if there the manifests have changed.

Caveat

This is half of the infrastructure for a working Puppet installation. The other half of a hygienic and efficient installation revolves around version-controlling the Puppet manifests and the files Puppet will be managing. It also provides a minimalist structure around which to build other Puppet classes.

Where to next

Have a look at the more advanced Puppet recipe to see how we can build on this basic recipe.