Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

ssh

Manage the ssh client and multiple daemons
Project URLRSS FeedReport issues

11,750 downloads

10,355 latest version

1.5 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 1.0.18 (latest)
  • 1.0.17
  • 1.0.16
  • 1.0.15
  • 1.0.14
  • 1.0.13
released Jan 9th 2014

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'foolean-ssh', '1.0.18'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add foolean-ssh
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install foolean-ssh --version 1.0.18

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: debian, ubuntu, redhat, client, ssh, server, fedora, freebsd, sles, centos, openbsd, opensuse, multi-daemon

Documentation

foolean/ssh — version 1.0.18 Jan 9th 2014

ssh

The ssh module is a collection of classes and defines that facilitate the configuration of the ssh client and multiple listening ssh daemons.

Example

node my_node {
    class { 'ssh::client': }
    ssh::server { 'default': }
    ssh::server { 'special': port => 2222 }
    ssh::server { 'forwarder':
        port               => 2212,
        allowtcpforwarding => true,
        x11forwarding      => true,
    }
}

About this module

Q: What's with having every possible SSH configuration option?

This started out as an experiment to see how granular Puppet could manage a particular service.

Q: What the heck did you do to sshd_config?

The resulting sshd_config looks nothing like the sshd_config format you may be used to. Because this module manages all configuration options it became obvious early on that they would need to be explicitly set in sshd_config. This is largely due to an inability (either with puppet or my own abilities) to process an undefined boolean variable (e.g. undefined = false). Since sshd_config does not really have any formal layout to it the decision was made to arrange the options in alphabetical order. The only exception to this are the Match blocks which are at the end of the file.

Q: What's with the defaults?

This module was written with security auditing in mind. The defaults were chosen to comply with various best practices such as CIS Benchmarks, vendor guidance, etc. The idea is that by not specifying any parameters in your ssh::server call (e.g. ssh::server { 'default': }) you can assert that the configuration follows best practices. Then by setting the parameters, your deviations from the baseline become self-documenting. An auditor should then be able to audit the default baseline configuration then simply observe the deviations, if any, within the node definition.

Supported Operating Systems

Primary development is done on Debian and then validated against other operating systems. The current list of supported operating systems is:

* Centos
* Debian
* Fedora
* FreeBSD
* OpenSUSE
* OpenBSD
* RedHat
* SLES
* Ubuntu

Packaging

Creating the package (tarball) that can be installed using puppet's module function is simple. Run the following command while in the top of the module directory (e.g. /usr/src/puppet-ssh).

puppet module build .

The resulting tarball will be named foolean-ssh-$VER.tar.gz and can be found in the "pkg" directory within the source tree.

PuppetForge Installation

Foolean SSH is on PuppetLab's PuppetForge making installation as simple as:

puppet module install foolean/ssh

Manual Installation

When we're installing from a tarball the installation and upgrade process is the same. You'll need to set --modulepath if f you're installing the module in a path other than the location defined in puppet.conf.

MODULEPATH=/var/lib/puppet/modules
puppet module install         \
    --force                   \
    --ignore-dependencies     \
    --module-path $MODULEPATH \
    $PATHTO/foolean-ssh-$VER.tar.gz

Class and Define Documentation

The individual class and define files have been documented using Puppet's rdoc format. You can view the documentation by opening the files in your favorite reader or by using the 'puppet doc' command. For a man(1)-like behavior, pipe it to less.

puppet doc $path_to/ssh/manifests/server.pp | less

For more information on Manifest Documentation see: http://projects.puppetlabs.com/projects/puppet/wiki/Puppet_Manifest_Documentation

Managing Server Host Keys

Most modern ssh packages will create the server's host keys if they don't already exist. This module will also create the server's host keys if they don't exist. In some situations it is adventageous for a server to retain it's server keys upon complete system rebuild. Doing so prevents clients from having to deal with the key mismatch errors that would happen otherwise. This module will look in several locations for copies of the key files before creating keys. 

The paths it will look in are:
${settings::vardir}/sites/${site_name}/${::fqdn}/etc/ssh/${key_file}
${settings::vardir}/private/${::fqdn}/etc/ssh/${key_file}
${settings::vardir}/hosts/${::fqdn}/etc/ssh/${key_file}
${settings::vardir}/nodefile/${::fqdn}/etc/ssh/${key_file}
${settings::vardir}/dist/${::fqdn}/etc/ssh/${key_file}

So far there doesn't seem to be a way to pass an array to puppet's file() function so these are hard-coded lists for each of the RSA and DSA keys. Passing the content of the keys as a parameter was also considered but it was decided that doing so would make the node definition too difficult to read. This concept will be revisited in the future when it is made Heira aware.

There are currently two parameters used to establish keys (rsakey and dsakey). Each daemon can use the same default key or you may specify the full path to key files if you want a specific daemon to use its own unique key.

Example: ssh::server { 'special': port => 1234, rsakey => '/etc/ssh/ssh_host_rsa_key_special', dsakey => '/etc/ssh/ssh_host_dsa_key_special', }

Limitations

[ ssh_known_hosts ]

Puppet's sshkey resource works well for managing the ssh_known_hosts file however it is an "all or nothing" solution. Currently there is no way to use both a template and the sshkey resource. Attempts to utilize both will result in the sshkey resource randomly destroying the templated file due to Puppet's natural ordering mechanisms. All attempts to force order did not work. As a result the decision was made to make the ssh_known_hosts file a template only and leave the use of sshkey up to the administrator to create the necessary local classes.

The paths it will look in are:
${settings::vardir}/sites/${site_name}/${::fqdn}/etc/ssh/${ssh_known_hosts}
${settings::vardir}/private/${::fqdn}/etc/ssh/${ssh_known_hosts}
${settings::vardir}/hosts/${::fqdn}/etc/ssh/${ssh_known_hosts}
${settings::vardir}/nodefile/${::fqdn}/etc/ssh/${ssh_known_hosts}
${settings::vardir}/dist/${::fqdn}/etc/ssh/${ssh_known_hosts}

If a ssh_known_hosts file is not found then the client class will ensure that the ssh_known_hosts file exists and has the proper ownership and permissions.

To Do

  • Validate the recent change to comprehensively manage all configuration options against all operating systems. Currently Debian has the most testing time. Feel free to open an issue if you discover something on an operating system that hasn't been fully tested.

  • Centralized default variables would make management of the defaults and their representation in the comments a bit easier.

  • Parameter validation for the PermitOpen option

  • Collapse match_user, match_group, match_host, and match_address into a single hash-of-hashes-of-hashes. ( This one is still under consideration )

  • Find and fix all of the "copy pasta" that is sure to exist

License

Copyright (c) 2013 Foolean.org

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contact

bennett@foolean.org