Installing and configuring puppet master and agent

Don't know what puppet is?

Go through my previous blog article: Introduction to Puppet

You can always try with 2 physical computers, one for puppet master and the other for puppet agent.

But why don't you try with VMware or VirtualBox virtual machines? It is easy and convenient. You don't have to install puppet in your host OS. Take two ubuntu images (say ubuntu 12.04) and put up two instances (say 1 GB RAM each). One will be used for puppet master and the other for puppet agent.

This tutorial goes on assuming you have ubuntu instances prepared for master and agent installation.

1. Installing and configuring puppet master

For the ease of tracking your progress, I have simply broken the master installation process into few simple steps.

Steps to be followed are as follows.

Step 1 - Install puppet master

$ sudo apt-get update

$ sudo apt-get install puppetmaster

Step 2 - Configure puppet.conf file

Add following lines to the appropriate sections in puppet.conf file as indicated below.

[main]

dns_alt_names=puppet,puppet.example.com,puppetmaster01,puppetmaster01.example.com

[master]

autosign=true

dns_alt_names are mentioned so that when creating ssl certificates for the master itself, the names will be embedded to the certificate itself which is easy for the agent to find out that agent is connecting to the intended puppet master.

autosign=true is used to automatically sign puppet agent join requests for the time being. So that you can easily learn puppet and later comment out the said line to manually sign agent certificates.

Step 3 - Modify hosts file

Modify the /etc/hosts file content as follows.

127.0.0.1       localhost

127.0.1.1       puppet.example.com

Step 4 - Modify hostname content

puppet.example.com

2. Installing and configuring puppet agent

For the ease of tracking your progress, I have simply broken the agent installation process also as follows.

Step 1 - Install puppet agent

$ sudo apt-get update

$ sudo apt-get install puppet

Step 2 - Configure puppet.conf file

Add following lines to the appropriate sections in puppet.conf file as indicated below.

[main]

server=puppet.example.com

Step 3 - Modify hosts file

Modify the /etc/hosts file content as follows.

127.0.0.1       localhost

127.0.1.1       agent1

192.168.92.2    puppet.example.com puppet

Note that the 192.168.92.2 is the ip assigned for the puppet master.

Step 4 - Modify hostname content

agent 1

First reboot master instance and then reboot agent instance as well.

3. Test master-agent connection by performing a simple catalog run.

Step 1 - Edit site.pp file

Go to master node terminal as root and open /etc/puppet/manifests/site.pp file for editing.

Insert a small code segment as follows.

node default {

}

This code segment does nothing at the moment but will help us in confirming that the connection between master and agent is successfully established.

Step 2 - Perform a catalog run in agent

Now go to the agent node instance terminal as root. 

Perform a catalog run as follows.

root@agent1:~# puppet agent --test

info: Caching catalog for agent1.domain.name

info: Applying configuration version '1416123976'

notice: Finished catalog run in 0.01 seconds

root@agent1:~# 

Congratulations! You have successfully established the master-agent connection.

But things always don't happen as we expect.

When you are trying to install master-agent you may get puppet master-agent communication errors.

See this blog article which may help to solve your common problems: Puppet master-agent communication errors

Want to go further with puppet?

See this blog article on how to create files from templates and change its content on the go: Puppet how to create a file and change its content using templates

Puppet master-agent communication errors

Don't know what puppet is?
Go through my previous blog article: Introduction to Puppet

Setup: two VMs inside Oracle VirtualBox; one for puppet-master and one for puppet-agent.
Puppet master is running on ip 192.168.92.2 and listening to 8140 port.

suhan@suhan-VirtualBox:~$ ps -ef | grep puppetmaster
suhan     2229  1802  0 10:11 pts/2    00:00:00 grep --color=auto puppetmaster
suhan@suhan-VirtualBox:~$ ps -ef | grep puppet
puppet    2224     1  0 10:11 ?        00:00:00 /usr/bin/ruby1.8 /usr/bin/puppet master --masterport=8140
suhan     2233  1802  0 10:11 pts/2    00:00:00 grep --color=auto puppet

