fail2ban

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
   • What fail2ban affects
   • Setup requirements
   • Beginning 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
   • Pre-defined jails
   • Custom jails
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.

Setup Requirements

• Puppet >= 3.0
• Facter >= 1.6
• Extlib module
• Stdlib module

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

Reference

Classes

Public Classes

• fail2ban: Main class, includes all other classes.

Private Classes

• fail2ban::install: Handles the packages.
• fail2ban::config: Handles the configuration file.
• fail2ban::service: Handles the service.

Parameters

package_ensure

Determines if the package should be installed. Valid values are 'present', 'latest', 'absent' and 'purged'. Defaults to 'present'.

package_name

Determines the name of package to manage. Defaults to 'fail2ban'.

package_list

Determines if additional packages should be managed. Defaults to 'undef'.

config_dir_ensure

Determines if the configuration directory should be present. Valid values are 'absent' and 'directory'. Defaults to 'directory'.

config_dir_path

Determines if the configuration directory should be managed. Defaults to '/etc/fail2ban'

config_dir_purge

Determines if unmanaged configuration files should be removed. Valid values are 'true' and 'false'. Defaults to 'false'.

config_dir_recurse

Determines if the configuration directory should be recursively managed. Valid values are 'true' and 'false'. Defaults to 'true'.

config_dir_source

Determines the source of a configuration directory. Defaults to 'undef'.

config_file_path

Determines if the configuration file should be managed. Defaults to '/etc/fail2ban/jail.conf'

config_file_owner

Determines which user should own the configuration file. Defaults to 'root'.

config_file_group

Determines which group should own the configuration file. Defaults to 'root'.

config_file_mode

Determines the desired permissions mode of the configuration file. Defaults to '0644'.

config_file_source

Determines the source of a configuration file. Defaults to 'undef'.

config_file_string

Determines the content of a configuration file. Defaults to 'undef'.

config_file_template

Determines the content of a configuration file. Defaults to 'undef'.

config_file_notify

Determines if the service should be restarted after configuration changes. Defaults to 'Service[fail2ban]'.

config_file_require

Determines which package a configuration file depends on. Defaults to 'Package[fail2ban]'.

config_file_hash

Determines which configuration files should be managed via fail2ban::define. Defaults to '{}'.

config_file_options_hash

Determines which parameters should be passed to an ERB template. Defaults to '{}'.

manage_defaults

Determines whether the file /etc/fail2ban/jail.d/defaults-debian.conf should be deleted or not. Defaults to 'absent'.

manage_firewalld

Determines whether the file /etc/fail2ban/jail.d/00-firewalld.conf should be deleted or not. Defaults to 'absent'.

service_ensure

Determines if the service should be running or not. Valid values are 'running' and 'stopped'. Defaults to 'running'.

service_name

Determines the name of service to manage. Defaults to 'fail2ban'.

service_enable

Determines if the service should be enabled at boot. Valid values are 'true' and 'false'. Defaults to 'true'.

action

Determines how banned ip addresses should be reported. Defaults to 'action_mb'.

bantime

Determines how many seconds ip addresses will be banned. Defaults to '432000'.

email

Determines which email address should be notified about restricted hosts and suspicious logins. Defaults to "fail2ban@${::domain}".

sender

Determines which email address should notify about restricted hosts and suspicious logins. Defaults to 'fail2ban@${::fqdn}'.

iptables_chain

Determines chain where jumps will to be added in iptables-* actions. Defaults to 'INPUT'.

jails

Determines which services should be protected by Fail2ban. Defaults to '['ssh', 'ssh-ddos']'.

maxretry

Determines the number of failed login attempts needed to block a host. Defaults to '3'.

whitelist

Determines which ip addresses will not be reported. Defaults to '['127.0.0.1/8', '192.168.56.0/24']'.

custom_jails

Determines which custom jails should be included (see Custom jails.

banaction

Determines which action to perform when performing a global ban (not overridden in a specific jail).

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

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

This module has been tested on:

• Debian 8/9/10
• Ubuntu 16.04/18.04/20.04
• RedHat 6/7/8
• CentOS 6/7/8

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