diff --git a/README.md b/README.md index 7fe5160..f93ea1d 100644 --- a/README.md +++ b/README.md @@ -79,78 +79,6 @@ fail2ban_jail_configuration: This format allows you to set any fail2ban configuration option without modifying the role itself. -### Debian-Specific Configuration - -#### SSH Service Name Issue - -On Debian systems, there's a common issue where fail2ban's default SSH jail doesn't work out of the box. The problem: - -- fail2ban's default configuration expects the service to be named `sshd` -- On many Debian systems, the actual systemd service is named `ssh.service` (not `sshd.service`) -- When using the `systemd` backend, fail2ban looks for logs from the `sshd` service and finds nothing -- Result: **SSH protection silently fails** - no errors, but no banning occurs - -#### The Solution - -This role provides the `fail2ban_default_debian_jail_configuration` variable to override Debian's default jail settings: -```yaml -fail2ban_default_debian_jail_configuration: - - option: backend - value: systemd - section: sshd - - option: journalmatch - value: "_SYSTEMD_UNIT=ssh.service" # Use ssh.service instead of sshd.service - section: sshd -``` - -This configuration: -- Explicitly sets the backend to `systemd` for better performance -- Corrects the journal match to look for `ssh.service` instead of the default `sshd.service` -- Is applied only on Debian systems (via `when: ansible_facts['distribution'] == 'Debian'`) - -#### Usage Example -```yaml -- hosts: debian_servers - become: yes - roles: - - role: fail2ban - vars: - fail2ban_backend: systemd - - # Fix SSH jail on Debian - fail2ban_default_debian_jail_configuration: - - option: backend - value: systemd - section: sshd - - option: journalmatch - value: "_SYSTEMD_UNIT=ssh.service" - section: sshd - - fail2ban_jails: - - name: sshd - enabled: true - maxretry: 3 - bantime: 1h -``` - -> [!NOTE] This only affects the default SSH jail in `/etc/fail2ban/jail.d/defaults-debian.conf`. If you're defining custom SSH jails using `fail2ban_jails`, make sure to specify the correct `journalmatch` or `logpath` for your system. - -#### Verifying SSH Protection is Working - -After applying the role, verify fail2ban is monitoring SSH: -```bash -# Check if the sshd jail is active -sudo fail2ban-client status sshd - -# Check what logs fail2ban is monitoring -sudo fail2ban-client get sshd logpath - -# Test with a failed login and check -sudo fail2ban-client status sshd -``` - -If you see "Currently banned: 0" and "Total banned: 0" after several failed login attempts, the jail may not be configured correctly for your system's SSH service name. - ### Creating Custom Jails #### Method 1: Define Jails as Dictionaries (Recommended for Simple Jails) @@ -343,6 +271,79 @@ The role uses the `ini_file` module to edit the default configuration files. You ``` +## Debian-Specific Configuration + +### SSH Service Name Issue + +On Debian systems, there's a common issue where fail2ban's default SSH jail doesn't work out of the box. The problem: + +- fail2ban's default configuration expects the service to be named `sshd` +- On many Debian systems, the actual systemd service is named `ssh.service` (not `sshd.service`) +- When using the `systemd` backend, fail2ban looks for logs from the `sshd` service and finds nothing +- Result: **SSH protection silently fails** - no errors, but no banning occurs + +### The Solution + +This role provides the `fail2ban_default_debian_jail_configuration` variable to override Debian's default jail settings: +```yaml +fail2ban_default_debian_jail_configuration: + - option: backend + value: systemd + section: sshd + - option: journalmatch + value: "_SYSTEMD_UNIT=ssh.service" # Use ssh.service instead of sshd.service + section: sshd +``` + +This configuration: +- Explicitly sets the backend to `systemd` for better performance +- Corrects the journal match to look for `ssh.service` instead of the default `sshd.service` +- Is applied only on Debian systems (via `when: ansible_facts['distribution'] == 'Debian'`) + +### Usage Example +```yaml +- hosts: debian_servers + become: yes + roles: + - role: fail2ban + vars: + fail2ban_backend: systemd + + # Fix SSH jail on Debian + fail2ban_default_debian_jail_configuration: + - option: backend + value: systemd + section: sshd + - option: journalmatch + value: "_SYSTEMD_UNIT=ssh.service" + section: sshd + + fail2ban_jails: + - name: sshd + enabled: true + maxretry: 3 + bantime: 1h +``` + +> [!NOTE] +> This only affects the default SSH jail in `/etc/fail2ban/jail.d/defaults-debian.conf`. If you're defining custom SSH jails using `fail2ban_jails`, make sure to specify the correct `journalmatch` or `logpath` for your system. + +### Verifying SSH Protection is Working + +After applying the role, verify fail2ban is monitoring SSH: +```bash +# Check if the sshd jail is active +sudo fail2ban-client status sshd + +# Check what logs fail2ban is monitoring +sudo fail2ban-client get sshd logpath + +# Test with a failed login and check +sudo fail2ban-client status sshd +``` + +If you see "Currently banned: 0" and "Total banned: 0" after several failed login attempts, the jail may not be configured correctly for your system's SSH service name. + ## Role Tasks This role performs the following tasks: