Skip to content

Latest commit

 

History

History
808 lines (409 loc) · 18.4 KB

REFERENCE.md

File metadata and controls

808 lines (409 loc) · 18.4 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

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

Defined types

Data types

  • Fail2ban::Logpath: Describes logpath format allowed
  • Fail2ban::Time: Describes time format allowed for bantime and findtime The time entries in fail2ban configuration (like findtime or bantime) can be provided

Tasks

  • banip: Ban IPs in a jail
  • unban: Unban IP in all jails and database
  • unbanip: Unban IP in a jail

Classes

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:

package_ensure

Data type: Enum['absent', 'latest', 'present', 'purged']

Determines if the package should be installed.

Default value: 'present'

package_name

Data type: String[1]

Determines the name of package to manage.

Default value: 'fail2ban'

package_list

Data type: Optional[Array[String]]

Determines if additional packages should be managed.

Default value: undef

config_dir_path

Data type: Stdlib::Absolutepath

Determines if the configuration directory should be managed.

Default value: '/etc/fail2ban'

config_dir_purge

Data type: Boolean

Determines if unmanaged configuration files should be removed.

Default value: false

config_dir_recurse

Data type: Boolean

Determines if the configuration directory should be recursively managed.

Default value: true

config_dir_source

Data type: Optional[String]

Determines the source of a configuration directory.

Default value: undef

config_file_path

Data type: Stdlib::Absolutepath

Determines if the configuration file should be managed.

Default value: '/etc/fail2ban/jail.conf'

config_file_owner

Data type: String[1]

Determines which user should own the configuration file.

Default value: 'root'

config_file_group

Data type: String[1]

Determines which group should own the configuration file.

Default value: 'root'

config_file_mode

Data type: String[1]

Determines the desired permissions mode of the configuration file.

Default value: '0644'

config_file_source

Data type: Optional[String[1]]

Determines the source of a configuration file.

Default value: undef

config_file_string

Data type: Optional[String[1]]

Determines the content of a configuration file.

Default value: undef

config_file_template

Data type: Optional[String[1]]

Determines the content of a configuration file.

Default value: undef

config_file_notify

Data type: String[1]

Determines if the service should be restarted after configuration changes.

Default value: 'Service[fail2ban]'

config_file_require

Data type: String[1]

Determines which package a configuration file depends on.

Default value: 'Package[fail2ban]'

config_file_hash

Data type: Hash[String[1], Any]

Determines which configuration files should be managed via fail2ban::define.

Default value: {}

config_file_options_hash

Data type: Hash

Determines which parameters should be passed to an ERB template.

Default value: {}

manage_defaults

Data type: Enum['absent', 'present']

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

Default value: 'absent'

manage_firewalld

Data type: Enum['absent', 'present']

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

Default value: 'absent'

service_ensure

Data type: Enum['running', 'stopped']

Determines if the service should be running or not.

Default value: 'running'

service_name

Data type: String[1]

Determines the name of service to manage.

Default value: 'fail2ban'

service_enable

Data type: Boolean

Determines if the service should be enabled at boot.

Default value: true

action

Data type: String[1]

Determines how banned ip addresses should be reported.

Default value: 'action_mb'

bantime

Data type: Fail2ban::Time

Determines how many time (second or hour or week) ip addresses will be banned.

Default value: 432000

email

Data type: String[1]

Determines which email address should be notified about restricted hosts and suspicious logins.

Default value: "fail2ban@${facts['networking']['domain']}"

sender

Data type: String[1]

Determines which email address should notify about restricted hosts and suspicious logins.

Default value: "fail2ban@${facts['networking']['fqdn']}"

iptables_chain

Data type: String[1]

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

Default value: 'INPUT'

jails

Data type: Array[String[1]]

Determines which services should be protected by Fail2ban.

Default value: ['ssh', 'ssh-ddos']

maxretry

Data type: Integer[0]

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

Default value: 3

whitelist

Data type: Array

Determines which ip addresses will not be reported

Default value: ['127.0.0.1/8', '192.168.56.0/24']

custom_jails

Data type: Hash[String, Hash]

Determines which custom jails should be included

Default value: {}

banaction

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

Default value: {}

sendmail_actions

Data type: Hash

Default value: {}

fail2ban::install

== Class: fail2ban::install

Defined types

fail2ban::define

== Define: fail2ban::define

Parameters

The following parameters are available in the fail2ban::define defined type:

config_file_path

Data type: Stdlib::Absolutepath

Default value: "${fail2ban::config_dir_path}/${title}"

config_file_owner

Data type: String

Default value: $fail2ban::config_file_owner

config_file_group

Data type: String

Default value: $fail2ban::config_file_group

config_file_mode

Data type: String

Default value: $fail2ban::config_file_mode

config_file_source

Data type: Optional[String]

Default value: undef

config_file_string

Data type: Optional[String]

Default value: undef

config_file_template

Data type: Optional[String]

Default value: undef

config_file_notify

Data type: String

Default value: $fail2ban::config_file_notify

config_file_require

Data type: String

Default value: $fail2ban::config_file_require

config_file_options_hash

Data type: Hash

Default value: $fail2ban::config_file_options_hash

fail2ban::jail

Handles the jails.

Parameters

The following parameters are available in the fail2ban::jail defined type:

logpath

Data type: Optional[Fail2ban::Logpath]

Filename(s) of the log files to be monitored

Default value: undef

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

maxretry

Data type: Integer

Default value: $fail2ban::maxretry

findtime

Data type: Optional[Fail2ban::Time]

Default value: undef

bantime

Data type: Fail2ban::Time

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

Data types

Fail2ban::Logpath

Describes logpath format allowed

Alias of Variant[String[1], Array[String[1]]]

Fail2ban::Time

Describes time format allowed for bantime and findtime The time entries in fail2ban configuration (like findtime or bantime) can be provided as integer in seconds or as string using special abbreviation format (e. g. 600 is the same as 10m).

Abbreviation tokens:

years?, yea?, yy? months?, mon? weeks?, wee?, ww? days?, da, dd? hours?, hou?, hh? minutes?, min?, mm? seconds?, sec?, ss?

The question mark (?) means the optional character, so day as well as days can be used.

You can combine multiple tokens in format (separated with space resp. without separator), e. g.: 1y 6mo or 1d12h30m. Note that tokens m as well as mm means minutes, for month use abbreviation mo or mon.

The time format can be tested using fail2ban-client:

   fail2ban-client --str2sec 1d12h

Alias of Variant[Integer[0], Pattern['^\d.*$']]

Tasks

banip

Ban IPs in a jail

Supports noop? false

Parameters

jail

Data type: String[1]

The jail to operate on

ips

Data type: Array[Stdlib::IP::Address]

IP addresses to ban

unban

Unban IP in all jails and database

Supports noop? false

Parameters

ips

Data type: Array[Stdlib::IP::Address]

IP addresses to unban

unbanip

Unban IP in a jail

Supports noop? false

Parameters

jail

Data type: String[1]

The jail to operate on

ips

Data type: Array[Stdlib::IP::Address]

IP addresses to unban