Installing Puppet is easy. On large Linux distributions, you can just install the Puppet package via apt-get or yum.

The installation of Puppet can be done in the following ways:

• From default operating system repositories
• From Puppet Inc

The former way is generally simpler. Chapter 2, Puppet Server and Agents, provides simple instructions to install the Puppet Inc packages. A platform-independent way to install Puppet is to get the puppet Ruby gem. This is fine for testing and managing single systems, but it is not recommended for production use.

After installing Puppet, you can use it right away. Puppet is driven by manifests, the equivalent of scripts or programs, written in Puppet's Domain-Specific Language (DSL). Let's start with the obligatory Hello, world! manifest:

# hello_world.pp
notify { 'Hello, world!':
} 

To put the manifest to work, use the following command (we avoided the term execute on purpose-manifests cannot be executed; more details will follow around the middle of this chapter):

root@puppetmaster:~# puppet apply hello_world.pp
Notice: Compiled catalog for puppetmaster.example.net in environment production in 0.45 seconds
Notice: Hello, world!
Notice: /Stage[main]/Main/Notify[Hello, world!]/message: defined 'message' as 'Hello, world!'
Notice: Applied catalog in 0.03 seconds  

Before we take a look at the structure of the manifest and the output from the puppet apply command, let's do something useful, just as an example. Puppet comes with its own background service. Let's assume that you want to learn the basics before letting it mess with your system. You can write a manifest to have Puppet make sure that the service is not currently running and will not be started at system boot:

# puppet_service.pp
service { 'puppet':
  ensure => 'stopped',
  enable => false,
}

To control system processes, boot options, software installation, and the same as the Puppet needs to be run with root privileges. This is the most common way to invoke the tool, because Puppet will often manage OS-level facilities. Apply your new manifest with root access, either through sudo or from a root shell, as shown in the following transcript:

root@puppetmaster:~# puppet apply puppet_service.pp
Notice: Compiled catalog for puppetmaster.example.net in environment production in 0.61 seconds
Notice: /Stage[main]/Main/Service[puppet]/ensure: ensure changed 'running' to 'stopped'
Notice: Applied catalog in 0.15 seconds 

Now, Puppet has disabled the automatic startup of its background service for you. Applying the same manifest again has no effect, because the necessary steps are already complete:

root@puppetmaster:~# puppet apply puppet_service.pp
Notice: Compiled catalog for puppetmaster.example.net in environment 
production in 0.62 seconds
Notice: Applied catalog in 0.07 seconds  

This reflects a standard behavior in Puppet: Puppet resources are idempotent, which means that every resource first compares the actual (system) with the desired (Puppet) state and only initiates actions in case there is a difference (configuration drift).

You will often get this output from Puppet. It tells you that everything is as it should be. As such, this is a desirable outcome, like the all clean output from git status.

Each of the manifests you wrote in the previous section declared one respective resource. Resources are the elementary building blocks of manifests. Each has a type (in this case, notify and service, respectively) and a name or title (Hello, world! and puppet). Each resource is unique to a manifest, and can be referenced by the combination of its type and name, such as Service["puppet"]. Finally, a resource also comprises a list of zero or more attributes. An attribute is a key-value pair, such as "enable => false".

Attribute names cannot be chosen arbitrarily. They are part of the Puppet resource type. Puppet differentiates between two different attributes: parameters and properties. Each resource type supports a specific set of attributes. Parameters describe the way that Puppet should deal with a resource type. Properties describe a specific setting of a resource. Certain parameters are available for all resource types (metaparameters), and some names are just very common, such as ensure. The service type supports the ensure property, which represents the status of the managed process. Its enabled property, on the other hand, relates to the system boot configuration (with respect to the service in question).

You have already seen two properties in action. Let's look at a parameter:

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

The provider parameter tells Puppet that it needs to interact with the upstart subsystem to control its background service, as opposed to systemd or init. If you don't specify this parameter, Puppet makes an educated guess. There is quite a multitude of supported facilities to manage services on a system. You will learn more about providers and their automatic choosing later on.

The difference between parameters and properties is that the parameter merely indicates how Puppet should manage the resource, not what a desired state is. Puppet will only take action on property values. In this example, these are ensure => 'stopped' and enable => false. For each such property, Puppet will perform the following tasks:

• Test whether the resource is already in sync with the target state
• If the resource is not in sync, it will trigger a sync action

