SSHD Ansible Role¶

An Ansible role to configure the OpenSSH server (sshd) on Debian-based systems.

Features¶

Configure sshd settings (e.g., port, authentication, logging, session behavior)
Install and manage openssh-server
Lightweight validation (checks sshd configuration syntax before applying)
Support for per-user/group/address SSH configurations using Match blocks

Installation¶

Add the following to your requirements.yml:

roles:
  - name: sshd
    src: https://gitlab.com/niclas-zone/tools/ansible/roles/sshd.git
    version: 1.10.1
    scm: git

Then install:

ansible-galaxy install -r requirements.yml --force

Role Variables¶

Variable	Default Value	Type	Description
`ansible_managed_warning`	`"This file is managed by Ansible. Manual changes will be overwritten."`	string	Text to embed as a header comment when templating files
`ansible_role_repository`	`https://gitlab.com/niclas-zone/tools/ansible/roles/sshd`	string	Repository URL for this role
`sshd_enabled`	`true`	boolean	Whether sshd should be enabled/started
`sshd_include_dir`	`"/etc/ssh/sshd_config.d"`	string	Directory for additional sshd configuration files
`sshd_port`	`22`	integer	Port on which sshd listens
`sshd_address_family`	`"any"`	string	Address family (`any`, `inet`, `inet6`)
`sshd_listen_addresses`	`[]`	list[str]	Specific addresses to bind to (leave empty for defaults)
`sshd_host_keys`	`["/etc/ssh/ssh_host_rsa_key", "/etc/ssh/ssh_host_ecdsa_key", "/etc/ssh/ssh_host_ed25519_key"]`	list[str]	Host key files to load (leave empty for commented defaults)
`sshd_syslog_facility`	`"AUTH"`	string	Facility for syslog logging
`sshd_log_level`	`"INFO"`	string	Logging level
`sshd_login_grace_time`	`"60"`	string	Time allowed for login before disconnect
`sshd_permit_root_login`	`"no"`	string	Permit root login (`no`, `prohibit-password`, `yes`)
`sshd_strict_modes`	`true`	boolean	Enable strict mode checking of home directory and files
`sshd_max_auth_tries`	`2`	integer	Maximum authentication attempts
`sshd_max_sessions`	`10`	integer	Maximum number of open sessions
`sshd_password_authentication`	`true`	boolean	Enable/disable password authentication
`sshd_pubkey_authentication`	`true`	boolean	Enable/disable public key authentication
`sshd_kbd_interactive_authentication`	`false`	boolean	Enable/disable keyboard-interactive authentication
`sshd_permit_empty_passwords`	`false`	boolean	Permit empty passwords
`sshd_allow_users`	`root`	list[str]	List of users allowed to SSH (leave empty for all users)
`sshd_deny_users`	`[]`	list[str]	List of users denied SSH access
`sshd_authorized_keys_file`	`[".ssh/authorized_keys"]`	list[str]	Paths to authorized keys files
`sshd_authorized_principals_file`	`"none"`	string	Path to authorized principals file
`sshd_authorized_keys_command`	`"none"`	string	Command to retrieve authorized keys
`sshd_authorized_keys_command_user`	`"nobody"`	string	User to run the authorized keys command
`sshd_hostbased_authentication`	`false`	boolean	Enable/disable host-based authentication
`sshd_ignore_user_known_hosts`	`false`	boolean	Ignore user known hosts
`sshd_ignore_rhosts`	`true`	boolean	Ignore `.rhosts` and `.shosts` files
`sshd_kerberos_authentication`	`false`	boolean	Enable/disable Kerberos authentication
`sshd_kerberos_or_local_passwd`	`true`	boolean	Use Kerberos or local password
`sshd_kerberos_ticket_cleanup`	`true`	boolean	Clean up Kerberos tickets
`sshd_kerberos_get_afs_token`	`false`	boolean	Get AFS token when Kerberos is used
`sshd_gssapi_authentication`	`false`	boolean	Enable/disable GSSAPI authentication
`sshd_gssapi_cleanup_credentials`	`true`	boolean	Clean up GSSAPI credentials
`sshd_gssapi_strict_acceptor_check`	`true`	boolean	Enable strict acceptor checking for GSSAPI
`sshd_gssapi_key_exchange`	`false`	boolean	Enable/disable GSSAPI key exchange
`sshd_use_pam`	`true`	boolean	Enable/disable PAM authentication
`sshd_disable_forwarding`	`true`	boolean	Disable all forwarding features (X11, agent, TCP, StreamLocal)
`sshd_allow_agent_forwarding`	`true`	boolean	Enable/disable agent forwarding
`sshd_allow_tcp_forwarding`	`true`	boolean	Enable/disable TCP forwarding
`sshd_gateway_ports`	`false`	boolean	Enable/disable gateway ports
`sshd_x11_forwarding`	`true`	boolean	Enable/disable X11 forwarding
`sshd_x11_display_offset`	`10`	integer	X11 display offset
`sshd_x11_use_localhost`	`true`	boolean	Use localhost for X11 forwarding
`sshd_permit_tty`	`true`	boolean	Permit TTY
`sshd_print_motd`	`false`	boolean	Print MOTD
`sshd_print_last_log`	`true`	boolean	Print last login
`sshd_tcp_keep_alive`	`true`	boolean	Enable/disable TCP keep-alive
`sshd_permit_user_environment`	`false`	boolean	Permit user environment variables
`sshd_client_alive_interval`	`15`	integer	Interval for client alive messages
`sshd_client_alive_count_max`	`3`	integer	Maximum number of client alive messages
`sshd_use_dns`	`false`	boolean	Enable/disable DNS lookups
`sshd_rekey_limit`	`"default none"`	string	Rekey limit
`sshd_pid_file`	`"/run/sshd.pid"`	string	Path to PID file
`sshd_max_startups`	`"10:30:60"`	string	Maximum startups
`sshd_permit_tunnel`	`false`	boolean	Permit tunneling
`sshd_chroot_directory`	`"none"`	string	Chroot directory
`sshd_version_addendum`	`"none"`	string	Version addendum
`sshd_banner`	`"/etc/issue.net"`	string	Path to banner file
`sshd_compression`	`"delayed"`	string	Compression setting
`sshd_accept_env`	see below	list[str]	Environment variables to accept from the client
`sshd_subsystem_sftp`	`"/usr/lib/openssh/sftp-server"`	string	Path to the SFTP subsystem
`sshd_match_blocks`	`[]`	list[dict]	Per-user/group/address SSH configurations using Match blocks
`sshd_allow_users`	`["root"]`	list[str]	Users allowed SSH access (leave empty to allow all users)
`sshd_deny_users`	`[]`	list[str]	Users denied SSH access
`sshd_kex_algorithms`	see below	list[str]	Key exchange algorithms (hardened defaults)
`sshd_ciphers`	see below	list[str]	Ciphers for encryption (hardened defaults)
`sshd_macs`	see below	list[str]	Message authentication codes (hardened defaults)

