SSH quick start guide

The Puppet Enterprise SSH quick start guide 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 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 ' (' 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:

Before you begin, you must 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.

Install the ghoneycutt-ssh module

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

  1. From 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 ...
    Notice: Installing -- do not interrupt ...
    └─┬ 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 group

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.

Groups let you assign classes and variables 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 automatically creates several groups in the console, which you can read more about in the PE docs.

  1. In the PE console, click Nodes > Classification, then click Add group.
  2. Specify options for the new node group:
    • Parent name – Select default.
    • Group name – Enter a name that describes the role of this environment node group, for example, ssh_example.
    • Environment – Select production.
    • Environment group – Don’t select this option.
  3. Click Add.
  4. Click the ssh_example group, then select 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 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 from user to user.

Add classes from the ssh module

Next, you’ll 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.

The ghoneycutt-ssh module contains one class: the ssh class. Classes are named chunks of Puppet code and are the primary means by which Puppet Enterprise configures nodes.

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.

  1. In the console, click Nodes > Classification, and find and select ssh_example group.

  2. On the Classes tab, n the Class name field, select ssh.

  3. 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.

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

  5. 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

The Events console 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.

  1. 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 set the known_hosts entries after it collects the public keys from agents nodes in your deployment .

  1. 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 down you navigate, the more information you’ll receive about the event. For example, in this case, you see that the the SSH rsa key for has been created and is now present in the known_hosts file for

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

You can edit or add class parameters in the PE console without needing to edit the module code directly.

The ghoneycutt-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 > Classification, and find and select the ssh_example group.
  2. On the Classes tab, find ssh in the list of classes.

  3. 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.

  4. In the Value field, enter no.
  5. Click Add parameter, and commit changes.
  6. From the command line of your Puppet master, run puppet agent -t.
  7. From the command line of each PE-managed node, run puppet agent -t.

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

  8. 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 blog gives some helpful hints for working with SSH.

Puppet 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 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