search

voxpupuli / puppet-fail2ban

This module installs, configures and manages the Fail2ban service.
Apache License 2.0
31 stars 106 forks source link
centos-puppet-module debian-puppet-module hacktoberfest linux-puppet-module opensuse-puppet-module puppet redhat-puppet-module ubuntu-puppet-module

readme

fail2ban

Build Status Code Coverage Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores

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
  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
  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

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

Jails available

Pre-defined jails

RedHat

Debian

Suse

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

Supported OSes and dependencies are given into metadata.json file.

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