Default Cryptographic Algorithms¶

The role includes hardened defaults for cryptographic algorithms:

sshd_kex_algorithms:
  - "curve25519-sha256@libssh.org"
  - "ecdh-sha2-nistp521"
  - "ecdh-sha2-nistp384"
  - "ecdh-sha2-nistp256"
  - "diffie-hellman-group-exchange-sha256"

sshd_ciphers:
  - "chacha20-poly1305@openssh.com"
  - "aes256-gcm@openssh.com"
  - "aes128-gcm@openssh.com"
  - "aes256-ctr"
  - "aes192-ctr"
  - "aes128-ctr"

sshd_macs:
  - "hmac-sha2-512-etm@openssh.com"
  - "hmac-sha2-256-etm@openssh.com"
  - "hmac-sha2-512"
  - "hmac-sha2-256"

Default Environment Variables¶

sshd_accept_env:
  - "LANG"
  - "LC_*"
  - "COLORTERM"
  - "NO_COLOR"

Per-User/Group/Address Configurations¶

The sshd_match_blocks variable allows you to define SSH configurations that apply only to specific users, groups, or addresses. Each block is a dictionary with:

name: (required) A descriptive comment for the Match block
match: (required) The Match criteria (e.g., User, Group, Address, or combinations)
settings: (required) A dictionary of SSH settings to apply for this Match block

Example Playbooks¶

Basic: configure sshd with defaults¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd

Custom sshd settings¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        sshd_port: 2222
        sshd_permit_root_login: "prohibit-password"
        sshd_password_authentication: false
        sshd_pubkey_authentication: true
        sshd_max_auth_tries: 3
        sshd_max_sessions: 5
        sshd_x11_forwarding: false

Minimal configuration (disable password authentication)¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        sshd_password_authentication: false
        sshd_pubkey_authentication: true

Per-user SSH configurations¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        # Global settings
        sshd_permit_root_login: "no"
        sshd_password_authentication: false

        # Per-user/group/address overrides using Match blocks
        sshd_match_blocks:
          # Restrict root login from a specific IP
          - name: "Restrict root login from admin host"
            match: "Address 10.0.2.31"
            settings:
              PermitRootLogin: "yes"

          # Allow password authentication for specific user from subnet
          - name: "Allow password auth for admin user"
            match: "User admin Address 10.0.2.*"
            settings:
              PasswordAuthentication: "yes"

          # Allow password authentication only for specific group
          - name: "Allow password for system administrators group"
            match: "Group sysadmin"
            settings:
              PasswordAuthentication: "yes"

          # Restrict port forwarding for specific users
          - name: "Disable forwarding for guest users"
            match: "User guest"
            settings:
              AllowTcpForwarding: "no"
              AllowAgentForwarding: "no"

Advanced: Combining Match blocks with different conditions¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        sshd_match_blocks:
          # subnet role
          - name: "Allow root from internal subnet with key-only auth"
            match: "User root Address 192.168.0.*"
            settings:
              PermitRootLogin: "prohibit-password"
              PasswordAuthentication: "no"

          # Group Specific role
          - name: "Service account configuration"
            match: "Group service-accounts"
            settings:
              AllowTcpForwarding: "yes"
              X11Forwarding: "no"
              PermitTTY: "no"
              ForceCommand: "internal-sftp"

User Access Control: Allow and Deny specific users¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        # Method 1: Allow only specific users
        sshd_allow_users:
          - vivek
          - jerry
          - admin

        # Method 2: Deny specific users (allow all others)
        # sshd_deny_users:
        #   - root
        #   - saroj
        #   - guest

User Access Control: Restrict SSH with patterns¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        # Allow users and patterns (wildcards supported)
        sshd_allow_users:
          - admin
          - "user*"  # Allow user1, user2, user3, etc.
          - "@admins"  # Allow users in the 'admins' group

        # Deny specific users and patterns
        sshd_deny_users:
          - root
          - "test*"  # Deny test1, test2, test3, etc.
          - "guest*"

Cryptographic hardening with custom algorithms¶

---
- hosts: servers
  become: true
  roles:
    - role: sshd
      vars:
        # Use stricter cryptographic algorithms
        sshd_kex_algorithms:
          - "curve25519-sha256@libssh.org"
          - "curve25519-sha256"

        sshd_ciphers:
          - "chacha20-poly1305@openssh.com"
          - "aes256-gcm@openssh.com"

        sshd_macs:
          - "hmac-sha2-512-etm@openssh.com"
          - "hmac-sha2-256-etm@openssh.com"