suhan@suhan-VirtualBox:~$ netstat -tupln | grep 8140

(Not all processes could be identified, non-owned process info

 will not be shown, you would have to be root to see it all.)

tcp        0      0 0.0.0.0:8140            0.0.0.0:*               LISTEN  

Agent also up and running on ip 192.168.92.3

suhan@suhan-VirtualBox:~$ ps -ef | grep puppet
root       907     1  0 10:07 ?        00:00:00 /usr/bin/ruby1.8 /usr/bin/puppet agent
suhan     2204  1776  0 10:36 pts/0    00:00:00 grep --color=auto puppet

Some how when my agent tried to communicate to master following errors occurred.

Error 1:
suhan@suhan-VirtualBox:~$ sudo puppet agent --test --server=puppet.example.com
err: Could not request certificate: No route to host - connect(2)
Exiting; failed to retrieve certificate and waitforcert is disabled

This was due to master node was not accessible to agent node by the said server identification.
This can be due to reasons like invalid server alias, network inaccessibility.
Even though I have created two host-only adaptors in VirtualBox and attached them to each virtual machine, communication between each machine was not possible.
Therefore I modified each /etc/network/interfaces file in both nodes and created eth0 interface with respective ip addresses.

e.g.: in puppet master,
auto eth0
iface eth0 inet static
address 192.168.92.2
network 192.168.92.0
netmask 255.255.255.0
broadcast 192.168.92.255

Then I configured each machine's virtual box settings for network interfaces as bridged network, bridge0.

Then got the following error since previously generated certificates are mismatched.

Error 2:
suhan@suhan-VirtualBox:~$ sudo puppet agent --test --server=puppet.example.com
info: Caching certificate for ca
info: Caching certificate for suhan-virtualbox
err: Could not request certificate: The certificate retrieved from the master does not match the agent's private key.
Certificate fingerprint: 97:48:44:EC:F7:E0:24:B0:C4:AB:48:F4:5C:F5:26:2D
To fix this, remove the certificate from both the master and the agent and then start a puppet run, which will automatically regenerate a certficate.
On the master:
  puppet cert clean suhan-virtualbox
On the agent:
  rm -f /var/lib/puppet/ssl/certs/suhan-virtualbox.pem
  puppet agent -t

Exiting; failed to retrieve certificate and waitforcert is disabled

As per the instruction given in the error message itself I followed the steps.

On master,
suhan@suhan-VirtualBox:~$ sudo puppet cert clean suhan-virtualbox
[sudo] password for suhan: 
notice: Revoked certificate with serial 3
notice: Removing file Puppet::SSL::Certificate suhan-virtualbox at '/var/lib/puppet/ssl/ca/signed/suhan-virtualbox.pem'
notice: Removing file Puppet::SSL::Certificate suhan-virtualbox at '/var/lib/puppet/ssl/certs/suhan-virtualbox.pem'
notice: Removing file Puppet::SSL::Key suhan-virtualbox at '/var/lib/puppet/ssl/private_keys/suhan-virtualbox.pem'

On agent,
suhan@suhan-VirtualBox:~$ sudo rm -f /var/lib/puppet/ssl/certs/suhan-virtualbox.pem
[sudo] password for suhan: 

suhan@suhan-VirtualBox:~$ puppet agent -t
info: Creating a new SSL key for suhan-virtualbox
info: Caching certificate for ca
info: Creating a new SSL certificate request for suhan-virtualbox
info: Certificate Request fingerprint (md5): B7:AE:21:4C:B8:03:2A:BC:8A:D5:A6:92:4E:A3:F1:84
Exiting; no certificate found and waitforcert is disabled

Issue was resolved. :)

But why wait for master to manually sign the certificate since this is an experimental setting?

