Puppet SSH

Manage SSH client and server via Puppet. Source: https://github.com/saz/puppet-ssh

Requirements

• Exported resources for host keys management
• puppetlabs/stdlib
• puppetlabs/concat

Usage

Since version 2.0.0 only non-default values are written to both, client and server, configuration files.

Multiple occurrences of one config key (e.g. sshd should be listening on port 22 and 2222) should be passed as an array.

options => {
  'Port' => [22, 2222],
}

This is working for both, client and server.

Both client, server and per user client configuration

Host keys will be collected and distributed unless storeconfigs_enabled is false.

include ssh

or

class { 'ssh':
  storeconfigs_enabled => false,
  server_options => {
    'Match User www-data' => {
      'ChrootDirectory' => '%h',
      'ForceCommand' => 'internal-sftp',
      'PasswordAuthentication' => 'yes',
      'AllowTcpForwarding' => 'no',
      'X11Forwarding' => 'no',
    },
    'Port' => [22, 2222, 2288],
  },
  client_options => {
    'Host *.amazonaws.com' => {
      'User' => 'ec2-user',
    },
  },
  users_client_options => {
    'bob' => {
      options => {
        'Host *.alice.fr' => {
          'User' => 'alice',
        },
      },
    },
  },
}

Hiera example

ssh::storeconfigs_enabled: true

ssh::server_options:
    Protocol: '2'
    ListenAddress:
        - '127.0.0.0'
        - '%{::hostname}'
    PasswordAuthentication: 'yes'
    SyslogFacility: 'AUTHPRIV'
    UsePAM: 'yes'
    X11Forwarding: 'yes'

ssh::server::match_block:
  filetransfer:
    type: group
    options:
      ChrootDirectory: /home/sftp
      ForceCommand: internal-sftp

ssh::client_options:
    'Host *':
        SendEnv: 'LANG LC_*'
        ForwardX11Trusted: 'yes'
        ServerAliveInterval: '10'

ssh::users_client_options:
    'bob':
        'options':
            'Host *.alice.fr':
                'User': 'alice'
                'PasswordAuthentication': 'no'

Client only

Collected host keys from servers will be written to known_hosts unless storeconfigs_enabled is false

include ssh::client

or

class { 'ssh::client':
  storeconfigs_enabled => false,
  options => {
    'Host short' => {
      'User' => 'my-user',
      'HostName' => 'extreme.long.and.complicated.hostname.domain.tld',
    },
    'Host *' => {
      'User' => 'andromeda',
      'UserKnownHostsFile' => '/dev/null',
    },
  },
}

Per user client configuration

User's home is expected to be /home/bob

SSH configuration file will be /home/bob/.ssh/config.

::ssh::client::config::user { 'bob':
  ensure => present,
  options => {
    'HashKnownHosts' => 'yes'
  }
}

User's home is passed to define type

SSH configuration file will be /var/lib/bob/.ssh/config and puppet will manage directory /var/lib/bob/.ssh.

::ssh::client::config::user { 'bob':
  ensure => present,
  user_home_dir => '/var/lib/bob',
  options => {
    'HashKnownHosts' => 'yes'
  }
}

User's ssh directory should not be managed by the define type

SSH configuration file will be /var/lib/bob/.ssh/config.

::ssh::client::config::user { 'bob':
  ensure => present,
  user_home_dir => '/var/lib/bob',
  manage_user_ssh_dir => false,
  options => {
    'HashKnownHosts' => 'yes'
  }
}

User's ssh config is specified with an absolute path

::ssh::client::config::user { 'bob':
  ensure => present,
  target => '/var/lib/bob/.ssh/ssh_config',
  options => {
    'HashKnownHosts' => 'yes'
  }
}

Server only

Host keys will be collected for client distribution unless storeconfigs_enabled is false

include ssh::server

or

