OpenSSH Server

This role sets up the OpenSSH server. It:

• Configures the SSH server using standard operating system defaults by default.
• Works with various UN*X systems.
• Can be set up with dictionaries or simple variables.
• Supports Match sets for configuration.
• Covers all options in the sshd_config file. Templates are generated automatically. (see meta/make_option_lists)
• Checks the sshd_config before restarting the SSH service.

WARNING Incorrect settings can lock you out of your server! Please test your configuration to ensure it works well with user settings before using it in production!

WARNING Digital Ocean allows root access with passwords over SSH on Debian and Ubuntu. This role will set PermitRootLogin without-password, which permits access via SSH key but not via a password. If you need root login with a password for these hosts, set sshd_PermitRootLogin yes.

Requirements

Tested on:

• Ubuntu (precise, trusty, xenial, bionic, focal, jammy, noble)
  • 
• Debian (wheezy, jessie, stretch, buster, bullseye, bookworm)
  • 
• EL 6, 7, 8, 9, 10 based distributions
  • 
• All Fedora versions
  • 
• Latest Alpine
  • 
• FreeBSD 10.1
• OpenBSD 6.0
• AIX 7.1, 7.2
• OpenWrt 21.03

It may work on other systems, and additional support through suitable vars/ files is welcome.

Optional Requirements

To use advanced features like configuring the firewall and SELinux, especially when a custom port is used, you'll need some additional collections specified in meta/collection-requirements.yml. These aren't installed automatically. To manage rpm-ostree systems, you'll need to install them like this:

ansible-galaxy install -vv -r meta/collection-requirements.yml

For more details, see the sshd_manage_firewall and sshd_manage_selinux options below, as well as the rpm-ostree section. This extra functionality only works on Red Hat based systems.

Role Variables

Key Role Variables

If you don't configure this role, it will create a sshd_config that matches the OS default settings, but without comments and in a different format.

sshd_enable

Set to false to completely disable the role. The default is true.

sshd_skip_defaults

Set to true to skip applying default values. This means you must provide all configuration defaults through the sshd dictionary or sshd_Key variables. The default is false unless sshd_config_namespace is set or sshd_config_file points to a drop-in directory.

sshd_manage_service

Set to false to stop managing the SSH service (it won't enable, start, or reload). The default is true under normal circumstances unless running inside a Docker container or AIX.

sshd_allow_reload

Set to false to prevent reloading the SSH service when changes occur, which can be helpful for troubleshooting. You will need to manually reload the SSH service for changes to take effect. Defaults to the value of sshd_manage_service.

sshd_install_service

Set to true to install service files for the SSH service. Defaults to false.

You can use custom service templates with the following variables:

• sshd_service_template_service (default: templates/sshd.service.j2)
• sshd_service_template_at_service (default: templates/[email protected])
• sshd_service_template_socket (default: templates/sshd.socket.j2)

sshd_manage_firewall

Set to true to open the SSH port(s) in the firewall (only works on Red Hat based systems). Default is false.

sshd_manage_selinux

Set to true to configure SELinux to allow SSH listening on specified ports (only for Red Hat based systems). Default is false.

sshd

A dictionary for SSH configuration. For example:

sshd:
  Compression: delayed
  ListenAddress:
    - 0.0.0.0

sshd_<OptionName>

You can also use simple variables that override dictionary values. For example:

sshd_Compression: off

Lists can be used for multiple lines; for example:

sshd_ListenAddress:
  - 0.0.0.0
  - '::'

Output:

ListenAddress 0.0.0.0
ListenAddress ::

sshd_match, sshd_match_1 through sshd_match_9

These can contain a list of dictionaries or just a dictionary for a Match configuration. Note that these variables don't override anything within sshd.

sshd_backup

Set to false to not back up the original sshd_config file. The default is true.

sshd_sysconfig

On RHEL-based systems, if set to true, this role will manage the /etc/sysconfig/sshd file too. Default is false.

sshd_sysconfig_override_crypto_policy

In RHEL 8-based systems, this can be set to true to allow changes to crypto policy (default is false).

sshd_config_file

Specifies where to save the configuration file generated by this role. Useful for including configuration snippets from a drop-in directory.

sshd_main_config_file

Use this for setting the main configuration file path when working with a drop-in directory. Defaults to /etc/ssh/sshd_config.

sshd_config_namespace

By default, this role defines the entire config file. You can use this variable to call the role from multiple places within a playbook.

...

Configure SSH Certificate Authentication

To set up SSH certificate authentication, provide at least the trusted user CA key using the sshd_trusted_user_ca_keys_list variable.

Additional Variables

...

Example Playbook

DANGER! The following example shows the broad configuration options this role offers. Running it may cause loss of access to your server!

---
- hosts: all
  vars:
    sshd_skip_defaults: true
    sshd:
      Compression: true
      ListenAddress:
        - "0.0.0.0"
        - "::"
      GSSAPIAuthentication: false
      Match:
        - Condition: "Group user"
          GSSAPIAuthentication: true
    sshd_UsePrivilegeSeparation: false
    sshd_match:
        - Condition: "Group xusers"
          X11Forwarding: true
  roles:
    - role: willshersystems.sshd

Generated output:

# Ansible managed: ...
Compression yes
GSSAPIAuthentication no
UsePrivilegeSeparation no
Match Group user
  GSSAPIAuthentication yes
Match Group xusers
  X11Forwarding yes

...

License

LGPLv3

Authors

Matt Willsher matt@willsher.systems

© 2014-2015 Willsher Systems Ltd.

Jakub Jelen jjelen@redhat.com

© 2020 - 2024 Red Hat, Inc.