Therefore I modified the /etc/puppet/puppet.conf file's [master] section to auto sign certificates for agents as follows,

[master]
# These are needed when the puppetmaster is run by passenger
# and can safely be removed if webrick is used.
# ssl_client_header = SSL_CLIENT_S_DN
# ssl_client_verify_header = SSL_CLIENT_VERIFY
autosign=true

Then the certificate was auto signed upon request by puppet master and can continue to work further.

Error 3:
root@base:~# puppet agent -t
err: Could not retrieve catalog from remote server: Error 400 on SERVER: Could not find default node or by name with 'base.openstacklocal, base' on node base.openstacklocal
warning: Not using cache on failed catalog
err: Could not retrieve catalog; skipping run

This was due to absence of a node definition in puppet master's /etc/puppet/manifests/site.pp for the node who is trying to contact puppet master.

I have added the following node to my site.pp file (hostname of my agent is 'appserver' in /etc/hostname and /etc/hosts).

node 'appserver' {

}

Then the catalog run was run successfully.

root@appserver:~# puppet agent -t

info: Caching catalog for appserver.openstacklocal

info: Applying configuration version '1415768619'

notice: Finished catalog run in 0.01 seconds

Error 4:
root@suhan-keymanager:/home/ubuntu# puppet agent -t
Warning: Unable to fetch my node definition, but the agent run will continue:
Warning: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed: [self signed certificate in certificate chain for /CN=Puppet CA: qaa-puppet-master.openstacklocal]
Info: Retrieving plugin
Error: /File[/var/lib/puppet/lib]: Failed to generate additional resources using 'eval_generate': SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed: [self signed certificate in certificate chain for /CN=Puppet CA: qaa-puppet-master.openstacklocal]
Error: /File[/var/lib/puppet/lib]: Could not evaluate: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed: [self signed certificate in certificate chain for /CN=Puppet CA: qaa-puppet-master.openstacklocal] Could not retrieve file metadata for puppet://puppet/plugins: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed: [self signed certificate in certificate chain for /CN=Puppet CA: qaa-puppet-master.openstacklocal]
Error: Could not retrieve catalog from remote server: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed: [self signed certificate in certificate chain for /CN=Puppet CA: qaa-puppet-master.openstacklocal]
Warning: Not using cache on failed catalog
Error: Could not retrieve catalog; skipping run
Error: Could not send report: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed: [self signed certificate in certificate chain for /CN=Puppet CA: qaa-puppet-master.openstacklocal]

This occurred when the puppet servers were changed and the CA certs changed, or when rebuilt a host with the same hostname. Please find the following fix.

find /var/lib/puppet/ssl -name '*.pem' -exec rm {} \;

This should make the agent re-download the puppet CA certificates, and re-apply for its own certificate.

Error 5:

root@qaa-puppet-apim-store-pub-1:/home/ubuntu# puppet agent -t --noop

Warning: Unable to fetch my node definition, but the agent run will continue:

Warning: SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

Info: Retrieving pluginfacts

Error: /File[/var/lib/puppet/facts.d]: Failed to generate additional resources using 'eval_generate': SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

Error: /File[/var/lib/puppet/facts.d]: Could not evaluate: Could not retrieve file metadata for puppet://puppet/pluginfacts: SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

Info: Retrieving plugin

Error: /File[/var/lib/puppet/lib]: Failed to generate additional resources using 'eval_generate': SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

Error: /File[/var/lib/puppet/lib]: Could not evaluate: Could not retrieve file metadata for puppet://puppet/plugins: SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

Info: Loading facts

Error: Could not retrieve catalog from remote server: SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

Warning: Not using cache on failed catalog

Error: Could not retrieve catalog; skipping run

Error: Could not send report: SSL_connect returned=1 errno=0 state=SSLv3 read server session ticket A: sslv3 alert certificate revoked

This occurs when the puppet agent certificate is revoked from puppet master.

