Skip to main content

Fail2Ban Setup for Stirling-PDF

This document provides instructions on how to set up Fail2Ban with Stirling-PDF to protect against unauthorized login attempts. (Note Stirling-PDF blocks IPs after a set retry count regardless of Fail2Ban, This configuration is only useful for users specifically wanting Fail2Ban configuration)

How does Fail2Ban Work with Stirling-PDF​

Stirling-PDF logs failed authentication attempts to a log file which Fail2Ban monitors. When it detects multiple failed login attempts from the same IP address, Fail2Ban automatically blocks that IP address for a configured period of time.

Prerequisites​

  • Fail2Ban installed on your system
  • Access to Stirling-PDF log directory
  • Security settings configured in /configs/settings.yml: 
    security:
      enableLogin: true    # Login must be enabled for Fail2Ban integration
      loginAttemptCount: -1 # Set to -1 when using Fail2Ban recommended but not required

Important Configuration Notes​

  • The enableLogin setting must be set to true as Fail2Ban integration requires authentication to be active
  • When using Fail2Ban, set loginAttemptCount to -1 to disable the built-in account locking mechanism and let Fail2Ban handle login attempt management
  • For more details on security configuration options, refer to the System and Security documentation

Configuration​

Log File Location​

The log file location containing the failed authentication messages depends on your installation type:

  • Default/Docker Installation: ./logs/invalid-auths.log
  • Windows Desktop: %APPDATA%\Stirling-PDF\logs\invalid-auths.log
  • MacOS Desktop: ~/Library/Application Support/Stirling-PDF/logs/invalid-auths.log
  • Linux Desktop: ~/.config/Stirling-PDF/logs/invalid-auths.log

Example Fail2Ban Filter​

/etc/fail2ban/filter.d/stirling-pdf.conf

[Definition]
failregex = Failed login attempt from IP: <HOST>

Example Jail Configuration​

/etc/fail2ban/jail.local

[stirling-pdf]
enabled = true
filter = stirling-pdf
logpath = /logs/invalid-auths.log
maxretry = 5
findtime = 300
bantime = 3600

Configuration parameters:

  • maxretry: Number of failed attempts before ban (default: 5)
  • findtime: Time window for failed attempts in seconds (default: 300 seconds / 5 minutes)
  • bantime: Duration of the ban in seconds (default: 3600 seconds / 1 hour)

Ensure access to Logs path​

Modify your docker-compose.yml to expose the log directory:

services:
  stirling-pdf:
    volumes:
      - ./logs:/logs