Skip to content

Commit f9d55a9

Browse files
georglauterbachgeorglauterbach
authored
docs: update F2B docs & bind mount links (docker-mailserver#3293)
1 parent 223c766 commit f9d55a9

4 files changed

Lines changed: 74 additions & 78 deletions

File tree

‎docs/content/config/security/fail2ban.md‎

Lines changed: 66 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -4,117 +4,109 @@ hide:
44
- toc # Hide Table of Contents for this page
55
---
66

7-
Fail2Ban is installed automatically and bans IP addresses for 1 week after 2 failed attempts in a time frame of 1 week by default.
7+
!!! quote "What is Fail2Ban (F2B)?"
88

9-
## Configuration files
9+
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.
1010

11-
If you want to change this, you can easily edit our github example file: [`config-examples/fail2ban-jail.cf`][github-file-f2bjail].
11+
[Source][wikipedia-fail2ban]
1212

13-
You can do the same with the values from `fail2ban.conf`, e.g `dbpurgeage`. In that case you need to edit: [`config-examples/fail2ban-fail2ban.cf`][github-file-f2bconfig].
13+
[wikipedia-fail2ban]: https://en.wikipedia.org/wiki/Fail2ban
1414

15-
The configuration files need to be located at the root of the `/tmp/docker-mailserver/` volume bind (usually `./docker-data/dms/config/:/tmp/docker-mailserver/`).
15+
## Configuration
1616

17-
This following configuration files from `/tmp/docker-mailserver/` will be copied during container startup.
17+
!!! warning
1818

19-
- `fail2ban-jail.cf` -> `/etc/fail2ban/jail.d/user-jail.local`
20-
- `fail2ban-fail2ban.cf` -> `/etc/fail2ban/fail2ban.local`
21-
22-
### Docker-compose config
23-
24-
Example configuration volume bind:
25-
26-
```yaml
27-
volumes:
28-
- ./docker-data/dms/config/:/tmp/docker-mailserver/
29-
```
30-
31-
!!! attention
32-
33-
DMS must be launched with the `NET_ADMIN` capability in order to be able to install the nftables rules that actually ban IP addresses.
34-
35-
Thus either include `--cap-add=NET_ADMIN` in the `docker run` command, or the equivalent in `docker-compose.yml`:
19+
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.yml`:
3620

3721
```yaml
3822
cap_add:
3923
- NET_ADMIN
4024
```
4125

42-
## Running fail2ban in a rootless container
26+
!!! bug "Running Fail2Ban on Older Kernels"
4327

44-
[`RootlessKit`][rootless::rootless-kit] is the _fakeroot_ implementation for supporting _rootless mode_ in Docker and Podman. By default RootlessKit uses the [`builtin` port forwarding driver][rootless::port-drivers], which does not propagate source IP addresses.
28+
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).
4529

46-
It is necessary for `fail2ban` 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`][rootless::slirp4netns], which is slower than `builtin` but does preserve the real source IPs.
30+
### DMS Defaults
4731

48-
### Docker with `slirp4netns` port driver
32+
DMS will automatically ban IP addresses of hosts that have generated 2 failed attempts over the course of the last week. The bans themselves last for one week.
4933

50-
For [rootless mode][rootless::docker] in Docker, create `~/.config/systemd/user/docker.service.d/override.conf` with the following content:
34+
### Custom Files
5135

52-
```
53-
[Service]
54-
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"
55-
```
36+
!!! question "What is [`docker-data/dms/config/`][docs-dms-config-volume]?"
37+
38+
This following configuration files inside the `docker-data/dms/config/` volume will be copied inside the container during startup
39+
40+
1. `fail2ban-jail.cf` is copied to `/etc/fail2ban/jail.d/user-jail.local`
41+
- with this file, you can adjust the configuration of individual jails and their defaults
42+
- the is an example provided [in our repository on GitHub][github-file-f2bjail]
43+
2. `fail2ban-fail2ban.cf` is copied to `/etc/fail2ban/fail2ban.local`
44+
- with this file, you can adjust F2B behavior in general
45+
- the is an example provided [in our repository on GitHub][github-file-f2bconfig]
46+
47+
[docs-dms-config-volume]: ../../faq.md#what-about-the-docker-datadmsconfig-directory
48+
[github-file-f2bjail]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/fail2ban-jail.cf
49+
[github-file-f2bconfig]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/fail2ban-fail2ban.cf
5650

