Fail2Ban Configuration Documentation: jail.local and fail2ban.local -

This documentation explains the key configurable values for fail2ban.local and jail.local in Fail2Ban. These files allow you to customize Fail2Ban behavior, manage which services are protected, and set specific options for each service.

Overview of Fail2Ban Configuration #

fail2ban.local: Used to define global configurations for the Fail2Ban service, such as logging, ban time, and retry limits.
jail.local: Contains the settings for individual services that Fail2Ban should monitor, such as SSH, HTTP, or custom services.

Both files are optional and override the default configurations found in fail2ban.conf and jail.conf. Modifications to .local files are preserved during upgrades.

`fail2ban.local` Configuration Options #

The fail2ban.local file is where you customize global settings. Below are the key options and their possible values:

General Settings #

loglevel:
- Description: Defines the verbosity of logs.
- Possible Values:
  - CRITICAL: Logs only critical errors.
  - ERROR: Logs errors.
  - WARNING: Logs warnings.
  - NOTICE: Logs notices.
  - INFO: Logs information messages.
  - DEBUG: Logs detailed debugging information.
- Default: INFO
logtarget:
- Description: Specifies where Fail2Ban should write log data.
- Possible Values:
  - syslog: Logs to syslog.
  - /path/to/logfile: Logs to a specific file.
  - STDOUT: Logs to the console.
- Default: /var/log/fail2ban.log
socket:
- Description: Path to the socket file used by Fail2Ban for communication.
- Possible Values: Path to the socket file, such as /var/run/fail2ban/fail2ban.sock.
- Default: /var/run/fail2ban/fail2ban.sock

Ban Settings #

bantime:
- Description: Duration (in seconds) for which an IP address is banned after failing authentication.
- Possible Values:
  - Any positive integer (e.g., 3600 for 1 hour).
  - -1 for a permanent ban.
- Default: 600 (10 minutes)
maxretry:
- Description: Number of failed attempts before banning an IP.
- Possible Values: Any positive integer (e.g., 5 for 5 attempts).
- Default: 5
findtime:
- Description: Time window (in seconds) during which maxretry failed attempts must occur for an IP to be banned.
- Possible Values: Any positive integer (e.g., 600 for 10 minutes).
- Default: 600 (10 minutes)
ignoreip:
- Description: Specifies IP addresses or ranges that should never be banned.
- Possible Values: IP addresses or CIDR ranges (e.g., 127.0.0.1/8, 192.168.0.0/16).
- Default: None (no IPs are ignored).

Email Notifications #

mta:
- Description: Mail Transfer Agent (MTA) used to send email notifications.
- Possible Values:
  - sendmail: Uses Sendmail to send emails.
  - mail: Uses the mail command.
- Default: sendmail
sendername:
- Description: Name of the email sender.
- Possible Values: Any valid string (e.g., Fail2Ban).
- Default: Fail2Ban
destemail:
- Description: Email address to which notifications should be sent.
- Possible Values: Any valid email address (e.g., admin@example.com).
- Default: root@localhost

`jail.local` Configuration Options #

The jail.local file defines settings for specific jails (services). Each jail monitors log files for failed login attempts or suspicious activity and takes the appropriate action (ban or notify).

Common Jail Options #

enabled:
- Description: Determines whether a specific jail is enabled.
- Possible Values:
  - true: Enable the jail.
  - false: Disable the jail.
- Default: false
port:
- Description: The port number or service name that the jail monitors.
- Possible Values:
  - A specific port number (e.g., 22 for SSH).
  - A service name (e.g., ssh).
- Default: Varies per service.
logpath:
- Description: Path to the log file the jail should monitor for suspicious activity.
- Possible Values: Any valid file path (e.g., /var/log/auth.log).
- Default: Varies per service (e.g., /var/log/auth.log for SSH).
filter:
- Description: The filter to use for matching log entries (each filter corresponds to a service or custom log entry pattern).
- Possible Values:
  - Predefined filters like sshd, apache-auth.
  - Custom filter names can also be created.
- Default: Varies by service.

Example Jail Configurations

SSH Jail #

[sshd]
enabled = true
port = ssh
logpath = /var/log/auth.log
maxretry = 5
findtime = 600
bantime = 3600

HTTP Authentication Jail #

[apache-auth]
enabled = true
port = http,https
logpath = /var/log/apache2/error.log
maxretry = 3
findtime = 600
bantime = 600

Custom Jail for FTP #

[vsftpd]
enabled = true
port = ftp
logpath = /var/log/vsftpd.log
filter = vsftpd
maxretry = 5
bantime = 7200

Ban Actions #

Each jail can be configured with a different banning action:

banaction:
- Description: The action Fail2Ban should take when banning an IP.
- Possible Values:
  - iptables-multiport: Uses iptables to ban across multiple ports.
  - firewalld: Uses Firewalld for managing the ban.
  - nftables: Uses nftables for banning.
  - Custom actions can also be defined.
- Default: iptables-multiport

Example jail.local File

Here’s a sample jail.local configuration that includes multiple jails (services):

# jail.local

[DEFAULT]
# Ban settings for all jails
bantime = 3600       # 1-hour ban
findtime = 600       # Must fail 5 times in 10 minutes
maxretry = 5         # Ban after 5 failed attempts
ignoreip = 127.0.0.1/8 ::1

[sshd]
enabled = true
port = ssh
logpath = /var/log/auth.log

[apache-auth]
enabled = true
port = http,https
logpath = /var/log/apache2/error.log

[vsftpd]
enabled = true
port = ftp
logpath = /var/log/vsftpd.log
filter = vsftpd
bantime = 7200       # Ban for 2 hours

Conclusion #

By configuring fail2ban.local and jail.local, you can customize Fail2Ban to meet the specific security requirements of your server. Use the global settings in fail2ban.local to define default behaviors like logging, ban duration, and email notifications. In jail.local, you can enable and configure jails to monitor different services, such as SSH, web servers, or FTP, with each having its own parameters like log path, ban action, and retry limits.