---
title: "Fail2Ban Configuration Documentation: jail.local and fail2ban.local"
description: "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`**:…"
url: "https://truehost.com/support/knowledge-base/fail2ban-configuration-documentation-jail-local-and-fail2ban-local/"
updated: "2024-10-15"
category: Cloud servers in Kenya
---

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