fail2ban-ui/deployment/systemd/README.md

Fail2Ban-UI Systemd Setup

This guide provides two methods to run Fail2Ban-UI as a systemd service.

1. Systemd service that starts the local compiled binary.
2. Systemd service that starts the fail2ban-ui container.

For SELinux enabled systems (needed in both cases)

If SELinux is enabled, you must apply the required SELinux policies to allow Fail2Ban to communicate with the Fail2Ban-UI API via port 8080.

Apply the prebuilt SELinux Module with:

semodule -i fail2ban-curl-allow.pp

Build and running Fail2Ban-UI from Local Source Code

In this case we will run Fail2Ban-UI from /opt/fail2ban-ui/ using systemd.

Prerequisites

Install Go 1.24+ and required dependencies:

sudo dnf install -y golang git

Note: Whois lookups are now performed by Fail2Ban UI directly (no Linux whois binary required).

Note: GeoIP lookups can use either:

• Built-in (ip-api.com): Default option, requires no installation
• MaxMind (Local Database): Optional, requires MaxMind GeoIP database at /usr/share/GeoIP/GeoLite2-Country.mmdb

Note: The local Fail2ban service is optional. Fail2Ban-UI can manage remote Fail2ban servers via SSH or API agents without requiring a local Fail2ban installation.

Clone the repository to /opt/fail2ban-ui:

sudo git clone https://github.com/swissmakers/fail2ban-ui.git /opt/fail2ban-ui
cd /opt/fail2ban-ui
sudo go build -o fail2ban-ui ./cmd/server/main.go

Create the fail2ban-ui.service

Save this file as /etc/systemd/system/fail2ban-ui.service: For production deployments, please use a dedicated service account instead of root.

[Unit]
Description=Fail2Ban UI
After=network.target
Wants=fail2ban.service

[Service]
Type=simple
WorkingDirectory=/opt/fail2ban-ui
ExecStart=/opt/fail2ban-ui/fail2ban-ui
Restart=always
User=root
Group=root

[Install]
WantedBy=multi-user.target

Start & Enable the Service

1. Reload systemd to detect our new service:

   sudo systemctl daemon-reload
   

2. Enable and start the service:

   sudo systemctl enable fail2ban-ui.service --now
   

3. Check the status:

   sudo systemctl status fail2ban-ui.service
   

View Logs

To see the real-time logs of Fail2Ban-UI:

sudo journalctl -u fail2ban-ui.service -f

Restart or Stop

Restart:

sudo systemctl restart fail2ban-ui.service

Stop:

sudo systemctl stop fail2ban-ui.service

First Launch & Server Configuration

After starting the service, access the web interface at http://localhost:8080 (or your configured port).

Important: On first launch, you need to:

1. Enable the local connector (if Fail2ban runs on the same host), OR
2. Add a remote server via SSH connection

Go to Settings → Manage Servers in the web UI to configure your first Fail2ban server.

Configure Settings:

• Fail2Ban Callback URL: URL where Fail2Ban instances send ban alerts (auto-updates with port changes)
• Callback URL Secret: Auto-generated 42-character secret for API authentication (viewable in Settings with show/hide toggle)
• GeoIP Provider: Choose between MaxMind (local database) or Built-in (ip-api.com)
• Maximum Log Lines: Configure how many log lines to include in ban notifications (default: 50)
• Set up email alerts and set alert countries
• Configure language preferences

The UI uses an embedded SQLite database (fail2ban-ui.db) to store all server configurations and ban events. This database is automatically created in the working directory.

Running Fail2Ban-UI as a (Systemd controlled) Container

This method runs Fail2Ban-UI as a containerized service with automatic startup and handling through systemd.

Prerequisites

• Ensure Podman or Docker is installed.

For Podman:

sudo dnf install -y podman

For Docker (if preferred):

sudo dnf install -y docker
sudo systemctl enable --now docker

Create the needed folder to store the fail2ban-ui config:

sudo mkdir /opt/podman-fail2ban-ui

Create the fail2ban-ui-container.service

Save this file as /etc/systemd/system/fail2ban-ui-container.service:

[Unit]
Description=Fail2Ban UI (Containerized)
After=network.target
Wants=fail2ban.service

[Service]
ExecStart=/usr/bin/podman run --rm \
    --name fail2ban-ui \
    --network=host \
    -v /opt/podman-fail2ban-ui:/config:Z \
    -v /etc/fail2ban:/etc/fail2ban:Z \
    -v /var/log:/var/log:ro \
    -v /var/run/fail2ban:/var/run/fail2ban \
    registry.swissmakers.ch/infra/fail2ban-ui:latest
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

For SELinux enabled systems

If SELinux is enabled, you must apply the required SELinux policies to allow the container to communicate with Fail2Ban. The policies are located here: "../container/SELinux/"

Apply the prebuilt SELinux Modules with:

semodule -i fail2ban-container-ui.pp
semodule -i fail2ban-container-client.pp

Manually Compile and Install SELinux Rules

If you want to change or compile the SELinux rules by yourself run:

checkmodule -M -m -o fail2ban-container-client.mod fail2ban-container-client.te
semodule_package -o fail2ban-container-client.pp -m fail2ban-container-client.mod
semodule -i fail2ban-container-client.pp

Start & Enable the Container Service

1. Reload systemd to detect the new service:

   sudo systemctl daemon-reload
   

2. Enable and start the containerized service:

   sudo systemctl enable --now fail2ban-ui-container.service
   

3. Check the status:

   sudo systemctl status fail2ban-ui-container.service
   

View Logs

sudo journalctl -u fail2ban-ui-container.service -f

Restart or Stop

Restart:

sudo systemctl restart fail2ban-ui-container.service

Stop:

sudo systemctl stop fail2ban-ui-container.service

Contact & Support

For issues, visit our GitHub repository:
🔗 GitHub Issues

For enterprise support:
🔗 Swissmakers GmbH