Managing SSH with Puppet

This guide provides instructions for getting started managing SSH across your PE deployment using a module from the Puppet Forge.

About SSH

Secure Shell (SSH) is a protocol that enables encrypted connections between nodes on a network for administrative purposes.

SSH is most commonly used on *nix systems by admins who wish to remotely log into machines to access the command line and execute commands and scripts.

Typically, the first time you attempt to SSH into a host you’ve never connected to before, you get a warning similar to the following:

The authenticity of host '10.10.10.9 (10.10.10.9)' can't be established.
RSA key fingerprint is 05:75:12:9a:64:2f:29:27:39:35:a6:92:2b:54:79:5f.
Are you sure you want to continue connecting (yes/no)?

If you select yes, the public key for that host is added to your SSH known_hosts file, and you won't have to authenticate it again unless that host's key changes.

Managing SSH overview

Install an SSH module that uses Puppet resources to collect and distribute the public key for each agent node in your Puppet Enterprise deployment. This enables you to SSH to and from any node without authentication warnings.

You install the ghoneycutt-ssh module, a simple module with one class that Puppet Enterprises uses to configure your nodes: the ssh class. Classes are named chunks of Puppet code and are the primary means by which Puppet Enterprise configures nodes.

The ghoneycutt-ssh module, available on the Puppet Forge, is one of many modules written by our user community. You can learn more about this module by visiting the Forge.

Then, in the PE console, you create a group of the nodes you want to manage SSH on. Groups let you assign variables and classes, such as the ssh class, to many nodes at once. Nodes can belong to many groups and inherit classes and variables from all of them. Groups can also be members of other groups and inherit configuration information from their parent group the same way nodes do. PE creates several groups automatically, which you can read more about in the related topic about groups in the console.

Using this guide, you :

Install the ghoneycutt-ssh module.
Create the SSH node group
Add classes from the ssh module to your agent nodes in the console.
View changes to your infrastructure in the console Events page.
Edit root login parameters of the ssh class in the console.

These instructions assume you have installed PE. Refer to the installation overview and the agent installation instructions for complete instructions. See the supported operating system documentation for supported platforms. This guide assumes you are not using Code Manager or r10k.

About module directories

By default, Puppet keeps modules in /etc/puppetlabs/code/environments/production/modules. This includes modules that you download from the Forge and those you write yourself.

PE also creates two other module directories: /opt/puppetlabs/puppet/modules and /etc/puppetlabs/staging-code/modules. For this guide, don't modify or add anything to either of these directories.

There are plenty of resources about modules and the creation of modules that you can reference.

Install the ghoneycutt-ssh module

The ghoneycutt-ssh module manages SSH keys and removes SSH keys that you aren't managing with Puppet.

This module, available on the Puppet Forge, is one of many modules written by our user community. It contains one class: the ssh class. You can learn more about the ghoneycutt-ssh module by visiting the Forge.

On the command line, on the PE master, run puppet module install ghoneycutt-ssh -v 3.40.0.

You should see output similar to the following:

Notice: Preparing to install into /etc/puppetlabs/code/environments/production/modules ...
Notice: Downloading from https://forgeapi.puppetlabs.com ...
Notice: Installing -- do not interrupt ...
/etc/puppetlabs/code/environments/production/modules
└─┬ ghoneycutt-ssh (v3.40.0)
   ├── ghoneycutt-common (v1.6.0)
   ├── puppetlabs-firewall (v1.8.1)
   └── puppetlabs-stdlib (v4.9.1)

That's it! You've just installed the ghoneycutt-ssh module. You'll need to wait a short time for the Puppet server to refresh before the classes are available to add to your agent nodes.

Create the SSH node group

In the console, create a group called ssh_example to designate which nodes Puppet should manage SSH on.

This group will contain all of your nodes. Depending on your needs or infrastructure, you might have a different group that you'll assign SSH to.

