Puppet module for fail2ban
Install and manage fail2ban with puppet
To use this module just include the jail2ban class. To change default configurations in /etc/fail2ban/jail.conf, you can pass values to parameters to the fail2ban class. See section below for full list of parameters.
Here's an example that sets default ignored IP address to local host and another non-routed IP:
<s>~ class { 'fail2ban': ignoreip => ['127.0.0.1', '10.0.0.1'], } </s>~
You can create a jail with the fail2ban::jail defined type (see section below) or you can use one of the predefined fail2ban::jail::* classes.
You can also create a filter for use with jails with the fail2ban::filter defined type (see section below).
Requirements
This module depends on the following modules to function:
-
puppetlabs' stdlib module (at least version 3.0.0)
Compatibility
This module supports
-
Debian 9
-
RHEL 6 and 7
-
CentOs 6 and 7
Versions | Puppet 2.7 | Puppet 3.x | Puppet 4.x | Puppet 5.x | :—————|:———-:|:———-:|:———-:|:———-: 2.x | yes | yes | no | no 3.x | no | no | yes | yes
Version 2.x is in maintenance mode only. If you need to use this module with puppet 4.x or 5.x then you should use version 3.x of this module.
Upgrade notices
-
3.0: fail2ban::jail's
order
parameter was removed. Users should adapt their calls in order to remove this parameter. All jail files are now just individual files dropped in jail.d and order is not relevant there. -
2.0: Jail definitions have been moved to
jail.d/*.conf
files . Thejail.local
file is now getting removed by the module. To avoid this, set rm_jail_local to true. -
2.0:
ignoreip
both on the main class and in fail2ban::jail (and thus in all fail2ban::jail::* classes too) is no longer expected to be a string. It is now a list of strings that automatically gets joined with spaces. Users of the fail2ban module will need to adjust these parameters. -
The directory
/etc/fail2ban/jail.d
is now getting purged by default. Users who would like to preserve files in this directory that are not managed by puppet should now set thepurge_jail_dot_d
parameter to thefail2ban
class to false.
Parameters to fail2ban class
All of the values configured through the fail2ban
class are
used to configure global default values. These values can be overridden by
individual jails.
-
ignoreip
Default ignored IP(s) when parsing logs. Default value is ['127.0.0.1']. Multiple values should be placed in an array. -
bantime
Number of seconds during which reaching maxretry gets an IP banned. Default value is '600' -
findtime
Time interval (in seconds) before the current time where failures will count towards a ban. Default is '600'. -
maxretry
Number of times an IP address must trigger failgregexes to get banned. Default value is '3' -
backend
How should fail2ban look for modifications on log files. Default value is 'auto' -
destemail
Default email address that should get notifications with the actions that send emails. Default value is 'root@localhost' -
banaction
Default action to use for jails. Default value is 'iptables-multiport' -
mta
Mail Transfer Agent program used for sending out email for actions that send out emails. Default value is 'sendmail' -
protocol
Default protocol for jails. Default value is 'tcp' -
action
Default action for jails. Default value is '%(action_)s', which is defined as '%(banaction)s[name=%(name)s, port=“%(port)s”, protocol=“%(protocol)s]' in jail.conf. -
rm_jail_local
Boolean value that decides whether/etc/fail2ban/jail.local
is removed by puppet or not. Defaut value is true. -
purge_jail_dot_d
Boolean value that decides whether/etc/fail2ban/jail.d/
is purged of files that are not managed by puppet. Default value is true. -
usedns
Specifies if jails should trust hostnames in logs. Options are yes, warn or no. Default is warn. -
persistent_bans
Boolean value that ensure bans persist over time (0.8.x or older). This feature is builtin with 0.9.x./etc/fail2ban/persistent.bans
file is created and populated by/etc/fail2ban/action.d/iptables-multiport.conf
. Default value is false.
Defining jails
To define a jail, you can use one of the jail parameter presets (see list below). Or you can define your own with the fail2ban::jail defined type:
<s>~ fail2ban::jail { 'jenkins': port => 'all', filter => 'jenkins', logpath => '/var/log/jenkins.log', } </s>~
Here's the full list of parameters you can use:
-
port
List of port names, separated by commas, that will get blocked for a banned IP. Can be “all” to block all ports. This parameter is mandatory. -
filter
Name of the filter to use. This parameter is mandatory. -
logpath
Path of the log to monitor. This parameter is mandatory unless you are using the systemd backend in which case it should not be set. -
ensure
Set this toabsent
to remove a jail. This parameter is useless with the default value ofpurge_jail_dot_d
since removing the jail resource will remove the jail file. It can be useful if you setpurge_jail_dot_d
to false since then puppet won't automatically remove jails that are not managed anymore. -
enabled
Should this jail be enabled or not. The subtility betweenensure
and this parameter is that ensure will make the contents of the jail appear or disappear, while this parameter will let the jail contents be present injail.local
but the jail will be marked as disabled. Default value is 'true' -
protocol
Override default protocol to ban ports for. -
maxretry
Override default number of trials that bans someone. -
findtime
Override default interval during which maxretry failures triggers a ban. -
action
Override default action used. -
banaction
Override defaultbanaction
. If you don't also overrideaction
, you will use the same default action template but with a different action name. -
bantime
Override default duration of a ban for an IP. -
ignoreip
Override default IP(s) to ignore (e.g. don't ban these IPs). Multiple values should be placed in an array. -
backend
Override default log file following method.
Predefined jails
The list at the end of this section contains all of the presets that can be
used to configure jails more easily. Each of them is a data point – a hash
of parameter and values – in hiera that needs to be gathered with the
lookup()
function. Each hash represents parameters and values
that should be passed in to the fail2ban::jail
defined type
documented above and has a lookup key of
'fail2ban::jail::$jailname'.
For example to configure a jail for the ssh service with the preset parameters:
<s>~ $ssh_params = lookup('fail2ban::jail::sshd') fail2ban::jail { 'sshd': * => $ssh_params, } </s>~
You can also override values from the preset or define new parameters by
concatenating your own hash to it. In the following example we define new
parameters bantime
and findtime
and we override
the preset for maxretry
:
<s>~ $ssh_extra_params = { 'bantime' => 300, 'findtime' => 200, 'maxretry' => 3, } $ssh_params = lookup('fail2ban::jail::sshd') + $ssh_extra_params fail2ban::jail { 'sshd': * => $ssh_params, } </s>~
This way you can set any parameter to the fail2ban::jail
defined type and override preset values.
Here's the full list of currently available presets. To know each
preset's default values you can inspect files in data/
.
Watch out: jails by default use the same filter name as the jail name, so
make sure to either use the same string as the lookup key as the resource
name for jail
, or override the filter
parameter.
-
3proxy
-
apache-auth
-
apache-badbots
-
apache-noscript
-
apache-overflows
-
apache-nohome
-
apache-botsearch
-
apache-fakegooglebot
-
apache-modsecurity
-
apache-shellshock
-
assp
-
asterisk
-
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
-
mongodb-auth
-
monit
-
murmur
-
mysql-auth
-
To log wrong MySQL access attempts add to
/etc/mysql/my.cnf
in[mysqld]
or equivalent section:log-warning = 2
-
nrpe
-
named-refused
-
nginx-http-auth
-
nginx-limit-req
-
To use 'nginx-limit-req' jail you should have
ngx_http_limit_req_module
and definelimit_req
andlimit_req_zone
as described in nginx documentation nginx.org/en/docs/http/ngx_http_limit_req_module.html or for example see in 'config/filter.d/nginx-limit-req.conf' -
nginx-botsearch
-
nsd
-
openhab-auth
-
openwebmail
-
oracleims
-
pam-generic
-
pass2allow-ftp
-
perdition
-
php-url-fopen
-
postfix
-
postfix-rbl
-
postfix-sasl
-
proftpd
-
pure-ftpd
-
qmail-rbl
-
recidive
-
Ban IPs that get repeatedly banned, but for a longer period of time – by default for one week and one day. Some warnings apply:
-
Make sure that your loglevel specified in fail2ban.conf/.local is not at DEBUG level – which might then cause fail2ban to fall into an infinite loop constantly feeding itself with non-informative lines
-
Increase dbpurgeage defined in fail2ban.conf to e.g. 648000 (7.5 days) to maintain entries for failed logins for sufficient amount of time
-
roundcube-auth
-
selinux-ssh
-
sendmail-auth
-
sieve
-
slapd
-
sogo-auth
-
solid-pop3d
-
squid
-
squirrelmail
-
sshd
-
sshd-ddos
-
stunnel
-
This pre-defined jail does not specify ports to ban since this service can run on many choices of ports. By default this means that all ports will be blocked for IPs that are banned by this jail. You may want to override the hash to add in specific ports in the
port
parameter. -
suhosin
-
tine20
-
uwimap-auth
-
vsftpd
-
webmin-auth
-
wuftpd
-
xinetd-fail
-
This pre-defined jail does not specify ports to ban since this service can run on many choices of ports. By default this means that all ports will be blocked for IPs that are banned by this jail. You may want to override the hash to add in specific ports in the
port
parameter.
Defining filters
You might want to define new filters for your new jails. To do that, you can use the fail2ban::filter defined type:
<s>~ fail2ban::filter { 'jenkins': failregexes => [ # Those regexes are really arbitrary examples. 'Invalid login to Jenkins by user mooh by IP '<HOST>'', 'Forced entry trial by <HOST>', ], } </s>~
Here's the full list of parameters you can use with the defined type:
-
failregexes
List of regular expressions (strings) that, if matched, will increase IP's maxretry count. This parameter is mandatory. -
ensure
Should this filter be present or not. Default value is present -
ignoreregexes
List of regular expressions (strings) that, if matched, will invalidate failregex matching. Default value is an empty list. -
includes
List of file names that should be included before the filter definition. An[INCLUDES]
section will be added to the top of the filter configuration file, and the file names in this list will be added to abefore =
line. -
includes_after
List of file names that should be included after the filter definition. An[INCLUDES]
section will be added to the top of the filter configuration file, and the file names in this list will be added to anafter =
line. -
additional_defs
List of lines that could define more arbitrary values. Lines will be placed in the file as they are in the list. Default value is an empty list.