docker-mailserver/docs/content/config/security/fail2ban.md

title	hide
Security | Fail2Ban	toc

!!! quote "What is Fail2Ban (F2B)?"

Fail2ban is an intrusion prevention software framework. Written in the Python programming language, it is designed to prevent against brute-force attacks. It is able to run on POSIX systems that have an interface to a packet-control system or firewall installed locally, such as \[NFTables\] or TCP Wrapper.

[Source][wikipedia-fail2ban]

[wikipedia-fail2ban]: https://en.wikipedia.org/wiki/Fail2ban

Configuration

!!! warning

DMS must be launched with the `NET_ADMIN` capability in order to be able to install the NFTables rules that actually ban IP addresses. Thus, either include `--cap-add=NET_ADMIN` in the `docker run` command, or the equivalent in the `compose.yaml`:

```yaml
cap_add:
  - NET_ADMIN
```

!!! bug "Running Fail2Ban on Older Kernels"

DMS configures F2B to use NFTables, not IPTables (legacy). We have observed that older systems, for example NAS systems, do not support the modern NFTables rules. You will need to configure F2B to use legacy IPTables again, for example with the [``fail2ban-jail.cf``][github-file-f2bjail], see the [section on configuration further down below](#custom-files).

DMS Defaults

DMS will automatically ban IP addresses of hosts that have generated 6 failed attempts over the course of the last week. The bans themselves last for one week. The Postfix jail is configured to use mode = extra in DMS.

Custom Files

!!! question "What is docker-data/dms/config/?"

This following configuration files inside the docker-data/dms/config/ volume will be copied inside the container during startup

1. fail2ban-jail.cf is copied to /etc/fail2ban/jail.d/user-jail.local
   • with this file, you can adjust the configuration of individual jails and their defaults
   • there is an example provided in our repository on GitHub
2. fail2ban-fail2ban.cf is copied to /etc/fail2ban/fail2ban.local
   • with this file, you can adjust F2B behavior in general
   • there is an example provided in our repository on GitHub

Viewing All Bans

When just running

setup fail2ban

the script will show all banned IP addresses.

To get a more detailed status view, run

setup fail2ban status

Managing Bans

You can manage F2B with the setup script. The usage looks like this:

docker exec <CONTAINER NAME> setup fail2ban [<ban|unban> <IP>]

Viewing the Log File

docker exec <CONTAINER NAME> setup fail2ban log

Running Inside A Rootless Container

RootlessKit is the fakeroot implementation for supporting rootless mode in Docker and Podman. By default, RootlessKit uses the builtin port forwarding driver, which does not propagate source IP addresses.

It is necessary for F2B to have access to the real source IP addresses in order to correctly identify clients. This is achieved by changing the port forwarding driver to slirp4netns, which is slower than the builtin driver but does preserve the real source IPs.

=== "Docker"

For [rootless mode][rootless::docker] in Docker, create `~/.config/systemd/user/docker.service.d/override.conf` with the following content:

!!! danger inline end

    This changes the port driver for all rootless containers managed by Docker. Per container configuration is not supported, if you need that consider Podman instead.

```cf
[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"
```

And then restart the daemon:

```console
$ systemctl --user daemon-reload
$ systemctl --user restart docker
```

[rootless::docker]: https://docs.docker.com/engine/security/rootless

=== "Podman"

[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yaml`:

!!! example

    ```yaml
    services:
      mailserver:
        network_mode: "slirp4netns:port_handler=slirp4netns"
        environment:
          - ENABLE_FAIL2BAN=1
          - NETWORK_INTERFACE=tap0
          ...
    ```

You must also add the ENV `NETWORK_INTERFACE=tap0`, because Podman uses a [hard-coded interface name][rootless::podman::interface] for `slirp4netns`. `slirp4netns` is not compatible with user-defined networks!

[rootless::podman]: https://github.com/containers/podman/blob/v3.4.1/docs/source/markdown/podman-run.1.md#--networkmode---net
[rootless::podman::interface]: https://github.com/containers/podman/blob/v3.4.1/libpod/networking_slirp4netns.go#L264