ANXS - openssh
Ansible role for installing and configuring the OpenSSH client and server. Ships with hardened defaults (public-key only, no root login, modern key exchange and MAC algorithms) and generates ed25519 and ECDSA host keys on first run. Per-distribution overrides handle algorithm differences across OpenSSH versions.
- Ansible 2.12 or higher.
- Ubuntu 20.04+ or Debian 12+.
SSH server and client configuration is managed by the semi free-form dicts, which allow you to set any OpenSSH variable. A default (per-OS) set is provided, and this maybe partially, or fully, overrriden.
openssh_server_settingsServer defaults that overridesshd_configoptions.openssh_client_settingsClient defaults that overridessh_configoptions.openssh_hostkey_types(defaults to["ecdsa", "ed25519"]) list of host key types to generate.openssh_enable_config_includes(defaults tofalse) emit anIncludefor/etc/ssh/sshd_config.d/*.conf. See Drop-in configuration before enabling it.openssh_config_includes_path(defaults to/etc/ssh/sshd_config.d/*.conf) glob used by thatInclude.
By default this role writes an sshd_config with no Include directive, so
files under /etc/ssh/sshd_config.d/ are not read. Anything another role drops
there is inert: the file is present, has the content you expect, passes
sshd -t, and changes nothing. Setting openssh_enable_config_includes: true
emits the Include and makes those files live.
Enabling the Include activates every file already in that directory
on the target host, not just the one you happen to care
about. sshd_config(5): "for each keyword, the first obtained value
will be used". The role therefore renders the Include as the
first directive in the file. An Include appended below the
role's global settings is outvoted by every keyword the role sets.
OpenSSH ANDs the sshd_config PermitListen list with the
permitlisten= list in authorized_keys (check_rfwd_permission()
in channels.c), so a Match User block that names one forwarded
port will refuse every other port that user forwards the moment the
Include goes live. Reverse tunnels a potential casualty, and the
symptom looks like a client fault rather than a config change. Check
any Match blocks in sshd_config.d/ against what those users
actually forward.
Both config tasks validate the candidate file before it is installed, so a bad value fails the play instead of breaking the host:
sshd_configis checked with/usr/sbin/sshd -t -f %s. Without this, an unparseable config is written and the service is signalled, and on a host reached only over ssh that is the host.ssh_configis checked with/usr/bin/ssh -G -F %s <placeholder>. There is no daemon to notify for the client config, but an unparseablessh_configbreaks every outboundssh,scpandrsyncon the host, Ansible's own connections included.ssh -Gonly parses and prints;-Fmakes it read the candidate file alone, and no network traffic is generated.
sshd -t is not a pure parser: it refuses to run without a loadable host key
or the privilege separation directory. Host keys are therefore generated, and
/run/sshd created, before either config is templated.
Before writing either config, the role checks the managed service lifecycle.
An inactive ssh.service with any extant sshd process is refused: starting
another daemon would collide with the existing listener, while a failed start
can remove /run/sshd and leave that listener accepting connections it cannot
authenticate. An inactive service with no sshd process is started normally.
A server config change is followed immediately by a strict systemctl reload ssh.service. This intentionally does not use Ansible's state: reloaded,
which starts an inactive unit and can turn a reload into a competing listener.
On Debian and Ubuntu, ExecReload runs /usr/sbin/sshd -t before signalling
the daemon, so a bad config aborts while the previous config remains live.
Reload also keeps established sessions. Directives read only at startup --
Port, ListenAddress, and AddressFamily -- are not picked up by a
reload; a Restart ssh handler remains available for explicit callers.
Notable server defaults out of the box:
PermitRootLogin: "no",PasswordAuthentication: "no",PubkeyAuthentication: "yes"- Only SHA-2 and ETM MACs (no hmac-md5, no hmac-sha1)
- KexAlgorithms limited to curve25519 and DH group16/18
- Certificate-aware HostKeyAlgorithms with ed25519 preferred
Tests use Molecule with Docker
and Testinfra. Run the full suite
with make test, or target a specific platform (e.g. make test-ubuntu2404).
The test suite verifies package installation, config file permissions,
absence of deprecated SSHv1-era options, modern security settings,
rejection of weak MACs, host key generation, and sshd -t config
validation. Tests run across Ubuntu 20.04, 22.04, 24.04, and Debian
12, 13.
Drop-in behaviour is checked by asking sshd what it resolved rather than by
reading files, because the inert-drop-in defect is invisible to a file-content
assertion by construction -- the drop-in is correct either way, it just is not
read. The scenario writes a probe drop-in with a Match User block, then
asserts that sshd -T -C user=... does not reflect it with the role's
defaults, and does reflect it once the Include is enabled. The connection
spec passed to -C is complete (user, host, addr): sshd only evaluates
Match blocks for a complete spec, so an incomplete one silently reports
global values and would make the test pass for the wrong reason. The converge
also asserts that the Include is rendered first rather than merely present,
that validate: refuses a deliberately broken config without writing it or
notifying the handler, and that ExecReload validates before signalling.
This project has been developed with AI assistance. Contributions making use of AI generated content are welcome, however they must be human reviewed prior to submission as pull requests, or issues. All contributors must be able to fully explain and defend any AI generated code, documentation, issues, or tests they submit. Contributions making use of AI must have this explicitly declared in the pull request or issue. This also applies to utilization of AI for reviewing of pull requests.
Are all welcome!