path: root/documentation/installation.page

---
inMenu: true
---
# Getting the Files

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

There are [packages][] available for some platforms, but for the rest
you will have to install using the [tarball][] or [GEMs][].

## 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](http://ruby-lang.org/).


#### Red Hat

If you are building 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

I have had mixed results with the Ruby packages from both
[Sunfreeware](http://sunfreeware.com) and [BlastWave](http://blastwave.org).
It might almost be easier to compile it manually for Solaris, but Ruby 1.8.3
from Sunfreeware 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.

#### Debian and Ubuntu

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

### 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

## Alternative: Using RubyGems

You can also use Reductive Labs' Gems server to install Facter and Puppet:

    gem install --remote --source http://reductivelabs.com/downloads facter
    gem install --remote --source http://reductivelabs.com/downloads puppet

For more information on RubyGems, see the [Gems User Guide][].

## Alternative alternative:  Native Packages

It is our goal to provide as many native packages as possible, but it's been
slow going.  Until I have official native packages, David Lutterkort used spec
and init files from Duane Griffin to create native RPMs that should work on
Red Hat Enterprise 4 and Fedora Core 4.  You can get them from his
[yum repository][].

There are also [Debian packages][], although they are not quite as well
maintained as the RPMs.

# 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.

For more information on how to create the site manifest, see the
[Language Reference][] and the [Library Reference][].

Puppet will look for your site manifest in ``/etc/puppet/manifests/site.pp``,
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 Manifests

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
    }

If you want to get more complicated, it's a good idea to split your
manifest into multiple files.  For instance, you could split it based on
operating systems (e.g., Solaris and Red Hat) and server classes (e.g.,
'webserver' and 'logserver').  I also find it useful to have a set of
functions, in an external file included first:

    # site.pp

    # import the functions
    import "functions.pp"

    # import all of the os classes, like redhat.pp and solaris.pp
    import "os/*"

    # import all of the server classes, like webserver.pp
    import "classes/*"

Here's an example of a generically useful function I use; it encapsulates the
source of files that I copy from a central server, and just saves a little
typing:

    # functions.pp
    
    define remotefile(owner = root, server = puppet, group = root, mode, source, backup = false, recurse = false) {
        file {
            $name:
                mode => $mode,
                owner => $owner,
                group => $group,
                backup => $backup,
                source => "puppet://$server/dist/$source"
        }
    }

You would use the function like this:

    remotefile { "/etc/sudoers":
        mode => 440, source => "apps/sudo/sudoers"
    }

## 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, 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).

The daemon should start just fine with no arguments:

    /usr/bin/puppetmasterd

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][].

If you are still only testing, and do not have node definitions in your
site manifest (such as with the above example manifest) , tell
``puppetmasterd`` not to look for them:

    /usr/bin/puppetmasterd --nonodes

Otherwise, you will need to define each of your nodes in your site manifest:

    node culain {
        include workstation
    }

# 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 here is equivalent to
adding ``--verbose --onetime --no-usecacheonfailure``.
This 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 a message that the client did not
receive a certificate (this message will repeat every 60 seconds with the
above command).  This is normal, since your server is not autosigning
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.

Beta Notes
==========
There are some important notes to keep in mind about using the current versions of
Puppet:

* Files are currently automatically reread when they are changed, within a
  timeout of 60 seconds.
* Patches are not only welcome, they're encouraged.

[developed]: /projects/facter
[download]: /downloads
[version control]: http://svnbook.red-bean.com/
[fileserver configuration file]: fsconfigref
[Gems User Guide]: http://docs.rubygems.org/read/book/1
[Language Reference]: structures
[Library Reference]: typedocs

[packages]: /downloads/packages
[tarball]: /downloads/puppet
[gems]: /downloads/gems
[rpms]: /downloads/rpm

[yum repository]: http://people.redhat.com/~dlutter/yum/
[debian packages]: /downloads/packages/Debian

*$Id$*