Skip to content

Setup-Instructions.md

Latest commit

 

History

History
252 lines (165 loc) · 6.19 KB

Setup-Instructions.md

File metadata and controls

252 lines (165 loc) · 6.19 KB

🔧 Fail2Ban-Report V 0.5.0 – Manual Setup Instructions

This guide explains how to install Fail2Ban-Report v0.5.0 from scratch. It covers the Web-UI setup, security hardening, backend configuration, and user management.

🚨 This guide assumes that you have downloaded the project to /home/USER/ and that the project folder is named Fail2Ban-Report-latest.

Also that you want to install the Web-UI in /var/www/html/ to get the URL https://yourdomain.tld/Fail2Ban-Report/

Therefore, any copy commands or paths in this guide are based on this assumption. Please edit Paths to fit your Setup.

Folder Names are Case Sensitive - please use them as descibed to avoid conflicts

Wanna know more about Chain of Trust or Syncronisation Concept ?

✅ Requirements

  • A Linux system (tested with debian only) with the following installed:
    • fail2ban
    • jq
    • awk (gawk)
    • curl
    • ufw (only UFW is supported at this time)
  • A PHP-enabled web server (e.g. Apache with PHP 7.4+)
  • The web server user (e.g. www-data) must have write access to the /archive/ directory

Step 1 – Install Web-UI on the Server

  1. Create the target directory on your web server, e.g.:

    mkdir -p /var/www/html/Fail2Ban-Report

  2. Copy the content of the Web-UI folder into it:

    cp -r /home/USER/Fail2Ban-Report-latest/Web-UI/* /var/www/html/Fail2Ban-Report/

  3. Adjust file ownership so your web server user can access them:

    chown -R -P www-data:www-data /var/www/html/Fail2Ban-Report

Step 2 – Secure the Web-UI

Edit the included .htaccess file and apply the following settings:

1. Enforce HTTPS

Go to the section “Basic HTTPS Headers” and make sure the Web-UI is only available via HTTPS. All unencrypted HTTP requests should be redirected to HTTPS.

2. Authentication

Fail2Ban-Report does not include a native base login. Use the .htaccess file to secure access with either Basic Authentication or IP-based restrictions.

Option A: Password Protection

Enable Basic Auth in .htaccess:

AuthType Basic
AuthName "Restricted Area"
AuthUserFile /etc/apache2/htpasswd/.htpasswd

<RequireAny>
   Require valid-user
</RequireAny>

  • Create the .htpasswd file outside of the web root, e.g.:

    htpasswd -c -B /etc/apache2/htpasswd/.htpasswd admin

  • Store only bcrypt-hashed passwords, never plain text. You can use the built-in Apache htpasswd tool (strongly recommended) or an external generator (e.g. my tool: bcrypt generator).

Note, that you need your Sync Clients to allow access via IP also to get over password restrictions

Option B: IP Restriction

<RequireAny>
   Require ip <YOUR_IP_ADDRESS>
</RequireAny>

If you want to allow your Sync Clients as well, list them explicitly:

Note that this will be needed, if you have sync clients and use password protection to allow sync-clients to get over password restriction by using ip address

<RequireAny>
   Require ip <YOUR_IP_ADDRESS>
   Require ip <Sync-Client-1>
   Require ip <Sync-Client-2>
</RequireAny>

⚠️ Important: Never allow unauthenticated access to your Web-UI! Use either password protection, IP restriction, or both.

Step 3 – Backend Setup

Create the following directory structure (case-sensitive!):

/opt/Fail2Ban-Report
├── archive
│   ├── fail2ban
│   └── blocklists
├── Helper-Scripts
├── Settings
└── Backend

Helper-Scripts

Copy helper scripts:

cp -r /home/USER/Fail2Ban-Report-latest/Helper-Scripts/* /opt/Fail2Ban-Report/Helper-Scripts/

Adjust paths in folder-watchdog.sh:

  • Set BASE_PATH to the directory of your Web-UI archive folder.

Config File

Copy the config file:

cp -r /home/USER/Fail2Ban-Report/Conf/fail2ban-report.config /opt/Fail2Ban-Report/Settings/

Example configuration:

[reports]
report=false
report_types=abuseipdb,ipinfo

[Fail2Ban-Daily-List-Settings]
max_display_days=7

[Warnings]
enabled=true
threshold=5:20

[Default Server]
defaultserver=
  • Reports: If enabled (report=true), you need API keys for AbuseIPDB and IPInfo.
  • report_types: can be configured with report_types= abuseipdb,ipinfo (you can set none, one or both - seperate them with ,)
  • Warnings: Threshold 5:20 means “Warning” at 5 bans/minute per jail, “Critical” at 20.
  • Default Server: Define the default server name (folder name) shown in the Web-UI.

Backend Scripts

Copy backend scripts:

cp -r /home/USER/Fail2Ban-Report/Backend/fail2ban_log2json.sh /opt/Fail2Ban-Report/Backend/
cp -r /home/USER/Fail2Ban-Report/Backend/firewall-update.sh /opt/Fail2Ban-Report/Backend/

Adjust script paths:

  • fail2ban_log2json.sh → set OUTPUT_JSON_DIR to /opt/Fail2Ban-Report/archive/<SERVERNAME>/fail2ban/
  • firewall-update.sh → set blocklist path to /var/www/html/Fail2Ban-Report/archive/<SERVERNAME>/blocklists

Make scripts executable:

chmod +x /opt/Fail2Ban-Report/Backend/*.sh

Cronjobs

Edit your crontab:

crontab -e

Example (run every 5 minutes):

*/5 * * * * /opt/Fail2Ban-Report/Backend/fail2ban_log2json.sh
*/5 * * * * /opt/Fail2Ban-Report/Backend/firewall-update.sh
  • */5 = every 5 minutes
  • */15 = every 15 minutes
  • */30 = every 30 minutes

Logging is recommended for easier debugging.

Step 4 – Create Admin User

To ensure only authorized users can manipulate blocklists, authentication is required since v0.5.0.

Go to the helper scripts directory:

cd /opt/Fail2Ban-Report/Helper-Scripts/
./manage-users.sh

  • Enter username and password (stored as bcrypt hash only).

  • Assign a role:

    • Admin → can manipulate blocklists
    • Viewer → read-only access

Done!

👉 Fail2Ban-Report is now running on your server. To add more clients, follow the “Adding-Clients” guide.

Username of the Client and Displayed Servername in Web-UI are the same.