Puppet module: ssh

Table of contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Backwards incompatibility
4. Setup - The basics of getting started with ssh
   • What ssh affects
   • Setup requirements
   • Beginning with ssh
5. Usage - Configuration options and additional functionality
6. Reference - An under-the-hood peek at what the module is doing and how
7. Limitations - OS compatibility, etc.
8. Development - Guide for contributing to the module
9. Contributors

##Overview

This is a puppet module to manage openssh, including management of hostkeys and a global known_hosts file. Works on puppet >= 2.7 and Debian- aswell as RedHat-based systems.

##Module description

openssh is an integral part of most linux infrastructures and this module provides a way to manage it. Apart from package installation, configuration and service management, it supports two ways to manage a global known_hosts file:

• based on storeconfig/puppetdb, by collecting the keys created with the package installation
• based on keys generated by the module, cached on the server and rolled out by puppet (enduring re-provisioning and working without storeconfig)

Backwards incompatibility

This module has just gone through a refactoring, from the module previously written for my employer (credativ/puppet-ssh-hiera). It is no longer compatible to that module, since some of its distinct features (user management) and specifics have been removed and/or changed. This module is no longer using the params_lookup function, nor is it managing anything except ssh.

Setup

What ssh effects

• openssh package
• openssh configuration
• openssh hostkey
• openssh service
• /etc/ssh/ssh_known_hosts

Beginning with ssh

If you just want a client installed, you can run include '::ssh::client'.

If you just want a server being installed and managed with default option, you can include '::ssh::server'.

If you need to customize options, such as the ListenAddress of the server or other configurations, you need to pass an options hash or use the appropriate parameters for a few often used cases.

class { '::ssh::server':
  permit_root_login => 'yes',
  listen_address    => '192.168.1.1',
  options           => $options_hash
}

Refer to the template to see what keys can be used in the options hash. Its also possible to specify an own template via the config_template parameter.

Setup requirements

This module does not have specific requirements, except if you want it to generate and manage the hostkeys of the system. Then its required to mkdir a directory /etc/puppet/ssh on your puppetmaster host and give it appropriate permissions so that puppetmaster can create and write files.

##Usage

You can include the classes you need and configure it via the parameters it supports. Please see the class docs for supported parameters and their meaning.

Classes

ssh::client

Currently only installs a ssh-client.

ssh::server

Installs and configures openssh-server, manages configuration and service by default and optionally hostkeys.

Parser Functions

ssh_keygen

The module includes a parser function ssh_keygen which can create and cache ssh keys on the server. Its used internally by the module if the module is configured to manage the hostkey.

Reference

The module contains the following public clases:

• ssh::client
• ssh::server

The following classes are currently not meant to be used directly, but used by the ssh::server class (depending on the parameters given).

• ssh::known_hosts
• ssh::known_hosts::storeconfig
• ssh::hostkey

Limitations

This module has been tested and is used primarily on Debian-based systems. Other systems are supported but cannot be guaranted.

Development

I happily accept bug reports and pull requests via github.

Contributors

This module is written and being maintained by

Patrick Schoenfeld <patrick.schoenfeld@credativ.de>.

It has been based on the module credativ/puppet-ssh-hiera, previously written for my employer and maintained together with my colleagues. It contains contributions from at least the following authors:

• Damian Lukowski
• Arnd Hannemann
• Alexander Wirt
• Tomas Barton
• Simon Page

Change log

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.

[2.4.0]

Summary:

Mostly a maintenance release with some bugfixes provided by the community (thank you!) and one new feature: Added support for custom config fragments.

This is probably the last non-breaking release, since I'm going to prepare for future parser soon and might make use of the new features.

Changes:

• Feature: Add support for custom config fragments: Which builds sshd_config from some concat resources and adds the ssh::server::custom_config resource.
• Feature: Module now passes the hostaliases parameter to the storeconfig class (if this is used) instead of using a hardcoded list of facts. The old way is still supported when hostaliases are not defined but will soon be obsolete.
• Bugfix for listen_address and permit_root_login for PE 2015.2 and CentOS 7
• Bugfix for non working manage_known_hosts switch
• Template fixes and added support for cipher setting
• Several changes to the build support files, including update to a new puppet-lint version.