Installation Guide

Table of Contents

1. Getting the Files
2. Install Puppet
3. Alternative: Using Ruby Gems
4. Building the Server
5. Start the Central Daemon
6. Verifying Installation
7. Finishing Installation

If there is anything about this introduction that is unclear or not correct, please email luke at madstop.com about it or file a bug at the bug tracker.

Getting the Files

Check the Downloading Puppet page for how to get packages or source for your platform.

You will need to install Puppet on all machines that will use it, including both clients and servers.

There are packages available for most platforms (use your normal package sources for them), but for the rest you will have to install using the tarball or GEMs. Install instructions do not cover installing packages, since it is assumed you know how to retrieve and install packages for your specific platform.

Prerequisites

The only prerequisite for Puppet that doesn't come as part of the Ruby standard library is facter, which is also developed by Reductive Labs.

All other prerequisites for Puppet are Ruby libraries, and they should all come with any standard Ruby 1.8.2 install. The other prerequisites, should your OS not come with the complete standard library, are:

• base64
• cgi
• digest/md5
• etc
• fileutils
• ipaddr
• openssl
• strscan
• syslog
• uri
• webrick
• webrick/https
• xmlrpc

Ruby. I recommend using whatever Ruby comes with your system, since that's what I've tested against in most cases and it's most likely to work correctly. If you feel the particular need to build it manually, you can get the source from the Ruby site.

Red Hat

Puppet and Facter are available in Fedora; thanks to David Lutterkort at Red Hat. Fedora users can retrieve them via yum from their Fedora repositoies. Users of Enterprise Linux (RHEL, CentOS, OEL, Scientific, Start.com, etc) can get the package from Extra Packages for Enterprise Linux (EPEL)- a Fedora add-on for EL.

Please let the puppet-users mailing list know if you have built RPM's for RHEL2.1 or RHEL3 (or the equivalent CentOS builds)

If you are building ruby on Red Hat (at least on version 3), you apparently must build it with CPPFLAGS=-I/usr/kerberos/include/, else you will have all kinds of unreasonable problems (thanks to Mario Martelli for tracking that one down).

Solaris

For newer packages, Gary Law maintains a repository, and older packages can be found in the downloads. These packages suffice for both sparc and x86 (even though they're marked x86), but they don't specify dependencies. They're automatically built during new releases, so they should always be the latest.

I have had mixed results with the Ruby packages from both Sunfreeware and BlastWave. It might almost be easier to compile it manually for Solaris, but Ruby 1.8.4 from BlastWave seems to be working right now.

If you get segfaults, core dumps, or 'library missing ciphers' errors, that is almost definitely a problem with that specific ruby package, not Puppet or Ruby itself.

You might also find the Solaris Puppet Client Installation Guide to be useful.

Debian and Ubuntu

You can download packages for Puppet from any Debian mirror.

The package maintainer for Ruby on these platforms has decided to split the Ruby standard library into many packages. According to Eric Hollensbe, this is the package dependency list for Puppet on Debian:

• ruby
• irb
• ri
• rdoc
• libxmlrpc-ruby
• libopenssl-ruby
• libstrscan-ruby
• libsyslog-ruby
• libwebrick-ruby

Debian Stable tends to lag behind a bit with packages. You might want to install the puppet packages from Unstable.

Ubuntu Dapper Server (LTS): You need to enable the universe repository to install the above package list.

SuSE

Martin Vuk has set up the SuSE build service to create Puppet and Facter packages, so you can get them there. Older versions of Puppet can still be retrieved from his old yum repository.

More about puppet on SuSE and opensuse.

Gentoo

Thanks to José González Gómez, there are now ebuilds available for Puppet in the official Portage repository.

Also, as of September 2006 there is a problem with the PPC Ruby package that causes rdoc/usage to fail. The bug has been reported to the Gentoo folks.

Facter

First install facter. Like Puppet, there are packages available for some platforms, but you might have to use the tarball:

# get the latest tarball
wget http://reductivelabs.com/downloads/facter/facter-latest.tgz

# untar and install it
gzip -d -c facter-latest.tgz | tar xf -
cd facter-*
sudo ruby install.rb # or become root and run install.rb

There are also gems available in the download directory.

Install Puppet

Using the same mechanism, install the puppet libraries and executables:

# get the latest tarball
$ wget http://reductivelabs.com/downloads/puppet/puppet-latest.tgz

# untar and install it
$ gzip -d -c puppet-latest.tgz | tar xf -
$ cd puppet-*
$ sudo ruby install.rb # or become root and run install.rb

You can also check the source out from the git repo:

$ mkdir -p ~/git && cd ~/git
$ git clone git://reductivelabs.com/puppet
$ cd puppet
$ sudo ruby ./install.rb

Alternative: Using Ruby Gems

You can also install Facter and Puppet via gems:

  wget http://reductivelabs.com/downloads/gems/facter-1.5.2.gem
  gem install facter-1.5.2.gem
  wget http://reductivelabs.com/downloads/gems/puppet-0.24.7.gem
  gem install puppet-0.24.7.gem

The Reductive Labs gem server is broken. Find the latest gems here

For more information on Ruby Gems, see the Gems User Guide

Building the Server

Create Your Site Manifest

Because the Puppet language is declarative, it does not make as much sense to speak of "executing" Puppet programs, or to describe them as "scripts". We choose to use the word manifest to describe Puppet programs, and we speak of applying those manifests to the local system. Thus, a manifest is a text document written in the Puppet language and meant to result in a desired configuration.

Puppet is written with the assumption that you will have one central manifest capable of configuring your entire network, which we call the site manifest. You could have multiple, separate site manifests if you wanted, but at this point each of them would need their own servers.

Puppet will start with /etc/puppet/manifests/site.pp as the primary manifest, so create /etc/puppet/manifests and add your manifest, along with any files it includes, to that directory. It is highly recommended that you use some kind of version control on your manifests.

Example Manifest

The site manifest can be as simple or as complicated as you want. A good starting point is to make sure that your sudoers file has the appropriate permissions:

# site.pp
file { "/etc/sudoers":
    owner => root, group => root, mode => 440
}

For more information on how to create the site manifest, see the tutorials listed on the Getting Started page.

Start the Central Daemon

Most sites should only need a single central server. Reductive Labs will soon publish a document describing how to build puppet architectures with failover capabilities and achitectures that are capable of handling large loads, but for now only a single server is supported.

Decide which machine you want to be your central server; this is where you will be starting puppetmasterd.

The best way to start any daemon is using your local server's service management system, often in the form of init scripts. Eventually Puppet will ship with an appropriate script for each platform (it already has appropriate scripts for Red Hat, Debian, and Solaris), but in the meantime you can either create your own, using an existing script as an example, or simply run without one (not recommended for production environments).

Other than the system manifest at /etc/puppet/manifests/site.pp, the last thing you'll need is to create the puppet user and group that the daemon runs as. You can create these manually, or you can just start the daemon with the --mkusers flag, and it should create both of them for you (of course, this flag is only necessary the first time the daemon is run):

# /usr/sbin/puppetmasterd --mkusers

Even without the --mkusers flag, it will automatically create all necessary certificates, directories, and files. If you want the daemon to also function as a file server, so your clients can copy files from it, you will need to create a fileserver configuration file; the daemon checks for the existence of this file at startup and automatically enables or disables file serving functionality.

Verifying Installation

To verify that your daemon is working as expected, pick a single client to use as a testbed. Once Puppet is installed on that machine, run a single client against the central server to verify that everything is working appropriately. You should start the first client in verbose mode, with the --waitforcert flag enabled:

# puppetd --server myserver.domain.com --waitforcert 60 --test

The default server for puppetd is puppet, so you could just create a CNAME of that to whatever server is running puppetmasterd.

Adding the --test flag causes puppetd to stay in the foreground, print extra output, only run once and then exit, and to just exit if the remote configuration fails to compile (by default, puppetd will use a cached configuration if there is a problem with the remote manifests).

In running the client, you should see the message

info: Requesting certificate
warning: peer certificate won't be verified in this SSL session
notice: Did not receive certificate

(This message will repeat every 60 seconds with the above command). This is normal, since your server is not auto-signing certificates as a security precaution. On your server, list the waiting certificates:

# puppetca --list

You should see the name of the test client. Now go ahead and sign the certificate:

# puppetca --sign mytestclient.domain.com

Within 60 seconds, your test client should receive its certificate from the server, receive its configuration, apply it locally, and exit normally.

By default, puppetd runs with a waitforcert of five minutes; set the value to 0 to disable it entirely.

Finishing Installation

There are already init scripts available for some platforms (notably, Red Hat versions, thanks to David Lutterkort's work on the RPMs), but for not-yet-supported platforms, you will need to create an init script that can start and stop puppetd. The process creates a PID file in its run directory (/var/puppet/run, by default), so you can use that to stop it.

The process will log to syslog by default in the daemon facility.