A property is considered to be in sync when the system entity that is managed by the given resource (in this case, the upstart service configuration for Puppet) is in the state that is described by the property value in the manifest. In this example, the ensure property will be in sync only if the puppet service is not running. The enable property is in sync if upstart is not configured to launch Puppet at system start.

As a mnemonic concerning parameters versus properties, just remember that properties can be out of sync, whereas parameters cannot.

Puppet also allows you to read your existing system state by using the puppet resource command:

root@puppetmaster:~# puppet resource user root
user { 'root':
  ensure           => 'present',
  comment          => 'root',
  gid              => '0',
  home             => '/root',
  password         => '$6$17/7FtU/$TvYEDtFgGr0SaS7xOVloWXVTqQxxDUgH.
  eBKJ7bgHJ.hdoc03Xrvm2ru0HFKpu1QSpVW/7o.rLdk/9MZANEGt/',
  password_max_age => '99999',
  password_min_age => '0',
  shell            => '/bin/bash',
  uid              => '0',
}  

Please note that some resource types will return read-only attributes (for example, the file resource type will return mtime and ctime). Refer to the appropriate type's documentation.

As you have already witnessed, the output presented by Puppet is rather verbose. As you get more experienced with the tool, you will quickly learn to spot the crucial pieces of information. Let's first take a look at the informational messages, though. Apply the service.pp manifest once more:

root@puppetmaster:~# puppet apply puppet_service.pp
Notice: Compiled catalog for puppetmaster.example.net in environment production in 0.48 seconds
Notice: Applied catalog in 0.05 seconds

Puppet took no particular action. You only get two timings: one from the compiling phase of the manifest, and the other from the catalog application phase. The catalog is a comprehensive representation of a compiled manifest. Puppet bases all its efforts concerning the evaluation and syncing of resources on the content of its current catalog.

Now, to quickly force Puppet to show you some more interesting output, pass it a one-line manifest directly from the shell. Regular users of Ruby or Perl will recognize the call syntax:

# puppet apply -e'service { "puppet": enable => true, }'
Notice: Compiled catalog for puppetmaster.example.net in environment production in 0.62 seconds
Notice: /Stage[main]/Main/Service[puppet]/enable: enable changed 'false' to 'true'
Notice: Applied catalog in 0.12 seconds.

You instructed Puppet to perform yet another change on the Puppet service. The output reflects the exact change that was performed. Let's analyze this log message:

• The Notice: keyword at the beginning of the line represents the log level. Other levels include Warning, Error, and Debug
• The property that changed is referenced with a whole path, starting with Stage[main]. Stages are beyond the scope of this book, so you will always just see the default of main here
• The next path element is Main, which is another default. It denotes the class in which the resource was declared. You will learn about classes in Chapter 4, Combining Resources in Classes and Defined Types
• Next, is the resource. You already learned that Service[puppet] is its unique reference
• Finally, enable is the name of the property in question. When several properties are out of sync, there will usually be one line of output for each property that gets synchronized
• The rest of the log line indicates the type of change that Puppet saw fit to apply. The wording depends on the nature of the property. It can be as simple as created, for a resource that is newly added to the managed system, or a short phrase, such as changed false to true

Another useful command-line switch for puppet apply is the --noop option.
It instructs Puppet to refrain from taking any action on unsynced resources.
Instead, you only get a log output that indicates what will change without the switch. This is useful in determining whether a manifest would possibly break anything on your system:

root@puppetmaster:~# puppet apply puppet_service.pp --noop
Notice: Compiled catalog for puppetmaster.example.net in environment production in 0.63 seconds
Notice: /Stage[main]/Main/Service[puppet]/enable: current_value true, should be false (noop)
Notice: Class[Main]: Would have triggered 'refresh' from 1 events
Notice: Stage[main]: Would have triggered 'refresh' from 1 events
Notice: Applied catalog in 0.06 seconds  

The additional notices about triggered refreshes will be described later, and can be ignored for the moment. You will have a better understanding of their significance after finishing this chapter and Chapter 4, Combining Resources in Classes and Defined Types.

Variable assignment works just like it does in most scripting languages. Any variable name is always prefixed with the $ sign:

$download_server = 'img2.example.net'
$url = "https://${download_server}/pkg/example_source.tar.gz"  

Also, just like most scripting languages, Puppet performs variable value substitution in strings that are in double quotes, but no interpolation at all in single-quoted strings.

