Instant Puppet 3 Starter

You can run your puppet servers and clients on many different platforms and architectures. To get up to speed as quickly as possible, we recommend that you use Red Hat Enterprise Linux 6 or CentOS 6 for your server. There are good reasons for this, which can be stated as follows:

After you have finished this book, you can migrate the server to any platform you wish to support. This guide will help you set up the server in a manner which makes it trivial to move it to another host server.

I am going to talk about the difference between deterministic results and procedural results. I will explain how Puppet is oriented around deterministic results, and why the best results can be achieved by learning to think in a deterministic manner.

What are deterministic results? Determinism is something that returns the same result every time, given the same input. A calculator or spreadsheet both return deterministic results. You might be thinking to yourself, "isn't all software deterministic?" Not in the sense that we are talking about. Most software applications don't return the same results every time; you have to check the environment in which the software runs, and modify the input you give it. For example, let's use a very simple program that creates a new user:

$ useradd –u 2000 deterministic

That worked fine, didn't it? Now let's run the same program again, with the exact same input.

useradd: user 'deterministic' already exists

Ah, same input but not the same result; that's not deterministic at all! To actually make this very simple idea deterministic requires a larger script that validates each value against the environment:

#!/bin/sh
USER=$1
USERID=$2
FOUND=$(id -u $USER 2> /dev/null)
if [ $? -ne 0 ]; then
  useradd –u 2000 deterministic
else
  if [ $FOUND -ne $USERID ]; then
    usermod –u 2000 deterministic
  fi
fi

This is how most programming is done. You have to check A, then B, and then do C or D based on what you observe. This is called Procedural programming. Think about how much more code would be required if you wanted to ensure that the gid, the comment, the home directory, and the password were correct? What about the extra code to make this function work properly for adding a root-equivalent user with UID 0? Do you agree that this would be quite a long script? You probably have a few scripts like this around. In all likeliness you end up fixing them every time you get a new platform to support, or a new version of the operating system.

Now, let's look at how you would approach this with Puppet. In Puppet, you express the ideas in a deterministic manner. By this, I mean to say that instead of expressing the steps to get to a result, you only express what you desire the final result to be. For our previous simple example, that could be as easy as this:

user { 'deterministic': uid => 2000 } 

If you want it to be much more specific, you can ensure that all the parameters for this user are defined, with less lines of text than our previous simple script:

user { 'deterministic':
  ensure  => present,
uid    => 2000,
gid    => 2000,
  comment  => 'Deterministic User',
  home    => '/home/determinism',
  shell  => '/bin/bash',
}

Instead of spending time to write out A then B then C or D, you simply express the final result that you desire. In Puppet this is called a policy. You'll find that expressing your needs with a deterministic policy (definition of a final result) saves a lot of time, especially if you manage a heterogeneous environment, where the commands used to check for or create a user differ. You don't need to think about those differences when you are writing Puppet policies.

I'd like you to stop and reread this section one more time before we proceed. Here we have identified a very important shift in how to approach systems management. As the new users start developing their first puppet policies, it is common to see them fall back to the procedural thinking styles. They can do things with a procedural style in Puppet, but they will be fighting the current, going uphill, and wasting time. After a short while, they realize the utility of the deterministic manner and start defining their policy accordingly. They learn to do more with less, and do it faster than ever before.

I am going to try and help you avoid that first round of mistakes. We are, together, going to get you working like an experienced hand at Puppet by the end of this short book. The first step in avoiding that introductory round of wasting time is to go back and reread this section. Come to terms with the simplicity of expressing a final result.

Before you install Puppet, you will need to check that you have all of the required elements, listed as follows:

$ sudo rpm –e puppet* facter ruby rubyge*

The best way to install Puppet is to use the packaged builds provided by Puppet Labs. If you are using a system listed on the following web page, installing Puppet will be quite easy:

http://docs.puppetlabs.com/guides/puppetlabs_package_repositories.html

If you are using CentOS or Red Hat, installation could be as easy as the following:

$ sudo rpm -i http://yum.puppetlabs.com/el/6/products/x86_64/puppetlabs-release-6-6.noarch.rpm
$ sudo yum install puppet puppet-server

If you are using CentOS 5, just change the path to /el/5 and your architecture. The Puppet Labs repository includes Ruby 1.8.7, so you won't have to do anything special to install puppet.

Debian is likewise simple:

$ wget http://apt.puppetlabs.com/puppetlabs-release-precise.deb
$ sudo dpkg –I puppetlabs-release-precise.deb
$ sudo apt-get update
$ sudo apt-get puppet

Windows packages can be downloaded from http://downloads.puppetlabs.com/windows/.

Even if you prefer to build things from source, I recommend that you use the packages provided by Puppet Labs for this starter. If you have a platform that is not listed on the Puppet Labs repositories page or can't use the prebuilt packages, you can install Puppet from Ruby gems:

$ sudo gem install puppet

Or directly from source:

$ wget http://downloads.puppetlabs.com/puppet/puppet-latest.tgz
$ tar xvzf puppet-latest.tgz
$ cd puppet
$ sudo ruby install.rb

Both of these installation methods require many manual steps, which will be unique to your platform and beyond the scope of this book. You will need to follow the steps documented at the following link:

http://docs.puppetlabs.com/guides/installation.html

At this point you have installed Puppet and the Puppet server packages. Right now, before you start the server up, we're going to save you a lot of grief and a few trips to the mailing list. The single most common query on the list deals with confusion over how Puppet's mutual authentication works. Let's nip this right away, and save you the trouble:

You should make certname be a name inside your own domain, and vardir can be any directory you like. However, I recommend that you do not use the name of a real host, or the standard var client directory (/var/lib/puppet on most platforms). Use an alias for the server right now. These two settings will allow you to move your Puppet server to a new host without any difficulty later on.

I'll explain why after you add this new hostname to your DNS. Go ahead, I'll wait.

At this point we are ready to start up the server. The following command works on almost all platforms:

$sudo /sbin/service puppetmaster start

You will get the following response:

Starting puppetmaster:                [OK]

Check out /var/log/messages to ensure no errors happened. The logs will show that it created a new certificate authority based on the name you gave it earlier.

If you ever need to start again from scratch, you can always stop the server, remove the directory named in vardir, and restart the server to get a fresh, clean start:

$ sudo /sbin/service puppetmaster stop
Stopping puppetmaster:                [OK]
$ sudo rm –rf /var/lib/puppet-server
$ sudo /sbin/service puppetmaster start
Starting puppetmaster:                [OK]

Now let's configure the first client, the system running the puppet server. You will see the system authenticate by its real hostname, not the puppet alias we created in step 3. This makes it easy if you move the puppet server to another host later.

Now we create a relationship with the Puppet server. This involves a handshake on both sides, so you will need two logins, one for the client and one for the server.

On the client, run the following command:

$ sudo puppet agent --test

You'll see that the client creates a certificate request and attempts to connect to the server:

Info: Creating a new SSL key for myhost.example.net
Info: Caching certificate for ca
Info: Creating a new SSL certificate request for myhost.example.net
Info: Certificate Request fingerprint (SHA256): 12:34:56:78:9A:BC:DE…
Exiting; no certificate found and waitforcert is disabled.

The final sentence isn't an error. This gives us time to sign the certificate request on the server. On the server, use the following command to see the authentication requests:

$ sudo puppet cert list

You will get the following response:

"myhost.example.net" (SHA256) 12:34:56:78:9A:BC:DE…

Look at the certificate request from the client. Compare the fingerprint and then sign the certificate as follows:

$ sudo puppet cert sign myhost.example.net

You will get the following response:

Notice: Signed certificate request for myhost.example.net
Notice: Removing file Puppet::SSL::CertificateRequestmyhost.example.netat '/var/lib/puppet-server/ssl/ca/requests/myhost.example.net.pem'

And now in the final step, we will connect with the client again. It will download the signed certificate and complete its first transaction with the server:

$ sudo puppet agent --test 

You will get the following response:

Info: Caching certificate for myhost.example.net
Info: Caching certificate_revocation_list for ca
Info: Retrieving plugin
Info: Caching catalog for myhost.example.net
Info: Applying configuration version '1357512658'
Info: Creating state file /var/lib/puppet/state/state.yaml
Notice: Finished catalog run in 0.06 seconds

At this point you have seen the client establish a connection with the server and download the node's catalog. We will explain what the catalog is in the next section. There's nothing in the policy just yet, so there is nothing in the catalog. But the secure relationship between the client and the server has been created and we'll be using this to test our policies.

You now have a working installation of Puppet. Let's move to the next section and create a basic policy.

