DEBOPS.FAIL2BAN(5)

NAME
debops.fail2ban - Manage fail2ban service using Ansible

SYNOPSIS

debops service/fail2ban [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

fail2ban <https://www.fail2ban.org/> is a service which parses specified log files and can perform configured actions when a given regexp <https://en.wikipedia.org/wiki/Regular_expression> is found. It's usually used to ban offending IP addresses using iptables rules (only IPv4 connections are supported at the moment).

GETTING STARTED

When fail2ban is installed, an ssh jail will be configured by default (by the Debian package, not DebOps).

debops.fail2ban role uses iptables recent module instead of adding the banned hosts to the firewall directly. The recent rule will be added to the INPUT chain at specific location, to work seamlessly with the default firewall configuration managed by debops.ferm role. If necessary, you can specify the location of the rules using custom item.position parameter.

  Example inventory

To enable fail2ban you can add a host or several hosts to [debops_service_fail2ban] group:

[debops_service_fail2ban]
hostname

If you have many hosts which you want to protect using fail2ban, you can instead create a child group and add it to the [debops_service_fail2ban] parent group:

[debops_service_fail2ban:children]
protected_hosts
[protected_hosts]
host1
host2
host3

To manage jails, you use fail2ban_*_jails list variables by adding them in group_vars/ or host_vars/ directories. For example, to disable the ssh jail by default on all hosts, create inventory/group_vars/all/fail2ban.yml file and add inside:

---
fail2ban_jails:
  - name: 'ssh'
    enabled: 'false'
    comment: 'Disable default ssh jail'

  Example playbook

Here's an example playbook which uses debops.fail2ban role to install fail2ban:

---
- name: Install fail2ban
  hosts: [ 'debops_service_fail2ban' ]
  roles:
    - role: fail2ban
      tags: [ 'role::fail2ban', 'skip::fail2ban' ]

DEFAULT VARIABLES: CONFIGURATION

some of debops.fail2ban default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  fail2ban_actions

List of local fail2ban actions that should be present or absent when configuring fail2ban. Each action is defined as a YAML dict with the following keys:

name
    Required. Name of the filter.

ban Required. Command executed when banning an IP. Take care that the command is executed with fail2ban user rights.

check
    Optional. Command executed once before each ban command.

filename
    Optional. Alternative name of the action configuration file.

start
    Optional. Command executed once at the start of fail2ban.

state
    Optional. If present, the action will be created when configuring fail2ban. If absent, the action will be removed when configuring fail2ban.

stop
    Optional. Command executed once at the end of fail2ban.

unban
    Optional. Command executed when unbanning an IP. Take care that the command is executed with fail2ban user rights.

  fail2ban_filters

List of local fail2ban filters that should be present or absent when configuring fail2ban. Each filter is defined as a YAML dict with the following keys:

name
    Required. Name of the filter.

after
    Optional. Specify an additional filter configuration file that fail2ban will read after reading this filter configuration filer.

before
    Optional. Specify an additional filter configuration file that fail2ban will read before reading this filter configuration file.

definitions
    Optional. Custom definitions used by the filter.

failregex
    Required. A string of regular expression(s) used by the filter to detect break-in attempts. You can have the filter try to match multiple regular expressions by using the | character (the YAML literal style operator). Each regular expression should be on its own line. Refer to the examples section.

filename
    Optional. Alternative name of the filter configuration file. If not specified, it will use the name of the filter.

ignoreregex
    Optional. Regular expression(s) used to filter out invalid break-in attempts. You can have the filter try to match multiple regular expressions. Each regular expression should be on its own line.

state
    Optional. If present, the filter will be created when configuring fail2ban. If absent, the filter will be removed when configuring fail2ban.

    Refer to the fail2ban filter wiki <https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Filters> for more information.

  fail2ban_jails

Jails are defined in the form of dicts, where dict keys are the option names and dict values are option values. You can specify values either as strings or YAML lists, in which case elements of the list will be separated by commas.

Some keys have a special meaning:

name
    Jail name, used as a section header and part of the filename. Required.

filename
    Alternative file name, optional.

comment
    A commented text added before the given jail

delete
    If this option is present and True, file which defines a given jail will be deleted

ignoreip
    List of IP addresses or CIDR subnets which should be ignored by fail2ban

action
    It should be a name of a default or custom action, which will be used by fail2ban

    Other options are the same as normal fail2ban jail configuration options. Refer to default /etc/fail2ban/jail.conf or fail2ban wiki <https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Jails> for possible options.

  Examples:

Jails

Enable ssh jail and configure it to send mail messages about banned hosts:

fail2ban_jails:
  - name: 'ssh'
    enabled: 'true'
    action: 'action_mw'

Enable dovecot jail with custom filename and send mail notifications to postmaster:

fail2ban_jails:
  - name: 'dovecot'
    filename: '50_dovecot'
    enabled: 'true'
    destemail: 'postmaster@{{ ansible_domain }}'

Filters

Add custom local filter web-auth with multiple failregex rules:

fail2ban_filters:
  - name: web-auth
    failregex: |
      Authentication failure for .* from <HOST>
      Failed [-/\w]+ for .* from <HOST>
      ROOT LOGIN REFUSED .* FROM <HOST>
    state: present

Add custom local filter root-auth with a single failregex rule:

fail2ban_filters:
  - name: root-auth
    failregex: 'Authentication failure for .* from <HOST>'
    state: present

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others