Variables are useful for making your manifest more concise and comprehensible. They help you with the overall goal of keeping your source code free from redundancy. An important distinction from variables in imperative programming and scripting languages is the immutability of variables in Puppet manifests. Once a value has been assigned, it cannot be overwritten.

Why is it called a variable at all if it is a constant? One should never look at Puppet as a tool that manages a single system. For a single system, a Puppet variable might look like a constant, but Puppet manages a multitude of systems with different operating systems. Across all these systems, variables will be different and not constants.

As of Puppet 3.x, there are only four variable types: strings, arrays, hashes, and Booleans. Puppet 4 introduces a rich data type system. The new data type system will be explained at the end of, Chapter 7, New Features from Puppet 4 and 5. The basic variable types work much like their respective counterparts in other languages. Depending on your background, you might be familiar with using associative arrays or dictionaries as semantic equivalents to Puppet's hash type:

$a_bool = true
$a_string = 'This is a string value'
$an_array = [ 'This', 'forms', 'an', 'array' ]
$a_hash = { 
  'subject'   => 'Hashes',
  'predicate' => 'are written',
  'object'    => 'like this',
  'note'      => 'not actual grammar!',
  'also note' => [ 'nesting is',
{ 'allowed'   => ' of course' } ], 
}

Accessing the values is equally simple. Note that the hash syntax is similar to that of Ruby, not Perl:

$x = $a_string
$y = $an_array[1]
$z = $a_hash['object'] 

Strings can be used as resource attribute values, but it's worth noting that a resource title can also be a variable reference:

package { $apache_package:
  ensure => 'installed'
}

It's intuitively clear what a string value means in this context. But you can also pass arrays here to declare a whole set of resources in one statement. The following manifest manages three packages, making sure that they are all installed:

$packages = [
  'apache2',
  'libapache2-mod-php5',
  'libapache2-mod-passenger',
 ]
package { $packages:
  ensure => 'installed'
}

You will learn how to make efficient use of hash values in later chapters.

The array does not need to be stored in a variable to be used, but it is a good practice in some cases.

The data type system in Puppet 4 allows you to check and verify whether a variable is of a specific data type. This prevents code from behaving incorrectly when (for example) it expects an array but receives a Boolean value.

The full power of data types will be explained in Chapter 7, New Features from Puppet 4 and 5. Within Puppet manifests, it is possible to check for data types using the regexp control structure.

Puppet has core data types and abstract data types. The core data types are the most commonly used types of data, such as string or integer, whereas abstract data types allow for more sophisticated type validation, such as optional or variant.

Prior to dealing with data types, we must understand the concept of control structures within Puppet manifests.

So far, you have written three simple manifests while following the instructions in this chapter. Each comprised only one resource, and one of them was given on the command line using the -e option. Of course, you would not want to write distinct manifests for each possible circumstance. Instead, just as how Ruby or Perl scripts branch out into different code paths, there are structures that make your Puppet code flexible and reusable for different circumstances.

The most common control element is the if/else block. It is quite similar to its equivalents in many programming languages:

if 'mail_lda' in $needed_services {
  service { 'dovecot': enable => true }
} else {
  service { 'dovecot': enable => false }
}

The Puppet DSL also has a case statement, which is reminiscent of its counterparts in other languages as well:

case $role {
  ‘imap_server’: {
    package { ‘dovecot’: ensure => installed, }
    service { ‘dovecot’: ensure => running, }
  }
  /_webservers$/: {
    service { [‘apache’, ‘ssh’]: ensure => running, }
  }
  default: {
    service { ‘ssh’: ensure => running, }
  }
}

At the second matcher, you can see how it is possible to use regular expressions.

The case statement can also be used to switch to specific code based on variable data types:

case $role {
  Array: {
    include $role[0]
  }
  String: {
    include $role
  }
  default: {
    notify { 'This nodes $role variable is neither an 
    Array nor a String':}
  }
}

A variation of the case statement is the selector. It's an expression, not a statement, and can be used in a fashion similar to the ternary if/else operator found in C-like languages:

package { 'dovecot':
  ensure => $role ? {
    'imap_server' => 'installed',
    /desktop$/    => 'purged',
    default       => 'removed',
  },
}

Similar to the case statement, the selector can also be used to return results, depending on the data types:

package { 'dovecot':
  ensure  => $role ? {
    Boolean => 'installed',
    String  => 'purged',
    default => 'removed',
  },
}

The selector should be used with caution, because in more complex manifests, this syntax will impede readability.