SSH

Table of Contents

• Module Description
• Setup
  • What ssh affects
  • Setup requirements
  • Beginning with SSH
• Usage
  • SSH client
    • Managing client settings
    • Managing client settings for specific hosts
    • Managing additional client settings using ssh_config
    • Including the client by itself
  • SSH server
    • Managing server settings
    • Managing additional server settings
      • Using Hiera
      • Using sshd_config
    • Including the server by itself
  • Managing SSH ciphers
    • Server ciphers
    • Client ciphers
  • Managing ssh_authorized_keys
• Limitations
• Development
• Acceptance tests
  • Environment variables specific to pupmod-simp-ssh

Module Description

Manages the SSH Client and Server

Setup

What ssh affects

SSH installs the SSH package, runs the sshd service and manages files primarily in /etc/ssh

Setup requirements

The only requirement is including the ssh module in your modulepath

Beginning with SSH

include 'ssh'

Usage

Including ssh will manage both the server and the client with reasonable settings:

include 'ssh'

The ssh class automatically includes both the ssh::client and ssh:server classes. To exclude one or both of these classes, set the appropriate parameter to false as shown:

class{ 'ssh':
  enable_client => false,
  enable_server => false,
}

SSH client

Managing client settings

Including ssh::client with no other options will automatically manage client settings to be used with all hosts (Host *).

If you want to customize any of these settings, you must disable the creation of the default entry with ssh::client::add_default_entry: false and manage Host * manually with the defined type ssh::client::host_config_entry:

class{ 'ssh::client': add_default_entry => false }

ssh::client::host_config_entry{ '*':
  gssapiauthentication      => true,
  gssapikeyexchange         => true,
  gssapidelegatecredentials => true,
}

Managing client settings for specific hosts

Different settings for particular hosts can be managed by using the defined type ssh::client::host_config_entry:

# `ancient.switch.fqdn` only understands old ciphers:
ssh::client::host_config_entry { 'ancient.switch.fqdn':
  ciphers => [ 'aes128-cbc', '3des-cbc' ],
}

Managing additional client settings using ssh_config

If you need to customize a setting in /etc/ssh/ssh_config that ssh::client::host_config_entry doesn't manage, use the ssh_config type, provided by augeasproviders_ssh:

# RequestTTY isn't handled by ssh::client::host_config_entry
# Note: RequestTTY is not a valid ssh_config setting on OpenSSH where version < 5.9
ssh_config { 'Global RequestTTY':
  ensure => present,
  key    => 'RequestTTY',
  value  => 'auto',
}

Including the client by itself

include `ssh::client`

You can prevent all inclusions of ssh from inadvertently managing the SSH server by specifying ssh::enable_server: false:

class{ 'ssh':
  enable_client => true,
  enable_server => false,
}

SSH server

Managing server settings

Including ssh::server with the default options will manage the server with reasonable settings for each host's environment.

include 'ssh::server'

# Alternative:
# if `ssh::enable_server: true`, this will also work
include 'ssh'

If you want to customize any ssh::server settings, you must edit the parameters of ssh::server::conf using Hiera or ENC (Automatic Parameter Lookup). These customizations cannot be made directly using a resource-style class declaration; they must be made via APL:

---
# Note: Hiera only!
ssh::server::conf::port: 2222
ssh::server::conf::ciphers:
- '[email protected]'
- 'aes256-ctr'
- '[email protected]'
ssh::server::conf::ssh_loglevel: "verbose"
ssh::server::conf::gssapiauthentication: true

include 'ssh::server'

# Alternative:
# if `ssh::enable_server: true`, this will also work
include 'ssh'

Managing additional server settings

Using Hiera

Users may specify any undefined global sshd settings using the ssh::server::conf::custom_entries parameter as follows:

---
ssh::server::conf::custom_entries:
  GSSAPIKeyExchange: "yes"
  GSSAPICleanupCredentials: "yes"

NOTE: This is parameter is not validated. Be careful to only specify options that are allowed for your particular SSH daemon. Invalid options may cause the ssh service to fail on restart. Duplicate settings will result in duplicate Puppet resources (i.e., manifest compilation failures).

Using sshd_config

Prior to version 6.7.0 of the simp-ssh module, undefined sshd settings were managed with sshd_config_ type, provided by augeasproviders_ssh. Although this functionality has been incorporated into ssh::server::conf::custom_entries, it is still available, and in some cases such as Match entries, necessary to call directly.

The following examples illustrate Match entries using sshd_config:

Puppet:

include 'ssh::server'

sshd_config { 
  "AllowAgentForwarding":
    ensure    => present,
    condition => "Host *.example.net",
    value     => "yes",
}

# Specify unique names to avoid duplicate declarations and compilation failures
sshd_config { 
  "X11Forwarding foo":
    ensure    => present,
    keys      => "X11Forwarding",
    condition => "Host foo User root",
    value     => "yes",
}

To delete a sshd_config entry, simply set ensure to absent as shown:

sshd_config {
  "X11Forwarding foo":
    ensure => absent,
}

Including the server by itself

You can focus ssh on managing the SSH server by itself by specifying ssh::enable_client: false:

class{ 'ssh':
  enable_client => false,
  enable_server => true,
}

Note: including ssh::client directly would still manage the SSH client

Managing SSH ciphers

Unless instructed otherwise, the ssh:: classes select ciphers based on the OS environment (the OS version, the version of the SSH server, whether FIPS mode is enabled, etc).

Server ciphers

At the time of 6.4.0, the default ciphers for ssh::server on EL7 when FIPS mode is disabled are:

• [email protected]
• [email protected]
• aes256-ctr
• aes192-ctr
• aes128-ctr

There are also 'fallback' ciphers, which are required in order to communicate with systems that are compliant with FIPS-140-2. These are always included by default unless the parameter ssh::server::conf::enable_fallback_ciphers is set to false:

• aes256-ctr
• aes192-ctr
• aes128-ctr

At the time of 6.4.0, the 'fallback' ciphers are the default ciphers for ssh::server on EL7 when FIPS mode is enabled and EL6 in either mode.

Client ciphers

By default, the system client ciphers in /etc/ssh/ssh_config are configured to strong ciphers that are recommended for use.

If you need to connect to a system that does not support these ciphers but uses older or weaker ciphers, you should either:

• Manage an entry for that specific host using an additional ssh::client::host_config_entry, or:
• Connect to the client with custom ciphers specified by the command line option, ssh -c
  • You can see a list of ciphers that your ssh client supports with ssh -Q cipher.
  • See the ssh man pages for further information.

Either of the choices above are preferable to weakening the system-wide client settings unecessarily.

Managing ssh_authorized_keys

You can manage users authorized_keys file using the ssh::authorized_keys class and the ssh::authorized_keys::keys hiera value.

---
ssh::authorized_keys::keys:
  kelly: ssh-rsa skjfhslkdjfs...
  nick:
  - ssh-rsa sajhgfsaihd...
  - ssh-rsa jrklsahsgfs...
  mike:
    key: dlfkjsahh...
    type: ssh-rsa
    user: mlast
    target: /home/gitlab-runner/.ssh/authorized_keys

Limitations

SIMP Puppet modules are generally intended to be used on a Red Hat Enterprise Linux-compatible distribution.

Development

Please read our Contribution Guide.

If you find any issues, they can be submitted to our JIRA.

To see a list of development tasks available for this module, run

  bundle exec rake -T

Acceptance tests

To run the system tests, you need Vagrant installed.

You can then run the following to execute the acceptance tests:

   bundle exec rake beaker:suites

Some environment variables may be useful:

   BEAKER_debug=true
   BEAKER_destroy=onpass
   BEAKER_provision=no
   BEAKER_fips=yes

• BEAKER_debug: show the commands being run on the SUT and their output.
• BEAKER_destroy=onpass prevent the machine destruction if the tests fail.
• BEAKER_provision=no: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.
• BEAKER_fips=yes: Provision the SUTs in FIPS mode.

Environment variables specific to pupmod-simp-ssh

   SIMP_SSH_report_dir=/PATH/TO/DIRECTORY

• SIMP_SSH_report_dir: If set to a valid directory, will record the Ciphers / MACs / kexalgorithms for each SSH server during the test. This can be used to validate and update the information in the Server ciphers section.