Introduction to Puppet Configuration files with Examples on Linux

Puppet is used to automate several routine sysadmin configuration tasks.

Puppet in an enterprise grade configuration management system.

It allows you to define the state of your IT infrastructure. Once it is defined, Puppet will automatically enforce the correct state on an on-going basis.

1. Puppet Architecture

Puppet typically has one server component and multiple agents. You have to designate a server on your network as puppet master, and each node on your network will have puppet agent installed on it.

The most common way to apply puppet configuration to a client is to use the puppet master daemon (puppetmasterd) and puppet client daemon (puppetd). You can also manually apply the manifests using puppet tool.

Configuration is defined on the puppet master, compiled and then pushed out to the puppet clients automatically when they connect.

Puppet supports a wide range of different platforms and operating systems, and it will automatically run the appropriate commands to apply your manifest in each environment.

A manifest is nothing but details about files, packages, configuration operations written in language that puppet can understand.

Each Puppet node contacts the puppet master, by default every 30 minutes, to confirm that its configuration is up to date. If the configuration is different or any new configuration is available, it is recompiled and then applied to the puppet node.

In this tutorial, we will explain how to create some basic manifests and apply to the clients using puppet tool.

Most of the system configuration can be viewed by using the puppet command line tool. All the configuration components are organized into resources. The resources are grouped into collections. Resources are made up of type, title and series of attributes.

2. Puppet Resource File Example

The following is a basic example on how to view a puppet resource. In this case, the puppet resource that we are viewing is a file (/etc/nsswitch).

# puppet resource file /etc/nsswitch.conf
file { '/etc/nsswitch.conf':
  ensure   => 'file',
  content  => '{md5}0d6009cdfd12646d251e86303bc0c48c',
  ctime    => 'Sun May 18 13:20:02 -0400 2014',
  group    => '0',
  mode     => '644',
  mtime    => 'Tue May 04 15:22:21 -0400 2010',
  owner    => '0',
  selrange => 's0',
  selrole  => 'object_r',
  seltype  => 'etc_t',
  seluser  => 'system_u',
  type     => 'file',
}

Puppet comes with a number of resource types by default including types to manage files, services, packages, cron jobs, and filesystems, among others.

In the above example, file is the resource type and the /etc/nsswitch.conf is title of the resource to be managed.

Everything else is attributes of the resource type and values present on the attributes. You can also extend puppet to add your own resource types.

To view all the resource types available use the following command:

# puppet resource --types
augeas
computer
cron
exec
file
filebucket
group
host
nagios_hostdepend
..
..

3. Puppet Manifest File Example

Let us take a look how to create a simple manifest file and execute the puppet command to apply the configuration to the server.

The following example creates a simple manifest file site.pp under /etc/puppet/manifests directory which will create a testfile under /var/tmp.

Initially, as we see below, we don’t have the test file.

# ls -ld /var/tmp/testfile
ls: cannot access /var/tmp/testfile: No such file or directory

The following is the resource declaration inside the manifest (site.pp) file:

# cat site.pp
file { "/var/tmp/testfile":
        ensure => "present",
        owner => "root",
        group => "root",
        mode => "664",
        content => "This is a test file created using puppet.
                    Puppet is really cool",
}

For demo purposes, we are running the puppet master and agent on the same node.

When you run the puppet apply command for first time with –noop option, this will do a dry-run without actually applying the configuration.

# puppet apply site.pp --noop
Notice: Compiled catalog for pemaster.mydomain.com in environment production in 0.06 seconds
Notice: /Stage[main]/Main/File[/var/tmp/testfile]/ensure: current_value absent, should be present (noop)
Notice: Class[Main]: Would have triggered 'refresh' from 1 events
Notice: Stage[main]: Would have triggered 'refresh' from 1 events
Notice: Finished catalog run in 0.03 seconds

The above you to see what new configuration will do without actually making changes to the node.

Now, execute the command without –noop option to really apply the configuration as shown below.

# puppet apply site.pp
Notice: Compiled catalog for pemaster.mydomain.com in environment production in 0.07 seconds
Notice: /Stage[main]/Main/File[/var/tmp/testfile]/ensure: created
Notice: Finished catalog run in 0.05 seconds

Once it is executed successfully, you will see the new temp file is created under /var/tmp/testfile with the contents defined in site.pp.

# ls -ld /var/tmp/testfile
-rw-rw-r--. 1 root root 69 Jun 26 14:25 /var/tmp/testfile

