SSH Quick Start Guide

A newer version is available; see the version menu above for details.

Welcome to the Puppet Enterprise SSH Quick Start Guide. This document provides instructions for getting started managing SSH across your PE deployment using a module from the Puppet Forge.

Secure Shell (SSH) is a protocol that enables encrypted connections between nodes on a network for administrative purposes. It is most commonly used in the *nix world 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.

The SSH module you’ll install in this exercise uses Puppet resources that collect and distribute the public key for each agent node in your PE deployment, which will enable you to SSH to and from any node without authentication warnings.

Using this guide, you will:

Install Puppet Enterprise and the Puppet Enterprise Agent

If you haven’t already done so, install PE. See the system requirements for supported platforms.

  1. Download and verify the appropriate tarball.
  2. Refer to the installation overview to determine how you want to install PE, and follow the instructions provided.
  3. Refer to the agent installation instructions to determine how you want to install your PE agents, and follow the instructions provided.

Install the saz-ssh Module

The saz-ssh module, available on the Puppet Forge, is one of many modules written by members of our user community.

You can learn more about the saz-ssh module by visitinghttp://forge.puppetlabs.com/saz/ssh.

To install the saz-ssh module:

From the PE master, run puppet module install saz-ssh.

You should see output similar to the following:

    Preparing to install into /etc/puppetlabs/code/environments/production/modules ...
    Notice: Downloading from http://forgeapi.puppetlabs.com ...
    Notice: Installing -- do not interrupt ...
    /etc/puppetlabs/code/environments/production/modules
    └── saz-ssh (v2.3.6)
          └── puppetlabs-stdlib (3.2.2) [/opt/puppetlabs/puppet/modules]

That’s it! You’ve just installed the saz-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.

Note: the Puppet Labs Standard Library module is listed as a dependency for the saz-ssh module. It was installed as part of your PE installation.

Create SSH Group

Groups let you assign classes and variables to many nodes at once. Nodes can belong to many groups and will 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 automatically creates several groups in the console, which you can read more about in the PE docs.

In this procedure, you’ll create a simple group called ssh_example, which will contain all of your nodes. Depending on your needs or infrastructure, you might have a different group that you’ll assign SSH to.

To create the ssh_example group:

  1. In the console, click Nodes in the navigation bar and select Classification.
  2. In the Node group name field, name your group ssh_example.
  3. Click Add group.
  4. Select the ssh_example group, and click the Rules tab.
  5. In the Fact field, enter name.
  6. From the Operator drop-down list, select matches regex.
  7. In the Value field, enter .\*.
  8. Click Add rule.

    This rule will [“dynamically” pin all nodes]((./console_classes_groups.html#adding-nodes-dynamically) 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 will vary from user to user.

Use the PE Console to Add Classes from the SSH Module

The saz-ssh module contains several classes. Classes are named chunks of Puppet code and are the primary means by which Puppet Enterprise configures nodes. Some useful classes in the saz-ssh module include:

  • ssh: the main class; this class handles all the other classes (including the classes in this list).
  • ssh::hostkeys: creates host keys on your servers, if needed.
  • ssh::knownhosts: contains Puppet resources that manages known host keys.
  • ssh::client::config: contains Puppet resources that manages the client configuration file.
  • ssh::server::config: contains Puppet resources that manages the server configuration file.

You’re going to add the ssh class to the ssh_example node group. 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.

To add the ssh class to the ssh_example group:

  1. In the console, click Nodes in the side navigation bar.

  2. On the Classification page, select the ssh_example group.

  3. Click the Classes tab.

  4. In the Class name field, begin typing ssh, and select it from the autocomplete list.

    Tip: You only need to add the main ssh class; it contains the other classes from the module.

  5. Click Add class.

  6. Click Commit 1 change.

    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.

  7. From the command line of your Puppet master, run puppet agent -t.

  8. From the command line of each PE-managed node, run puppet agent -t.

    This will configure 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 also able to retrieve the keys from the other agents. It will collect the other keys on the second Puppet run.

Use the Puppet Enterprise Console Events Page to View Changes Made by the ssh Class

The Events 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 Resources: with events.

Click With Changes in the Classes: with events summary view. The main pane will show you that the Ssh:Knownhosts class was successfully added when you ran PE after adding the main ssh class. This class set 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 will show you that public key resources for each agent in our example has now been brought under PE management. The further you drill down, the more information you’ll 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 Navigating Events.

Use the PE Console to Edit Root Login Parameters of the ssh Class

With Puppet Enterprise you can edit or add class parameters in the PE console without needing to edit the module code directly.

The saz-ssh module, by default, allows root login over SSH. But what if your compliance protocols do not allow this on certain pools of nodes?

Changing this parameter of the ssh class can be accomplished in a few steps using the PE console.

To edit the root login parameter of the ssh class:

  1. In the console, click Nodes in the navigation bar.
  2. On the Classification page, select the ssh_example group.
  3. Click the Classes tab, and find ssh in the list of classes.

  4. From the parameter drop-down menu, choose server_options.

    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.

  5. In the Value field, enter {"PermitRootLogin":"no"}.
  6. Click Add parameter.
  7. Click Commit 1 change.
  8. From the command line of your Puppet master, run puppet agent -t.
  9. From the command line of each PE-managed node, run puppet agent -t.

    This will trigger a Puppet run to have Puppet Enterprise create the new configuration.

  10. Attempt to SSH from one agent to another. Note that root login permissions are now denied over SSH.

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.

Other Resources

For a video on automating SSH with Puppet Enterprise, check out Automate SSH configuration in 5 minutes with Puppet Enterprise.

Speed up SSH by reusing connections on the Puppet Labs blog gives some helpful hints for working with SSH.

Puppet Labs offers many opportunities for learning and training, from formal certification courses to guided online lessons. We’ve noted a few below; head over to the learning Puppet page to discover more.

  • Learning Puppet is a series of exercises on various core topics about deploying and using PE.
  • The Puppet Labs workshop contains a series of self-paced, online lessons that cover a variety of topics on Puppet basics. You can sign up at the learning page.

↑ Back to top