Skip to main content

fail2ban Integration

MAPS integrates cleanly with fail2ban to provide IP-level enforcement on top of its built-in authentication controls.

Where AuthManager slows users down and locks accounts, fail2ban handles the blunt instrument: stop the IP from talking to the server at all.

This integration is intentionally simple and log-driven.

Location​

All fail2ban assets are shipped with MAPS:

$MAPS_HOME/bin/fail2ban/
  • Installation script: fail2ban-config.sh
  • Jail definition: maps-auth.local
  • Filter definition: maps-auth.conf

The script installs these into the system fail2ban configuration directories.

Jail Configuration (maps-auth.local)​

[maps-auth]
enabled = true
filter = maps-auth

# Point this at your MAPS log file
logpath = /opt/maps_data/log/messaging.log

# How aggressive you want it:
findtime = 300
maxretry = 5
bantime  = 3600

# If your host is behind a proxy and logs proxy IPs, fix logging first.
# action defaults to banning via firewall (nftables/iptables) depending on distro.

Behaviour​

  • Watches the MAPS server log for authentication abuse
  • Tracks failures per IP within the findtime window
  • Bans the IP for bantime seconds once maxretry is exceeded

Key Parameters​

SettingMeaning
findtimeTime window (seconds) for counting failures
maxretryFailures allowed before ban
bantimeDuration of IP ban (seconds)

This operates independently of AuthManager lockouts.

Filter Definition (maps-auth.conf)​

[Definition]
# Match failures and lockouts emitted by MAPS auth monitor logging.
# Assumes the log line contains one of these tokens and the client IP address.
#
# Example lines this will match (examples only):
# ... AUTH_FAILURE user=bob attempts=3 ip=203.0.113.9
# ... AUTH_LOCKOUT_STARTED user=bob attempts=5 lockSeconds=60 ip=203.0.113.9
#
# If your log format is different, adjust the tail so the IP is captured as <HOST>.

failregex = ^.*\bAUTH_FAILURE\b.*\b(?P<host><HOST>)\b.*$
            ^.*\bAUTH_LOCKOUT_STARTED\b.*\b(?P<host><HOST>)\b.*$
            ^.*EndPoint closed during protocol negotiation ip=<HOST>\s*$
            ^.*Failed to detect protocol on End Point .*?, ip=<HOST>\s*$

ignoreregex = ^.*ip=127\..*$
              ^.*ip=::1.*$

What This Catches​

The filter reacts to:

  • Repeated authentication failures
  • Explicit authentication lockout events
  • Protocol abuse during negotiation
  • Invalid protocol detection attempts

All rules rely on the IP address being logged and captured as <HOST>.

Localhost Exclusions​

ignoreregex = ^.*ip=127\..*$
              ^.*ip=::1.*$

This prevents:

  • Accidental self-bans
  • Local monitoring tools from triggering fail2ban
  • Administrative testing from locking you out of your own server

Removing these lines is possible but strongly discouraged unless you enjoy console-only recovery.

Relationship to AuthManager​

LayerResponsibility
AuthManagerPer-user failure tracking, delays, account lockout
fail2banPer-IP enforcement and firewall bans

Recommended setup:

  • Enable both
  • Use AuthManager for precision and fairness
  • Use fail2ban for hostile or automated traffic

Proxies and Load Balancers​

If MAPS runs behind:

  • Reverse proxies
  • TLS terminators
  • Load balancers

Ensure that:

  • The real client IP is logged by MAPS
  • Proxy IPs are not logged as the source

Otherwise fail2ban will enthusiastically ban your own infrastructure.

Installation​

Installation is handled by:

$MAPS_HOME/bin/fail2ban/fail2ban-config.sh

The script:

  • Installs the jail and filter
  • Reloads fail2ban
  • Leaves existing configuration intact

The provided configuration is suitable for:

  • Internet-facing brokers
  • Public REST endpoints
  • MQTT, STOMP, AMQP listeners

For internal-only deployments, fail2ban may be disabled while keeping AuthManager protection enabled.