# cat /var/tmp/testfile
This is a test file created using puppet.
  Puppet is really cool

4. Control a Service on a Remote Node using Puppet

Here is an example to change service from stopped state to running state on the agent nodes.

When this configuration manifest is saved in the master server under a specific location under puppet configuration directory, the agent running on all the nodes contacts the master node and fetches the configuration and applies it on all the client nodes so this way the service would be started on all the agent nodes after the puppet configuration is executed successfully.

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

In this example, we will control the service multipathd. You can use puppet to control any services that are running on the system. For example, httpd, mysqld, etc.

# puppet resource service multipathd > site.pp

Make sure the site.pp has the following values. If not, edit it accordingly.

# vi site.pp
service { 'multipathd':
  ensure => 'running',
  enable => 'true',
}

First do a dry-run to make sure it works as expected.

# puppet apply site.pp --noop
Notice: Compiled catalog for pemaster.mydomain.com in environment production in 0.07 seconds
Notice: /Stage[main]/Main/Service[multipathd]/ensure: current_value stopped, should be running (noop)
Notice: Class[Main]: Would have triggered 'refresh' from 1 events
Notice: Stage[main]: Would have triggered 'refresh' from 1 events
Notice: Finished catalog run in 0.06 seconds

Finally, apply the configuration file, which will start the service (in this example multipathd), if it is not already running.

# puppet apply site.pp
Notice: Compiled catalog for pemaster.mydomain.com in environment production in 0.07 seconds
Notice: /Stage[main]/Main/Service[multipathd]/ensure: ensure changed 'stopped' to 'running'
Notice: Finished catalog run in 0.28 seconds

# puppet resource service multipathd
service { 'multipathd':
  ensure => 'running',
  enable => 'true',
}

# chkconfig --list | grep multipath
multipathd      0:off   1:off   2:on    3:on    4:on    5:on    6:off

5. Install a Package on a Remote Node using Puppet

You can do package installation on all the agent nodes remotely using puppet.

The following is a sample manifest file for package installation.

# cat site.pp
package { 'httpd':
  ensure => 'present',
}

In this example, it will install Apache package httpd if it is not present on the remote site. As you see below, it installed the package.

# puppet apply site.pp
Notice: Compiled catalog for pemaster.mydomain.net in environment production in 0.70 seconds
Notice: /Stage[main]/Main/Package[httpd]/ensure: created
Notice: Finished catalog run in 79.97 seconds

Verify that the package is installed properly using rpm command.

# rpm -qa | grep -i httpd
httpd-2.2.15-39.el6.centos.x86_64
httpd-tools-2.2.15-39.el6.centos.x86_64

6. Two Types of Puppet Collections

Resources can configure the characteristics of single configuration items on nodes. But, most services and applications are made up of multiple resources.

For example, a web server consists of the software package, users to run the software, and a variety of configuration, logging, and other files.

Resources collections allows you to gather the resources, assign them to collection and have the collection applied to the agent nodes.

There are 2 types of resource collection:

1. Classes
2. Definitions

7. Puppet Class Collection Example

A class is a collection of resources that represents single configuration item on your node whereas definition is collection of configuration items that have multiple representations on your node.

In the previous example after the package installation the services are not started by default. We can create a simple manifest with class to install the package and start the service after installation.

In the following example we specified the relationship between two resources using require attribute.

# cat site.pp
class apache {
        package { 'httpd':
           ensure => 'present',
                }
        service {'httpd':
           ensure => 'running',
           require => Package["httpd"],
           }
}
include apache

This ensure that the condition is met before the resource changes gets applied. In this case service httpd requires the httpd package to be installed first before it can attempt to bring up the services.

# puppet apply site.pp
Notice: Compiled catalog for pemaster.mydomain.net in environment production in 0.93 seconds
Notice: /Stage[main]/Apache/Package[httpd]/ensure: created
Notice: /Stage[main]/Apache/Service[httpd]/ensure: ensure changed 'stopped' to 'running'
Notice: Finished catalog run in 32.82 seconds

# chkconfig --list | grep http
httpd           0:off   1:off   2:on    3:on    4:on    5:on    6:off

# rpm -qa | grep -i http
httpd-2.2.15-39.el6.centos.x86_64
httpd-tools-2.2.15-39.el6.centos.x86_64

8. Puppet Definition Collection Example

A definition is a type of puppet resource collection.

Definitions should be used for configuration items that have multiple instances on a node.