To clean puppet agent certificate in puppet agent and regenerate, issue the following command.

root@qaa-puppet-apim-store-pub-1:/home/ubuntu# puppet cert clean

Error: The certificate retrieved from the master does not match the agent's private key.

Certificate fingerprint: A9:6C:3E:2E:99:03:9F:95:9C:A8:94:BF:E9:75:C3:7D:EB:67:6A:85:09:32:A3:0B:D5:96:79:AF:9F:0D:93:EB

To fix this, remove the certificate from both the master and the agent and then start a puppet run, which will automatically regenerate a certficate.

On the master:

  puppet cert clean apim-publisher-1

On the agent:

  1a. On most platforms: find /var/lib/puppet/ssl -name apim-publisher-1.pem -delete

  1b. On Windows: del "/var/lib/puppet/ssl/apim-publisher-1.pem" /f

  2. puppet agent -t

Instructions will be given in the error itself.

As an example if you are using Ubuntu 14.04:

In puppet master,

> puppet cert clean apim-publisher-1

In puppet agent,

> find /var/lib/puppet/ssl -name apim-publisher-1.pem -delete

> puppet agent -t --noop

OR

> find /var/lib/puppet/ssl -name qaa-puppet-apim-key-manager-1.openstacklocal.pem -delete

> puppet agent -t --noop

root@qaa-puppet-apim-store-pub-1:/home/ubuntu# puppet agent -t --noop

Info: Creating a new SSL key for apim-publisher-1

Info: csr_attributes file loading from /etc/puppet/csr_attributes.yaml

Info: Creating a new SSL certificate request for apim-publisher-1

Info: Certificate Request fingerprint (SHA256): 09:FA:92:18:0E:C7:31:9B:7E:F7:D6:31:78:63:85:52:DF:4F:A7:7D:B8:D6:B1:A2:B7:23:66:63:07:C2:21:F7

Info: Caching certificate for apim-publisher-1

Info: Caching certificate for apim-publisher-1

Info: Retrieving pluginfacts

Info: Retrieving plugin

Info: Loading facts

...

Enough with communication errors... :)

How about for a change we learn how to create files from templates and change its content on the go. Believe me its fun! Go through my blog article:Puppet how to create a file and change its content using templates

Introduction to Puppet

What is puppet?
Puppet is an open-source IT automation tool [1].
"The Puppet Domain Specific Language (DSL) is a Ruby-based coding language that provides a precise and adaptable way to describe a desired state for each machine in your infrastructure. Once you've described a desired state, Puppet does the work to bring your systems in line and keeping them there" - Puppet Labs

Why not write a simple shell script instead of using puppet?
For small number of nodes and simple shell commands, writing shell scripts may appear appealing.
But what if you are having large number of nodes/machines or having different operating systems?
How you are going to manage all of your large number of scripts?

This is where Puppet comes in to play.
Puppet allows you to define details of a configuration in a way that takes off the burden of operating system specifics.
It lets you easily maintain, audit and understand your whole IT infrastructure than having large number of complicated shell scripts.

How to check puppet version?
>puppet -V
Note that it must be the capital letter 'V'.

You will get a response as below if you have installed puppet in your system.
>3.6.2 (Puppet Enterprise 3.3.2)

Puppet not installed?

Manually install and configure puppet master and agent
Read this blog article: Installing and configuring puppet master and agent

Lazy to install puppet?
How about a preconfigured VM image to learn puppet :)
Given that you have VMware or Oracle VirtualBox installed on your system,
you can follow the link [1] and download a preconfigured VM to follow the puppet tutorial from puppet labs.

When you are trying to install master-agent you may get puppet master-agent communication errors.
See this blog article which may help to solve your common problems: Puppet master-agent communication errors

Want to go further with puppet?
See this blog article on how to create files from templates and change its content on the go: Puppet how to create a file and change its content using templates

Reference:
[1] http://puppetlabs.com/download-learning-vm