This site is now 100% read-only, and retired.

1/2: An introduction to using Puppet

Posted by Steve on Mon 21 May 2007 at 12:55

Tags: , ,

Puppet is a relatively new system configuration and management tool which can be used to administer a large number of machines. It is similar to CFEngine, but written in Ruby. In this introduction to working with Puppet we'll demonstrate how to install it, and use it upon a small LAN.

In this article we'll demonstrate the installation of the central puppet server upon a host as well as configuring several nodes which may be controlled using it. For reference the machines we'll be seeing are as follows:

    • This will be the master Puppet server which is responsible for configuring each of the other machines.
    • This is a simple client.
    • This is a simple client.

Note: In order for the puppet server and the puppet client(s) to be able to communicate you should ensure that port 8140 is open between the systems. If you're using a firewall I'd suggest you ensure that you configure it such that the clients may only accept connections from the server upon this port.

Server Installation

The installation of the server should be as simple as:

root@vain:~# apt-get install puppetmaster

This will install the server, but it will fail to start because we don't have a manifest installed. This is harmless for the moment.

When it comes to time to use the server for real we'll want to:

  • Serve files which may be copied to the managed client nodes.
  • Have a list of actions and the hosts to apply them upon.

By default the file-serving is disabled so we'll need to fix that by updating /etc/puppet/fileserver.conf. In my case I want to serve files to the 192.168.1.x network, so I'll update that file to read:

  path /etc/puppet/files

This means that any host in the range can request files located in the directory /etc/puppet/files directory upon the host.

The next thing to do is to create a stub manifest file:

root@vain:~# mkdir -p /etc/puppet/manifests/

The file puppet looks for is called site.pp, for the moment we'll create the following file:

# fixup permissions on sudo
class sudo {
    file { "/etc/sudoers":
        owner => root,
        group => root,
        mode => 440,

node default {
     include sudo

(We'll come back to this file in the second part of our article where we discuss how to control your hosts using puppet. For the moment rest assured that this /etc/puppet/manifests/site.pp file is correct and will ensure that the /etc/sudoers file always exists with the correct permissions.)

Client Installation

The next job is to install the puppet client upon each of the hosts you wish to have managed. To install it run:

root@vain:~# apt-get install puppet

Once the package has been installed you will need to configure the client with the name of your master-server. By default the client will attempt to lookup the hostname puppet and connect to that.

In my case I control DNS so I could just setup as an alias of the real server, but to be explicit about things we'll do it manually.

Update the file /etc/puppet/puppetd.conf to look similar to this:

server =
logdir = /var/log/puppet
vardir = /var/lib/puppet
rundir = /var/run

Once this has been done you can restart the client:

root@etch-builder:~# /etc/init.d/puppet restart
Restarting puppet configuration management tool.


The puppet system uses a small certificate authority to protect the network communication, and control access to the server.

So far we've installed a server with a simple manifest file, and a single client which knows the name of the server to be controlled from. However we've not yet configured the authentication.

To reiterate: Right now we have a server which is listening for client connections and we have a client which knows where to request actions from. However nothing will actually be happening because the client is not yet authorised to contact the server.

We'll fix that now.

Upon the server you should run the following command to list the request which have been received and not authorised:

root@vain:~# puppetca  --list

To sign these requests we can now run:

root@vain:~# puppetca  --sign
root@vain:~# puppetca  --sign

Now everything should be hooked up. The server will accept connections from our two client nodes, and these in turn will pull down and execute the contents of the site.pp file. If this file changes upon the server the clients will notice every 30 minutes or so and update themselves accordingly.

This concludes the process of installing and configuring the puppet client and server. In the next article of this series we'll demonstrate how you can:

  • Make puppet behave in a more CFEngine-like fashion.
  • Start using puppet to control your hosts in a useful manner.



Re: 1/2: An introduction to using Puppet
Posted by Thorsten (84.58.xx.xx) on Mon 21 May 2007 at 19:27
wow, nice peace of software!

I"m looking forward to the second part.

[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by eric (194.2.xx.xx) on Tue 22 May 2007 at 14:06
[ View Weblogs ]
Very interesting documentation, and software.
I'm going to install it right now, and see if I can use it for something useful ;)


[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by eric (194.2.xx.xx) on Tue 22 May 2007 at 17:12
[ View Weblogs ]
Ok, I've read this article and made some of the examples. I've also read some of the documentation on the puppet site (the url:

So here goes some questions :

  • what the difference with cfengine? And what are the pros and cons of the two solutions? Because I never looked for these kind of tools, so I prefer to use a 'better' one (one that feets my needs better)
  • if I understand correctly: before running puppetca --sign xxxx, no actions are made on the clients?

Another great article from Steve :) (could be a tv-ad) and a nice tool discovered: thanks.


[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by Anonymous (65.193.xx.xx) on Tue 22 May 2007 at 20:36
Interview with main developer of puppet 02/02/2007

[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by mwr (149.149.xx.xx) on Tue 22 May 2007 at 22:24
[ View Weblogs ]

On differences between puppet and cfengine, any of the interviews with Luke Kaines should make that part clear. The short form would be puppet's more consistent syntax; abstraction layers for cron, services, package management, and others; benefits of thinking "what could cfengine do better?"; etc.

On the second one, no puppet rules get downloaded to the clients until their keys are signed. I think they can download facts (little procedures for facter, an underlying Ruby library for detecting characteristics of the client system) from the puppet server, but nothing else.

[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by Anonymous (212.112.xx.xx) on Wed 23 May 2007 at 08:46

[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by andrew_janke (202.161.xx.xx) on Thu 31 May 2007 at 14:22
Hi Steve,

Thanks again for (yet another) great tutorial. I am a long time user of FAI and cfengine and was in the throes of setting up a new network and was investigating options. (one of them puppet).

You might like to add a:

/etc/init.d/puppetmaster restart

Into the server config after you have created the site.pp file. If not, the server is not started (at least on Ubuntu, haven't checked debian stable) and thus puppetca --list is not all that successful.


[ Parent ]

Re: 1/2: An introduction to using Puppet
Posted by henning (85.177.xx.xx) on Tue 28 Apr 2009 at 00:23
Thanks for this tutorial, Steve! Two things I found when trying this on Lenny:

* the manifest directory is already there
* the client config file seems to be called /etc/puppet.conf and the section where the server must be added is [main]

[ Parent ]