class { 'ssh::server':
  storeconfigs_enabled => false,
  options => {
    'Match User www-data' => {
      'ChrootDirectory' => '%h',
      'ForceCommand' => 'internal-sftp',
      'PasswordAuthentication' => 'yes',
      'AllowTcpForwarding' => 'no',
      'X11Forwarding' => 'no',
    },
    'PasswordAuthentication' => 'no',
    'PermitRootLogin'        => 'no',
    'Port'                   => [22, 2222],
  },
}

Validate config before replacing it

validate_sshd_file allows you to run /usr/sbin/sshd -tf against the sshd config file before it gets replaced, and will raise an error if the config is incorrect.

class { 'ssh::server':
  validate_sshd_file => true,
}

Default options

Client

'Host *'                 => {
  'SendEnv'              => 'LANG LC_*',
  'HashKnownHosts'       => 'yes',
  'GSSAPIAuthentication' => 'yes',
}

Server

'ChallengeResponseAuthentication' => 'no',
'X11Forwarding'                   => 'yes',
'PrintMotd'                       => 'no',
'AcceptEnv'                       => 'LANG LC_*',
'Subsystem'                       => 'sftp /usr/lib/openssh/sftp-server',
'UsePAM'                          => 'yes',

Overwriting default options

Default options will be merged with options passed in. If an option is set both as default and via options parameter, the latter will win.

The following example will disable X11Forwarding, which is enabled by default:

class { 'ssh::server':
  options           => {
    'X11Forwarding' => 'no',
  },
}

Which will lead to the following sshd_config file:

# File is managed by Puppet

ChallengeResponseAuthentication no
X11Forwarding no
PrintMotd no
AcceptEnv LANG LC\_\*
Subsystem sftp /usr/lib/openssh/sftp-server
UsePAM yes
PasswordAuthentication no

Values can also be arrays, which will result in the option being specified multiple times

class { 'ssh::server':
  options           => {
    'HostKey' => ['/etc/ssh/ssh_host_ed25519_key', '/etc/ssh/ssh_host_rsa_key'],
  },
}

Which will lead to the following sshd_config file:

# File is managed by Puppet

ChallengeResponseAuthentication no
HostKey /etc/ssh/ssh_host_ed25519_key
HostKey /etc/ssh/ssh_host_rsa_key
PrintMotd no
AcceptEnv LANG LC_\*
Subsystem sftp /usr/lib/openssh/sftp-server
UsePAM yes
PasswordAuthentication no

Defining host keys for server

You can define host keys your server will use

ssh::server::host_key {'ssh_host_rsa_key':
  private_key_content => '<the private key>',
  public_key_content  => '<the public key>',
}

Alternately, you could create the host key providing the files, instead of the content:

ssh::server::host_key {'ssh_host_rsa_key':
  private_key_source => 'puppet:///mymodule/ssh_host_rsa_key',
  public_key_source  => 'puppet:///mymodule/ssh_host_rsa_key.pub',
}

Both of these definitions will create /etc/ssh/ssh_host_rsa_key and /etc/ssh/ssh_host_rsa_key.pub and restart sshd daemon.

Adding custom match blocks

class YOURCUSTOMCLASS {

  include ssh

  ssh::server::match_block { 'sftp_only':
    type    => 'User',
    options => {
      'ChrootDirectory'        => "/sftp/%u",
      'ForceCommand'           => 'internal-sftp',
      'PasswordAuthentication' => 'no',
      'AllowTcpForwarding'     => 'no',
      'X11Forwarding'          => 'no',
    }
  }
}

Tag hostkey

Assign tags to exported sshkey resources (when ssh::storeconfigs_enabled is set to true).

ssh::hostkeys::tags:
  - hostkey_group1
  - hostkey_group2

Host keys then can be imported using:

Sshkey <<| tag == "hostkey_group1" |>>

Excluding network interfaces or ipaddresses

Use hiera to exclude interfaces or ipaddresses from hostkey inclusion

ssh::hostkeys::exclude_interfaces:
  - eth0
  - eth3
ssh::hostkeys::exclude_ipaddresses:
  - 192.168.0.1
  - 10.42.24.242

Facts

This module provides facts detailing the available SSH client and server versions.

