diff --git a/README.md b/README.md index f38510f3..e7b2534a 100644 --- a/README.md +++ b/README.md @@ -40,12 +40,6 @@ operating systems and distributions. * fail2ban configuration file. * fail2ban service. -### Setup Requirements - -* Puppet >= 3.0 -* Facter >= 1.6 -* [Extlib module](https://github.com/voxpupuli/puppet-extlib) -* [Stdlib module](https://github.com/puppetlabs/puppetlabs-stdlib) ### Beginning with fail2ban @@ -181,174 +175,6 @@ Disable the fail2ban service. } ``` -## 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](#custom-jails). - -#### `banaction` - -Determines which action to perform when performing a global ban (not overridden -in a specific jail). - ## Jails available ### Pre-defined jails @@ -649,13 +475,7 @@ fail2ban::sendmail_config: ## Limitations -This module has been tested on: - -* Debian 8/9/10 -* Ubuntu 16.04/18.04/20.04 -* RedHat 6/7/8/9 -* CentOS 6/7/8/9 -* OpenSuSE 15 +Supported OSes and dependencies are given into metadata.json file. ## Development diff --git a/REFERENCE.md b/REFERENCE.md index a674eb9b..49a96084 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -6,15 +6,25 @@ ### Classes -* [`fail2ban`](#fail2ban): == Class: fail2ban -* [`fail2ban::config`](#fail2ban--config): == Class: fail2ban::config +#### Public Classes + +* [`fail2ban`](#fail2ban): Installs, configures and manages the Fail2ban service. * [`fail2ban::install`](#fail2ban--install): == Class: fail2ban::install -* [`fail2ban::service`](#fail2ban--service): == Class: fail2ban::service + +#### Private Classes + +* `fail2ban::config`: Handles the configuration file. +* `fail2ban::service`: Handles the service. ### Defined types +#### Public Defined types + * [`fail2ban::define`](#fail2ban--define): == Define: fail2ban::define -* [`fail2ban::jail`](#fail2ban--jail): == Define: fail2ban::jail + +#### Private Defined types + +* `fail2ban::jail`: Handles the packages. ### Tasks @@ -26,18 +36,17 @@ ### `fail2ban` -== Class: fail2ban +This module installs, configures and manages the Fail2ban service. +Main class, includes all other classes. #### Parameters The following parameters are available in the `fail2ban` class: -* [`config_file_before`](#-fail2ban--config_file_before) * [`package_ensure`](#-fail2ban--package_ensure) * [`package_name`](#-fail2ban--package_name) * [`package_list`](#-fail2ban--package_list) * [`config_dir_path`](#-fail2ban--config_dir_path) -* [`config_dir_filter_path`](#-fail2ban--config_dir_filter_path) * [`config_dir_purge`](#-fail2ban--config_dir_purge) * [`config_dir_recurse`](#-fail2ban--config_dir_recurse) * [`config_dir_source`](#-fail2ban--config_dir_source) @@ -64,24 +73,20 @@ The following parameters are available in the `fail2ban` class: * [`iptables_chain`](#-fail2ban--iptables_chain) * [`jails`](#-fail2ban--jails) * [`maxretry`](#-fail2ban--maxretry) -* [`default_backend`](#-fail2ban--default_backend) * [`whitelist`](#-fail2ban--whitelist) * [`custom_jails`](#-fail2ban--custom_jails) * [`banaction`](#-fail2ban--banaction) +* [`config_file_before`](#-fail2ban--config_file_before) +* [`config_dir_filter_path`](#-fail2ban--config_dir_filter_path) +* [`default_backend`](#-fail2ban--default_backend) * [`sendmail_config`](#-fail2ban--sendmail_config) * [`sendmail_actions`](#-fail2ban--sendmail_actions) -##### `config_file_before` - -Data type: `String[1]` - - - ##### `package_ensure` Data type: `Enum['absent', 'latest', 'present', 'purged']` - +Determines if the package should be installed. Default value: `'present'` @@ -89,7 +94,7 @@ Default value: `'present'` Data type: `String[1]` - +Determines the name of package to manage. Default value: `'fail2ban'` @@ -97,7 +102,7 @@ Default value: `'fail2ban'` Data type: `Optional[Array[String]]` - +Determines if additional packages should be managed. Default value: `undef` @@ -105,23 +110,15 @@ Default value: `undef` Data type: `Stdlib::Absolutepath` - +Determines if the configuration directory should be managed. Default value: `'/etc/fail2ban'` -##### `config_dir_filter_path` - -Data type: `Stdlib::Absolutepath` - - - -Default value: `'/etc/fail2ban/filter.d'` - ##### `config_dir_purge` Data type: `Boolean` - +Determines if unmanaged configuration files should be removed. Default value: `false` @@ -129,7 +126,7 @@ Default value: `false` Data type: `Boolean` - +Determines if the configuration directory should be recursively managed. Default value: `true` @@ -137,7 +134,7 @@ Default value: `true` Data type: `Optional[String]` - +Determines the source of a configuration directory. Default value: `undef` @@ -145,7 +142,7 @@ Default value: `undef` Data type: `Stdlib::Absolutepath` - +Determines if the configuration file should be managed. Default value: `'/etc/fail2ban/jail.conf'` @@ -153,7 +150,7 @@ Default value: `'/etc/fail2ban/jail.conf'` Data type: `String[1]` - +Determines which user should own the configuration file. Default value: `'root'` @@ -161,7 +158,7 @@ Default value: `'root'` Data type: `String[1]` - +Determines which group should own the configuration file. Default value: `'root'` @@ -169,7 +166,7 @@ Default value: `'root'` Data type: `String[1]` - +Determines the desired permissions mode of the configuration file. Default value: `'0644'` @@ -177,7 +174,7 @@ Default value: `'0644'` Data type: `Optional[String[1]]` - +Determines the source of a configuration file. Default value: `undef` @@ -185,7 +182,7 @@ Default value: `undef` Data type: `Optional[String[1]]` - +Determines the content of a configuration file. Default value: `undef` @@ -193,7 +190,7 @@ Default value: `undef` Data type: `Optional[String[1]]` - +Determines the content of a configuration file. Default value: `undef` @@ -201,7 +198,7 @@ Default value: `undef` Data type: `String[1]` - +Determines if the service should be restarted after configuration changes. Default value: `'Service[fail2ban]'` @@ -209,7 +206,7 @@ Default value: `'Service[fail2ban]'` Data type: `String[1]` - +Determines which package a configuration file depends on. Default value: `'Package[fail2ban]'` @@ -217,7 +214,7 @@ Default value: `'Package[fail2ban]'` Data type: `Hash[String[1], Any]` - +Determines which configuration files should be managed via `fail2ban::define`. Default value: `{}` @@ -225,7 +222,7 @@ Default value: `{}` Data type: `Hash` - +Determines which parameters should be passed to an ERB template. Default value: `{}` @@ -233,7 +230,7 @@ Default value: `{}` Data type: `Enum['absent', 'present']` - +Determines whether the file `/etc/fail2ban/jail.d/defaults-debian.conf` should be deleted or not. Default value: `'absent'` @@ -241,7 +238,7 @@ Default value: `'absent'` Data type: `Enum['absent', 'present']` - +Determines whether the file `/etc/fail2ban/jail.d/00-firewalld.conf` should be deleted or not. Default value: `'absent'` @@ -249,7 +246,7 @@ Default value: `'absent'` Data type: `Enum['running', 'stopped']` - +Determines if the service should be running or not. Default value: `'running'` @@ -257,7 +254,7 @@ Default value: `'running'` Data type: `String[1]` - +Determines the name of service to manage. Default value: `'fail2ban'` @@ -265,7 +262,7 @@ Default value: `'fail2ban'` Data type: `Boolean` - +Determines if the service should be enabled at boot. Default value: `true` @@ -273,7 +270,7 @@ Default value: `true` Data type: `String[1]` - +Determines how banned ip addresses should be reported. Default value: `'action_mb'` @@ -281,7 +278,7 @@ Default value: `'action_mb'` Data type: `Variant[Integer[0], String[1]]` - +Determines how many seconds ip addresses will be banned. Default value: `432000` @@ -289,7 +286,7 @@ Default value: `432000` Data type: `String[1]` - +Determines which email address should be notified about restricted hosts and suspicious logins. Default value: `"fail2ban@${facts['networking']['domain']}"` @@ -297,7 +294,7 @@ Default value: `"fail2ban@${facts['networking']['domain']}"` Data type: `String[1]` - +Determines which email address should notify about restricted hosts and suspicious logins. Default value: `"fail2ban@${facts['networking']['fqdn']}"` @@ -305,7 +302,7 @@ Default value: `"fail2ban@${facts['networking']['fqdn']}"` Data type: `String[1]` - +Determines chain where jumps will to be added in iptables-\* actions. Default value: `'INPUT'` @@ -313,7 +310,7 @@ Default value: `'INPUT'` Data type: `Array[String[1]]` - +Determines which services should be protected by Fail2ban. Default value: `['ssh', 'ssh-ddos']` @@ -321,23 +318,15 @@ Default value: `['ssh', 'ssh-ddos']` Data type: `Integer[0]` - +Determines the number of failed login attempts needed to block a host. Default value: `3` -##### `default_backend` - -Data type: `Enum['pyinotify', 'gamin', 'polling', 'systemd', 'auto']` - - - -Default value: `'auto'` - ##### `whitelist` Data type: `Array` - +Determines which ip addresses will not be reported Default value: `['127.0.0.1/8', '192.168.56.0/24']` @@ -345,7 +334,7 @@ Default value: `['127.0.0.1/8', '192.168.56.0/24']` Data type: `Hash[String, Hash]` - +Determines which custom jails should be included Default value: `{}` @@ -353,10 +342,32 @@ Default value: `{}` Data type: `String[1]` - +Determines which action to perform when performing a global ban (not overridden in a specific jail). Default value: `'iptables-multiport'` +##### `config_file_before` + +Data type: `String[1]` + + + +##### `config_dir_filter_path` + +Data type: `Stdlib::Absolutepath` + + + +Default value: `'/etc/fail2ban/filter.d'` + +##### `default_backend` + +Data type: `Enum['pyinotify', 'gamin', 'polling', 'systemd', 'auto']` + + + +Default value: `'auto'` + ##### `sendmail_config` Data type: `Hash` @@ -373,18 +384,10 @@ Data type: `Hash` Default value: `{}` -### `fail2ban::config` - -== Class: fail2ban::config - ### `fail2ban::install` == Class: fail2ban::install -### `fail2ban::service` - -== Class: fail2ban::service - ## Defined types ### `fail2ban::define` @@ -486,231 +489,6 @@ Data type: `Hash` Default value: `$fail2ban::config_file_options_hash` -### `fail2ban::jail` - -== Define: fail2ban::jail - -#### Parameters - -The following parameters are available in the `fail2ban::jail` defined type: - -* [`filter_includes`](#-fail2ban--jail--filter_includes) -* [`filter_failregex`](#-fail2ban--jail--filter_failregex) -* [`filter_ignoreregex`](#-fail2ban--jail--filter_ignoreregex) -* [`filter_maxlines`](#-fail2ban--jail--filter_maxlines) -* [`filter_datepattern`](#-fail2ban--jail--filter_datepattern) -* [`filter_additional_config`](#-fail2ban--jail--filter_additional_config) -* [`enabled`](#-fail2ban--jail--enabled) -* [`action`](#-fail2ban--jail--action) -* [`filter`](#-fail2ban--jail--filter) -* [`logpath`](#-fail2ban--jail--logpath) -* [`maxretry`](#-fail2ban--jail--maxretry) -* [`findtime`](#-fail2ban--jail--findtime) -* [`bantime`](#-fail2ban--jail--bantime) -* [`port`](#-fail2ban--jail--port) -* [`backend`](#-fail2ban--jail--backend) -* [`journalmatch`](#-fail2ban--jail--journalmatch) -* [`ignoreip`](#-fail2ban--jail--ignoreip) -* [`config_dir_filter_path`](#-fail2ban--jail--config_dir_filter_path) -* [`config_file_owner`](#-fail2ban--jail--config_file_owner) -* [`config_file_group`](#-fail2ban--jail--config_file_group) -* [`config_file_mode`](#-fail2ban--jail--config_file_mode) -* [`config_file_source`](#-fail2ban--jail--config_file_source) -* [`config_file_notify`](#-fail2ban--jail--config_file_notify) -* [`config_file_require`](#-fail2ban--jail--config_file_require) - -##### `filter_includes` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `filter_failregex` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `filter_ignoreregex` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `filter_maxlines` - -Data type: `Optional[Integer]` - - - -Default value: `undef` - -##### `filter_datepattern` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `filter_additional_config` - -Data type: `Any` - - - -Default value: `undef` - -##### `enabled` - -Data type: `Boolean` - - - -Default value: `true` - -##### `action` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `filter` - -Data type: `String` - - - -Default value: `$title` - -##### `logpath` - -Data type: `Optional[String[1]]` - - - -Default value: `undef` - -##### `maxretry` - -Data type: `Integer` - - - -Default value: `$fail2ban::maxretry` - -##### `findtime` - -Data type: `Optional[Integer]` - - - -Default value: `undef` - -##### `bantime` - -Data type: `Integer` - - - -Default value: `$fail2ban::bantime` - -##### `port` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `backend` - -Data type: `Optional[String]` - - - -Default value: `undef` - -##### `journalmatch` - -Data type: `Optional[String[1]]` - - - -Default value: `undef` - -##### `ignoreip` - -Data type: `Array[Stdlib::IP::Address]` - - - -Default value: `[]` - -##### `config_dir_filter_path` - -Data type: `Stdlib::Absolutepath` - - - -Default value: `$fail2ban::config_dir_filter_path` - -##### `config_file_owner` - -Data type: `Optional[String]` - - - -Default value: `$fail2ban::config_file_owner` - -##### `config_file_group` - -Data type: `Optional[String]` - - - -Default value: `$fail2ban::config_file_group` - -##### `config_file_mode` - -Data type: `Optional[String]` - - - -Default value: `$fail2ban::config_file_mode` - -##### `config_file_source` - -Data type: `Optional[String]` - - - -Default value: `$fail2ban::config_file_source` - -##### `config_file_notify` - -Data type: `Optional[String]` - - - -Default value: `$fail2ban::config_file_notify` - -##### `config_file_require` - -Data type: `Optional[String]` - - - -Default value: `$fail2ban::config_file_require` - ## Tasks ### `banip` diff --git a/manifests/config.pp b/manifests/config.pp index d30b9886..3bbb31d0 100644 --- a/manifests/config.pp +++ b/manifests/config.pp @@ -1,6 +1,10 @@ -# == Class: fail2ban::config +# @summary Handles the configuration file. +# +# @api private # class fail2ban::config { + assert_private() + file { 'fail2ban.dir': ensure => $fail2ban::config_dir_ensure, path => $fail2ban::config_dir_path, diff --git a/manifests/init.pp b/manifests/init.pp index bebc12b3..da87f670 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,4 +1,41 @@ -# == Class: fail2ban +# @summary Installs, configures and manages the Fail2ban service. +# +# This module installs, configures and manages the Fail2ban service. +# Main class, includes all other classes. +# +# @param package_ensure Determines if the package should be installed. +# @param package_name Determines the name of package to manage. +# @param package_list Determines if additional packages should be managed. +# @param config_dir_path Determines if the configuration directory should be managed. +# @param config_dir_purge Determines if unmanaged configuration files should be removed. +# @param config_dir_recurse Determines if the configuration directory should be recursively managed. +# @param config_dir_source Determines the source of a configuration directory. +# @param config_file_path Determines if the configuration file should be managed. +# @param config_file_owner Determines which user should own the configuration file. +# @param config_file_group Determines which group should own the configuration file. +# @param config_file_mode Determines the desired permissions mode of the configuration file. +# @param config_file_source Determines the source of a configuration file. +# @param config_file_string Determines the content of a configuration file. +# @param config_file_template Determines the content of a configuration file. +# @param config_file_notify Determines if the service should be restarted after configuration changes. +# @param config_file_require Determines which package a configuration file depends on. +# @param config_file_hash Determines which configuration files should be managed via `fail2ban::define`. +# @param config_file_options_hash Determines which parameters should be passed to an ERB template. +# @param manage_defaults Determines whether the file `/etc/fail2ban/jail.d/defaults-debian.conf` should be deleted or not. +# @param manage_firewalld Determines whether the file `/etc/fail2ban/jail.d/00-firewalld.conf` should be deleted or not. +# @param service_ensure Determines if the service should be running or not. +# @param service_name Determines the name of service to manage. +# @param service_enable Determines if the service should be enabled at boot. +# @param action Determines how banned ip addresses should be reported. +# @param bantime Determines how many seconds ip addresses will be banned. +# @param email Determines which email address should be notified about restricted hosts and suspicious logins. +# @param sender Determines which email address should notify about restricted hosts and suspicious logins. +# @param iptables_chain Determines chain where jumps will to be added in iptables-\* actions. +# @param jails Determines which services should be protected by Fail2ban. +# @param maxretry Determines the number of failed login attempts needed to block a host. +# @param whitelist Determines which ip addresses will not be reported +# @param custom_jails Determines which custom jails should be included +# @param banaction Determines which action to perform when performing a global ban (not overridden in a specific jail). # class fail2ban ( String[1] $config_file_before, diff --git a/manifests/jail.pp b/manifests/jail.pp index a49c24f6..cbb7ab62 100644 --- a/manifests/jail.pp +++ b/manifests/jail.pp @@ -1,4 +1,4 @@ -# == Define: fail2ban::jail +# @summary Handles the jails. # define fail2ban::jail ( Optional[String] $filter_includes = undef, diff --git a/manifests/service.pp b/manifests/service.pp index dcd64372..874be2d6 100644 --- a/manifests/service.pp +++ b/manifests/service.pp @@ -1,6 +1,10 @@ -# == Class: fail2ban::service +# @summary Handles the service. +# +# @api private # class fail2ban::service { + assert_private() + if $fail2ban::service_name { service { 'fail2ban': ensure => $fail2ban::_service_ensure,