Chapter 20. Creating a Puppet Master

This chapter will cover installing and tuning the well-known Puppet master Rack application.

At this point, we’re going to spin up another virtual machine. You should open a new Terminal window, or add a new tab on your existing terminal for this virtual machine. This will allow you to switch back and forth between the machines, which is necessary in this chapter.

Starting the puppetmaster VM

In the new Terminal window, move into the directory where you checked out the learning-puppet4 Git repository. Start up the puppetmaster instance just like we did the client instance at the beginning of the book:

~$ cd learning-puppet4
learning-puppet4$ vagrant up puppetmaster
Bringing machine 'puppetmaster' up with 'virtualbox' provider...
==> puppetmaster: Importing base box 'puppetlabs/centos-7.2-64-nocm'...
==> puppetmaster: Matching MAC address for NAT networking...
==> puppetmaster: Checking if box 'puppetlabs/centos-7.2-64-nocm' is up to date.
==> puppetmaster: Setting the name of the VM: learning-puppet4_puppetmaster_1437
...snip...
==> puppetmaster: Machine booted and ready!

Now that it is running, log in and get started:

learning-puppet4$ vagrant ssh puppetmaster
[vagrant@puppetmaster ~]$

Installing the Puppet Master

The Puppet master is included in the Puppet agent all-in-one (AIO) package. Install the puppet-agent package exactly as you did on the client instance. You can refer back to Part I for the installation instructions, or simply run the fastsetup.sh script shown here. This script installs all the dependencies and symlinks discussed earlier:

[vagrant@client ~]$ /vagrant/bin/fastsetup.sh
Installing utilities necessary for the lessons
warning: /var/cache/yum/x86_64/7/base/packages/gpm-libs-1.20.7-5.el7.x86_64.rpm:
  Header V3 RSA/SHA256 Signature, key ID f4a80eb5: NOKEY
Public key for gpm-libs-1.20.7-5.el7.x86_64.rpm is not installed
Importing GPG key 0xF4A80EB5:
 Userid     : "CentOS-7 Key (CentOS 7 Official Signing Key) <security@centos.org>"
 Fingerprint: 6341 ab27 53d7 8a78 a7c2 7bb1 24c6 a8a7 f4a8 0eb5
 Package    : centos-release-7-0.1406.el7.centos.2.3.x86_64 (@anaconda)
 From       : /etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7

Installing Puppet
Public key for puppet-agent-1.10.9-1.el7.x86_64.rpm is not installed
Importing GPG key 0x4BD6EC30:
 Userid     : "Puppet Labs Release Key (Puppet Labs Release Key)"
 Fingerprint: 47b3 20eb 4c7c 375a a9da e1a0 1054 b7a2 4bd6 ec30
 Package    : puppetlabs-release-pc1-1.0.0-1.el7.noarch
 From       : /etc/pki/rpm-gpg/RPM-GPG-KEY-puppetlabs
warning: /etc/puppetlabs/puppet/puppet.conf created as
         /etc/puppetlabs/puppet/puppet.conf.rpmnew

Enabling convenience symlinks.
Changing owner of /etc/puppetlabs

This has installed Puppet and the tools you installed in Part I. It has also changed the owner of /etc/puppetlabs to the vagrant user for your convenience:

[vagrant@puppetmaster ~]$ which puppet
/opt/puppetlabs/bin/puppet
[vagrant@puppetmaster ~]$ which git rsync vim nano emacs
/usr/bin/git
/usr/bin/rsync
/usr/bin/vim
/usr/bin/nano
/usr/bin/emacs
[vagrant@puppetmaster ~]$ ls -la /etc/puppetlabs
total 12
drwxr-xr-x   5 vagrant vagrant   48 Aug  2 21:50 .
drwxr-xr-x. 77 root    root    8192 Aug  2 21:53 ..
drwxr-xr-x   5 vagrant vagrant   96 Aug  2 21:50 code
drwxr-xr-x   2 vagrant vagrant  145 Aug  2 21:50 mcollective
drwxr-xr-x   3 vagrant vagrant  111 Aug  2 21:50 puppet

If you prefer an editor other than the three listed here, you’ll need to install it as discussed in “Choosing a Text Editor”.

Configuring a Firewall for the Puppet Master

At this point, we’ll need to adjust the firewall on the server. Puppet clients connect to servers on TCP port 8140 by default. Use the following commands to allow incoming TCP connections to this port:

[puppetmaster ~]$ sudo firewall-cmd --permanent --zone=public --add-port=8140/tcp
success
[puppetmaster ~]$ sudo firewall-cmd --reload
success

This change allows incoming connections to the Puppet master.

Tip