• ssh_*_version_full Provides the full version number including the portable version number.
• ssh_*_version_major Provides the first two numbers in the version number.
• ssh_*_version_release Provides the first three number components of the version, no portable version is present.

Example facter output for OpenSSH 6.6.1p1:

ssh_client_version_full => 6.6.1p1
ssh_client_version_major => 6.6
ssh_client_version_release => 6.6.1
ssh_server_version_full => 6.6.1p1
ssh_server_version_major => 6.6
ssh_server_version_release => 6.6.1

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[12.1.0]

Added

• allow puppet/systemd < 8, fixes #382

Changed

• set sshd config mode to 0644 on AIX, fixes #371 (#383)
• use contain instead of include, fixes #367 (#387)

Fixed

• fix tests on OpenBSD (#384)
• drop tag from concat_{file,fragment}, fixes #304 (#385)
• fix subsystem option if use_augeas = true, fixes #376 (#386)

[12.0.1]

Fixed

• make ssh::hostkeys::exclude_interfaces_re parameter work properly (#380)

[12.0.0]

Added

• add parameter to exclude interfaces with a regex (#378)
• Allow User to add additonal systemd options to instances (#374)

Changed

• puppet/systemd: Allow 6.x (#364)

Fixed

• allow ssh::server::ensure = latest, fixes #370 (#377)

[11.1.0]

Fixed

• write ciphers,macs and kex as comma-separated string (#362)
• Fix "No ssh_server_version_major created with OpenSSH 9.2" (#359)

[11.0.0]

Removed

• BREAKING CHANGE: drop support for puppet 6

Changed

• puppetlabs/concat: Allow 9.x (#354)
• puppet/systemd: Allow 5.x (#354)
• puppetlabs/stdlib: Require 9.x (#354)

Added

• add Debian 12 as supported OS

[10.2.0]

Changed

• bump puppetlabs/concat to < 9.0.0 (#352)
• Replace deprecated functions (#350)

[10.1.0]

Added

• Support assigning multiple tags to a hostkey (#345)
• Add AIX support (#341)

Changed

• bump puppet/systemd to < 5.0.0 (#344)

Fixed

• Fix for service name on latest versions of opensuse. (#343)

[10.0.0]

Added

• Add support for client "match blocks" (#332, #333)
• Add data file for OpenBSD (#339)
• Add support for service_ensure/service_enable in ssh::server::instances (#338)

Changed

• Use hiera instead of params.pp (#325, #328)

Fixed

• Fix parameter lookup for ssh::server and ssh::client (#331)

[9.0.0]

Added

• Support for multiple instances (#318, #319, #321) - Thanks!

Changed

• "hostkeys.pp" isn't marked private anymore (#317)

[8.0.0]

Changed

• update path to sftp server on Gentoo (#315, breaking change)

[7.0.2]

Added

• allow stdlib < 9.0.0 (#314)

[7.0.1]

Fixed

• ssh_config: Don't populate options that are set to undef (#312)

[7.0.0]

Fixed

• Fix grammar and spelling in various places

Changed

• Use GitHub Actions instead of TravisCI
• Update module dependencies

Removed

• Dropped support for puppet 4 and 5 (Breaking Change)

[6.2.0]

Changed

• support older facter versions (#293)

[6.1.0]

Fixed

• Fix absolute class name includes
• Use gid 0 instead of group name for $host_priv_key_group (#289)
• Sort hostkeys (#288)
• Do not show diff when installing a ssh private host key (#283)
• Don't populate options which have a value of undef (#281)

Added

• document exclusion of interfaces and ipaddresses within hostkeys.pp (#267)
• add parameter to use trusted facts to hostkeys.pp (#226)

[6.0.0]

Fixed

• don't fail at deep_merge if hiera data not available, see #272
• Fix typo in match_block example in README, see #271, #273

Added

• Add CHANGELOG (starting with this release), see #222
• Test module with Puppet 6.1, see #269

Changed

• Convert ipaddresses to 4x API namespaced function, see #270
• Allow puppetlabs stdlib and concat 6.x, see #280