Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/crazy-max/docker-fail2ban
Fail2ban Docker image
https://github.com/crazy-max/docker-fail2ban
alpine-linux docker docker-compose fail2ban firewall iptables
Last synced: 19 days ago
JSON representation
Fail2ban Docker image
- Host: GitHub
- URL: https://github.com/crazy-max/docker-fail2ban
- Owner: crazy-max
- License: mit
- Created: 2018-04-24T19:14:31.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-05-09T16:36:42.000Z (about 2 months ago)
- Last Synced: 2024-05-10T09:02:20.352Z (about 2 months ago)
- Topics: alpine-linux, docker, docker-compose, fail2ban, firewall, iptables
- Language: Dockerfile
- Homepage:
- Size: 344 KB
- Stars: 608
- Watchers: 13
- Forks: 78
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Support: .github/SUPPORT.md
Lists
- awesome-starred - crazy-max/docker-fail2ban - Fail2ban Docker image (docker)
- awesome - docker-fail2ban - Fail2ban Docker image based on Alpine Linux (Dockerfile)
- awesome-stars - crazy-max/docker-fail2ban - Fail2ban Docker image (Dockerfile)
- awesome-stars - docker-fail2ban - max | 260 | (Dockerfile)
README
## About
[Fail2ban](https://www.fail2ban.org) Docker image to ban hosts that cause
multiple authentication errors.
> **Note**
>
> Want to be notified of new releases? Check out 🔔 [Diun (Docker Image Update Notifier)](https://github.com/crazy-max/diun)
> project!
___
* [Build locally](#build-locally)
* [Image](#image)
* [Environment variables](#environment-variables)
* [Volumes](#volumes)
* [Usage](#usage)
* [Docker Compose](#docker-compose)
* [Command line](#command-line)
* [Upgrade](#upgrade)
* [Notes](#notes)
* [`DOCKER-USER` chain](#docker-user-chain)
* [`DOCKER-USER` and `INPUT` chains](#docker-user-and-input-chains)
* [Jails examples](#jails-examples)
* [Use iptables tooling without nftables backend](#use-iptables-tooling-without-nftables-backend)
* [Use fail2ban-client](#use-fail2ban-client)
* [Global jail configuration](#global-jail-configuration)
* [Custom jails, actions and filters](#custom-jails-actions-and-filters)
* [Contributing](#contributing)
* [License](#license)
## Build locally
```shell
git clone https://github.com/crazy-max/docker-fail2ban.git
cd docker-fail2ban
# Build image and output to docker (default)
docker buildx bake
# Build multi-platform image
docker buildx bake image-all
```
## Image
| Registry | Image |
|-----------------------------------------------------------------------------------------------------|------------------------------|
| [Docker Hub](https://hub.docker.com/r/crazymax/fail2ban/) | `crazymax/fail2ban` |
| [GitHub Container Registry](https://github.com/users/crazy-max/packages/container/package/fail2ban) | `ghcr.io/crazy-max/fail2ban` |
Following platforms for this image are available:
```
$ docker run --rm mplatform/mquery crazymax/fail2ban:latest
Image: crazymax/fail2ban:latest
* Manifest List: Yes
* Supported platforms:
- linux/amd64
- linux/arm/v6
- linux/arm/v7
- linux/arm64
- linux/386
- linux/ppc64le
- linux/s390x
```
## Environment variables
* `TZ`: The timezone assigned to the container (default `UTC`)
* `F2B_LOG_TARGET`: Set the log target. This could be a file, SYSLOG, STDERR or STDOUT (default `STDOUT`)
* `F2B_LOG_LEVEL`: Log level output (default `INFO`)
* `F2B_DB_PURGE_AGE`: Age at which bans should be purged from the database (default `1d`)
* `SSMTP_HOST`: SMTP server host
* `SSMTP_PORT`: SMTP server port (default `25`)
* `SSMTP_HOSTNAME`: Full hostname (default `$(hostname -f)`)
* `SSMTP_USER`: SMTP username
* `SSMTP_PASSWORD`: SMTP password
* `SSMTP_TLS`: Use TLS to talk to the SMTP server (default `NO`)
* `SSMTP_STARTTLS`: Specifies whether ssmtp does a EHLO/STARTTLS before starting SSL negotiation (default `NO`)
> **Note**
>
> `SSMTP_PASSWORD_FILE` can be used to fill in the value from a file, especially
> for Docker's secrets feature.
## Volumes
* `/data`: Contains customs jails, actions and filters and Fail2ban persistent database
## Usage
### Docker Compose
Docker compose is the recommended way to run this image. Copy the content of
folder [examples/compose](examples/compose) in `/var/fail2ban/` on your host
for example. Edit the Compose and env files with your preferences and run the
following commands:
```console
$ docker compose up -d
$ docker compose logs -f
```
### Command line
You can also use the following minimal command :
```console
$ docker run -d --name fail2ban --restart always \
--network host \
--cap-add NET_ADMIN \
--cap-add NET_RAW \
-v $(pwd)/data:/data \
-v /var/log:/var/log:ro \
crazymax/fail2ban:latest
```
## Upgrade
Recreate the container whenever I push an update:
```console
$ docker compose pull
$ docker compose up -d
```
## Notes
### `DOCKER-USER` chain
In Docker 17.06 and higher through [docker/libnetwork#1675](https://github.com/docker/libnetwork/pull/1675),
you can add rules to a new table called `DOCKER-USER`, and these rules will be
loaded before any rules Docker creates automatically. This is useful to make
`iptables` rules created by Fail2Ban persistent.
If you have an older version of Docker, you may just change the chain
definition for your jail to `chain = FORWARD`. This way, all Fail2Ban rules
come before any Docker rules but these rules will now apply to ALL forwarded
traffic.
More info : https://docs.docker.com/network/iptables/
### `DOCKER-USER` and `INPUT` chains
If your Fail2Ban container is attached to `DOCKER-USER` chain instead of
`INPUT`, the rules will be applied **only to containers**. This means that any
packets coming into the `INPUT` chain will bypass these rules that now reside
under the `FORWARD` chain.
This is why the [sshd](examples/jails/sshd) jail contains a [`chain = INPUT`](examples/jails/sshd/jail.d/sshd.conf)
in its definition and [traefik](examples/jails/traefik) jail contains
[`chain = DOCKER-USER`](examples/jails/traefik/jail.d/traefik.conf).
### Jails examples
Here are some examples using the `DOCKER-USER` chain:
* [guacamole](examples/jails/guacamole)
* [traefik](examples/jails/traefik)
And others using the `INPUT` chain:
* [proxmox](examples/jails/proxmox)
* [sshd](examples/jails/sshd)
### Use iptables tooling without nftables backend
As you may know, [nftables](https://wiki.nftables.org) is available as a modern
replacement for the kernel's iptables subsystem on Linux.
This image still uses `iptables` to preserve backwards compatibility but [an issue is opened](https://github.com/crazy-max/docker-fail2ban/issues/29)
about its implementation.
If your system's `iptables` tooling uses the nftables backend, this will throw
the error `stderr: 'iptables: No chain/target/match by that name.'`. You need
to switch the `iptables` tooling to 'legacy' mode to avoid these problems. This
is the case on at least Debian 10 (Buster), Ubuntu 19.04, Fedora 29 and newer
releases of these distributions by default. RHEL 8 does not support switching
to legacy mode, and is therefore currently incompatible with this image.
On Ubuntu or Debian:
```console
$ update-alternatives --set iptables /usr/sbin/iptables-legacy
$ update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
$ update-alternatives --set arptables /usr/sbin/arptables-legacy
$ update-alternatives --set ebtables /usr/sbin/ebtables-legacy
```
On Fedora:
```console
$ update-alternatives --set iptables /usr/sbin/iptables-legacy
```
Then reboot to apply changes.
### Use fail2ban-client
[Fail2ban commands](http://www.fail2ban.org/wiki/index.php/Commands) can be used
through the container. Here is an example if you want to ban an IP manually:
```console
$ docker exec -t fail2ban-client set banip
```
### Global jail configuration
You can provide customizations in `/data/jail.d/*.local` files.
For example to change the default bantime for all jails, send an e-mail with
whois report and relevant log lines to the destemail:
```text
[DEFAULT]
bantime = 1h
destemail = root@localhost
sender = root@$(hostname -f)
action = %(action_mwl)s
```
> **Warning**
>
> If you want email to be sent after a ban, you have to configure SSMTP env vars
FYI, here is the order *jail* configuration would be loaded:
```text
jail.conf
jail.d/*.conf (in alphabetical order)
jail.local
jail.d/*.local (in alphabetical order)
```
A sample configuration file is [available on the official repository](https://github.com/fail2ban/fail2ban/blob/master/config/jail.conf).
### Custom jails, actions and filters
Custom jails, actions and filters can be added respectively in `/data/jail.d`,
`/data/action.d` and `/data/filter.d`. If you add an action/filter that already
exists, it will be overriden.
> **Warning**
>
> Container has to be restarted to propagate changes
## Contributing
Want to contribute? Awesome! The most basic way to show your support is to star
the project, or to raise issues. You can also support this project by [**becoming a sponsor on GitHub**](https://github.com/sponsors/crazy-max)
or by making a [Paypal donation](https://www.paypal.me/crazyws) to ensure this
journey continues indefinitely!
Thanks again for your support, it is much appreciated! :pray:
## License
MIT. See `LICENSE` for more details.