In the PE console, click Nodes> Classification, and click Add group.
Specify options for the new node group:
- Parent name : select All nodes
- Group name : enter a name that describes the role of this environment node group
- Environment: select production
- Environment group: don't select this option
Click Add
Click the ssh_example group, then select the Rules tab.
In the Fact field, enter name.
From the Operator drop-down list, select ~ (matches regex).
In the Value field, enter .*.
Click Add rule.

This rule "dynamically" pins all nodes to the ssh_example group. Note that this rule is for testing purposes, and that decisions about pinning nodes to groups in a production environment vary.

Add classes from the ssh module

Add the ssh class to the ssh_example node group to add the necessary resources that allow Puppet to manage SSH.

Depending on your needs or infrastructure, you may have a different group that you'll assign SSH to, but these same instructions would apply.

After you apply the ssh class and run Puppet, the public key for each agent node will be exported and then disseminated to the known_hosts files of the other agent nodes in the group, and you will no longer be asked to authenticate those nodes on future SSH attempts.

In the console, click Classification, and find and select ssh_example group.
On the Configuration tab, in the Class name field, select ssh.
Click Add class, and commit changes.

Note: The ssh class now appears in the list of classes for the ssh_example group, but it has not yet been configured on your nodes. For that to happen, kick off a Puppet run.
From the command line of your Puppet master, run puppet agent -t.
From the command line of each PE-managed node, run puppet agent -t.

This configures the nodes using the newly assigned classes. Wait one or two minutes.

Important: You need to run Puppet a second time due to the round-robin nature of the key sharing. In other words, the first server that ran on the first Puppet run was only able to share its key, but it was not able to retrieve the keys from the other agents. It will collect the other keys on the second Puppet run.

View changes made by the ssh class

To confirm that the ssh class made changes to your infrastructure, check the Events console page. This page lets you view and research changes and other events.

For example, after applying the ssh class, you can use the Events page to confirm that changes were indeed made to your infrastructure.

Note that in the summary pane on the left, one event, a successful change, has been recorded for Classes: with events. However, there are three changes for Classes: with events and six changes for Resources: with events.

Click With changes in the Classes: with events summary view.

The main pane will show you that the ssh class was successfully added when you ran PE. This class sets the known_hosts entries after it collects the public keys from agents nodes in your deployment .
Click Changed in the Resources: with events summary view.

The main page shows you that public key resources for each agent in our example has now been brought under PE management. The further down you navigate, the more information you receive about the event. For example, in this case, you see that the the SSH rsa key for agent1.example.com has been created and is now present in the known_hosts file for master.example.com.

If there had been a problem applying any piece of the ssh class, the information found here could tell you exactly which piece of code you need to fix. In this case, the Events page simply lets you confirm that PE is now managing SSH keys.

In the upper right corner of the detail pane is a link to a run report which contains information about the Puppet run that made the change, including logs and metrics about the run. See Infrastructure reports for more information.

For more information about using the Events page, see Working with the Events page.

Edit root login parameters of the ssh class

Edit or add class parameters from the ssh class in the PE console without needing to edit the module code directly.

The ghoneycutt-ssh module, by default, allows root login over SSH. But if your compliance protocols do not allow this, you can change this parameter of the ssh class in a few steps using the PE console.

In the console, click Classification, and find and select the ssh_example group.
On the Configuration tab, find ssh in the list of classes.
From the parameter drop-down menu, choose permit_root_login.

Note: The grey text that appears as values for some parameters is the default value, which can be either a literal value or a Puppet variable. You can restore this value by clicking Discard changes after you have added the parameter.
In the Value field, enter no.
Click Add parameter, and commit changes.
From the command line of your Puppet master, run puppet agent -t.
From the command line of each PE-managed node, run puppet agent -t.

Puppet Enterprise is now managing the root login parameter for your SSH configuration. You can see this setting in /etc/ssh/sshd_config. For fun, change the PermitRootLogin parameter to yes, run PE, and then recheck this file. As long as the parameter is set to no in the PE console, the parameter in this file will be set back to no on every Puppet run if it is ever changed.

You can use the PE console to manage other SSH parameters, such as agent forwarding, X11 forwarding, and password authentication.