Forge Home


Manage fail2ban; works with roles/profiles; plays nicely with firewall module


13,441 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

  • 1.2.0 (latest)
  • 1.1.0
  • 1.0.1
  • 1.0.0
released Jul 18th 2018
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.0.0 < 6.0.0
  • , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'calmenergy-fail2ban', '1.2.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

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

Manually install this module globally with Puppet module tool:

puppet module install calmenergy-fail2ban --version 1.2.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.



calmenergy/fail2ban — version 1.2.0 Jul 18th 2018


Build Status contributions welcome

Table of Contents

  1. Module Description - What the module does and why it is useful
  2. Setup - The basics of getting started with fail2ban
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what fail2ban is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module

Module Description

The fail2ban module installs the fail2ban package, establishes local overrides to the distribution's config files, and configures and starts the fail2ban service.

It is designed to:

  • Play nicely with the puppetlabs firewall module, by not creating firewall rules that the firewall module will then purge.

  • Work well with the profile/roles pattern:

    * declaring the base class sets up and runs fail2ban, but does not activate any jails.
    * a profile that manages a particular service (e.g., sshd, apache) can also manage the jail associated with that service

As recommended by fail2ban's authors, this module makes no changes to the underlying fail2ban dstribution, instead using local overrides for configuration.

It works with Debian 7 or 8, RedHat 6 and 7, and CentOS 6 and 7. It requires puppet version 4.9.0 or newer, or Puppet Enterprise 2017.1 or newer.


What fail2ban affects

Other than the files associated with the fail2ban package itself, the fail2ban module creates a firewall chain (default name FAIL2BAN) and adds a jump to it at the beginning of the INPUT firewall chain.

Setup Requirements

This module itself has no special setup requirements. The fail2ban package imposes its own requirements. In particular, it needs access to a firewall system (typically iptables), and to the logfiles of any process it is instructed to monitor.

Note that if Puppet is managing fail2ban and the iptables firewall, and if fail2ban is configured to add rules to the INPUT chain,
puppet will see the rules that fail2ban has added as being unmanaged, and so Puppet will, by default, purge them. This module addresses that problem by creating a separate iptables chain (default name 'FAIL2BAN'), managing rules only in that chain, and adding to the beginning of the INPUT chain a jump to the FAIL2BAN chain.

Beginning with fail2ban

For a basic installation just declare or include the fail2ban class

   class {'::fail2ban':}


   include ::fail2ban

The basic installation includes no jails. Jails can be activated by declaring fail2ban::jail resources.



Stock installation

  • For a stock installation, just declare the fail2ban class, and declare a fail2ban::jail resource for every jail you wish to activate

Overriding default parameters

Use Hiera to provide alternatives to the default values for the fail2ban class

Activating built-in jails

To activate a built-in jail, using default parameters:

  ::fail2ban::jail {'sshd':}

To activate a built-in jail, modifying one or more parameters:

   ::fail2ban::jail {'sshd':
        bantime => 3600,

Defining custom jails

   ::fail2ban::jail {'myjail':
        port   => 2718,
        filter => 'myfilter',
        log_path => ['/var/log/myapp/log', '/var/log/myapp/other.log tail'],
        protocol => 'tcp',
        maxretry => 4,
        findtime => 300,
        action   => '%(action_mw)s',
        banaction => 'iptables-multiport',
        bantime   => 360,
        ignoreip  => ['', 'localhost', ''],
        backend   => 'auto',

Defining custom filters

     failregexes => ['^%(_apache_error_client)s (AH01789: )?(Digest: )?unknown algorithm `.*?' received: \S*(, referer: \S+)?\s*$'],
     ensure => present,
     ignoreregexes => ['bogus_error', 'just_kidding'],
     includes_before => ['myincludefile.conf', 'otherincludefile.conf'],
     includes_after  => ['cleanupfile.conf'],
     additional_defs   => ['foo = 2718', 'entropy_seed = 2917384297'],


All classes, types, and associated parameters are documented via puppet-strings.


This module depends on:


This module supports

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


Contributions and pull requests are welcome.


Release Notes/Etc

See the for release notes.