Update README.md
This commit is contained in:
145
README.md
145
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:
|
||||
|
||||
Reference in New Issue
Block a user