At this point in the process, it would be essential for me to tell you how to ensure that Puppet runs after reboot. It would be chkconfig on the RHEL systems, or update-rc.d on Debian, or smf on Solaris. But hey, why don't we use Puppet itself and let you see how Puppet saves you time and effort?

Use your favorite editor to edit /etc/puppet/manifests/site.pp. Add the following code:

node default {
  service { 'puppet': 
    ensure => running,
    enable => true,
  }
}

ensure => running means that the Puppet agent daemon should be running. This might sound like a catch-22, but it's not really. You can run the Puppet agent manually (we will do this throughout the book.) This service resource ensures that the daemon is running, and starts it if it is not.

enable => true ensures that the process is configured to start up at boot time. This means different things on different platforms, but Puppet allows us to not focus on those details.

Now go to a client node and run the following command. You will see it apply this policy to the system:

$ sudo puppet agent –-test

You will get the following response:

Info: Retrieving plugin
Info: Caching catalog for myhost.example.net
Info: Applying configuration version '1357518358'
Notice: /Stage[main]//Node[default]/Service[puppet]/ensure: ensure changed 'stopped' to 'running'
Notice: Finished catalog run in 0.95 seconds

If you want to stop the Puppet daemon, you could easily change the policy to the following code. During the next Puppet run it will disable the service and stop the daemon:

service { 'puppet': 
  ensure => stopped,
  enable => false,
}

You can't start services if their packages aren't installed. So why don't we tweak the default node and add a little bit more code? The following segment ensures that the Puppet package is installed, and is the latest version. If the Puppet package is updated, the Puppet service will restart itself to get the new version:

  package { 'puppet': 
    ensure    => latest,
    notify    => Service['puppet'],
  }
service { 'puppet': 
    ensure    => running,
    enable    => true,
    subscribe => Package['puppet'],
  }

Notice how easy it is to set up dependencies between items? notify and subscribe are actually redundant here. You only need one or the other to build the linkage between these two resources. But if you're a belt-and-suspenders kind of person, it never hurts to list the dependency in both the places.

Now let's go a little further and customize the policy for one node. In the following section, we are going to ensure that the Puppet server is running the latest version of the Puppet master. Just below the default node block, let's add the following code:

node puppet-server-name inherits default {
  package { 'puppet-server': 
    ensure    => latest,
    notify    => Service['puppetmaster'],
  }
  service { 'puppetmaster': 
    ensure    => running,
    enable    => true,
    subscribe => Package['puppet-server'],
  }
}

The inherits syntax of the node line says "do everything most nodes do, and also include this policy". You could leave off inherits default and the node would only execute the policy specifically within the node block. In this step we have now customized the catalog, which will be given to this one node.

Let's enable file synchronization down to the client node. First, we need to enable the file server. Use your favorite editor to edit /etc/puppet/fileserver.conf:

[files]
  path /etc/puppet/files
  allow *

Now let's create some test files for this example. We'll make the directory owned by you so that we don't have to sudo every command:

$ sudo mkdir /etc/puppet/files
$ sudo chown `id –u` /etc/puppet/files
$ cp /etc/hosts /etc/puppet/files/
$ cp /etc/motd /etc/puppet/files/

Now let's put some file resources here as examples. You can put the following policy text in the default node block (for all hosts), or you can put it inside a node block for a single host:

  file { '/tmp/hosts':
    ensure  => file, 
    owner   => nobody,
    group   => nobody,
    mode    => 0444,
    force   => false,
    source  => 'puppet:///files/hosts',
  }

  file { '/tmp/hosts.linked':
    ensure  => link,
    target  => '/tmp/hosts',
  }

  file { '/tmp/puppet-files':
    ensure  => directory, 
    owner   => root,
    group   => root,
    mode    => 0444,
    recurse => true,
    source  => 'puppet:///files',
  }

Now let's test out the revised policy on your node:

$ sudo puppet agent --test

You will get the following response:

Info: Retrieving plugin
Info: Caching catalog for myhost.example.com
Info: Applying configuration version '1357520339'
Notice: /Stage[main]//Node[myhost]/File[/tmp/hosts]/ensure: defined content as '{md5}41e6824ef17c17aa577cd6fd6f794351'
Notice: /Stage[main]//Node[myhost]/File[/tmp/hosts.linked]/ensure: created
Notice: /Stage[main]//Node[myhost]/File[/tmp/puppet-files]/ensure: created
Notice: /File[/tmp/puppet-files/hosts]/ensure: defined content as '{md5}41e6824ef17c17aa577cd6fd6f794351'
Notice: /File[/tmp/puppet-files/motd]/ensure: defined content as '{md5}d41d8cd98f00b204e9800998ecf8427e'
Notice: Finished catalog run in 0.51 seconds

With a simple ls –la /tmp you'll be able to see the file, link, and directory that this policy has created.

At this point we've created a small but very effective Puppet policy. You have three different ways to copy files down to hosts. Packages are installed, and services are stopped or started based on your policy. And yet, the entire policy as expressed in the site.pp file, still fits on a single page. In this you can start to perceive the power of Puppet.

Modules are self-contained classes that provide new resources, facts, types, providers, and functions for use in your puppet policy. Each module has its own namespace, so its variables will not conflict with the variables within your policy, or within another module. You can create your own modules, or you can download them from the Puppet Forge.

Module names should only contain lowercase letters, numbers, and underscores, and should begin with a lowercase letter. There is a reason for the last requirement, which I will explain later.

Modules are installed in your module path, usually /etc/puppet/modules.

Now we shall take the examples from our previous section, and build a complete module for maintaining the puppet configuration on your clients and the server. This idea could be easily expanded to maintain any other application. The first step is to build the correct directory structure for a module. The following puppet command will create all of the necessary files and directories for a module to operate as expected:

$ cd /etc/puppet/modules
$ puppet module generate my-puppet
Notice: Generating module at /etc/puppet/modules/my-puppet
my-puppet
my-puppet/spec
my-puppet/spec/spec_helper.rb
my-puppet/README
my-puppet/manifests
my-puppet/manifests/init.pp
my-puppet/tests
my-puppet/tests/init.pp
my-puppet/Modulefile
$ mv my-puppet puppet   ##(see tip below)##
$ cd puppet
$ mkdir files templates
$ cd manifests

The one file that must exist in every module is manifests/init.pp. This file must contain a class with the same name as the module. Use your favorite editor and open that file now. Set up the initial contents as follows:

class puppet(
  $version      = 'latest',
  $status       = 'running',
  $environment  = 'production',
  $server       = 'puppet.example.net',
) {
  package { 'puppet': 
    ensure  => $version,
    notify  => Service['puppet']
       }
  service { 'puppet':
    ensure  => ${status},
    enable  => true,
    require => Package['puppet'],
  }
}

You will observe that this is much like the Puppet policy we used in site.pp. You will also note that we have supplied four new variables but only used one of them. We will get to that shortly. For now, let's go back to site.pp and remove this policy. In site.pp, we will replace that with the following invocation of our module:

node default {
  class { 'puppet': }
}

Much shorter and easier to read, isn't it? We have replaced a block of code with a simple module invocation. This is the main benefit of modules; they allow you to make extensive changes with small and easy-to-read policy statements.

node default {
  class { 'puppet':
    version => '3.2.0'
  }
}

class puppet::server(
  $version = 'latest',
  $status  = 'running',
  $onboot  = true,
) {
  package { 'puppet-server': 
    ensure => $version,
    notify => Service['puppetmaster'],
  }
  service { 'puppetmaster': 
    ensure  => $status,
    enable  => $onboot,
  }
}

node puppet-server-name inherits default {
  class { 'puppet::server': 
    version => '3.2.0',
  }
}

$packagename = $operatingsystem ? {
  'redhat'  => 'puppet',
  'freebsd' => 'puppet3',
  default   => 'puppet',
}
package { ${packagename}: 
  ensure  => $version,
  notify  => Service['puppet'],
  }

$ cd /etc/puppet/modules/puppet/
$ cp /etc/puppet/puppet.conf files/ puppet.conf

file { '/etc/puppet/puppet.conf':
  ensure  => file, 
  source  => 'puppet:///modules/puppet/puppet.conf',
  owner   => root,
  group   => root,
  mode    => 0444,
  force   => true,
  notify  => Service['puppet'],
}

$ cd /etc/puppet/modules/puppet/
$ cp /etc/puppet/puppet.conf templates/puppet.conf.erb

  server      = <%= @server =>
  environment = <%= @environment =>

