Chapter 14. Configuring secure communication by using the ssh and sshd RHEL System Roles
Chapter 14. Configuring secure communication by using the ssh and sshd RHEL System Roles As an administrator, you can use the sshd System Role to configure SSH servers and the ssh System Role to configure SSH clients consistently on any number of RHEL systems at the same time by using Red Hat Ansible Automation Platform. 14.1. ssh Server System Role variables In an sshd System Role playbook, you can define the parameters for the SSH configuration file according to your preferences and limitations. If you do not configure these variables, the System Role produces an sshd_config file that matches the RHEL defaults. In all cases, Booleans correctly render as yes and no in sshd configuration. You can define multi-line configuration items using lists. For example: renders as: Variables for the sshd System Role sshd_enable If set to False , the role is completely disabled. Defaults to True . sshd_skip_defaults If set to True , the System Role does not apply default values. Instead, you specify the complete set of configuration defaults by using either the sshd dict, or sshd_Key variables. Defaults to False . sshd_manage_service If set to False , the service is not managed, which means it is not enabled on boot and does not start or reload. Defaults to True except when running inside a container or AIX, because the Ansible service module does not currently support enabled for AIX. sshd_allow_reload If set to False , sshd does not reload after a change of configuration. This can help with troubleshooting. To apply the changed configuration, reload sshd manually. Defaults to the same value as sshd_manage_service except on AIX, where sshd_manage_service defaults to False but sshd_allow_reload defaults to True . sshd_install_service If set to True , the role installs service files for the sshd service. This overrides files provided in the operating system. Do not set to True unless you are configuring a second instance and you also change the sshd_service variable. Defaults to False . The role uses the files pointed by the following variables as templates: sshd_service This variable changes the sshd service name, which is useful for configuring a second sshd service instance. sshd A dict that contains configuration. For example: sshd _OptionName You can define options by using simple variables consisting of the sshd_ prefix and the option name instead of a dict. The simple variables override values in the sshd dict.. For example: sshd_match and sshd_match_1 to sshd_match_9 A list of dicts or just a dict for a Match section. Note that these variables do not override match blocks as defined in the sshd dict. All of the sources will be reflected in the resulting configuration file. Secondary variables for the sshd System Role You can use these variables to override the defaults that correspond to each supported platform. sshd_packages You can override the default list of installed packages using this variable. sshd_config_owner , sshd_config_group , and sshd_config_mode You can set the ownership and permissions for the openssh configuration file that this role produces using these variables. sshd_config_file The path where this role saves the openssh server configuration produced. sshd_config_namespace The default value of this variable is null, which means that the role defines the entire content of the configuration file including system defaults. Alternatively, you can use this variable to invoke this role from other roles or from multiple places in a single playbook on systems that do not support drop-in directory. The sshd_skip_defaults variable is ignored and no system defaults are used in this case. When this variable is set, the role places the configuration that you specify to configuration snippets in an existing configuration file under the given namespace. If your scenario requires applying the role several times, you need to select a different namespace for each application. Note Limitations of the openssh configuration file still apply. For example, only the first option specified in a configuration file is effective for most of the configuration options. Technically, the role places snippets in "Match all" blocks, unless they contain other match blocks, to ensure they are applied regardless of the match blocks in the existing configuration file. This allows configuring any non-conflicting options from different roles invocations. sshd_binary The path to the sshd executable of openssh . sshd_service The name of the sshd service. By default, this variable contains the name of the sshd service that the target platform uses. You can also use it to set the name of the custom sshd service when the role uses the sshd_install_service variable. sshd_verify_hostkeys Defaults to auto . When set to auto , this lists all host keys that are present in the produced configuration file, and generates any paths that are not present. Additionally, permissions and file owners are set to default values. This is useful if the role is used in the deployment stage to make sure the service is able to start on the first attempt. To disable this check, set this variable to an empty list [] . sshd_hostkey_owner , sshd_hostkey_group , sshd_hostkey_mode Use these variables to set the ownership and permissions for the host keys from sshd_verify_hostkeys . sshd_sysconfig On RHEL-based systems, this variable configures additional details of the sshd service. If set to true , this role manages also the /etc/sysconfig/sshd configuration file based on the following configuration. Defaults to false . sshd_sysconfig_override_crypto_policy In RHEL, when set to true , this variable overrides the system-wide crypto policy. Defaults to false . sshd_sysconfig_use_strong_rng On RHEL-based systems, this variable can force sshd to reseed the openssl random number generator with the number of bytes given as the argument. The default is 0 , which disables this functionality. Do not turn this on if the system does not have a hardware random number generator. 14.2. Configuring OpenSSH servers using the sshd System Role You can use the sshd System Role to configure multiple SSH servers by running an Ansible playbook. Note You can use the sshd System Role with other System Roles that change SSH and SSHD configuration, for example the Identity Management RHEL System Roles. To prevent the configuration from being overwritten, make sure that the sshd role uses namespaces (RHEL 8 and earlier versions) or a drop-in directory (RHEL 9). Prerequisites Access and permissions to one or more managed nodes , which are systems you want to configure with the sshd System Role. Access and permissions to a control node , which is a system from which Red Hat Ansible Core configures other systems. On the control node: The ansible-core and rhel-system-roles packages are installed. Important RHEL 8.0-8.5 provided access to a separate Ansible repository that contains Ansible Engine 2.9 for automation based on Ansible. Ansible Engine contains command-line utilities such as ansible , ansible-playbook , connectors such as docker and podman , and many plugins and modules. For information about how to obtain and install Ansible Engine, see the How to download and install Red Hat Ansible Engine Knowledgebase article. RHEL 8.6 and 9.0 have introduced Ansible Core (provided as the ansible-core package), which contains the Ansible command-line utilities, commands, and a small set of built-in Ansible plugins. RHEL provides this package through the AppStream repository, and it has a limited scope of support. For more information, see the Scope of support for the Ansible Core package included in the RHEL 9 and RHEL 8.6 and later AppStream repositories Knowledgebase article. An inventory file which lists the managed nodes. Procedure Copy the example playbook for the sshd System Role: # cp /usr/share/doc/rhel-system-roles/sshd/example-root-login-playbook.yml path/custom-playbook.yml Open the copied playbook by using a text editor, for example: # vim path/custom-playbook.yml --- - hosts: all tasks: - name: Configure sshd to prevent root and password login except from particular subnet include_role: name: rhel-system-roles.sshd vars: sshd: # root login and password login is enabled only from a particular subnet PermitRootLogin: no PasswordAuthentication: no Match: - Condition: "Address 192.0.2.0/24" PermitRootLogin: yes PasswordAuthentication: yes The playbook configures the managed node as an SSH server configured so that: password and root user login is disabled password and root user login is enabled only from the subnet 192.0.2.0/24 You can modify the variables according to your preferences. For more details, see SSH Server System Role variables . Optional: Verify playbook syntax. # ansible-playbook --syntax-check path/custom-playbook.yml Run the playbook on your inventory file: # ansible-playbook -i inventory_file path/custom-playbook.yml ... PLAY RECAP ************************************************** localhost : ok=12 changed=2 unreachable=0 failed=0 skipped=10 rescued=0 ignored=0 Verification Log in to the SSH server: Where: user1 is a user on the SSH server. 10.1.1.1 is the IP address of the SSH server. Check the contents of the sshd_config file on the SSH server: Check that you can connect to the server as root from the 192.0.2.0/24 subnet: Determine your IP address: If the IP address is within the 192.0.2.1 - 192.0.2.254 range, you can connect to the server. Connect to the server as root : Additional resources /usr/share/doc/rhel-system-roles/sshd/README.md file. ansible-playbook(1) man page. 14.3. ssh System Role variables In an ssh System Role playbook, you can define the parameters for the client SSH configuration file according to your preferences and limitations. If you do not configure these variables, the System Role produces a global ssh_config file that matches the RHEL defaults. In all cases, booleans correctly render as yes or no in ssh configuration. You can define multi-line configuration items using lists. For example: renders as: Note The configuration options are case sensitive. Variables for the ssh System Role ssh_user You can define an existing user name for which the System Role modifies user-specific configuration. The user-specific configuration is saved in ~/.ssh/config of the given user. The default value is null, which modifies global configuration for all users. ssh_skip_defaults Defaults to auto . If set to auto , the System Role writes the system-wide configuration file /etc/ssh/ssh_config and keeps the RHEL defaults defined there. Creating a drop-in configuration file, for example by defining the ssh_drop_in_name variable, automatically disables the ssh_skip_defaults variable. ssh_drop_in_name Defines the name for the drop-in configuration file, which is placed in the system-wide drop-in directory. The name is used in the template /etc/ssh/ssh_config.d/{ssh_drop_in_name}.conf to reference the configuration file to be modified. If the system does not support drop-in directory, the default value is null. If the system supports drop-in directories, the default value is 00-ansible . Warning If the system does not support drop-in directories, setting this option will make the play fail. The suggested format is NN-name , where NN is a two-digit number used for ordering the configuration files and name is any descriptive name for the content or the owner of the file. ssh A dict that contains configuration options and their respective values. ssh _OptionName You can define options by using simple variables consisting of the ssh_ prefix and the option name instead of a dict. The simple variables override values in the ssh dict. ssh_additional_packages This role automatically installs the openssh and openssh-clients packages, which are needed for the most common use cases. If you need to install additional packages, for example, openssh-keysign for host-based authentication, you can specify them in this variable. ssh_config_file The path to which the role saves the configuration file produced. Default value: If the system has a drop-in directory, the default value is defined by the template /etc/ssh/ssh_config.d/{ssh_drop_in_name}.conf . If the system does not have a drop-in directory, the default value is /etc/ssh/ssh_config . if the ssh_user variable is defined, the default value is ~/.ssh/config . ssh_config_owner , ssh_config_group , ssh_config_mode The owner, group and modes of the created configuration file. By default, the owner of the file is root:root , and the mode is 0644 . If ssh_user is defined, the mode is 0600 , and the owner and group are derived from the user name specified in the ssh_user variable. 14.4. Configuring OpenSSH clients using the ssh System Role You can use the ssh System Role to configure multiple SSH clients by running an Ansible playbook. Note You can use the ssh System Role with other System Roles that change SSH and SSHD configuration, for example the Identity Management RHEL System Roles. To prevent the configuration from being overwritten, make sure that the ssh role uses a drop-in directory (default from RHEL 8). Prerequisites Access and permissions to one or more managed nodes , which are systems you want to configure with the ssh System Role. Access and permissions to a control node , which is a system from which Red Hat Ansible Core configures other systems. On the control node: The ansible-core and rhel-system-roles packages are installed. Important RHEL 8.0-8.5 provided access to a separate Ansible repository that contains Ansible Engine 2.9 for automation based on Ansible. Ansible Engine contains command-line utilities such as ansible , ansible-playbook , connectors such as docker and podman , and many plugins and modules. For information about how to obtain and install Ansible Engine, see the How to download and install Red Hat Ansible Engine Knowledgebase article. RHEL 8.6 and 9.0 have introduced Ansible Core (provided as the ansible-core package), which contains the Ansible command-line utilities, commands, and a small set of built-in Ansible plugins. RHEL provides this package through the AppStream repository, and it has a limited scope of support. For more information, see the Scope of support for the Ansible Core package included in the RHEL 9 and RHEL 8.6 and later AppStream repositories Knowledgebase article. An inventory file which lists the managed nodes. Procedure Create a new playbook.yml file with the following content: --- - hosts: all tasks: - name: "Configure ssh clients" include_role: name: rhel-system-roles.ssh vars: ssh_user: root ssh: Compression: true GSSAPIAuthentication: no ControlMaster: auto ControlPath: ~/.ssh/.cm%C Host: - Condition: example Hostname: example.com User: user1 ssh_ForwardX11: no This playbook configures the root user's SSH client preferences on the managed nodes with the following configurations: Compression is enabled. ControlMaster multiplexing is set to auto . The example alias for connecting to the example.com host is user1 . The example host alias is created, which represents a connection to the example.com host the with user1 user name. X11 forwarding is disabled. Optionally, you can modify these variables according to your preferences. For more details, see ssh System Role variables . Optional: Verify playbook syntax. Run the playbook on your inventory file: Verification Verify that the managed node has the correct configuration by opening the SSH configuration file in a text editor, for example: After application of the example playbook shown above, the configuration file should have the following content: 14.5. Using the sshd System Role for non-exclusive configuration Normally, applying the sshd System Role overwrites the entire configuration. This may be problematic if you have previously adjusted the configuration, for example with a different System Role or playbook. To apply the sshd System Role for only selected configuration options while keeping other options in place, you can use the non-exclusive configuration. In RHEL 8 and earlier, you can apply the non-exclusive configuration with a configuration snippet. Prerequisites Access and permissions to one or more managed nodes , which are systems you want to configure with the sshd System Role. Access and permissions to a control node , which is a system from which Red Hat Ansible Core configures other systems. On the control node: The ansible-core package is installed. An inventory file which lists the managed nodes. A playbook for a different RHEL System Role. Procedure Add a configuration snippet with the sshd_config_namespace variable to the playbook: --- - hosts: all tasks: - name: <Configure SSHD to accept some useful environment variables> include_role: name: rhel-system-roles.sshd vars: sshd_config_namespace: <my-application> sshd: # Environment variables to accept AcceptEnv: LANG LS_COLORS EDITOR When you apply the playbook to the inventory, the role adds the following snippet, if not already present, to the /etc/ssh/sshd_config file. # BEGIN sshd system role managed block: namespace <my-application> Match all AcceptEnv LANG LS_COLORS EDITOR # END sshd system role managed block: namespace <my-application> Verification Optional: Verify playbook syntax. Additional resources /usr/share/doc/rhel-system-roles/sshd/README.md file. ansible-playbook(1) man page.
sshd_ListenAddress: - 0.0.0.0 - '::' ListenAddress 0.0.0.0 ListenAddress :: sshd_service_template_service (default: templates/sshd.service.j2) sshd_service_template_at_service (default: templates/sshd@.service.j2) sshd_service_template_socket (default: templates/sshd.socket.j2) sshd: Compression: yes ListenAddress: - 0.0.0.0 sshd_Compression: no cp /usr/share/doc/rhel-system-roles/sshd/example-root-login-playbook.yml path/custom-playbook.yml vim path/custom-playbook.yml --- - hosts: all tasks: - name: Configure sshd to prevent root and password login except from particular subnet include_role: name: rhel-system-roles.sshd vars: sshd: # root login and password login is enabled only from a particular subnet PermitRootLogin: no PasswordAuthentication: no Match: - Condition: "Address 192.0.2.0/24" PermitRootLogin: yes PasswordAuthentication: yes ansible-playbook --syntax-check path/custom-playbook.yml ansible-playbook -i inventory_file path/custom-playbook.yml PLAY RECAP ************************************************** localhost : ok=12 changed=2 unreachable=0 failed=0 skipped=10 rescued=0 ignored=0 ssh user1 @ 10.1.1.1 cat /etc/ssh/sshd_config ... PasswordAuthentication no PermitRootLogin no ... Match Address 192.0.2.0/24 PasswordAuthentication yes PermitRootLogin yes ... hostname -I 192.0.2.1 ssh root@10.1.1.1 LocalForward: - 22 localhost:2222 - 403 localhost:4003 LocalForward 22 localhost:2222 LocalForward 403 localhost:4003 --- - hosts: all tasks: - name: "Configure ssh clients" include_role: name: rhel-system-roles.ssh vars: ssh_user: root ssh: Compression: true GSSAPIAuthentication: no ControlMaster: auto ControlPath: ~/.ssh/.cm%C Host: - Condition: example Hostname: example.com User: user1 ssh_ForwardX11: no ansible-playbook --syntax-check path/custom-playbook.yml ansible-playbook -i inventory_file path/custom-playbook.yml vi ~root/.ssh/config Ansible managed Compression yes ControlMaster auto ControlPath ~/.ssh/.cm%C ForwardX11 no GSSAPIAuthentication no Host example Hostname example.com User user1 --- - hosts: all tasks: - name: <Configure SSHD to accept some useful environment variables> include_role: name: rhel-system-roles.sshd vars: sshd_config_namespace: <my-application> sshd: # Environment variables to accept AcceptEnv: LANG LS_COLORS EDITOR BEGIN sshd system role managed block: namespace <my-application> Match all AcceptEnv LANG LS_COLORS EDITOR END sshd system role managed block: namespace <my-application> ansible-playbook --syntax-check playbook.yml -i inventory_file