linux-system-roles.ssh

SSH

This is an Ansible role for managing SSH client settings.

Requirements

This role works on any system with OpenSSH client that is supported by Ansible. It was tested on:

RHEL/CentOS versions 6, 7, 8, 9
Fedora
Debian
Ubuntu

Collection requirements

To manage rpm-ostree systems, you'll need additional modules from external collections. Install them using:

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

Role Variables

By default, this role does not change the system settings and creates a global ssh_config that matches the operating system's default settings (it does not keep comments or order of options).

ssh_user

By default, the role modifies the global configuration for all users. If you specify a username, it will modify the configuration for that specific user in their ~/.ssh/config file. The user must exist beforehand; otherwise, the role will fail.

ssh_skip_defaults

The role normally writes the system-wide configuration file /etc/ssh/ssh_config and keeps the default settings from the OS. This is automatically turned off when you create a drop-in configuration file or a per-user configuration file.

ssh_drop_in_name

This sets the name for a drop-in configuration file that goes in the system-wide drop-in directory. If the system doesn't support drop-in directories, this will cause the play to fail. The default name is null if unsupported, or 00-ansible if supported.

The recommended format is NN-name, where NN is a two-digit number for sorting and name is a descriptive name for the file.

ssh dict

A dictionary containing configuration options and their values. See the example below.

ssh_...: Simple variables that start with ssh_ can be used instead of the above dictionary. These simple variables take priority over the dictionary values.

ssh_additional_packages

This role automatically installs commonly used packages for the given platform. If you need to install extra packages (e.g., openssh-keysign for host-based authentication), you can specify them here.

ssh_config_file

The configuration file that this role will write to. The default location is /etc/ssh/ssh_config.d/{name}.conf if the system has a drop-in directory, or /etc/ssh/ssh_config otherwise. If the ssh_user is set, the default is ~/.ssh/config.

To force it to write to /etc/ssh/ssh_config even if a drop-in directory is available, set ssh_drop_in_name to null.

ssh_config_owner, ssh_config_group, ssh_config_mode

These define the owner, group, and permissions of the created configuration file. By default, files are owned by root:root with 0644 permissions, unless a specific user is set, in which case permissions become 0600 and the owner and group change to the specified user.

ssh_backup

If set to false, the original ssh_config file will not be backed up. The default setting is true.

ssh_transactional_update_reboot_ok

This variable manages reboots needed for transactional updates. If a reboot is required, the role will proceed if this variable is set to true. If false, it will notify the user a reboot is needed without performing it. If not set, the role will fail to ensure the reboot is addressed.

Example Playbook

Here's an example of a playbook that configures the root user’s SSH settings in their home directory to use compression, control-master multiplexing, and enables GSSAPI authentication under the "match final all" section. It also creates an alias "example" for connecting to example.com as "somebody," and turns off X11 forwarding.

- name: Manage ssh clients
  hosts: all
  tasks:
  - name: Configure ssh clients
    include_role:
      name: linux-system-roles.ssh
    vars:
      ssh_user: root
      ssh:
        Compression: true
        ControlMaster: auto
        ControlPath: ~/.ssh/.cm%C
        Match:
          - Condition: "final all"
            GSSAPIAuthentication: true
        Host:
          - Condition: example
            Hostname: example.com
            User: somebody
      ssh_ForwardX11: false