57-
And then restart the daemon:
51+
### Managing Bans
5852

59-
```console
60-
$ systemctl --user daemon-reload
61-
$ systemctl --user restart docker
53+
You can manage F2B with the `setup` script. The usage looks like this:
54+
55+
```bash
56+
docker exec <CONTAINER NAME> setup fail2ban [<ban|unban> <IP>]
6257
```
6358

64-
!!! note
59+
When just running `setup fail2ban`, the script will show all banned IP addresses.
6560

66-
This changes the port driver for all rootless containers managed by Docker.
61+
## Running Inside A Rootless Container
6762

68-
Per container configuration is not supported, if you need that consider Podman instead.
63+
[`RootlessKit`][rootless::rootless-kit] is the _fakeroot_ implementation for supporting _rootless mode_ in Docker and Podman. By default, RootlessKit uses the [`builtin` port forwarding driver][rootless::port-drivers], which does not propagate source IP addresses.
6964

70-
### Podman with `slirp4netns` port driver
65+
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`][rootless::slirp4netns], which is slower than the builtin driver but does preserve the real source IPs.
7166

72-
[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `docker-compose.yml`.
67+
[rootless::rootless-kit]: https://github.com/rootless-containers/rootlesskit
68+
[rootless::port-drivers]: https://github.com/rootless-containers/rootlesskit/blob/v0.14.5/docs/port.md#port-drivers
69+
[rootless::slirp4netns]: https://github.com/rootless-containers/slirp4netns
7370

71+
=== "Docker"
7472

75-
You must also add the ENV `NETWORK_INTERFACE=tap0`, because Podman uses a [hard-coded interface name][rootless::podman::interface] for `slirp4netns`.
73+
For [rootless mode][rootless::docker] in Docker, create `~/.config/systemd/user/docker.service.d/override.conf` with the following content:
7674

75+
!!! danger inline end
7776

78-
!!! example
77+
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.
7978

80-
```yaml
81-
services:
82-
mailserver:
83-
network_mode: "slirp4netns:port_handler=slirp4netns"
84-
environment:
85-
- ENABLE_FAIL2BAN=1
86-
- NETWORK_INTERFACE=tap0
87-
...
79+
```cf
80+
[Service]
81+
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"
8882
```
8983

90-
!!! note
91-
92-
`slirp4netns` is not compatible with user-defined networks.
84+
And then restart the daemon:
9385

94-
## Manage bans
86+
```console
87+
$ systemctl --user daemon-reload
88+
$ systemctl --user restart docker
89+
```
9590

96-
You can also manage and list the banned IPs with the [`setup.sh`][docs-setupsh] script.
91+
[rootless::docker]: https://docs.docker.com/engine/security/rootless
9792

98-
### List bans
93+
=== "Podman"
9994

100-
```sh
101-
./setup.sh fail2ban
102-
```
95+
[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yml`:
10396

104-
### Un-ban
97+
!!! example
10598

106-
Here `192.168.1.15` is our banned IP.
99+
```yaml
100+
services:
101+
mailserver:
102+
network_mode: "slirp4netns:port_handler=slirp4netns"
103+
environment:
104+
- ENABLE_FAIL2BAN=1
105+
- NETWORK_INTERFACE=tap0
106+
...
107+
```
107108

108-
```sh
109-
./setup.sh fail2ban unban 192.168.1.15
110-
```
109+
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!
111110

112-
[docs-setupsh]: ../setup.sh.md
113-
[github-file-f2bjail]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/fail2ban-jail.cf
114-
[github-file-f2bconfig]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/fail2ban-fail2ban.cf
115-
[rootless::rootless-kit]: https://github.com/rootless-containers/rootlesskit
116-
[rootless::port-drivers]: https://github.com/rootless-containers/rootlesskit/blob/v0.14.5/docs/port.md#port-drivers
117-
[rootless::slirp4netns]: https://github.com/rootless-containers/slirp4netns
118-
[rootless::docker]: https://docs.docker.com/engine/security/rootless
119-
[rootless::podman]: https://github.com/containers/podman/blob/v3.4.1/docs/source/markdown/podman-run.1.md#--networkmode---net
120-
[rootless::podman::interface]: https://github.com/containers/podman/blob/v3.4.1/libpod/networking_slirp4netns.go#L264
111+
[rootless::podman]: https://github.com/containers/podman/blob/v3.4.1/docs/source/markdown/podman-run.1.md#--networkmode---net
112+
[rootless::podman::interface]: https://github.com/containers/podman/blob/v3.4.1/libpod/networking_slirp4netns.go#L264

‎docs/content/config/security/rspamd.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,15 +99,15 @@ DMS brings sane default settings for Rspamd. They are located at `/etc/rspamd/lo
9999

100100
### Manually
101101

102-
If you want to overwrite the default settings and / or provide your own settings, you can place files at `docker-data/dms/config/rspamd/override.d/` (a directory that is linked to `/etc/rspamd/override.d/`, if it exists) to override Rspamd and DMS default settings.
102+
!!! question "What is [`docker-data/dms/config/`][docs-dms-config-volume]?"
103103

104-
!!! note "What is [`docker-data/dms/config/`][docs-dms-config-volume]?"
104+
If you want to overwrite the default settings and / or provide your own settings, you can place files at `docker-data/dms/config/rspamd/override.d/` (a directory that is linked to `/etc/rspamd/override.d/`, if it exists) to override Rspamd and DMS default settings.
105105

106106
!!! warning "Clashing Overrides"
107107

108108
Note that when also [using the `rspamd-commands` file](#with-the-help-of-a-custom-file), files in `override.d` may be overwritten in case you adjust them manually and with the help of the file.
109109

110-
[docs-dms-config-volume]: ../../faq.md#what-about-the-docker-datadmsmail-state-folder
110+
[docs-dms-config-volume]: ../../faq.md#what-about-the-docker-datadmsconfig-directory
111111

112112
### With the Help of a Custom File
113113

‎docs/content/faq.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ None! No database is required. The filesystem is the database. This image is bas
1010

1111
Mails are stored in `/var/mail/${domain}/${username}`. Since `v9.0.0` it is possible to add custom `user_attributes` for each accounts to have a different mailbox configuration (See [#1792][github-issue-1792]).
1212

13+
### What About the `docker-data/dms/config/` Directory?
14+
15+
This documentation and all example configuration files in the GitHub repository use `docker-data/dms/config/` to refer to the directory in the host that is mounted (e.g. via a bind mount) to `/tmp/docker-mailserver/` inside the container,.
16+
1317
### How are IMAP mailboxes (_aka IMAP Folders_) set up?
1418

1519
`INBOX` is setup by default with the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash`. You can learn how to modify or add your own folders (_including additional special folders like `Archive`_) by visiting our docs page [_Customizing IMAP Folders_](../examples/use-cases/imap-folders) for more information.

‎docs/content/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Usage
44

55
This pages explains how to get started with DMS. The guide uses Docker Compose as a reference. In our examples, a volume mounts the host location [`docker-data/dms/config/`][docs-dms-config-volume] to `/tmp/docker-mailserver/` inside the container.
66

7-
[docs-dms-config-volume]: ./config/advanced/optional-config.md
7+
[docs-dms-config-volume]: ./faq.md#what-about-the-docker-datadmsconfig-directory
88

99
## Preliminary Steps
1010

0 commit comments

Comments
 (0)