Role Name

An ansible role to install and manage Fail2ban

Requirements

Ansible version 2.6 or later

Installation

Ansible Galaxy

Use ansible-galaxy install sakibmoon.fail2ban

Git

Use git clone https://github.com/sakibmoon/ansible-role-fail2ban.git

Basic Usage

Install and enable fail2ban and configure ssh with fail2ban

    - hosts: servers
      vars:
        fail2ban_services:
          - name: "sshd"
            enabled: "true"
            port: "ssh"
            filter: "sshd"
            logpath: "/var/log/auth.log"
            maxretry: 6       
      roles:
         - sakibmoon.fail2ban

See Role Variables and Example Playbook for more complex Usecase and how you can finetune all the options

Role Variables

Service Monitor Options

fail2ban_services
A list of Services to monitor by fail2ban. Every list option must contain service name, logpath. Only specify the settings you want to change. The rest of the configuration will come from global jail configuration as seen/set here.

Service options:

name: Name of the Service
logpath: Logpath of the service to monitor
port: Comma separated ports to monitor
enabled: Whether to enable this jail

Action List

fail2ban_actionlist
A list of action to create. The actions are saved in /etc/fail2ban/action.d/ directory. A single action can contain following options:

name: Action name. The name of the file.
sections: A list of sections like Definition, Init etc wchih contains dictionary of entries
file_ext: (Optional) The file extionsion. Can be either local or conf. Default: local

Example:

    fail2ban_actionlist:
      - name: toy-action1
        sections:
          - name: Definition
            options:
              - name: actionstart
                value: "ActionStart value"
              - name: actionflush
                value: "Actionflush value"
          - name: Init
            options:
              - name: timeout
                value: "timeout value"
        file_ext: "local"
      - name: toy-action2
        sections:
          - name: INCLUDES
            options:
              - name: before
                value: something-to-include.local
          - name: Definition
            options:
              - name: actionstart
                value: "ActionStart value"
              - name: actionflush
                value: "Actionflush value"
          - name: Init
            options:
              - name: timeout
                value: "timeout value"

Filter List

fail2ban_filterlist
A list of filter to create. The filter is saved in /etc/fail2ban/action.d/ directory. The format is same as fail2ban_actionlist as shown above.

Fail2ban Configuration Options

Variable Name	Fail2ban Option Name	Option Values	Default Value	Description
fail2ban_confpath		[FILE]	/etc/fail2ban/fail2ban.local	The path where fail2ban configuration are written.
fail2ban_loglevel	loglevel	CRITICAL ERROR WARNING INFO DEBUG \ [0-3]	ERROR for version > 0.8.x 1 for version 0.8.x	Set the log level output.
fail2ban_logtarget	logtarget	[FILE] STDOUT STDERR SYSLOG	/var/log/fail2ban.log	Set the log target. Only one log target can be specified. If you change logtarget from the default value and you are using logrotate -- also adjust or disable rotation in the corresponding configuration file (e.g. /etc/logrotate.d/fail2ban on Debian systems)
fail2ban_syslogsocket	syslogsocket	auto [FILE]	auto	Set the syslog socket file. Only used when logtarget is SYSLOG. auto uses platform.system() to determine predefined paths
fail2ban_socket	socket	[FILE]	/var/run/fail2ban/fail2ban.sock	Set the socket file. This is used to communicate with the daemon. Do not remove this file when Fail2ban runs. It will not be possible to communicate with the server afterwards.
fail2ban_pidfile	pidfile	[FILE]	/var/run/fail2ban/fail2ban.pid	Set the PID file. This is used to store the process ID of the fail2ban server.
fail2ban_dbfile	dbfile	None :memory: [FILE]	/var/lib/fail2ban/fail2ban.sqlite3	Set the file for the fail2ban persistent data to be stored. A value of :memory: means database is only stored in memory and data is lost when fail2ban is stopped. A value of None disables the database.
fail2ban_dbpurgeage	dbpurgeage	[ SECONDS ]	86400	Sets age at which bans should be purged from the database
fail2ban_dbmaxmatches	dbmaxmatches	[ INT ]	20	Number of matches stored in database per ticket.
fail2ban_stacksize	stacksize	[ SIZE ]	0	This specifies the stack size (in KiB) to be used for subsequently created threads, and must be 0 or a positive integer value of at least 32.

