194 lines
6.6 KiB
Markdown
194 lines
6.6 KiB
Markdown
# Fail2ban
|
||
|
||
Role which installs and configures Fail2ban.
|
||
|
||
## Role usage
|
||
|
||
The role should be used after other roles installing software which needs protection.
|
||
|
||
## Deploy example (do not copy blindly!)
|
||
|
||
```yaml
|
||
roles:
|
||
- role: fail2ban
|
||
fail2ban_ignores_ips: ['10.0.0.0/8']
|
||
fail2ban_enable_ignorecommand: true
|
||
fail2ban_custom_ipset_lists: [whitelist, whitelist6]
|
||
fail2ban_recidive_ignore_jails: [some-jail, another-jail]
|
||
fail2ban_filters: [
|
||
{ name: nginx-req-limits,
|
||
failregex: [ '^\s*\[error\] \d+#\d+: \*\d+ limiting requests, excess: [\d\.]+ by zone "[^"]+", client: <HOST>' ],
|
||
ignoreregex: []
|
||
},
|
||
{ name: nginx-con-limits,
|
||
failregex: [ '^\s*\[error\] \d+#\d+: \*\d+ limiting connections by zone "[^"]+", client: <HOST>' ],
|
||
ignoreregex: []
|
||
},
|
||
{ name: multiple-regexps-example,
|
||
failregex: [ 'some-fail-regexp1', 'some-fail-regexp2' ],
|
||
ignoreregex: [ 'some-ignore-regexp1', 'some-ignore-regexp2' ]
|
||
}
|
||
]
|
||
fail2ban_sshd:
|
||
maxretry: 5
|
||
bantime: 3600
|
||
findtime: 600
|
||
fail2ban_services: [
|
||
{ name: nginx-req-limits,
|
||
filter: nginx-req-limits,
|
||
port: 'http,https',
|
||
logpath: '/var/log/nginx/*error.log',
|
||
bantime: 600,
|
||
findtime: 300,
|
||
maxretry: 5
|
||
},
|
||
{ name: nginx-con-limits,
|
||
filter: nginx-con-limits,
|
||
port: 'http,https',
|
||
logpath: '/var/log/nginx/*error.log',
|
||
bantime: 600,
|
||
findtime: 300,
|
||
maxretry: 5
|
||
}
|
||
]
|
||
fail2ban_containers: [
|
||
{ name: web-prod,
|
||
logpath: /tmp/web-prod.log
|
||
},
|
||
{ name: backend-prod,
|
||
logpath: /tmp/backend-prod.log,
|
||
bantime: 9000
|
||
}
|
||
]
|
||
```
|
||
|
||
## About available parameters
|
||
|
||
### Main params
|
||
|
||
| Param | Default | Description |
|
||
| -------- | -------- | -------- |
|
||
| `fail2ban_setup` | `full` | - |
|
||
| `fail2ban_defaults` | see defaults/main.yml | controls default bantime, findtime and maxretry params |
|
||
| `fail2ban_ignores_ips` | - | controls list of IP's to ignore (see ignoreip fail2ban param) |
|
||
| `fail2ban_alerts` | see defaults/main.yml | control on alert-sending, just in case if we'll need it anywhere |
|
||
| `fail2ban_filters` | - | describes the filters to create, more details below |
|
||
| `fail2ban_services` | - | describes the custom jails to create, more details below |
|
||
| `fail2ban_containers` | - | params for sshd-jails for LXC containers, more details below |
|
||
| `fail2ban_blocktype` | `DROP` | we want to drop packets instead of rejecting them. Do not change this without a reason |
|
||
| `fail2ban_role_test_mode` | - | could be used for test purposes only, do not use it in production playbooks |
|
||
| `fail2ban_enable_ignorecommand` | `false` | enables ignorecommand options in jail.local and checking script generation |
|
||
| `fail2ban_default_ipset_lists` | `[whitelist, whitelist6]` | describes the default ipset lists for checking script |
|
||
| `fail2ban_custom_ipset_lists` | `[]` | describes the custom ipset lists for checking script |
|
||
| `fail2ban_dummy_logs` | `false` | Whether to create dummy logs to avoid service failing to start due to absence of any jail logs. |
|
||
| `fail2ban_dummy_log_path` | `/var/log/fail2ban-dummy.log` | Path to dummy log (will be automatically created). |
|
||
| `fail2ban_recidive_ignore_jails` | `[]` | List of jails that need to be ignored by recidive jail. |
|
||
|
||
### Jail generation
|
||
|
||
#### SSH jails
|
||
|
||
Our common sshd jail is generated automatically if openssh-server package was found during role setup. By default it will look like this:
|
||
|
||
```plaintext
|
||
[sshd]
|
||
enabled = true
|
||
ports = 22
|
||
maxretry = 3
|
||
bantime = 7200
|
||
findtime = 1800
|
||
```
|
||
|
||
If needed, default params for this jail could be overwritten from playbook with **fail2ban_sshd** variable, for example:
|
||
|
||
#### SSH jails for LXC containers
|
||
|
||
```yaml
|
||
fail2ban_sshd:
|
||
maxretry: 5
|
||
bantime: 3600
|
||
findtime: 600
|
||
```
|
||
|
||
Jails for LXC containers are being created only if **fail2ban_containers** list is not empty. You can control any param of this jail from playbook, for example:
|
||
|
||
```yaml
|
||
fail2ban_containers: [
|
||
{ name: web-prod,
|
||
logpath: /mnt/data/containers/web-prod/var/log/auth.log.log
|
||
},
|
||
{ name: backend-prod,
|
||
logpath: /mnt/data/containers/backend-prod/var/log/auth.log,
|
||
bantime: 9000,
|
||
findtime: 600
|
||
}
|
||
]
|
||
```
|
||
|
||
Make sure to set "logpath" variable, role can't guess the correct path by itself!
|
||
|
||
#### Custom jails
|
||
|
||
Could be created with **services** list, usage example:
|
||
|
||
```yaml
|
||
fail2ban_services: [
|
||
{ name: nginx-req-limits,
|
||
filter: nginx-req-limits,
|
||
port: 'http,https',
|
||
logpath: '/var/log/nginx/*error.log',
|
||
bantime: 600,
|
||
findtime: 300,
|
||
maxretry: 5
|
||
},
|
||
{ name: nginx-con-limits,
|
||
filter: nginx-con-limits,
|
||
port: 'http,https',
|
||
logpath: '/var/log/nginx/*error.log',
|
||
bantime: 600,
|
||
findtime: 300,
|
||
maxretry: 5
|
||
}
|
||
]
|
||
```
|
||
|
||
You can describe any key-value pairs here. **name** is mandatory for jail creation.
|
||
|
||
### Custom filters creation
|
||
|
||
Can be done with **filters** variable. For example:
|
||
|
||
```yaml
|
||
fail2ban_filters: [
|
||
{ name: nginx-req-limits,
|
||
failregex: [ '^\s*\[error\] \d+#\d+: \*\d+ limiting requests, excess: [\d\.]+ by zone "[^"]+", client: <HOST>' ],
|
||
ignoreregex: []
|
||
},
|
||
{ name: nginx-con-limits,
|
||
failregex: [ '^\s*\[error\] \d+#\d+: \*\d+ limiting connections by zone "[^"]+", client: <HOST>' ],
|
||
ignoreregex: []
|
||
},
|
||
{ name: multiple-regexps-example,
|
||
failregex: [ 'some-fail-regexp1', 'some-fail-regexp2' ],
|
||
ignoreregex: [ 'some-ignore-regexp1', 'some-ignore-regexp2' ]
|
||
}
|
||
]
|
||
```
|
||
|
||
You can describe any key-value pairs here. **name** is mandatory for filter creation.
|
||
|
||
### Checking ip in ipset lists
|
||
|
||
Fail2ban can use external command to dynamically check if IP should be ingored. Option fail2ban_enable_ignorecommand enables it. External script will check the IP’s presence in every ipset list from fail2ban_default_ipset_lists and fail2ban_custom_ipset_lists. If IP will be found in any list given - fail2ban will ignore it, if not - IP will be placed in appropriate jail.
|
||
|
||
## Useful links
|
||
|
||
- [Official wiki](https://www.fail2ban.org/wiki/index.php/Main_Page)
|
||
- [Documentation on ubuntu.ru](https://help.ubuntu.ru/wiki/fail2ban)
|
||
|
||
## TODO
|
||
|
||
- update readme
|
||
- remove syslog user creation (leave in test mode only maybe)
|
||
- move names and paths from check_ip_script template to vars
|