4.11.3. HOWTO Customize Settings for SSH¶
By default, SIMP will include the ssh
class from the simp-ssh
module
under most of the SIMP scenarios. If it is absent
from the scenario you have selected, add the following to Hiera to
include the class:
simp::classes:
- 'ssh'
To exclude the SIMP ssh
class so that you can manage SSH configuration
by other means, refer to Disable SSH Management.
The SIMP ssh
class is configured to automatically include the
ssh::server
and ssh::client
classes. These classes, in turn, manage
the SSH daemon settings for incoming connections and the SSH client settings
for outgoing connections, respectively. They configure SSH with reasonable
defaults for the OS and environment.
If you want to disable SIMP management of either the SSH server or client settings, you can do so through Hiera. For example, to disable SIMP management of both:
ssh::enable_client: false
ssh::enable_server: false
4.11.3.1. Managing Settings for the SSH Server¶
The ssh::server
class is responsible for configuring sshd
. It delegates
configuration of specific sshd
settings found in sshd_config
to
ssh::server::conf
. Detailed descriptions of the these settings are provided
in the sshd_config(5)
man page.
The ssh::server::conf
class uses a number of SIMP-specific parameters, such
as whether the system is FIPS enabled, has a firewall, or utilizes LDAP. This
allows seamless integration of SSH with other SIMP-managed applications in the
larger SIMP environment. For example, ssh::server::conf
ensures the
appropriate fallback ciphers are used, ensures proper authentication is
configured, and allows SSH traffic through the firewall. More detailed
information is provided in the simp-ssh
module README file.
4.11.3.1.1. Configuring ssh::server::conf
from Hiera¶
ssh::server::conf
provides default configuration for key sshd_config
settings and a mechanism to set most other settings.
To customize the SSH server, edit the parameters of ssh::server::conf
using
Hiera or ENC.
Note
Unlike many SIMP modules, these customizations cannot be made directly with a resource-style class declaration ― they must be made via automatic parameter lookup provided by Hiera or an ENC. Examples using Hiera are provided for illustrative purposes.
In Hiera:
ssh::server::conf::port: 2222
ssh::server::conf::passwordauthentication: false
Starting with version 6.8.0 of the simp-ssh
module, multiple ports
can be specified to listen for incoming SSH connections. So the
ssh::server::conf::port
parameter in the previous example could be set
as follows in Hiera to listen on multiple ports:
ssh::server::conf::port: [22, 2222, 22222]
4.11.3.1.2. Managing Additional Settings with sshd_config
¶
Starting with version 6.7.0 of the simp-ssh
module, you can manage
additional settings not explicitly mapped to ssh::server::conf
parameters,
using the ssh::server::conf::custom_entries
parameter. For example, to specify
configuration for AllowAgentForwarding
and AuthorizedPrincipalsCommand
sshd
settings, you would include Hiera such as the following:
ssh::server::conf::custom_entries:
AllowAgentForwarding: "yes"
AuthorizedPrincipalsCommand: "/usr/local/bin/my_command"
There are a few limitations with ssh::server::conf::custom_entries
that
need to be noted:
- No setting validation:
- This parameter is not validated. Be careful to only specify settings
that are allowed for your particular SSH daemon and avoid duplicate
declaration of settings already specified. Invalid options may cause the
sshd
service to fail on restart. Duplicate settings will result in duplicate Puppet resources (i.e., manifest compilation failures).
- No direct MATCH entry support:
- Due to their complexity,
Match
entries are not supported. However, you can add them using thesshd_config_match
resource from the herculesteam-augeasproviders_ssh module. Sincesimp-ssh
uses this module internally, thesshd_config_match
resource will be available to you on any node usingsimp-ssh
.
4.11.3.2. Managing Settings for the SSH Client¶
The ssh::client
class is responsible for configuring default client settings
for outgoing SSH sessions to all hosts (Host *
).
4.11.3.2.1. Managing Settings for the Default Host Entry (Host *
)¶
If you want to customize the default settings, you must prevent ssh::client
from declaring them automatically and then declare Host *
settings manually.
You do this by setting ssh::client::add_default_entry
to false
and
using the defined type ssh::client::host_config_entry
. For example:
In Hiera:
ssh::client::add_default_entry: false
In Puppet:
ssh::client::host_config_entry{ '*':
gssapiauthentication => true,
gssapikeyexchange => true,
gssapidelegatecredentials => true,
}
4.11.3.2.2. 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' ],
}
4.11.3.2.3. Managing Additional Settings with ssh_config
¶
Starting with version 6.4.0 of the simp-ssh
module, you can use the
ssh_config resource from the herculesteam-augeasproviders_ssh module to
manage settings that the module does not cover.
For instance, to ensure that the default host entry’s RequestTTY
option is
set to auto
:
# RequestTTY is not managed by ssh::client::host_config_entry
ssh_config { 'Global RequestTTY':
ensure => present,
key => 'RequestTTY',
value => 'auto',
}