fail2ban

Overview
Module Description - What the module does and why it is useful
Setup - The basics of getting started with fail2ban
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Jails available
- Pre-defined jails
- Custom jails
Development - Guide for contributing to the module

Overview

This module installs, configures and manages the Fail2ban service.

Module Description

This module handles installing, configuring and running Fail2ban across a range of operating systems and distributions.

Setup

What fail2ban affects

fail2ban package.
fail2ban configuration file.
fail2ban service.

Setup Requirements

Puppet >= 3.0
Facter >= 1.6
Extlib module
Stdlib module

Beginning with fail2ban

Install and configure fail2ban:

    class { 'fail2ban': }

Config file template

You can also manually specify a different configuration template. To do it, use your desired configuration template (e.g. if your template is in your local profile):

  class { 'fail2ban':
    config_file_template => "profile/fail2ban/etc/fail2ban/jail.conf.epp"
  }

Or using Hiera:

fail2ban::config_file_template: "profile/fail2ban/etc/fail2ban/jail.conf.epp"

Usage

Update the fail2ban package.

    class { 'fail2ban':
      package_ensure => 'latest',
    }

Remove the fail2ban package.

    class { 'fail2ban':
      package_ensure => 'absent',
    }

Purge the fail2ban package (All configuration files will be removed).

    class { 'fail2ban':
      package_ensure => 'purged',
    }

Deploy the configuration files from source directory.

    class { 'fail2ban':
      config_dir_source => "puppet:///modules/profile/fail2ban/etc/fail2ban",
    }

Deploy the configuration files from source directory (Unmanaged configuration files will be removed).

    class { 'fail2ban':
      config_dir_purge  => true,
      config_dir_source => "puppet:///modules/profile/fail2ban/etc/fail2ban",
    }

Deploy the configuration file from source.

    class { 'fail2ban':
      config_file_source => "puppet:///modules/profile/fail2ban/etc/fail2ban/jail.conf",
    }

Deploy the configuration file from string.

    class { 'fail2ban':
      config_file_string => '# THIS FILE IS MANAGED BY PUPPET',
    }

Deploy the configuration file from template.

    class { 'fail2ban':
      config_file_template => "profile/fail2ban/etc/fail2ban/jail.conf.epp",
    }

Deploy the configuration file from custom template (Additional parameters can be defined).

    class { 'fail2ban':
      config_file_template     => "profile/fail2ban/etc/fail2ban/jail.conf.epp",
      config_file_options_hash => {
        'key' => 'value',
      },
    }

Deploy additional configuration files from source, string or template.

    class { 'fail2ban':
      config_file_hash => {
        'jail.2nd.conf' => {
          config_file_path   => '/etc/fail2ban/jail.2nd.conf',
          config_file_source => "puppet:///modules/profile/fail2ban/etc/fail2ban/jail.2nd.conf",
        },
        'jail.3rd.conf' => {
          config_file_path   => '/etc/fail2ban/jail.3rd.conf',
          config_file_string => '# THIS FILE IS MANAGED BY PUPPET',
        },
        'jail.4th.conf' => {
          config_file_path     => '/etc/fail2ban/jail.4th.conf',
          config_file_template => "profile/fail2ban/etc/fail2ban/jail.4th.conf.epp",
        },
      },
    }

Disable the fail2ban service.

    class { 'fail2ban':
      service_ensure => 'stopped',
    }

Reference

Classes

Public Classes

fail2ban: Main class, includes all other classes.

Private Classes

fail2ban::install: Handles the packages.
fail2ban::config: Handles the configuration file.
fail2ban::service: Handles the service.

Parameters

`package_ensure`

Determines if the package should be installed. Valid values are 'present', 'latest', 'absent' and 'purged'. Defaults to 'present'.

`package_name`

Determines the name of package to manage. Defaults to 'fail2ban'.

`package_list`

Determines if additional packages should be managed. Defaults to 'undef'.

`config_dir_ensure`

Determines if the configuration directory should be present. Valid values are 'absent' and 'directory'. Defaults to 'directory'.

`config_dir_path`

Determines if the configuration directory should be managed. Defaults to '/etc/fail2ban'

`config_dir_purge`

Determines if unmanaged configuration files should be removed. Valid values are 'true' and 'false'. Defaults to 'false'.

`config_dir_recurse`

Determines if the configuration directory should be recursively managed. Valid values are 'true' and 'false'. Defaults to 'true'.

`config_dir_source`

Determines the source of a configuration directory. Defaults to 'undef'.

`config_file_path`

Determines if the configuration file should be managed. Defaults to '/etc/fail2ban/jail.conf'

`config_file_owner`

Determines which user should own the configuration file. Defaults to 'root'.

`config_file_group`

Determines which group should own the configuration file. Defaults to 'root'.

`config_file_mode`

Determines the desired permissions mode of the configuration file. Defaults to '0644'.

`config_file_source`

Determines the source of a configuration file. Defaults to 'undef'.

`config_file_string`

Determines the content of a configuration file. Defaults to 'undef'.

`config_file_template`

Determines the content of a configuration file. Defaults to 'undef'.

`config_file_notify`

Determines if the service should be restarted after configuration changes. Defaults to 'Service[fail2ban]'.

`config_file_require`

Determines which package a configuration file depends on. Defaults to 'Package[fail2ban]'.

`config_file_hash`

Determines which configuration files should be managed via fail2ban::define. Defaults to '{}'.

`config_file_options_hash`

Determines which parameters should be passed to an ERB template. Defaults to '{}'.

`manage_defaults`

Determines whether the file /etc/fail2ban/jail.d/defaults-debian.conf should be deleted or not. Defaults to 'absent'.

`manage_firewalld`

Determines whether the file /etc/fail2ban/jail.d/00-firewalld.conf should be deleted or not. Defaults to 'absent'.

`service_ensure`

Determines if the service should be running or not. Valid values are 'running' and 'stopped'. Defaults to 'running'.

`service_name`

Determines the name of service to manage. Defaults to 'fail2ban'.

`service_enable`

Determines if the service should be enabled at boot. Valid values are 'true' and 'false'. Defaults to 'true'.

`action`

Determines how banned ip addresses should be reported. Defaults to 'action_mb'.

`bantime`

Determines how many seconds ip addresses will be banned. Defaults to '432000'.

`email`

Determines which email address should be notified about restricted hosts and suspicious logins. Defaults to "fail2ban@${::domain}".

`sender`

Determines which email address should notify about restricted hosts and suspicious logins. Defaults to 'fail2ban@${::fqdn}'.

`iptables_chain`

Determines chain where jumps will to be added in iptables-* actions. Defaults to 'INPUT'.

`jails`

Determines which services should be protected by Fail2ban. Defaults to '['ssh', 'ssh-ddos']'.

`maxretry`

Determines the number of failed login attempts needed to block a host. Defaults to '3'.

`whitelist`

Determines which ip addresses will not be reported. Defaults to '['127.0.0.1/8', '192.168.56.0/24']'.

`custom_jails`

Determines which custom jails should be included (see Custom jails.

`banaction`

Determines which action to perform when performing a global ban (not overridden in a specific jail).

Jails available

Pre-defined jails

RedHat

3proxy
apache-auth
apache-badbots
apache-botsearch
apache-fakegooglebot
apache-modsecurity
apache-nohome
apache-noscript
apache-overflows
apache-shellshock
assp
asterisk
counter-strike
courier-auth
courier-smtp
cyrus-imap
directadmin
dovecot
dropbear
drupal-auth
ejabberd-auth
exim
exim-spam
freeswitch
froxlor-auth
groupoffice
gssftpd
guacamole
horde
kerio
lighttpd-auth
monit
mysqld-auth
nagios
named-refused
nginx-botsearch
nginx-http-auth
nsd
openwebmail
oracleims
pam-generic
pass2allow-ftp
perdition
php-url-fopen
portsentry
postfix
postfix-rbl
postfix-sasl
proftpd
pure-ftpd
qmail-rbl
recidive
roundcube-auth
selinux-ssh
sendmail-auth
sendmail-reject
sieve
sogo-auth
solid-pop3d
squid
squirrelmail
sshd
sshd-ddos
stunnel
suhosin
tine20
uwimap-auth
vsftpd
webmin-auth
wuftpd
xinetd-fail

Debian

3proxy
apache-auth
apache-badbots
apache-botsearch
apache-fakegooglebot
apache-modsecurity
apache-multiport
apache-nohome
apache-noscript
apache-overflows
apache-shellshock
assp
asterisk
bitwarden
centreon
counter-strike
courierauth
courier-smtp
cyrus-imap
directadmin
domino-smtp
dovecot
dropbear
drupal-auth
ejabberd-auth
exim
exim-spam
freeswitch
froxlor-auth
groupoffice
gssftpd
guacamole
haproxy-http-auth
horde
kerio
lighttpd-auth
lighttpd-fastcgi
mongodb-auth
monit
murmur
mysqld-auth
nagios
named-refused
nginx-botsearch
nginx-http-auth
nginx-limit-req
nsd
openhab-auth
openwebmail
oracleims
pam-generic
pass2allow-ftp
perdition
php-url-fopen
phpmyadmin-syslog
portsentry
postfix
postfix-rbl
postfix-sasl
proftpd
pure-ftpd
qmail-rbl
recidive
roundcube-auth
sasl
selinux-ssh
sendmail-auth
sendmail-reject
sieve
screensharing
slapd
sogo-auth
solid-pop3d
squid
squirrelmail
ssh
ssh-blocklist
ssh-ddos
ssh-iptables-ipset4
ssh-iptables-ipset6
ssh-route
stunnel
suhosin
tine20
traefik-auth
uwimap-auth
vsftpd
webmin-auth
wuftpd
xinetd-fail
zoneminder
znc-adminlog

Suse

3proxy
apache-auth
apache-badbots
apache-botsearch
apache-common
apache-fakegooglebot
apache-modsecurity
apache-nohome
apache-noscript
apache-overflows
apache-pass
apache-shellshock
assp
asterisk
botsearch-common
common
counter-strike
courier-auth
courier-smtp
cyrus-imap
directadmin
domino-smtp
dovecot
dropbear
drupal-auth
ejabberd-auth
exim-common
exim-spam
exim
freeswitch
froxlor-auth
groupoffice
gssftpd
guacamole
haproxy-http-auth
horde
ignorecommands
kerio
lighttpd-auth
mongodb-auth
monit
murmur
mysqld-auth
nagios
named-refused
nginx-botsearch
nginx-http-auth
nginx-limit-req
nsd
openhab
openwebmail
oracleims
pam-generic
perdition
php-url-fopen
phpmyadmin-syslog
portsentry
postfix
proftpd
pure-ftpd
qmail
recidive
roundcube-auth
screensharingd
selinux-common
selinux-ssh
sendmail-auth
sendmail-reject
sieve
slapd
sogo-auth
solid-pop3d
squid
squirrelmail
sshd
stunnel
suhosin
tine20
uwimap-auth
vsftpd
webmin-auth
wuftpd
xinetd-fail
zoneminder

Custom jails

Users can add their own jails by using this YAML definition:

---
  fail2ban::custom_jails:
    'nginx-wp-login':
      filter_failregex: '<HOST>.*] "POST /wp-login.php'
      port: 'http,https'
      logpath: '/var/log/nginx/access.log'
      maxretry: 3
      findtime: 120
      bantime: 1200
      ignoreip: ['127.0.0.1', '192.168.1.1/24']
    'nginx-login':
      filter_failregex: '^<HOST> -.*POST /sessions HTTP/1\.." 200'
      action: 'iptables-multiport[name=NoLoginFailures, port="http,https"]'
      logpath: '/var/log/nginx*/*access*.log'
      maxretry: 6
      bantime: 600
      ignoreip: ['127.0.0.1', '192.168.1.1/24']

Sendmail notifications

Default e-mail notification are defined in /etc/fail2ban/action.d/sendmail-common.conf. Following configuration will create override config sendmail-common.local.

fail2ban::sendmail_actions:
  actionstart: ''
  actionstop: ''
fail2ban::sendmail_config:
  dest: root@localhost
  sender: fail2ban@localhost
  sendername: Fail2Ban

Limitations

This module has been tested on:

Debian 8/9/10
Ubuntu 16.04/18.04/20.04
RedHat 6/7/8/9
CentOS 6/7/8/9
OpenSuSE 15

Development

Bug Report

If you find a bug, have trouble following the documentation or have a question about this module - please create an issue.

Pull Request

If you are able to patch the bug or add the feature yourself - please make a pull request.

Contributors

The list of contributors can be found at: https://github.com/voxpupuli/puppet-fail2ban/graphs/contributors

karolgrudzinski/puppet-fail2ban

fail2ban

Table of Contents

Overview

Module Description

Setup

What fail2ban affects

Setup Requirements

Beginning with fail2ban

Config file template

Usage

Reference

Classes

Public Classes

Private Classes

Parameters

package_ensure

package_name

package_list

config_dir_ensure

config_dir_path

config_dir_purge

config_dir_recurse

config_dir_source

config_file_path

config_file_owner

config_file_group

config_file_mode

config_file_source

config_file_string

config_file_template

config_file_notify

config_file_require

config_file_hash

config_file_options_hash

manage_defaults

manage_firewalld

service_ensure

service_name

service_enable

action

bantime

email

sender

iptables_chain

jails

maxretry

whitelist

custom_jails

banaction