Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

fail2ban

Manage fail2ban bruteforce protector
Project URLRSS FeedReport issues

67,501 downloads

501 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 4.0.1 (latest)
  • 4.0.0
  • 3.3.1
  • 3.3.0
  • 3.2.4
  • 3.2.3
  • 3.2.2
  • 3.2.1
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.0.3
  • 2.0.2
  • 2.0.0
  • 1.3.0
  • 1.2.1
  • 1.2.0
  • 1.1.0
  • 1.0.2
  • 1.0.1
  • 1.0.0
released Feb 1st 2016
This version is compatible with:
  • , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'LeLutin-fail2ban', '1.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add LeLutin-fail2ban
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install LeLutin-fail2ban --version 1.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: iptables, fail2ban, firewall, bruteforce, nftables

Documentation

LeLutin/fail2ban — version 1.1.0 Feb 1st 2016

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:

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

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)
  • puppetlabs' concat module (at least version 1.0.0)

Compatibility

This module supports

  • Debian 7 and 8
  • RHEL 6 and 7
  • CentOs 6 and 7

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 separated by spaces
  • 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 'polling'
  • 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.

Defining jails

To define a jail, you can use one of the predefined jails (see list below). Or you can define your own with the fail2ban::jail defined type:

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

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.
  • ensure Should this jail be present or not. Default value is present.
  • enabled Should this jail be enabled or not. The subtility between ensure 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 in jail.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 default banaction. If you don't also override action, 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 this IP).
  • order Optional numerical position. This lets you order jails as you see fit.

Predefined jails

  • apache_noscript
  • apache_overflows
  • apache
  • asterisk
  • courierauth
  • couriersmtp
  • dovecot
  • dropbear
  • named_refused_tcp
  • pam_generic
  • postfix
  • proftpd
  • pure_ftpd
  • sasl
  • sendmailauth
  • sendmailreject
  • ssh_ddos
  • ssh
  • vsftpd
  • wuftpd
  • xinetd_fail

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

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