For example, the httpd server may have multiple virtual hosts defined. You can create a definition to configure virtual hosts and pass in appropriate arguments to configure each. As long as each set of arguments was different, puppet would configure the new virtual host every time the definition was evaluated.

The following is an example of a simple manifest with a class and definition.

# cat site1.pp
class testdefine {
    define testdefine ($data) {
      file {"$title":
        ensure  => file,
        content => $data,
      }
    }

    testdefine {'/var/tmp/puppetfile1':
      data => "The name of the file is puppetfile1 and it is created by puppet\n",
    }

    testdefine {'/var/tmp/puppetfile2':
      data => "The name of the file is puppetfile2 and it is created by puppet\n",
    }
    testdefine {'/var/tmp/puppetfile3':
      data => "The name of the file is puppetfile3 and it is created by puppet\n",
    }

}

include testdefine

Execute the above puppet class and definition manifest as shown below.

# puppet apply site1.pp
Notice: Compiled catalog for pemaster.mydomain.net in environment production in 0.24 seconds
Notice: /Stage[main]/Testdefine/Testdefine::Testdefine[/var/tmp/puppetfile2]/File[/var/tmp/puppetfile2]/ensure: defined content as '{md5}9079bd9c7650ae7d503c7df1a68bb9f0'
Notice: /Stage[main]/Testdefine/Testdefine::Testdefine[/var/tmp/puppetfile3]/File[/var/tmp/puppetfile3]/ensure: defined content as '{md5}75d495f0d3180b1f2dd052ac208d81fe'
Notice: /Stage[main]/Testdefine/Testdefine::Testdefine[/var/tmp/puppetfile1]/File[/var/tmp/puppetfile1]/ensure: defined content as '{md5}1fa93f1f2b82f8358866d58b2cb2f0b4'
Notice: Finished catalog run in 0.19 seconds

# ls -l /var/tmp/puppetfile*
-rw-r--r--. 1 root root 64 Jun 26 19:11 /var/tmp/puppetfile1
-rw-r--r--. 1 root root 64 Jun 26 19:11 /var/tmp/puppetfile2
-rw-r--r--. 1 root root 64 Jun 26 19:11 /var/tmp/puppetfile3

# cat /var/tmp/puppetfile*
The name of the file is puppetfile1 and it is created by puppet
The name of the file is puppetfile2 and it is created by puppet
The name of the file is puppetfile3 and it is created by puppet

9. Puppet Node Configuration File Example

So far we have seen defining resources and collections of resources in form of classes and definitions.

Now the next step is how to assign these resources and collections to clients.

Here is an example how the nodes are defined in node.pp.

Puppet uses this file to determine which class(contains resources) should go to which server, for example, on client 1 you want to run the class httpd which contains resources like httpd package, httpd service & on client 2 you want to run the class ngnix which contains resources like ngnix package, ngnix service & other ngnix configuration files.

The following sample nodes.pp file explains this:

node 'puppetclient1.mydomain.net' {
include httpd_class
}
node 'puppetclient2.mydomain.net' {
include ngnix_class
}
node default {
    package { "perl": 
       ensure => present }
}

Inside your node definition, you can add resources, classes and definitions.

Classes are added using the include function.

In puppetclient1.mydomain.net we have included httpd_class and in puppetclient2.mydomain.net we have included ngnix_class.

You can also include multiple class with a single include function. If no node definition is matched, then it takes the default values defined. In this case, if there is any other nodes it will just install perl packages if it is not present.

10. Import Puppet Manifest Files

The resources, classes, and definitions are stored in manifest files.

A special manifest file, called the site manifest, is at the core of our configuration.

When starting the Puppet master daemon, the site manifest file, by default located in /etc/puppet/manifests/site.pp, needs to be present.

In the above examples, we used site.pp just to explain how to apply the manifests.

In a real puppet environment your site.pp will have only the below contents and from this file the other files are imported for execution.

# cat site.pp
import "templates.pp"
import "nodes.pp"
import "classes/*"
import "groups/*"
import "users/*"
import "os/*"

The following is the puppet manifest directory structure:

• /manifests/classes/ – Directory containing all classes
• /manifests/site.pp – the primary manifest file
• /manifests/templates.pp – Contains template nodes
• /manifests/nodes.pp – Contains node definitions
• /manifests/definitions/ – Contains all definitions
• /manifests/groups/ – Contains manifests configuring groups
• /manifests/os/ – Contains classes designed to configure nodes with particular operating systems
• /manifests/users/ – Contains manifests configuring users
• /manifest/files/ – Contains file server modules for Puppet distributable files