Puppet module for fail2ban

Table of contents:

1. Overview
2. Module description
3. Usage
   • Defining jails
     • Predefined jails
   • Defining filters
   • Defining actions
     • Python action scripts
     • nftables support
4. Requirements
5. Compatibility
6. Upgrade notices
7. Documentation
8. Testing
   • Unit tests
   • Funtionality tests

Overview

Install and manage fail2ban with puppet to block bruteforce attempts.

Module description

With this module, you can install fail2ban and define any configuration for the service in order to slow down bruteforce attempts on services that need to be exposed to the internet.

This module lets you create:

• actions (e.g. what to do when there's a problematic case)
• filters (e.g. how to discover problematic cases)
• jails (e.g. combining actions and filters with a rate limit on filter matches)

Usage

To use this module just include the fail2ban class.

To change default configurations in jail.conf or fail2ban.conf, you can pass values to parameters to the fail2ban class. See technical reference documentation (REFERENCE.md) for full list of parameters.

Here's an example that sets default ignored IP address for all jails to localhost plus another rfc1819 IP:

class { 'fail2ban':
  ignoreip => ['127.0.0.1', '10.0.0.1'],
}

Defining jails

The fail2ban::jail defined type lets you configure jails. This is the resource you'll mostly likely be using the most.

You can use one of the jail parameter presets (see details and list of presets in the section below. for more details the presets are defined in hiera files in data/) to speed up defining some common jails.

The following example defines a jail for the jenkins service:

fail2ban::jail { 'jenkins':
  port    => 'all',
  filter  => 'jenkins',
  logpath => ['/var/log/jenkins.log'],
}

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 (so they are really just presets for the type's parameters) documented above and has a lookup key of fail2ban::jail::$jailname.

For example, to quickly configure a jail for the ssh service with the preset parameters:

$ssh_params = lookup('fail2ban::jail::sshd')
fail2ban::jail { 'sshd':
  * => $ssh_params,
}

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:

$ssh_extra_params  = {
  'bantime'  => 300,
  'findtime' => 200,
  'maxretry' => 3,
}
$ssh_params = lookup('fail2ban::jail::sshd') + $ssh_extra_params
fail2ban::jail { 'sshd':
  * => $ssh_params,
}

This way you can set any parameter to the fail2ban::jail defined type and override preset values.

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 for the jail resource name, or override the filter parameter.

Here's the full list of currently available presets. To know each preset's default values you can inspect files in data/:

• 3proxy
• apache-auth
• apache-badbots
• apache-noscript
• apache-overflows
• apache-nohome
• apache-botsearch
• apache-fakegooglebot
• apache-modsecurity
• apache-shellshock
• assp
• asterisk
• bitwarden
• centreon
• counter-strike
• courier-auth
• courier-smtp
• cyrus-imap
• directadmin
• domino-smtp
• dovecot
• dropbear
• drupal-auth
• ejabberd-auth
• exim
• exim-spam
• freeswitch
• froxlor-auth
• gitlab
• grafana
• groupoffice
• gssftpd
• guacamole
• haproxy-http-auth
• 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
• nagios
• named-refused
• nginx-http-auth
• nginx-limit-req
  • To use 'nginx-limit-req' jail you should have ngx_http_limit_req_module and define limit_req and limit_req_zone as described in nginx documentation http://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
• phpmyadmin-syslog
• portsentry
• 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:
  1. 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
  2. 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
• screensharing
• selinux-ssh
• sendmail-auth
• sendmail-reject
• sieve
• slapd
• softethervpn
• 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
• traefik-auth
• 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.
• znc-adminlog
• zoneminder

Defining filters

You might want to define new filters for your new jails. To do that, you can use the fail2ban::filter defined type:

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>',
  ],
}

Defining actions

Fail2ban can do pretty much what you want it to do (e.g. run an action) when an IP matches a filter enough times during the rate limit set by the jail.

To define a new action, you can use the fail2ban::action defined type. Here's an example that would call out to a fictitious REST API whenever an IP address is banned and unbanned:

fail2ban::action { 'rest_api':
  ensure      => present,
  actionban   => ['curl -s -X PUT http://yourapi:8080/theapi/v4/firewall/rules -H "Content-Type:application/json" -H "Authorization: ..." -d "{\"ban\": \"<ip>\"}"'],
  actionunban => ['curl -s -X DELETE http://yourapi:8080/theapi/v4/firewall/rules/1 -H "Authorization: ..."'],
}

Python action scripts

Fail2ban lets users define actions as python scripts. These actions should exist as a file within /etc/fail2ban/action/$action.py where $action is the name of the action.

The contents of those files can differ wildly. Other than ensuring the location of the file and its permissions, this module wouldn't actually add much more on top of simply managing the python scripts as file resources, so no defined resource type was created for them.

If you manage such an action script, it is recommended to make it signal Class['fail2ban::service'] (e.g. with ~>) in order to automatically restart the service upon changes.

nftables support

Fail2ban supports nftables with the builtin actions:

• nftables
• nftables-multiport (it's just an alias of nftables)
• nftables-allports

These actions use nftables' set functionality to contain banned IPs instead of adding a firewall rule for each new banned IP. This should make your firewall more efficient if you have lots of banned IPs.

Since nftables is now used by default on Debian since the buster release but iptables is still used by fail2ban's default action, here's how to quickly enable usage of nftables for fail2ban:

Only two global parameters need to be changed:

• chain needs to be set to the same value but lowercased
  • by default the chain used is expected to be in table filter of address family ip (e.g. the iptables compatibility table).
• banaction needs to be set to the nftables action of your choice
• If you want to customize further what table, address family, chain hook, hook priority or the action taken by the rule if an address is matched, you can create a file /etc/fail2ban/filter.d/nftables-common.local that overrides the variables in the Init section of the nftables.conf file.

Here's an example minimal configuration for using nftables with one sshd jail defined as usual:

class { 'fail2ban':
  banaction      => 'nftables',
  chain          => 'input',
}
$ssh_params = lookup('fail2ban::jail::sshd')
fail2ban::jail { 'sshd':
  * => $ssh_params,
}

Do note that upon service restart, fail2ban will not create the ip set and the corresponding rule right away so it will appear as though "it's not working". They will only be added whenever the first "action" is taken (so when banning the first IP for a jail). After that you should see both the set and the rule for that jail when running nft list ruleset.

To list which IPs are currently banned, you can either use fail2ban-client status sshd or list elements of the corresponding set. For the example above: nft list set filter f2b-sshd

Requirements

This module depends on the following modules to function:

• puppetlabs' stdlib module (at least version 4.6.0)

Compatibility

This module supports

• Debian 10, 11
• Ubuntu 18.04, 20.04, 22.04
• RHEL 7, 8, 9
• CentOS 7 and 8
  • version 8 is currently EOL and support for it will be removed along with version 7 when that one becomes EOL as well

Puppet versions 6 and 7 are supported.

If you still need to use this module with puppet 5 or 4.10+ you can either try your luck with version 4.x of this module even though support is not official, or you can use the 3.x releases of the module.

Upgrade notices

• 4.0.0: Support for Debian 11 was added, but Debian 8 was removed from supported releases.

  With the removal of debian 8 support, the $persistent_bans parameter was removed since it is not needed anymore. This has the side-effect of stopping management of the actions.d/iptables-multiport.conf file, so users may let their package manager change it back to its default form now.

  A couple of new parameters have been added to match newly available configuration options in the fail2ban version (0.11) in Debian bullseye.

  Watch out though, the $logpath parameter has changed data type from String to Array[String] so you'll need to adapt your calls to the main class and to the jail defined type.

  The $action parameter in the main class and in the fail2ban::jail defined type now accept an array of strings. Using a simple String is now considered deprecated and the data type will get removed in version 5.x of the module.

  Similarly, the $failregex and $ignoreregex parameters in the main class now accept an array of strings and using a simple String is now considered deprecated. The String type will be removed from those parameters in version 5.x of the module.

  Some new default jails were added to match what's available in newer versions of fail2ban. You can check them out in data/common.yaml.

  Some default jails were modified. You might want to check what their changes are before upgrading. Namely:

  • asterisk
  • dovecot
  • freeswitch
  • murmur
  • mysql-auth was renamed to mysqld-auth
  • nrpe was renamed to nagios
  • nsd
  • openhab-auth
  • openwebmail

• 3.3: Support for the 2.x branch was discontinued. Only puppet 4.x+ is supported from now on.

  Documentation in the README.md file is now limited to only examples of how to use the module. For a technical reference of all classes, defined types and their parameters, please refer to REFERENCE.md or generate html documentation with puppet-strings.

  Note that debian 8 is still being supported for a little while, but with the expectation that users use this module with puppet 4.x+. Debian 8's support cycle is almost over, thus so it is for this module. Expect support to be removed from this module in the coming months.

• 3.2: No pre-defined jail sends out an email as an action by default. Users who still want to receive emails when an action is taken can override the action field from the predefined jail data and append the action the following: \n %(mta)s-whois[name=%(__name__)s, dest=\"%(destemail)s\"]

  Also note that puppet 4.x prior to 4.10 is not supported anymore, and that hiera 5 is now required (hence the limitation for the puppet version.

• 3.1: fail2ban.local and all unmanaged files in fail2ban.d are now being purged by default. Users who have local modifications that they want to keep should set $rm_fail2ban_local and/or $purge_fail2ban_d to false.

• 3.0: all of the defined types for predefined jails in fail2ban::jail::* have been removed and instead transformed into data structures with hiera. If you were using the predefined jails, you will need to change your code: please take a look at the new method of using them with lookup() further down in this file.

• 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.

• 3.0: Deprecation notice: the persistent_bans parameter to the fail2ban class is now deprecated and will be removed for the 4.0 release. fail2ban can now manage persistent bans naturally by using its own sqlite3 database.

• 2.0: Jail definitions have been moved to jail.d/*.conf files . The jail.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 the purge_jail_dot_d parameter to the fail2ban class to false.

Documentation

This module uses puppet-strings comments. The most stable way of using puppet-strings is to reuse the same version as what's specified in the Gemfile, so start by running gem install (you might need to setup local path for non-root install first).

Then you can generate HTML documentation in the docs directory with the following command:

bundle exec rake strings:generate

The REFERENCE.md file should be updated along with the code if any API and accompanying puppet-strings documentation change. You can do this with:

bundle exec rake strings:generate:reference

Testing

This module has some tests that you can run to ensure that everything is working as expected.

Before you can use the tests, make sure that you setup your local environment with bundle install.

Smoke tests

You can run sanity check with the validate task from puppet-syntax:

bundle exec rake validate

This will check manifest syntax, template syntax, yaml syntax for hiera files and ensure that the REFERENCE.md file is up to date.

Additionally to this, you can also use rubocop to run sanity checks on ruby files:

bundle exec rake rubocop

Unit tests

The unit tests are built with rspec-puppet.

The usual rspec-puppet_helper rake tasks are available. So, to run spec tests:

bundle exec rake spec

Funtionality tests

Unit tests are great, but sometimes it's nice to actually run the code in order to see if everything is setup properly and that the software is working as expected.

This repository does not have automated functionality tests, but it has a Vagrantfile that you can use to bring up a VM and run this module inside it.

The Vagrantfile expects you to have the vagrant plugin vagrant-librarian-puppet installed. If you don't have it you can also download this module's requirements (see metadata.json) and place them inside tests/modules/.

A couple of manifest files inside tests/ prepare sets of use cases. You can modify the Vagrantfile to use any of them for provisioning the VM.

Reference

Table of Contents

Classes

Public Classes

• fail2ban: Manage fail2ban and its configuration to jam bruteforce attempts on services running on a computer.

Private Classes

• fail2ban::config: Configure fail2ban service
• fail2ban::install: Install fail2ban
• fail2ban::service: Enable fail2ban daemon

Defined types

• fail2ban::action: Create an action for fail2ban
• fail2ban::filter: Setup a filter for fail2ban
• fail2ban::jail: Setup a fail2ban jail to reduce effectiveness of bruteforce.

Data types

• Fail2ban::Backend: Backend names that fail2ban understands Can be one of the pre-defined backend names, "systemd" with optionally a list of parameters between s
• Fail2ban::Dbfile: Where fail2ban's database gets stored. None disables storage
• Fail2ban::Loglevel: How much logging is needed from fail2ban
• Fail2ban::Logtarget: Where logs are sent
• Fail2ban::Port: Possible values for the port parameter ports can be specified by number, but you can also pass in a comma-separated list of values in a strin
• Fail2ban::Protocol: Options for protocol type This is used by the default action iptables-multiport to defined what protocol to ban for the specified ports.
• Fail2ban::Syslogsocket: Path to a socket for communication with syslog, or 'auto' for letting fail2ban auto-discover the path.
• Fail2ban::Time: Time in seconds for some configuration options can be specified either in an integer number of seconds, or an abbreviation that can help spec
• Fail2ban::Usedns: Possible values for usedns parameter

Classes

fail2ban

fail2ban/manifests/init.pp

• Copyright (C) 2007 admin@immerda.ch
• Copyright (C) 2014-2018 gabster@lelutin.ca

• Note blocktype is not offered as a global option since it's not a great idea to set a globally used default value for this option. It's used differently by all actions and different values are expected from each action, so it's generally recommended to override this for each action individually by creating a .local file in actions.d.

• See also

  • https://github.com/fail2ban/fail2ban/blob/0.11/man/jail.conf.5
    • jail.conf(5)

Examples

basic usage

class { 'fail2ban: }

ignore localhost and another non-routable IP

class { 'fail2ban':
  ignoreip => ['127.0.0.1', '10.0.0.1'],
}

Parameters

The following parameters are available in the fail2ban class:

• rm_fail2ban_local
• rm_jail_local
• purge_fail2ban_dot_d
• purge_jail_dot_d
• config_file_mode
• manage_service
• fail2ban_conf_template
• loglvl
• logtarget
• syslogsocket
• socket
• pidfile
• dbfile
• dbpurgeage
• dbmaxmatches
• stacksize
• jail_conf_template
• enabled
• mode
• backend
• usedns
• filter
• logpath
• logencoding
• logtimezone
• prefregex
• failregex
• ignoreregex
• ignoreself
• ignoreip
• ignorecommand
• ignorecache
• maxretry
• maxmatches
• findtime
• action
• bantime
• banaction
• banaction_allports
• chain
• port
• protocol
• mta
• destemail
• sender
• fail2ban_agent

rm_fail2ban_local

Data type: Boolean

Force removal of file /etc/fail2ban/fail2ban.local if present.

Default value: true

rm_jail_local

Data type: Boolean

Force removal of file /etc/fail2ban/jail.local if present.

Default value: true

purge_fail2ban_dot_d

Data type: Boolean

Remove all unmanaged files in /etc/fail2ban/fail2ban.d/

Default value: true

purge_jail_dot_d

Data type: Boolean

Remove all unmanaged files in /etc/fail2ban/jail.d/

Default value: true

config_file_mode

Data type: Stdlib::Filemode

File mode set on all fail2ban configuration files managed by this module.

Default value: '0644'

manage_service

Data type: Boolean

Manage the fail2ban service, true by default

Default value: true

fail2ban_conf_template

Data type: String[1]

Alternative template to use for the fail2ban.conf file.

Default value: 'fail2ban/fail2ban.conf.epp'

loglvl

Data type: Fail2ban::Loglevel

Set fail2ban's loglevel.

Default value: 'INFO'

logtarget

Data type: Fail2ban::Logtarget

Define where fail2ban's logs are sent.

Default value: '/var/log/fail2ban.log'

syslogsocket

Data type: Fail2ban::Syslogsocket

Path to syslog's socket file, or "auto" for automatically discovering it.

Default value: 'auto'

socket

Data type: Stdlib::Absolutepath

Path to fail2ban's own socket file. This file is used by fail2ban-client to communicate with the daemon.

Default value: '/var/run/fail2ban/fail2ban.sock'

pidfile

Data type: Stdlib::Absolutepath

Path to fail2ban's pid file. This usually needs to be in a place where the init script or systemd unit file can find it.

Default value: '/var/run/fail2ban/fail2ban.pid'

dbfile

Data type: Fail2ban::Dbfile

Path to fail2ban's database file.

Default value: '/var/lib/fail2ban/fail2ban.sqlite3'

dbpurgeage

Data type: Integer

Age of entries in fail2ban's database that get removed when performing a database purge operation.

Default value: 86400

dbmaxmatches

Data type: Integer

Number of matches stored in database per ticket.

Default value: 10

stacksize

Data type: Variant[Integer[0,0], Integer[32]]

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. 0 means that fail2ban will use platform or configured default.

Default value: 0

jail_conf_template

Data type: String[1]

Alternative template to use for the jail.conf file.

Default value: 'fail2ban/debian/jail.conf.epp'

enabled

Data type: Boolean

Whether or not to enable jails by default. fail2ban's man page recommends to keep this to false, but by default the module purges jail.d of unknown files so it might be safe to set to true in order to avoid repeating this setting on all jails. If you set purge_jail_dot_d to false, it might be wiser to keep this to false in order to avoid enabling jails that get dropped in jail.d.

Default value: false

mode

Data type: String

Change the default behavior for filters. Watch out however, each individual filter can define its own value and so most values are not guaranteed to be available with all filters. The mode will generally determine which regular expressions the filter will include. To know exactly which values are available in filters, you need to read their configuration files.

Default value: 'normal'

backend

Data type: Fail2ban::Backend

Default method used to get information from logs.

Default value: 'auto'

usedns

Data type: Fail2ban::Usedns

Default behaviour whether or not to resolve IPs when they are found in a log by a filter.

Default value: 'warn'

filter

Data type: String

Default name of filter to use for jails.

Default value: '%(__name__)s[mode=%(mode)s]'

logpath

Data type: Array[String]

Array of absolute paths specifying the default path(s) to log file(s) being used by jails. This value is usually not set and logpath is defined for each jail for more clarity.

Default value: []

logencoding

Data type: String

Name of the encoding of log files. If set to "auto", fail2ban will use what is set in the system's locale setting.

Default value: 'auto'

logtimezone

Data type: Optional[String]

Force a timezone by default for logs that don't specify them on timestamps.

Default value: undef

prefregex

Data type: Optional[String]

Regular expression to parse common part in every message.

Default value: undef

failregex

Data type: Optional[Variant[String, Array[String[1]]]]

Array of regular expressions to add to all filters' failregex. This is usually not used at the global level, but it can still be set.

Default value: undef

ignoreregex

Data type: Optional[Variant[String, Array[String[1]]]]

Array of regular expressions to add to all filters' ignoreregex. This is usually not used at the global level, but could be useful to have something excluded from bans everywhere.

Default value: undef

ignoreself

Data type: Boolean

If set to false, fail2ban will not ignore IP addresses that are bound to interfaces on the host.

Default value: true

ignoreip

Data type: Array[String, 0]

Default list of IPs or CIDR prefixes that should not get banned.

Default value: ['127.0.0.1']

ignorecommand

Data type: Optional[String]

Default command used to determine if an IP should be exempted from being banned.

Default value: undef

ignorecache

Data type: Optional[String]

If set, caches the results from ignoreip, ignoreself and ignorecommand for a set amount of time to avoid calling ignorecommand repeatedly.

Default value: undef

maxretry

Data type: Integer[1]

Default number of times an IP should be detectd by a filter during findtime for it to get banned.

Default value: 3

maxmatches

Data type: Variant[Integer[1], String]

Number of matches stored in ticket.

Default value: '%(maxretry)s'

findtime

Data type: Fail2ban::Time

Default interval during which to count occurences of an IP.

Default value: '10m'

action

Data type: Variant[String, Array[String, 1]]

List of default actions that get called when an IP triggers maxretry number of times a filter within findtime.

Default value: ['%(action_)s']

bantime

Data type: Fail2ban::Time

Default duration in number of seconds to ban an IP address for.

Default value: '10m'

banaction

Data type: String

Default action name extrapolated when defining some of the default actions.

Default value: 'iptables-multiport'

banaction_allports

Data type: String

Default action name that can be extrapolated when defining some of the default actions. This one is meant to ban all ports at once instead of specific ones.

Default value: 'iptables-allports'

chain

Data type: String

Default name of the iptables chain used by iptables-based actions.

Default value: 'INPUT'

port

Data type: Fail2ban::Port

Default comma separated list of ports, port names or port ranges used by actions when banning an IP.

Default value: '0:65535'

protocol

Data type: Fail2ban::Protocol

Default protocol name used by actions.

Default value: 'tcp'

mta

Data type: String

Default program name used for sending out email by actions that do so.

Default value: 'sendmail'

destemail

Data type: String

Default email address used as recipient by actions that send out emails.

Default value: 'root@localhost'

sender

Data type: String

Default email address set as sender by actions that send out emails.

Default value: 'root@localhost'

fail2ban_agent

Data type: String

User-agent sent on HTTP requests that are made by some actions.

Default value: 'Fail2Ban/%(fail2ban_version)s'

Defined types

fail2ban::action

fail2ban/manifests/action.pp

• Copyright (C) 2014-2019 gabster@lelutin.ca

Actions define what fail2ban should do when if finds mischief happening in logs. Usually, an action defines commands that should be run during setup/teardown and commands for when a ban or an unban happen. Using action you can make fail2ban whatever you want, from creating an iptables rule to calling out to your edge server API to create a rule there instead.

• See also
  • jail.conf(5)

Examples

defining a new action to call out to a REST API

fail2ban::action { 'rest_api':
  ensure      => present,
  actionban   => ['curl -s -X PUT http://yourapi:8080/theapi/v4/firewall/rules -H "Content-Type:application/json" -H "Authorization: ..." -d "{\"ban\": \"<ip>\"}"'],
  actionunban => ['curl -s -X DELETE http://yourapi:8080/theapi/v4/firewall/rules/1 -H "Authorization: ..."'],
}

Parameters

The following parameters are available in the fail2ban::action defined type:

• ensure
• config_file_mode
• timeout
• init
• includes
• includes_after
• additional_defs
• actionban
• actionunban
• actioncheck
• actionstart
• actionstop

ensure

Data type: Enum['present', 'absent']

Whether the resources should be installed or removed.

Default value: 'present'

config_file_mode

Data type: String

Permission mode given to the filter file created by this defined type.

Default value: '0644'

timeout

Data type: Optional[Integer[1]]

Special tag in the Init section that, if present, defines the maximum period of time in seconds that an action command can be executed before being killed.

Default value: undef

init

Data type: Array[String]

List of arbitrary lines that will be a part of the [Init] section. All tags (variables) defined in this section can be overridden by any individual jail to change the action's behaviour.

Default value: []

includes

Data type: Array[String]

List of files to include before considering the rest of the action definition. These files can declare variables used by the action to set default or common behaviours.

Default value: []

includes_after

Data type: Array[String]

List of files to include after action definition.

Default value: []

additional_defs

Data type: Array[String]

List of arbitrary lines that should appear at the begining of the action's definition section, for anything that didn't fit in other parameters. Each item in the list is output on its own line in the action file. No syntax checking is done.

Default value: []

actionban

Data type: Array[String[1], 1]

List of commands that are executed when fail2ban has found too many matches for a given IP address.

actionunban

Data type: Array[String[1], 1]

List of commands that are executed after bantime has elapsed.

actioncheck

Data type: Array[String[1]]

List of commands that are run by fail2ban before any other action to verify that the environment (or setup) is still in good shape.

Default value: []

actionstart

Data type: Array[String[1]]

List of commands that are executed when the jail is started.

Default value: []

actionstop

Data type: Array[String[1]]

List of commands that are executed when the jail is stopped.

Default value: []

fail2ban::filter

fail2ban/manifests/filter.pp

• Copyright (C) 2014-2018 gabster@lelutin.ca

Filters are how fail2ban detects mischief in logs. They contain regular expressions that should catch bad activity and identify the IP that is doing this activity.

• See also
  • https://fail2ban.readthedocs.io/en/latest/filters.html
  • https://github.com/fail2ban/fail2ban/blob/0.11/man/jail.conf.5
    • jail.conf(5)

Examples

defining filter for jenkins

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>',
  ],
}

Parameters

The following parameters are available in the fail2ban::filter defined type:

• filter_template
• failregexes
• ensure
• config_file_mode
• init
• includes
• includes_after
• additional_defs
• prefregex
• ignoreregexes
• maxlines
• datepattern
• journalmatch

filter_template

Data type: String[1]

Path to the epp template given to the epp() function in order to render the filter file.

Default value: 'fail2ban/filter.epp'

failregexes

Data type: Array[String, 1]

List of regular expressions that will be run against new log lines as they reach fail2ban. The regular expressions follow the Python regular expression format, and there are some special patterns that fail2ban can use. See the jail.conf(5) man page for more details. Each item in the list is placed on its own line. Lines starting with the second one are prepended with spaces so that the regular expressions line up with the beginning of the first one.

ensure

Data type: Enum['present', 'absent']

Whether the resources should be installed or removed.

Default value: 'present'

config_file_mode

Data type: String

Permission mode given to the filter file created by this defined type.

Default value: '0644'

init

Data type: Array[String]

List of arbitrary lines that should appear in the optional filter Init section. Variable definitions in the Init section can be overridden by users in *.local files. Each item in the list is output on its own line in the filter file. No syntax checking is done.

Default value: []

includes

Data type: Array[String, 0]

List of files to include before considering the rest of the filter definition. These files can declare variables used by the filter to set default behaviours.

Default value: []

includes_after

Data type: Array[String, 0]

List of files to include after filter definition.

Default value: []

additional_defs

Data type: Array[String, 0]

List of arbitrary lines that should appear at the begining of the filter's definition section, for anything that didn't fit in other parameters. Each item in the list is output on its own line in the filter file. No syntax checking is done.

Default value: []

prefregex

Data type: Optional[String]

If this is set, it contains a regular expression that should be used to parse (after datepattern found a match) a common part to all messages that can then match a smaller failregex or ignoreregex. If this regex does not match, then failregex or ignoreregex are not even tried.

Default value: undef

ignoreregexes

Data type: Array[String, 0]

List of Python regular expressions that should prevent a log line from being considered for banning. If a line matches regular expressions contained in this parameter, they are ignored even though they would have matched a failregex. Each item in the list is placed on its own line. Lines starting with the second one are prepended with spaces so that the regular expressions line up with the beginning of the first one.

Default value: []

maxlines

Data type: Optional[Integer[1]]

Maximum number of lines that fail2ban should buffer for matching multi-line regexes.

Default value: undef

datepattern

Data type: Optional[String]

Custom date pattern/regex for the log file. This is useful if dates use a non-standard formatting.

Default value: undef

journalmatch

Data type: Optional[String]

If the log backend is set to systemd, this specifies a matching pattern to filter journal entries.

Default value: undef

fail2ban::jail

fail2ban/manifests/jail.pp

• Copyright (C) 2014-2018 gabster@lelutin.ca

Jails are the top level of fail2ban configuration; what you'll be using most often to setup protection of a service from bruteforce attempts or pesky attack traffic. They rely on a filter to find out IPs that are doing mischief, and then use an action to ban (and subsequently unban) IPs.

Most parameters of this defined type are used for overriding what has been set in the global context in jail.conf/jail.local (see parameters to the fail2ban class). They are not mandatory if you can reuse the global values.

• See also
  • https://github.com/fail2ban/fail2ban/blob/0.11/man/jail.conf.5
    • jail.conf(5)

Examples

creating simple jail for service

fail2ban::jail { 'honeypot':
  findtime => 300,
  maxretry => 1,
  port     => 'all',
  logpath  => ['/var/log/honeypot.log'],
}

using a pre-defined jail

$ssh_params = lookup('fail2ban::jail::sshd')
fail2ban::jail { 'sshd':
  * => $ssh_params,
}

overriding parameters from a pre-defined jail

$ssh_extra_params  = {
  'bantime'  => 300,
  'findtime' => 200,
  'maxretry' => 3,
}
$ssh_params = lookup('fail2ban::jail::sshd') + $ssh_extra_params
fail2ban::jail { 'sshd':
  * => $ssh_params,
}

Parameters

The following parameters are available in the fail2ban::jail defined type:

• ensure
• config_file_mode
• enabled
• mode
• backend
• usedns
• filter
• logpath
• logencoding
• logtimezone
• prefregex
• failregex
• ignoreregex
• ignoreself
• ignoreip
• ignorecommand
• ignorecache
• maxretry
• maxmatches
• findtime
• action
• bantime
• banaction
• banaction_allports
• chain
• port
• protocol
• mta
• destemail
• sender
• fail2ban_agent
• additional_options

ensure

Data type: Enum['present','absent']

Whether resources for the defined jail should be installed or removed.

Default value: 'present'

config_file_mode

Data type: String

Permission mode given to the jail file created by this defined type.

Default value: '0644'

enabled

Data type: Boolean

Whether or not a jail is enabled. Setting this to false makes it possible to keep configuration around for a certain jail but temporarily disable it.

Default value: true

mode

Data type: Optional[String]

Change the behavior of the filter used by this jail. The mode will generally determine which regular expressions the filter will include. The values that this can take are determined by each individual filter. To know exactly which values are available in filters, you need to read their configuration files.

Default value: undef

backend

Data type: Optional[Fail2ban::Backend]

Method used by fail2ban to obtain new log lines from the log file(s) in logpath.

Default value: undef

usedns

Data type: Optional[Fail2ban::Usedns]

Whether or not to resolve DNS hostname of IPs that have been found by a failregex.

Default value: undef

filter

Data type: Optional[String]

Name of the filter to use for this jail. The default value for the filter is usually to use a filter with the same name as the jail name (although this could be changed by the filter parameter on the fail2ban class).

Default value: undef

logpath

Data type: Array[String]

Array of absolute paths to the log files against which regular expressions should be verified to catch activity that you want to block. This parameter must be set to a non-empty array when not using the 'systemd' backend, however it must be empty if the 'systemd' backend is used.

Default value: []

logencoding

Data type: Optional[String]

Name of the encoding of log files. If set to "auto", fail2ban will use what is set in the system's locale setting.

Default value: undef

logtimezone

Data type: Optional[String]

Force a timezone if the logs don't specify them on timestamps.

Default value: undef

prefregex

Data type: Optional[String[1]]

Regular expression to parse common part in every message for this jail.

Default value: undef

failregex

Data type: Optional[Array[String[1]]]

Regular expressions to add to the failregex of the filter used by this jail.

Default value: undef

ignoreregex

Data type: Optional[Array[String[1]]]

Regular expressions to add to the ignoreregex of the filter used by this jail.

Default value: undef

ignoreself

Data type: Optional[Boolean]

If set to false, fail2ban will not ignore IP addresses, for this jail, that are bound to interfaces on the host.

Default value: undef

ignoreip

Data type: Optional[Array[String, 1]]

List of IPs or CIDR prefixes to ignore when identifying matches of failregex. The IPs that fit the descriptions in this parameter will never get banned by the jail.

Default value: undef

ignorecommand

Data type: Optional[String]

Command used to determine if an IP should found by a failregex be ignored. This can be used to have a more complex and dynamic method of listing and identifying IPs that should not get banned. It can be used also when ignoreip is present.

Default value: undef

ignorecache

Data type: Optional[String]

If set, caches the results from ignoreip, ignoreself and ignorecommand for a set amount of time to avoid calling ignorecommand repeatedly.

Default value: undef

maxretry

Data type: Optional[Integer[1]]

Number of failregex matches during findtime after which an IP gets banned.

Default value: undef

maxmatches

Data type: Optional[Variant[Integer[1], String]]

Number of matches stored in ticket.

Default value: undef

findtime

Data type: Optional[Fail2ban::Time]

Time period in seconds during which maxretry number of matches will get an IP banned.

Default value: undef

action

Data type: Optional[Variant[String, Array[String, 1]]]

List of actions that should be used to ban and unban IPs when maxretry matches of failregex has happened for an IP during findtime.

Default value: undef

bantime

Data type: Optional[Fail2ban::Time]

Time period in seconds for which an IP is banned if maxretry matches of failregex happen for the same IP during findtime.

Default value: undef

banaction

Data type: Optional[String]

Name of the action that is extrapolated in default action definitions, or in the action param. This can let you override the action name but keep the default parameters to the action.

Default value: undef

banaction_allports

Data type: Optional[String]

Action name that can be extrapolated by some of the default actions. This one is meant to ban all ports at once instead of specific ones. Setting this will change the action for this jail.

Default value: undef

chain

Data type: Optional[String]

Name of the iptables chain used by iptables-based actions.

Default value: undef

port

Data type: Optional[Fail2ban::Port]

Comma separated list of ports, port ranges or service names (as found in /etc/services) that should get blocked by the ban action.

Default value: undef

protocol

Data type: Optional[Fail2ban::Protocol]

Name of the protocol to ban using the action.

Default value: undef

mta

Data type: Optional[String]

Program name used for sending out email by actions that do so.

Default value: undef

destemail

Data type: Optional[String]

Email address used as recipient by actions that send out emails. Setting this will override destemail for this jail only.

Default value: undef

sender

Data type: Optional[String]

Email address set as sender by actions that send out emails.

Default value: undef

fail2ban_agent

Data type: Optional[String]

User-agent sent on HTTP requests that are made by some actions.

Default value: undef

additional_options

Data type: Hash[String, String]

Hash of additional values that should be declared for the jail. Keys represent the jail configuration value names and hash values are placed to the right of the "=". This can be used to declare arbitrary values for filters or actions to use. No syntax checking is done on the contents of this hash. Note that any keys in this hash that correspond to a parameter name for this defined type will get overridden by the value that the defined type's parameter was given (e.g. if there is mode => '0600' in additional_options, the value of mode in the file on disk will not take on the value '0600' since there is a resource parameter that already corresponds to this key name).

Default value: {}

Data types

Fail2ban::Backend

Backend names that fail2ban understands Can be one of the pre-defined backend names, "systemd" with optionally a list of parameters between square brackets or a python-style variable

Alias of Variant[Enum['auto','pyinotify','gamin','polling'], Pattern[/^systemd(\[.*\]$)?/], Pattern[/%\(\w+\)s/]]

Fail2ban::Dbfile

Where fail2ban's database gets stored. None disables storage

Alias of Variant[Stdlib::Absolutepath, Enum['None']]

Fail2ban::Loglevel

How much logging is needed from fail2ban

Alias of Enum['CRITICAL', 'ERROR', 'WARNING', 'NOTICE', 'INFO', 'DEBUG', 'TRACEDEBUG', 'HEAVYDEBUG']

Fail2ban::Logtarget

Where logs are sent

Alias of Variant[Stdlib::Absolutepath, Enum['SYSLOG', 'STDERR', 'STDOUT']]

Fail2ban::Port

Possible values for the port parameter ports can be specified by number, but you can also pass in a comma-separated list of values in a string. The values in the string can be port numbers (integers), a range of port numbers in the format 'number:number', service names (looked up in /etc/services) or 'all' which is translated to '0:65535'

Alias of Variant[Integer, String]

Fail2ban::Protocol

Options for protocol type This is used by the default action iptables-multiport to defined what protocol to ban for the specified ports.

Alias of Enum['tcp', 'udp', 'icmp', 'all']

Fail2ban::Syslogsocket

Path to a socket for communication with syslog, or 'auto' for letting fail2ban auto-discover the path.

Alias of Variant[Stdlib::Absolutepath, Enum['auto']]

Fail2ban::Time

Time in seconds for some configuration options can be specified either in an integer number of seconds, or an abbreviation that can help specify some time periods more easily

Time abbreviation can be combined to make a more precise amount. For example 1d3h20m

• See also
  • https://github.com/fail2ban/fail2ban/blob/master/man/jail.conf.5
  • jail.conf(5)

Alias of Variant[Integer[1], Pattern[/^(\d+(ye(a(r(s)?)?)?|yy?|mo(n(th(s)?)?)?|we(e(k(s)?)?)?|ww?|da(y(s)?)?|dd?|ho(u(r(s)?)?)?|hh?|mi(n(ute(s)?)?)?|mm?|se(c(ond(s)?)?)?|ss?))+$/]]

Fail2ban::Usedns

Possible values for usedns parameter

Alias of Enum['yes', 'no', 'warn', 'raw']