- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with fail2ban
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Jails available
- Development - Guide for contributing to the module
This module installs, configures and manages the Fail2ban service.
This module handles installing, configuring and running Fail2ban across a range of operating systems and distributions.
- fail2ban package.
- fail2ban configuration file.
- fail2ban service.
- Puppet >= 3.0
- Facter >= 1.6
- Extlib module
- Stdlib module
Install fail2ban with the default parameters (No configuration files will be changed).
class { 'fail2ban': }
Install fail2ban with the recommended parameters.
class { 'fail2ban':
config_file_template => "fail2ban/${::lsbdistcodename}/etc/fail2ban/jail.conf.epp",
}
You'll find an example on examples folder for each operating system. Previous example show how to enable config for every supported operating system, using ${::lsbdistcodename} fact.
You can also manually specify a different configuration template. To do it, instead of the one using ${::lsbdistcodename} fact, use your desired configuration template:
class { 'fail2ban':
config_file_template => "fail2ban/${::lsbdistcodename}/etc/fail2ban/jail.conf.epp"
}
Or using Hiera:
fail2ban::config_file_template: "fail2ban/%{::lsbdistcodename}/etc/fail2ban/jail.conf.epp"
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/fail2ban/${::lsbdistcodename}/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/fail2ban/${::lsbdistcodename}/etc/fail2ban",
}
Deploy the configuration file from source.
class { 'fail2ban':
config_file_source => "puppet:///modules/fail2ban/${::lsbdistcodename}/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 => "fail2ban/${::lsbdistcodename}/etc/fail2ban/jail.conf.epp",
}
Deploy the configuration file from custom template (Additional parameters can be defined).
class { 'fail2ban':
config_file_template => "fail2ban/${::lsbdistcodename}/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/fail2ban/${::lsbdistcodename}/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 => "fail2ban/${::lsbdistcodename}/etc/fail2ban/jail.4th.conf.epp",
},
},
}
Disable the fail2ban service.
class { 'fail2ban':
service_ensure => 'stopped',
}
- fail2ban: Main class, includes all other classes.
- fail2ban::install: Handles the packages.
- fail2ban::config: Handles the configuration file.
- fail2ban::service: Handles the service.
Determines if the package should be installed. Valid values are 'present', 'latest', 'absent' and 'purged'. Defaults to 'present'.
Determines the name of package to manage. Defaults to 'fail2ban'.
Determines if additional packages should be managed. Defaults to 'undef'.
Determines if the configuration directory should be present. Valid values are 'absent' and 'directory'. Defaults to 'directory'.
Determines if the configuration directory should be managed. Defaults to '/etc/fail2ban'
Determines if unmanaged configuration files should be removed. Valid values are 'true' and 'false'. Defaults to 'false'.
Determines if the configuration directory should be recursively managed. Valid values are 'true' and 'false'. Defaults to 'true'.
Determines the source of a configuration directory. Defaults to 'undef'.
Determines if the configuration file should be managed. Defaults to '/etc/fail2ban/jail.conf'
Determines which user should own the configuration file. Defaults to 'root'.
Determines which group should own the configuration file. Defaults to 'root'.
Determines the desired permissions mode of the configuration file. Defaults to '0644'.
Determines the source of a configuration file. Defaults to 'undef'.
Determines the content of a configuration file. Defaults to 'undef'.
Determines the content of a configuration file. Defaults to 'undef'.
Determines if the service should be restarted after configuration changes. Defaults to 'Service[fail2ban]'.
Determines which package a configuration file depends on. Defaults to 'Package[fail2ban]'.
Determines which configuration files should be managed via fail2ban::define
.
Defaults to '{}'.
Determines which parameters should be passed to an ERB template. Defaults to '{}'.
Determines if the service should be running or not. Valid values are 'running' and 'stopped'. Defaults to 'running'.
Determines the name of service to manage. Defaults to 'fail2ban'.
Determines if the service should be enabled at boot. Valid values are 'true' and 'false'. Defaults to 'true'.
Determines how banned ip addresses should be reported. Defaults to 'action_mb'.
Determines how many seconds ip addresses will be banned. Defaults to '432000'.
Determines which email address should be notified about restricted hosts and suspicious logins. Defaults to "fail2ban@${::domain}".
Determines which email address should notify about restricted hosts and suspicious logins. Defaults to 'fail2ban@${::fqdn}'.
Determines chain where jumps will to be added in iptables-* actions. Defaults to 'INPUT'.
Determines which services should be protected by Fail2ban. Defaults to '['ssh', 'ssh-ddos']'.
Determines the number of failed login attempts needed to block a host. Defaults to '3'.
Determines which ip addresses will not be reported. Defaults to '['127.0.0.1/8', '192.168.56.0/24']'.
Determines which custom jails should be included (see Custom jails.
Determines which action to perform when performing a global ban (not overridden in a specific jail).
- 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
- apache
- apache-modsecurity
- apache-multiport
- apache-nohome
- apache-noscript
- apache-overflows
- asterisk-tcp
- asterisk-udp
- courierauth
- couriersmtp
- dovecot
- dropbear
- ejabberd-auth
- freeswitch
- lighttpd-auth
- lighttpd-fastcgi
- mysqld-auth
- nagios
- named-refused-tcp
- nginx-http-auth
- pam-generic
- php-url-fopen
- postfix
- proftpd
- pure-ftpd
- recidive
- roundcube-auth
- sasl
- sogo-auth
- ssh
- ssh-blocklist
- ssh-ddos
- ssh-iptables-ipset4
- ssh-iptables-ipset6
- ssh-route
- vsftpd
- wuftpd
- xinetd-fail
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']
This module has been tested on:
- Debian 6/7/8
- Ubuntu 12.04/14.04/16.04/18.04
- RedHat 5/6/7
- CentOS 5/6/7
If you find a bug, have trouble following the documentation or have a question about this module - please create an issue.
If you are able to patch the bug or add the feature yourself - please make a pull request.
The list of contributors can be found at: https://github.com/voxpupuli/puppet-fail2ban/graphs/contributors