It is safe to run these commands in a virtual instance on your personal workstation. In a production setting, you’d want to limit access to specific IP networks. Don’t make this change to a production system without reviewing your organization’s existing security setup.

Guides for altering other firewalls can be found in Appendix B.

Running the WEBrick Server

In this section, we’ll start up the Puppet master manually so that it can set up the directories and files it needs to run as a service. It is necessary to do this once, even if you plan to run it under Passenger or another Rack server.

At this point, we need to stop and create a user and group under which to run the Puppet master service. This service doesn’t need any special permissions on the system that hosts it, as it is a typical application service that answers queries from nodes. It can and should run as a nonprivileged user.

Note

This is different from the Puppet agent, which must run as a privileged account to make changes to the managed node.

It may surprise you that the installation package doesn’t create the user and group for you. This is because the Puppet master has been deprecated. The Puppet Server package does create the puppet user and group during installation, but to run a Puppet master, we’ll have to do it ourselves:

[vagrant@puppetmaster ~]$ sudo groupadd puppet
[vagrant@puppetmaster ~]$ sudo useradd -m -d /var/opt/puppetlabs -g puppet puppet

Now that everything has been prepared, let’s start the service as a foreground process so that we can observe the initialization process. You will notice that it creates a certificate authority based on the configured certname, and then signs its own certificate:

[vagrant@puppetmaster ~]$ sudo /opt/puppetlabs/bin/puppet master -v --no-daemon
Notice: Signed certificate request for ca
Notice: puppet.example.com has a waiting certificate request
Notice: Signed certificate request for puppet.example.com
Notice: Removing file Puppet::SSL::CertificateRequest puppet.example.com at
 '/var/opt/puppetlabs/puppetserver/ssl/ca/requests/puppet.example.com.pem'
Notice: Removing file Puppet::SSL::CertificateRequest puppet.example.com at
 '/var/opt/puppetlabs/puppetserver/ssl/certificate_requests/puppet.example.com'
Warning: The WEBrick Puppet master server is deprecated and will be removed in a
future release. Please use Puppet Server instead.
See http://links.puppetlabs.com/deprecate-rack-webrick-servers for more...
Notice: Starting Puppet master version 4.4.0

By signing its own certificate, the Puppet master has become the root certificate authority for this Puppet installation. Only agents with certificates signed by this certificate authority will be able to access the service. We’ll discuss ways to handle distributed or third-party certificate authorities in “Using an External Certificate Authority”.

I recommend at this point that you skip forward and complete all the steps in Chapter 22. Leave the Puppet master running on this screen. Use other windows to execute the commands in that chapter. As you finish each step, check back here and view the messages output by the Puppet master.

After you are comfortable with the Puppet master service, you can press Ctrl-C to stop this process. Then you can configure it to run as a limited test service, or configure it to support many nodes with Passenger.

Testing with the Puppet Master Service

Use the following process to enable a Puppet master service for your host. This service will only support a single connection at a time, but may be sufficient for testing Puppet 4 manifests.

As Puppet 4 has deprecated the Puppet master in favor of Puppet Server, the installation package does not include a service startup script. You can find one in the /vagrant mount of the files from the Git repository used by this book:

[vagrant@puppetmaster ~]$ sudo cp /vagrant/systemd-puppet/puppetmaster.service \
         /usr/lib/systemd/system/puppetmaster.service
[vagrant@puppetmaster ~]$ sudo cp /vagrant/systemd-puppet/puppetmaster.sysconfig \
         /etc/sysconfig/puppetmaster
[vagrant@puppetmaster ~]$ sudo systemctl daemon-reload
[vagrant@puppetmaster ~]$ systemctl status puppetmaster
puppetmaster.service - Puppet master
   Loaded: loaded (/usr/lib/systemd/system/puppetmaster.service; disabled)
   Active: inactive (dead)
[vagrant@puppetmaster ~]$ sudo systemctl enable puppetmaster
ln -s '/usr/lib/systemd/system/puppetmaster.service'
      '/etc/systemd/system/multi-user.target.wants/puppetmaster.service'

After you have run the service manually as shown in the previous section, you can use the files we just installed to start it as a normal service. Use the standard systemctl commands to start and stop the service:

[vagrant@puppetmaster ~]$ sudo systemctl start puppetmaster
[vagrant@puppetmaster ~]$ sudo systemctl status puppetmaster
puppetmaster.service - Puppet master
   Loaded: loaded (/usr/lib/systemd/system/puppetmaster.service; enabled)
   Active: active (running) since Thu 2015-08-27 05:02:37 UTC; 10s ago
 Main PID: 4100 (puppet)
   CGroup: /system.slice/puppetmaster.service
           └─4100 /opt/puppetlabs/puppet/bin/ruby
              /opt/puppetlabs/puppet/bin/puppet master --no-daemonize

systemd[1]: Starting Puppet master...
systemd[1]: Started Puppet master.
puppet[4100]: Warning: The WEBrick Puppet master server is deprecated and
will be removed in a future release. Please use Puppet Server instead.
See http://links.puppetlabs.com/deprecat...more information.
puppet[4100]: Notice: Starting Puppet master version 4.4.0
Hint: Some lines were ellipsized, use -l to show in full.

Warning

As discussed previously, the puppetmaster service uses the Ruby WEBrick test server. This is only suitable for a few nodes. You should never use this for a production environment.

Scaling the Puppet Master with Passenger

This section covers the installation of Puppet to run as a service under Passenger Rack.

Tip

Before installing Passenger, you should first start up the Puppet master manually as documented on the previous page. This will create all of the required directories with the appropriate permissions for running Puppet under Passenger.

If you have enabled the puppetmaster service, you’ll need to disable it, as it will conflict with the master service running under Passenger:

[vagrant@puppetmaster ~]$ sudo systemctl stop puppetmaster
[vagrant@puppetmaster ~]$ sudo systemctl disable puppetmaster
rm '/etc/systemd/system/multi-user.target.wants/puppetmaster.service'

Installing Apache

To run Puppet under Passenger, we’ll use the Apache httpd to provide the base web service. Install Apache httpd, the Apache development tools, and the TLS module:

[vagrant@puppetmaster ~]$ sudo yum install -y httpd httpd-devel mod_ssl
Loaded plugins: fastestmirror
...snip...

Installed:
  httpd.x86_64 0:2.4.6-31.el7.centos    httpd-devel.x86_64 0:2.4.6-31.el7.centos
  mod_ssl.x86_64 1:2.4.6-31.el7.centos

Dependency Installed:
  apr.x86_64 0:1.4.8-3.el7              apr-devel.x86_64 0:1.4.8-3.el7
  apr-util.x86_64 0:1.5.2-6.el7         apr-util-devel.x86_64 0:1.5.2-6.el7
  cyrus-sasl.x86_64 0:2.1.26-17.el7     cyrus-sasl-devel.x86_64 0:2.1.26-17.el7
  expat-devel.x86_64 0:2.1.0-8.el7      httpd-tools.x86_64 0:2.4.6-31.el7.centos
  mailcap.noarch 0:2.1.41-2.el7         openldap-devel.x86_64 0:2.4.39-6.el7  
  libdb-devel.x86_64 0:5.3.21-17.el7_0.1

Complete!

Tip

You can also run Passenger under the nginx web server. This requires extensive manual configuration, and is thus not documented here. As Puppet Server provides its own web server, I recommend that you avoid this distraction and focus on upgrading instead.

Installing Phusion Passenger

We’ll need to get some dependencies from the EPEL repository, so let’s install that first:

[vagrant@puppetmaster ~]$ sudo yum install -y epel-release
Loaded plugins: fastestmirror
...snip...

Installed:
  epel-release.noarch 0:7-5                                                                                                                                                                                                                           

Complete!

Phusion provides a Yum repository with Passenger binaries. They don’t provide a release RPM, just the repo configuration file. Download and install it with the following commands:

[vagrant@puppetmaster ~]$ curl -sSLo passenger.repo \
     https://oss-binaries.phusionpassenger.com/yum/definitions/el-passenger.repo
$ sudo mv passenger.repo /etc/yum.repos.d/passenger.repo

Now install Passenger. Yum will acquire necessary dependencies from the EPEL repository:

$ sudo yum install -y passenger mod_passenger
Loaded plugins: fastestmirror
...snip...

Installed:
  passenger.x86_64 0:5.0.16-8.el7         mod_passenger.x86_64 0:5.0.16-8.el7

Dependency Installed:
  rubygem-rack.noarch 1:1.5.2-4.el7

Complete!

Configuring the Puppet Master

Now we’ll configure the system to start Apache with the Puppet master running as a Rack service under Phusion Passenger.

First, let’s start up Apache and confirm that the Phusion Passenger configuration is correct:

$ sudo systemctl enable httpd
ln -s '/usr/lib/systemd/system/httpd.service'
      '/etc/systemd/system/multi-user.target.wants/httpd.service'
$ sudo systemctl start httpd
$ sudo passenger-config validate-install --validate-apache2 --auto
 * Checking whether this Passenger install is in PATH... ✓
 * Checking whether there are no other Passenger installations... ✓
 * Checking whether Apache is installed... ✓
 * Checking whether the Passenger module is correctly configured in Apache... ✓

Everything looks good. :-)

