Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

fail2ban

Manage fail2ban; works with roles/profiles; plays nicely with firewall module
Project URLRSS FeedReport issues

26,975 downloads

15,190 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.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

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.

Download
Tags: iptables, fail2ban, firewall

Documentation

calmenergy/fail2ban — version 1.2.0 Jul 18th 2018

fail2ban

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.

Setup

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':}

or 

   include ::fail2ban

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

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

Usage

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  => ['172.24.8.0/24', 'localhost', 'myserver.com'],
        backend   => 'auto',
   }

Defining custom filters

  ::fail2ban::filter{'myfilter':
     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'],
   }

Reference

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

Requirements

This module depends on:

Compatibility

This module supports

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

Development

Contributions and pull requests are welcome.

Contributors

https://github.com/calmenergy/calmenergy-fail2ban/graphs/contributors

Release Notes/Etc

See the CHANGELOG.md for release notes.