Ansible collection: foundata.sshd

Die Ansible-Collection foundata.sshd stellt Ressourcen zur Verwaltung und Nutzung des OpenSSH Secure-Shell-Daemons (sshd) bereit, des vermutlich weltweit am häufigsten eingesetzte SSH (Secure Shell)-Servers.

Die folgenden Abschnitte listen die README.md-Dateien der wichtigsten enthaltenen Inhalte (z. B. Rollen) auf. Für einen umfassenderen Überblick empfiehlt sich ein Blick in die Quellcode-Repositories.

Ansible role: foundata.sshd.run

The foundata.sshd.run Ansible role (part of the foundata.sshd Ansible collection). It provides automated configuration management of sshd, implementing security best practices by default across major platforms.

Features

Main features:

• Sane defaults:
  • Modern cryptography.
  • Extended Logging.
  • Key-based authentication, no password based root login
  • Disabled Kerberos and GSSAPI (easy to re-enable but quite often not needed by default).
  • See __run_sshd_service_settings_defaults in ./vars/main.yml for a complete list.
• Default configuration result passes ssh-audit without errors or warnings.
• Simple to use: extend or adapt / overwrite the role’s default configuration with a simple dictionary.

Example playbooks, using this role

Installation with automatic upgrade:

---

- name: "Initialize the foundata.sshd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.sshd.run role"
      ansible.builtin.include_role:
        name: "foundata.sshd.run"
      vars:
        run_sshd_autoupgrade: true

Installation with custom configuration options (e.g., GatewayPorts: false) and an override of the role’s default setting for GSSAPIAuthentication and Port:

---

- name: "Initialize the foundata.sshd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.sshd.run role"
      ansible.builtin.include_role:
        name: "foundata.sshd.run"
      vars:
        run_sshd_autoupgrade: true
        run_sshd_service_settings:
          Port: 2222
          GatewayPorts: false
          GSSAPIAuthentication: true

Uninstall (⚠️ Warning: This will remove SSH access from the target machines!)

---

- name: "Initialize the foundata.sshd.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.sshd.run role"
      ansible.builtin.include_role:
        name: "foundata.sshd.run"
      vars:
        run_sshd_state: "absent"

Supported tags

It might be useful and faster to only call parts of the role by using tags:

• run_sshd_setup: Manage basic resources, such as packages or service users.
• run_sshd_config: Manage settings, such as adapting or creating configuration files.
• run_sshd_service: Manage services and daemons, such as running states and service boot configurations.

There are also tags usually not meant to be called directly but listed for the sake of completeness** and edge cases:

• run_sshd_always, always: Tasks needed by the role itself for internal role setup and the Ansible environment.

Role variables

The following variables can be configured for this role:

run_sshd_state

⇑ Back to ToC ⇑

Determines whether the managed resources should be present or absent.

present ensures that required components, such as software packages, are installed and configured.

absent reverts changes as much as possible, such as removing packages, deleting created users, stopping services, restoring modified settings, …

• Type: str
• Required: No
• Default: "present"
• Choices: present, absent

run_sshd_autoupgrade

⇑ Back to ToC ⇑

If set to true, all managed packages will be upgraded during each Ansible run (e.g., when the package provider detects a newer version than the currently installed one).

• Type: bool
• Required: No
• Default: false

run_sshd_service_state

⇑ Back to ToC ⇑

Defines the status of the service(s).

enabled: Service is running and will start automatically at boot.

disabled: Service is stopped and will not start automatically at boot.

running Service is running but will not start automatically at boot. This can be used to start a service on the first Ansible run without enabling it for boot.

unmanaged: Service will not start at boot, and Ansible will not manage its running state. This is primarily useful when services are monitored and managed by systems other than Ansible.

The singular form (service) is used for simplicity. However, the defined status applies to all services if multiple are being managed by this role.

• Type: str
• Required: No
• Default: "enabled"
• Choices: enabled, disabled, running, unmanaged

run_sshd_service_settings

⇑ Back to ToC ⇑

sshd service configuration values (additional ones or to overwrite defaults; see __run_sshd_service_settings_defaults in vars/main.yml for them).

Simply use standard SSH option names as keys with their corresponding values. Special cases:

• For boolean values, use true/false (these will be converted to “yes”/“no” strings by the role as needed).

• For options that can have multiple values, you can use a list:

  HostKey:
    - "/etc/ssh/ssh_host_ed25519_key"
    - "/etc/ssh/ssh_host_ecdsa_key"
  

  This will generate multiple entries in the config file, one per list item.

• Type: dict

• Required: No

• Default: {}

run_sshd_config_service_dropin_file_name

⇑ Back to ToC ⇑

Filename of the drop-in configuration file to be placed in /etc/ssh/sshd_config.d. Defaults to 00-managed.conf. The 00- prefix ensures early loading and thus higher precedence over files with higher-numbered prefixes.

If a non-default filename is used, any existing /etc/ssh/sshd_config.d/00-managed.conf from previous Ansible runs will be removed automatically to prevent conflicts.

• Type: str
• Required: No
• Default: "00-managed.conf"

Dependencies

See dependencies in meta/main.yml.

Compatibility

See min_ansible_version in meta/main.yml and __run_sshd_supported_platforms in vars/main.yml.

External requirements

• SELinux: This role does not handle SELinux configurations. Please add additional tasks before or after this role to accommodate these changes (e.g. if you’re changing SSH port on a system with SELinux enabled, allowing it via ssh_port_t is needed). The following Ansible modules may help with SELinux configuration:
  • ansible.posix.selinux
  • community.general.sefcontext_module
  • community.general.seport_module
• Firewall: This role does not manage firewall configurations. Please add additional tasks before or after this role to configure firewall rules as needed to access your SSH service.

Beside that, there are no special requirements not covered by the role or Ansible itself.