Apache comes with several configuration files useful for providing a friendly environment for setting up websites. We don’t need and won’t be using this configuration, so let’s disable them. You can use either of the following commands:

[vagrant@puppetmaster ~]$ sudo rm /etc/httpd/conf.d/*.conf

Or perhaps less drastically, this will achieve the same effect:

[vagrant@puppetmaster ~]$ cd /etc/httpd/conf.d
[vagrant@puppetmaster conf.d]$ for cfg in *.conf; do sudo mv $cfg $cfg.dis; done

Instead, we’ll install our own virtual configuration file that will include the specific Apache directives we require. This file contains a complete, self-standing service definition for the Puppet master service:

[vagrant@puppetmaster ~]$ cd /etc/httpd/conf.d/
[vagrant@puppetmaster conf.d]$ sudo cp /vagrant/etc-puppet/puppetmaster.conf ./

The next step is to configure the Puppet master application Rack service. Now we’ll install a config.ru file with the Rack application configuration:

[vagrant@puppetmaster ~]$  mkdir -p /etc/puppetlabs/puppetmaster/public
[vagrant@puppetmaster ~]$  cd /etc/puppetlabs/puppetmaster
[vagrant@puppetmaster puppetmaster]$  sudo cp /vagrant/etc-puppet/config.ru ./

It is essential that the puppet user own all of the following files and directories. In particular, the Puppet master service will be started as the user who owns the config.ru file:

$  sudo chown puppet:puppet /etc/puppetlabs/puppetmaster/config.ru
$  sudo mkdir /var/run/puppetlabs/puppetmaster
$  sudo chown puppet:puppet /var/run/puppetlabs/puppetmaster
$  sudo mkdir /var/log/puppetlabs/puppetmaster
$  sudo chown puppet:puppet /var/log/puppetlabs/puppetmaster

Finally, restart Apache to pick up the changes. Check the status to ensure it is running successfully. Here’s what it looks like when it is restarted successfully:

$ sudo systemctl restart httpd
$ sudo systemctl status httpd
httpd.service - The Apache HTTP Server
   Loaded: loaded (/usr/lib/systemd/system/httpd.service; enabled)
   Active: active (running) since Thu 2015-08-27 05:24:38 UTC; 5s ago
  Process: 14661 ExecStop=/bin/kill -WINCH ${MAINPID} (code=exited, status=0)
 Main PID: 14666 (httpd)
   Status: "Processing requests..."
   CGroup: /system.slice/httpd.service
           ├─14666 /usr/sbin/httpd -DFOREGROUND
           ├─14693 Passenger watchdog
           ├─14696 Passenger core
           ├─14703 Passenger ust-router
           ├─14714 /usr/sbin/httpd -DFOREGROUND
           ├─14715 /usr/sbin/httpd -DFOREGROUND
           ├─14716 /usr/sbin/httpd -DFOREGROUND
           ├─14717 /usr/sbin/httpd -DFOREGROUND
           └─14718 /usr/sbin/httpd -DFOREGROUND

Aug 27 05:24:38 puppetmaster systemd[1]: Starting The Apache HTTP Server...
Aug 27 05:24:38 puppetmaster systemd[1]: Started The Apache HTTP Server.

There are two logs that may contain errors from the Puppet master. Check the Apache error log for Passenger startup failures, and your syslog daemon log for messages from the Puppet master. The following command can be useful to view both of these logs when investigating problems:

[vagrant@puppetmaster ~]$ sudo tail -f /var/log/messages /var/log/httpd/error_log

IPv6 Dual-Stack Puppet Master

To enable IPv6 connections to a WEBrick Puppet master, add the bindaddress configuration setting to the [master] section of the Puppet configuration file, then restart the puppetmaster service:

[master]
  bindaddress = ::

This is completely unnecessary when the Puppet master runs under Apache/Passenger, and should be removed.

If you query for listening services using netstat -an, you’ll see the Puppet master listening on a tcp6 socket. This socket accepts both IPv4 and IPv6 connections:

[vagrant@puppetmaster ~]$ netstat -an |grep 8140
tcp6       0      0 :::8140                 :::*                    LISTEN

Clients will connect to the IPv6 or IPv4 port based on the configuration of the client node, and the addresses available from DNS or the hosts file. To force a node to connect using a specific protocol, only provide the address of the Puppet master in that format.

Debugging Puppet Master

You can find messages from the Puppet master in the syslog logfiles. To display the log output in a manner similar to the screen output provided by the --no-daemonize option, use this command:

[vagrant@puppetmaster ~]$ sudo tail -f /var/log/messages |grep puppet

Previous Chapter

19. Preparing for a Puppet Server

Next Chapter

21. Creating a Puppet Server

Table of Contents for Learning Puppet 4