From 881c55a9671d057ecc8e6809cdc0cce2d725cc4e Mon Sep 17 00:00:00 2001 From: Fabien COMBERNOUS Date: Mon, 16 Sep 2024 16:49:56 +0200 Subject: [PATCH] Move parameters description from README to puppet-strings. Define some classes as private accordingly with README. --- README.md | 183 +------------------------------------------ REFERENCE.md | 142 +++++++++++++++++---------------- manifests/config.pp | 6 +- manifests/init.pp | 39 ++++++++- manifests/jail.pp | 2 +- manifests/service.pp | 6 +- 6 files changed, 120 insertions(+), 258 deletions(-) diff --git a/README.md b/README.md index f38510f3..5e12aedc 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,6 @@ 1. [Module Description - What the module does and why it is useful](#module-description) 1. [Setup - The basics of getting started with fail2ban](#setup) * [What fail2ban affects](#what-fail2ban-affects) - * [Setup requirements](#setup-requirements) * [Beginning with fail2ban](#beginning-with-fail2ban) 1. [Usage - Configuration options and additional functionality](#usage) 1. [Reference - An under-the-hood peek at what the module is doing and how](#reference) @@ -40,12 +39,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 +174,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 +474,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..9f831f63 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -6,15 +6,20 @@ ### 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 * [`fail2ban::define`](#fail2ban--define): == Define: fail2ban::define -* [`fail2ban::jail`](#fail2ban--jail): == Define: fail2ban::jail +* [`fail2ban::jail`](#fail2ban--jail): Handles the jails. ### Tasks @@ -26,18 +31,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 +68,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 +89,7 @@ Default value: `'present'` Data type: `String[1]` - +Determines the name of package to manage. Default value: `'fail2ban'` @@ -97,7 +97,7 @@ Default value: `'fail2ban'` Data type: `Optional[Array[String]]` - +Determines if additional packages should be managed. Default value: `undef` @@ -105,23 +105,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 +121,7 @@ Default value: `false` Data type: `Boolean` - +Determines if the configuration directory should be recursively managed. Default value: `true` @@ -137,7 +129,7 @@ Default value: `true` Data type: `Optional[String]` - +Determines the source of a configuration directory. Default value: `undef` @@ -145,7 +137,7 @@ Default value: `undef` Data type: `Stdlib::Absolutepath` - +Determines if the configuration file should be managed. Default value: `'/etc/fail2ban/jail.conf'` @@ -153,7 +145,7 @@ Default value: `'/etc/fail2ban/jail.conf'` Data type: `String[1]` - +Determines which user should own the configuration file. Default value: `'root'` @@ -161,7 +153,7 @@ Default value: `'root'` Data type: `String[1]` - +Determines which group should own the configuration file. Default value: `'root'` @@ -169,7 +161,7 @@ Default value: `'root'` Data type: `String[1]` - +Determines the desired permissions mode of the configuration file. Default value: `'0644'` @@ -177,7 +169,7 @@ Default value: `'0644'` Data type: `Optional[String[1]]` - +Determines the source of a configuration file. Default value: `undef` @@ -185,7 +177,7 @@ Default value: `undef` Data type: `Optional[String[1]]` - +Determines the content of a configuration file. Default value: `undef` @@ -193,7 +185,7 @@ Default value: `undef` Data type: `Optional[String[1]]` - +Determines the content of a configuration file. Default value: `undef` @@ -201,7 +193,7 @@ Default value: `undef` Data type: `String[1]` - +Determines if the service should be restarted after configuration changes. Default value: `'Service[fail2ban]'` @@ -209,7 +201,7 @@ Default value: `'Service[fail2ban]'` Data type: `String[1]` - +Determines which package a configuration file depends on. Default value: `'Package[fail2ban]'` @@ -217,7 +209,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 +217,7 @@ Default value: `{}` Data type: `Hash` - +Determines which parameters should be passed to an ERB template. Default value: `{}` @@ -233,7 +225,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 +233,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 +241,7 @@ Default value: `'absent'` Data type: `Enum['running', 'stopped']` - +Determines if the service should be running or not. Default value: `'running'` @@ -257,7 +249,7 @@ Default value: `'running'` Data type: `String[1]` - +Determines the name of service to manage. Default value: `'fail2ban'` @@ -265,7 +257,7 @@ Default value: `'fail2ban'` Data type: `Boolean` - +Determines if the service should be enabled at boot. Default value: `true` @@ -273,7 +265,7 @@ Default value: `true` Data type: `String[1]` - +Determines how banned ip addresses should be reported. Default value: `'action_mb'` @@ -281,7 +273,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 +281,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 +289,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 +297,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 +305,7 @@ Default value: `'INPUT'` Data type: `Array[String[1]]` - +Determines which services should be protected by Fail2ban. Default value: `['ssh', 'ssh-ddos']` @@ -321,23 +313,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 +329,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 +337,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 +379,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` @@ -488,7 +486,7 @@ Default value: `$fail2ban::config_file_options_hash` ### `fail2ban::jail` -== Define: fail2ban::jail +Handles the jails. #### Parameters 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,