file { '/etc/puppet/puppet.conf':
  ensure  => file, 
  content => template('puppet/puppet.conf.erb'),
  owner   => root,
  group   => root,
  mode    => 0444,
  force   => true,
  notify  => Service['puppet'],
}

node /testlab/ {
  class { 'puppet': 
    server      => 'labhost.example.net',
    environment => 'staging',
  }
}

You have probably noticed from the preceding examples that in most situations the Puppet resources are lowercase, but in some cases the resource types are capitalized. Why is that? When should you use upper or lowercase for the resource types?

When you define new resource, you must use lowercase:

service { 'puppet: ensure => running }

When you later refer to that specific resource, you capitalize the resource type. Think of this as a proper noun. In the preceding example you have created a service. After you have created and named this service, you use the capitalized form to refer to it:

package { 'puppet:
  ensure => present,
  notify => Service['puppet],
}

A lowercase resource declares a specific instance. A capitalized resource type refers to an existing resource defined somewhere else. Okay, the proper name analogy isn't quite accurate because we capitalize the resource type, not the resource title. However, it remains the easiest way to think of it.

You will also use uppercase when you want to define some default attributes for a resource. In this situation you use the capitalized resource type without a title. Here are some examples of defaults for some resources:

User {
  managehome => true,
  shell      => '/bin/bash',
}
Package {
  schedule => 'daily',
}

With these definitions, all the packages in a module will be checked in the daily schedule, unless explicitly defined otherwise, and all users will have the Bash shell unless explicitly overridden. This can save you a great deal of redundant lines in some circumstances.

You may want to limit how often a puppet resource is applied. For example, the Puppet Exec resource type allows you to run an arbitrary command. Unfortunately, the Exec resource will run during every Puppet run. There are two ways to limit how often a resource is applied: run it only when notified, or limit the runs by a schedule. Here are some examples:

You can tell a resource to only apply itself to the system when another resource notifies it. This is done by defining the refreshonly attribute. Here's an example that updates a file containing a list of installed packages every time a new package is installed:

# This defines the default, so all packages will notify the exec
Package {
  notify => Exec['save-package-list'],
}
exec { 'save-package-list':
  command     => 'rpm –qa> /var/tmp/packages-installed.txt',
  refreshonly => true,
}

Since a resource is only applied once, the command will be run only once no matter how many packages were installed during the Puppet run. If we did not have the refreshonly attribute, the command would be run every time the Puppet agent ran.

Another way to limit how often or when a resource is applied is by using a schedule. A schedule allows you to specify the hours a resource may be applied within, and how often within a given period. For example, I prefer to limit the package upgrades to early in the day when people will be around to deal with any issues that may arise:

# Schedule in the early part of the working day (not peak)
schedule { 'early-day':
  range       => '9 - 13',
  period      => daily,
periodmatch => number,
}# default for all packages
Package {
  schedule => 'early-day',
}

You can read more about defining schedules at http://docs.puppetlabs.com/references/latest/type.html#schedule and more about the schedule and refreshonly metaparameters that you can apply to any resource at http://docs.puppetlabs.com/references/latest/metaparameter.html.

If you step back and look at how your site policy site.pp has changed, you will notice that we have done something very important. We have moved all of the nitty-gritty details (such as the exact name of the Puppet package on each platform) out of the site policy, while leaving all the control and characterization there.

A well-built module hides all of the detailed work of implementation, without specifying the policy. The site manifest defines whether to install a module, what version it should be installing, and whether it should be enabled. This makes it to use the site manifest as a documentation for the site configuration. It becomes easy to expand a configuration to include a whole new class of hosts without any changes the modules.

Likewise, you can add an entirely new operating system to your environment without changing your site policy. In that situation you would edit the modules as necessary, with selectors for each distinct characteristic of the new operating system.

The site manifest expresses what you want. The modules are like butlers and maids; components which implement policy without bothering you with the details. You will find that this approach enables you to do more, faster, and easier than ever before.

The easiest way to review the history of changes made to the system is to examine the Puppet log. This is normally in the messages log from syslog, but you can also enable direct file logging in the puppet.conf configuration. If you are just looking for the recent changes on a client system, the following is likely all you need:

$ grep puppet-agent /var/log/messages

You can also have the Puppet agent send a report to the server. The server can store or process these reports. Let's see how to set that up now. The first step is to enable the sending of reports to the server. Add the following line to /etc/puppet/puppet.conf:

[agent]
  report = true

Now we need to tell the server what to do with the reports. Here is an example setting for the server:

[master]
  reports = tagmail, store

This tells the server to store the Puppet report and to give it to a report processor named tagmail. You can also create your own report processor and list it here.

cron { 'clean-up-reports':
  ensure  => present,
  command => 'find /var/lib/puppet-server/reports –type f –name \*.yaml –mtime +21 –delete', 
  user    => puppet,
  weekday => 0,
  hour    => 2,
  minute  => 11,
}

# Send every log message at every level to me
all: me@example.net

# Send critical messages to my pager
alert,emergy,crit: 4155551212@vtext.com

# Send log messages from the apache module to the webmaster
apache,!info,!debug: webmaster@example.net

# Send every change notification or error to the operations team
notice,warning,err,alert,emergy,crit: operations@example.net

[master]
reports = tagmail, store, http
reporturl = http://dashboard.example.net/reports/upload

$ sudo yum install mysql-server puppet-dashboard

$ sudo /sbin/service puppet-dashboard start
$ sudo /sbin/service puppet-dashboard-workers start
$ sudo /sbin/chkconfig puppet-dashboard on
$ sudo /sbin/chkconfig puppet-dashboard-workers on 

When Puppet changes a file, it makes a backup of the file and stores it on the disk in the directory specified by the clientbucket configuration option. You can pull the old versions of files out of this directory at any time. Puppet includes a command to restore the files, but it doesn't provide a command to find them. Given the odd directory structure with the file contents stored by their MD5 checksum, this isn't trivial. Here's a good script for finding the Puppet backups of a given file:

#!/bin/bash 
FILE=$1
FOUND=0
CLIENTBUCKET=$(puppet config print clientbucketdir) 

echo "Searching for local backups of $FILE..." 
for backup in $(find $CLIENTBUCKET -type f -name paths \
  -exec grep -l $FILE {} \; |xargs -r ls -t); 
do 
  hash=$( basename $(dirname $backup)) 
  filename=$(< $backup ) 
  modify_time=$(stat --format '%y' $backup) 
  echo -e "$filename\t$hash\t$modify_time" 
  FOUND=$((FOUND+1)) 
done 

if [ $FOUND -gt 0 ]; then 
  if [ $FOUND -eq 1 ]; then 
	echo "1 backup was found." 
  elif [ $FOUND -gt 1 ]; then
	echo "$FOUND backups were found."
  fi
   echo "" 
   echo "To view a file: puppet filebucket get -b $CLIENTBUCKET <hash>"
   echo "To restore a file: puppet filebucket restore -b $CLIENTBUCKET /new/path <hash>"

else 
    echo "No previous versions of the $FILE were found."
fi

An exercise for the reader: use the file resource example from the Quick start section and replicate this script to all client nodes.

Environments provide you with the ability to isolate pieces of code and only invoke them for systems specifically configured for that environment, or only when the environment is enabled by hand. I'll show you how you can use environments to extend what Puppet can accomplish.

The following configuration option will provide flexibility when loading modules. This configuration will first check to see if a module exists in an environment-specific directory, then fall back to the main module directory. The rest of the following examples assume that you have added this option and restarted the Puppet master:

[master]
modulepath = $confdir/env/$environment/modules:$confdir/modules

[agent]
 environment = testing

$ sudo puppet agent --test --environment testing

$ sudo puppet agent --test --environment release

The Puppet master process is a WEBrick ruby application server. It will handle only two concurrent Puppet clients. In any environment with more than 50 Puppet clients before it gets overloaded. If you intend to have more than 50 clients, you should disable the Puppet master process and enable it under a more powerful Ruby on the Rails application server. In this section we will document how to make it run under the popular Passenger Rails application server.

First, you will need to install the Apache web server and Phusion Passenger for your platform. The platform-specific instructions are available at http://www.modrails.com/documentation/Users%20guide%20Apache.html.

If you are using a Red Hat or CentOS system, it could be as simple as this:

$ sudo rpm –i http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
$ sudo rpm –i http://passenger.stealthymonkeys.com/rhel/6/passenger-release.noarch.rpm
$ sudo yum install httpd rubygems mod_ssl mod_passenger

Configure the puppetmaster service as a Passenger application. We do this by creating a configuration file for Apache, which defines the Puppet master application, and a config.ru file that contains the Phusion Passenger application environment. All of these steps must be done as root:

$ sudo bash
# sed –e 's/squigley.namespace.at/puppet.example.net/' \
  -e 's#/etc/puppet/ssl#/var/lib/puppet-server/ssl#' \
  /usr/share/puppet/ext/rack/files/apache2.conf\
  > /etc/httpd/conf.d/puppetmaster.conf

# mkdir –p /etc/puppet/rack/public
# sed –e 's#/var/lib/puppet#/var/lib/puppet-server#' \
/usr/share/puppet/ext/rack/files/config.ru \
>/etc/puppet/rack/config.ru
# chown puppet /etc/puppet/rack/config.ru
# exit

The chown command shown the previous code snippet is essential. Passenger runs the application specified in the config.ru file as the user who owns the file. Failing to set the owner of this file correctly is more than 50 percent of the issues we see on the mailing list.

Now, stop the Puppet master service (and Puppet Dashboard if you have it) and start Apache Passenger.

$ sudo /sbin/service puppetmaster stop
Stopping puppetmaster:                [OK]
$ sudo /sbin/chkconfigpuppetmaster off
$ sudo /sbin/chkconfighttpd on
$ sudo /sbin/service httpd start
Starting httpd:                [OK]

At this point you can test your clients as before. Absolutely nothing should be different from a client/agent perspective.

To run Puppet Dashboard under Passenger, you would create a configuration file named /etc/httpd/conf.d/dashboard.conf, similar to the example file /usr/share/puppet-dashboard/ext/passenger/dashboard-vhost.conf. However, be aware that the first 12 lines duplicate the settings already present in the other files in this directory. I would start with the following file, and add more options from the example as necessary:

<VirtualHost *:80>
  ServerNamedashboard.example.net
  DocumentRoot /usr/share/puppet-dashboard/public/
  RailsBaseURI /
  <Directory /usr/share/puppet-dashboard/public/>
    Options None
    Order allow,deny
    allow from all
  </Directory>
  ErrorLog /var/log/httpd/dashboard.example.net_error.log
  LogLevel warn
  CustomLog /var/log/httpd/dashboard.example.net_access.log combined
  ServerSignature On</VirtualHost>

Then perform the following steps to make the change active:

$ sudo /sbin/service puppet-dashboard stop
Stopping Puppet Dashboard:           [OK]
$ sudo /sbin/chkconfig puppet-dashboard off
$ sudo rm /etc/httpd/conf.d/welcome.conf
$ sudo /sbin/service httpd restart
Stopping httpd:                      [OK]
Starting httpd:                      [OK]

Do you already have a source of data about your hosts or users? You really wouldn't want to maintain that same data in your Puppet policy now, would you? In this section we will talk about how to import external data and use it in your Puppet policy.

The best way to source external data is through a component called Hiera. Since you can import any kind of data, this topic is worthy of its own book. But we will set up a very small but powerful example that you can easily expand on: providing a list of user accounts.

All examples in this section use the YAML data format. You can install modules to provide other data backends, like JSON or MySQL. Puppet 3 includes only two Hiera backends by default: YAML and Puppet. The Puppet backend allows you to lookup data from Puppet and return it with the YAML data in a single result set.

---
:backends:
  - yaml
:yaml:
  :datadir: '/etc/puppet/hiera'
:hierarchy:
  - %{::hostname} 
  - common

---
managehomedirs: true
users: 
  root:
    uid: 0
    gid: 0
  jack:
    uid: 1002
    gid: 1002
  jill:
    uid: 1001
    gid: 1001

---
users:
  john:
    uid: 1003
    gid: 1003

$managehomedirs = hiera('managehomedirs')
$users          = hiera_hash('users')

class 'users' {
  $managehomedirs = hiera('managehomedirs',true)
  $defaults       = { managehome => $managehomedirs }
  $userlist       = hiera_hash('users')
  create_resources( user, $userlist, $defaults )
}

The official site is the only location to download Puppet itself, and contains the best tutorials for various bits of the puppet ecosystem. The official site is http://docs.puppetlabs.com/#puppetpuppet.

The Puppet Forge is a community-driven collection of custom Puppet modules written by others. Before you set out to write your own module, you should check the Forge to see if someone has already done most of the work for you. The Puppet Forge webpage is at http://forge.puppetlabs.com/.

The following links go into the topics we have introduced in this book in greater depth: