Forge Home

fail2ban

This module installs, configures and manages the Fail2ban service.

85,085 downloads

1,005 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

  • 5.0.2 (latest)
  • 5.0.1
  • 4.2.0
  • 4.1.0
  • 4.0.0
  • 3.3.0
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.4.1
  • 2.4.0
  • 2.3.0
  • 2.2.0
  • 2.1.0
  • 2.0.0
released Sep 19th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , , , ,
Tasks:
  • banip
  • unban
  • unbanip

Start using this module

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

Add this module to your Puppetfile:

mod 'puppet-fail2ban', '5.0.2'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

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

Manually install this module globally with Puppet module tool:

puppet module install puppet-fail2ban --version 5.0.2

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

Documentation

puppet/fail2ban — version 5.0.2 Sep 19th 2024

fail2ban

Build Status Code Coverage Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores

Table of Contents

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

Overview

This module installs, configures and manages the Fail2ban service.

Module Description

This module handles installing, configuring and running Fail2ban across a range of operating systems and distributions.

Setup

What fail2ban affects

  • fail2ban package.
  • fail2ban configuration file.
  • fail2ban service.

Beginning with fail2ban

Install and configure fail2ban:

    class { 'fail2ban': }

Config file template

You can also manually specify a different configuration template. To do it, use your desired configuration template (e.g. if your template is in your local profile):

  class { 'fail2ban':
    config_file_template => "profile/fail2ban/etc/fail2ban/jail.conf.epp"
  }

Or using Hiera:

fail2ban::config_file_template: "profile/fail2ban/etc/fail2ban/jail.conf.epp"

Usage

Update the fail2ban package.

    class { 'fail2ban':
      package_ensure => 'latest',
    }

Remove the fail2ban package.

    class { 'fail2ban':
      package_ensure => 'absent',
    }

Purge the fail2ban package (All configuration files will be removed).

    class { 'fail2ban':
      package_ensure => 'purged',
    }

Deploy the configuration files from source directory.

    class { 'fail2ban':
      config_dir_source => "puppet:///modules/profile/fail2ban/etc/fail2ban",
    }

Deploy the configuration files from source directory (Unmanaged configuration files will be removed).

    class { 'fail2ban':
      config_dir_purge  => true,
      config_dir_source => "puppet:///modules/profile/fail2ban/etc/fail2ban",
    }

Deploy the configuration file from source.

    class { 'fail2ban':
      config_file_source => "puppet:///modules/profile/fail2ban/etc/fail2ban/jail.conf",
    }

Deploy the configuration file from string.

    class { 'fail2ban':
      config_file_string => '# THIS FILE IS MANAGED BY PUPPET',
    }

Deploy the configuration file from template.

    class { 'fail2ban':
      config_file_template => "profile/fail2ban/etc/fail2ban/jail.conf.epp",
    }

Deploy the configuration file from custom template (Additional parameters can be defined).

    class { 'fail2ban':
      config_file_template     => "profile/fail2ban/etc/fail2ban/jail.conf.epp",
      config_file_options_hash => {
        'key' => 'value',
      },
    }

Deploy additional configuration files from source, string or template.

    class { 'fail2ban':
      config_file_hash => {
        'jail.2nd.conf' => {
          config_file_path   => '/etc/fail2ban/jail.2nd.conf',
          config_file_source => "puppet:///modules/profile/fail2ban/etc/fail2ban/jail.2nd.conf",
        },
        'jail.3rd.conf' => {
          config_file_path   => '/etc/fail2ban/jail.3rd.conf',
          config_file_string => '# THIS FILE IS MANAGED BY PUPPET',
        },
        'jail.4th.conf' => {
          config_file_path     => '/etc/fail2ban/jail.4th.conf',
          config_file_template => "profile/fail2ban/etc/fail2ban/jail.4th.conf.epp",
        },
      },
    }

Disable the fail2ban service.

    class { 'fail2ban':
      service_ensure => 'stopped',
    }

Jails available

Pre-defined jails

RedHat

  • 3proxy
  • apache-auth
  • apache-badbots
  • apache-botsearch
  • apache-fakegooglebot
  • apache-modsecurity
  • apache-nohome
  • apache-noscript
  • apache-overflows
  • apache-shellshock
  • assp
  • asterisk
  • counter-strike
  • 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
  • monit
  • mysqld-auth
  • nagios
  • named-refused
  • nginx-botsearch
  • nginx-http-auth
  • nsd
  • openwebmail
  • oracleims
  • pam-generic
  • pass2allow-ftp
  • perdition
  • php-url-fopen
  • portsentry
  • postfix
  • postfix-rbl
  • postfix-sasl
  • proftpd
  • pure-ftpd
  • qmail-rbl
  • recidive
  • roundcube-auth
  • selinux-ssh
  • sendmail-auth
  • sendmail-reject
  • sieve
  • sogo-auth
  • solid-pop3d
  • squid
  • squirrelmail
  • sshd
  • sshd-ddos
  • stunnel
  • suhosin
  • tine20
  • uwimap-auth
  • vsftpd
  • webmin-auth
  • wuftpd
  • xinetd-fail

Debian

  • 3proxy
  • apache-auth
  • apache-badbots
  • apache-botsearch
  • apache-fakegooglebot
  • apache-modsecurity
  • apache-multiport
  • apache-nohome
  • apache-noscript
  • apache-overflows
  • apache-shellshock
  • assp
  • asterisk
  • bitwarden
  • centreon
  • counter-strike
  • courierauth
  • courier-smtp
  • cyrus-imap
  • directadmin
  • domino-smtp
  • dovecot
  • dropbear
  • drupal-auth
  • ejabberd-auth
  • exim
  • exim-spam
  • freeswitch
  • froxlor-auth
  • groupoffice
  • gssftpd
  • guacamole
  • haproxy-http-auth
  • horde
  • kerio
  • lighttpd-auth
  • lighttpd-fastcgi
  • mongodb-auth
  • monit
  • murmur
  • mysqld-auth
  • nagios
  • named-refused
  • nginx-botsearch
  • nginx-http-auth
  • nginx-limit-req
  • 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
  • roundcube-auth
  • sasl
  • selinux-ssh
  • sendmail-auth
  • sendmail-reject
  • sieve
  • screensharing
  • slapd
  • sogo-auth
  • solid-pop3d
  • squid
  • squirrelmail
  • ssh
  • ssh-blocklist
  • ssh-ddos
  • ssh-iptables-ipset4
  • ssh-iptables-ipset6
  • ssh-route
  • stunnel
  • suhosin
  • tine20
  • traefik-auth
  • uwimap-auth
  • vsftpd
  • webmin-auth
  • wuftpd
  • xinetd-fail
  • zoneminder
  • znc-adminlog

Suse

  • 3proxy
  • apache-auth
  • apache-badbots
  • apache-botsearch
  • apache-common
  • apache-fakegooglebot
  • apache-modsecurity
  • apache-nohome
  • apache-noscript
  • apache-overflows
  • apache-pass
  • apache-shellshock
  • assp
  • asterisk
  • botsearch-common
  • common
  • counter-strike
  • courier-auth
  • courier-smtp
  • cyrus-imap
  • directadmin
  • domino-smtp
  • dovecot
  • dropbear
  • drupal-auth
  • ejabberd-auth
  • exim-common
  • exim-spam
  • exim
  • freeswitch
  • froxlor-auth
  • groupoffice
  • gssftpd
  • guacamole
  • haproxy-http-auth
  • horde
  • ignorecommands
  • kerio
  • lighttpd-auth
  • mongodb-auth
  • monit
  • murmur
  • mysqld-auth
  • nagios
  • named-refused
  • nginx-botsearch
  • nginx-http-auth
  • nginx-limit-req
  • nsd
  • openhab
  • openwebmail
  • oracleims
  • pam-generic
  • perdition
  • php-url-fopen
  • phpmyadmin-syslog
  • portsentry
  • postfix
  • proftpd
  • pure-ftpd
  • qmail
  • recidive
  • roundcube-auth
  • screensharingd
  • selinux-common
  • selinux-ssh
  • sendmail-auth
  • sendmail-reject
  • sieve
  • slapd
  • sogo-auth
  • solid-pop3d
  • squid
  • squirrelmail
  • sshd
  • stunnel
  • suhosin
  • tine20
  • uwimap-auth
  • vsftpd
  • webmin-auth
  • wuftpd
  • xinetd-fail
  • zoneminder

Custom jails

Users can add their own jails by using this YAML definition:

---
  fail2ban::custom_jails:
    'nginx-wp-login':
      filter_failregex: '<HOST>.*] "POST /wp-login.php'
      port: 'http,https'
      logpath: '/var/log/nginx/access.log'
      maxretry: 3
      findtime: 120
      bantime: 1200
      ignoreip: ['127.0.0.1', '192.168.1.1/24']
    'nginx-login':
      filter_failregex: '^<HOST> -.*POST /sessions HTTP/1\.." 200'
      action: 'iptables-multiport[name=NoLoginFailures, port="http,https"]'
      logpath: '/var/log/nginx*/*access*.log'
      maxretry: 6
      bantime: 600
      ignoreip: ['127.0.0.1', '192.168.1.1/24']

Sendmail notifications

Default e-mail notification are defined in /etc/fail2ban/action.d/sendmail-common.conf. Following configuration will create override config sendmail-common.local.

fail2ban::sendmail_actions:
  actionstart: ''
  actionstop: ''
fail2ban::sendmail_config:
  dest: root@localhost
  sender: fail2ban@localhost
  sendername: Fail2Ban

Limitations

Supported OSes and dependencies are given into metadata.json file.

Development

Bug Report

If you find a bug, have trouble following the documentation or have a question about this module - please create an issue.

Pull Request

If you are able to patch the bug or add the feature yourself - please make a pull request.

Contributors

The list of contributors can be found at: https://github.com/voxpupuli/puppet-fail2ban/graphs/contributors