Global Jail Configuration Options

Variable Name	Fail2ban Option Name	Option Values	Default Value	Description
fail2ban_jailpath		[FILE]	/etc/fail2ban/jail.local	The file to write Fail2ban jail default configuration
fail2ban_ignoreself	ignoreself	boolean true false	true	Indicates the banning of own IP addresses should be prevented.
fail2ban_ignoreip	ignoreip	List of IP address		list of IPs not to ban. They can include a DNS resp. CIDR mask too. The option affects additionally to ignoreself (if true) and don't need to contain own DNS resp. IPs of the running host.
fail2ban_ignorecommand	ignorecommand	/path/to/command		External command that will take an tagged arguments to ignore, e.g. , and return true if the IP is to be ignored. False otherwise.
fail2ban_ignorecache	ignorecache		disabled	provide cache parameters for ignore failure check (caching of the result from ignoreip, ignoreself and ignorecommand)
fail2ban_bantime	bantime	[ SECONDS ]	600	Effective ban duration (in seconds).
fail2ban_findtime	findtime	[ SECONDS ]	600	time interval (in seconds) before the current time where failures will count towards a ban.
fail2ban_maxretry	maxretry	[ INT ]	5	The number of failures before a host get banned.
fail2ban_backend	backend	pyinotify gamin polling systemd auto	auto	Specifies the backend used to get files modification.
fail2ban_usedns	usedns	yes warn no raw	warn	Specifies if jails should trust hostnames in logs, warn when DNS lookups are performed, or ignore all hostnames in logs
fail2ban_logencoding	logencoding	auto ascii utf-8 etc.	auto	Specifies the encoding of the log files handled by the jail. Default value of auto uses current system locale.
fail2ban_mode	mode	normal ddos extra aggressive	normal	The mode of the filter
fail2ban_filter	filter	filter name	%(__name__)s[mode=%(mode)s]	The filter to use by the jail. By default jails have names matching their filter name
fail2ban_logtimezone	logtimezone	UTC UTC+0200 GMT-0100 etc.		Force the time zone for log lines that don't have one. If this option is not specified, log lines from which no explicit time zone has been found are interpreted by fail2ban in its own system time zone.
fail2ban_banaction	banaction	iptables, iptables-new, iptables-multiport, shorewall, etc	iptables-multiport	Default banning action. It is used to define action_* variables. Can be overridden globally or per section within jail.local file
fail2ban_banaction_allports	banaction_allports	iptables, iptables-new, iptables-multiport, shorewall, etc	iptables-allports	the same as banaction but for some "allports" jails like "pam-generic" or "recidive"
fail2ban_action	action		%(action_)s	Choose default action. To change, just override value of 'action' with the interpolation to the chosen action shortcut (e.g. action_mw, action_mwl, etc) or chose action(s) from /etc/fail2ban/action.d/ without the .conf/.local extension.
fail2ban_failregex	failregex	Python Regualr Expression		regex (Python regular expression) to be added to the filter's failregexes (see failregex in section FILTER FILES for details).
fail2ban_ignoreregex	ignoreregex			regex which, if the log line matches, would cause Fail2Ban not consider that line. This line will be ignored even if it matches a failregex of the jail or any of its filters.
fail2ban_maxmatches	maxmatches	[INT]		max number of matched log-lines the jail would hold in memory per ticket. By default it is the same value as maxretry of jail (or default)

Dependencies

No dependencies

Supported Platforms

This role should work on any Redhat or Debian based linux distribution. It's tested on the following platforms

• CentOS 8
• CentOS 7
• Ubuntu 18.04
• Ubuntu 16.04
• Debian 10
• Debian 9

Example Playbook

The followng playbook install, enable fail2ban and add ssh jail

    - hosts: servers
      vars:
        fail2ban_services:
          - name: "sshd"
            enabled: "true"
            port: "ssh"
            filter: "sshd"
            logpath: "/var/log/auth.log"
            maxretry: 6       
      roles:
         - sakibmoon.fail2ban

License

MIT

Author Information

This role was created by sakibmoon @2020