Extension:Wiki2Ban

**MediaWiki extensions manual**
Wiki2Ban; Release status: stable
Implementation	Hook
Description	Logs failed authentication attempts to a file consumable by Fail2Ban for automatic IP blocking
Author(s)	Luca Mauri (Lucamauritalk)
Latest version	1.1.0 (2026-04-17)
MediaWiki	1.42+
PHP	8.4+
Database changes	No
Composer	lucamauri/wiki2ban
	Parameters $wgW2BLogFilePath
	Hooks used AuthManagerLoginAuthenticateAudit;
Licence	GNU General Public License 2.0 or later
Download	GitHub: project page; git repository URL; commit history; ; Note:; No localisation updates are; provided by translatewiki.net. ; https://github.com/lucamauri/Wiki2Ban/blob/main/README.md

The Wiki2Ban extension logs failed MediaWiki authentication attempts to a structured log file that Fail2Ban can monitor, enabling automatic IP blocking of attackers.

This extension is inspired by Extension:Fail2banlog, which is unmaintained and built for older MediaWiki versions. Wiki2Ban was written from scratch by Luca Mauri, originally for WikiTrek, and released as open source for the broader MediaWiki community.

Features

Hooks into MediaWiki's authentication system to detect failed login attempts
Writes a structured log line for each failure, including timestamp, username, wiki name, and client IP address
Correctly resolves the client IP address behind reverse proxies and CDNs
Log format is compatible with Fail2Ban out of the box
Includes ready-to-use Fail2Ban filter and jail configuration files
Includes an optional Log Navigator format definition for interactive log analysis
No database changes required
Configurable log file path

Installation

The easiest way to install the extension is via Composer, which will automatically resolve all dependencies.

Add the following to composer.local.json at the root of your MediaWiki installation, creating the file if it does not exist:

{
    "require": {
        "lucamauri/wiki2ban": "~1.1"
    },
    "extra": {
        "merge-plugin": {
            "include": []
        }
    }
}

Then run Composer from the root of your MediaWiki installation:

composer install --no-dev

Add the following line near the rest of the extension loading calls in LocalSettings.php:

wfLoadExtension( 'Wiki2ban' );

Then add the configuration parameters described in the Configuration section below.

Configuration

Add the following to LocalSettings.php:

$wgW2BLogFilePath = "/var/log/mediawiki/wiki2ban.log";

`$wgW2BLogFilePath`

The full path to the log file that Wiki2Ban will write to and that Fail2Ban will monitor. The web server process must have write permission to this file and its parent directory.

Default value: /var/log/mediawiki/wiki2ban.log

Fail2Ban configuration

After installing and configuring the extension, configure Fail2Ban to monitor the log file. The f2bconf/ directory in the repository contains ready-to-use configuration files.

Filter

Copy f2bconf/w2bfilter.conf to Fail2Ban's filter directory:

cp f2bconf/w2bfilter.conf /etc/fail2ban/filter.d/w2bfilter.conf

Jail rule

Copy f2bconf/w2brule.conf to Fail2Ban's jail directory:

cp f2bconf/w2brule.conf /etc/fail2ban/jail.d/wiki2ban.conf

Edit the file to set logpath to match the value of $wgW2BLogFilePath in your LocalSettings.php.

Tuning for production

The default rule triggers after 5 failed attempts in 60 seconds and bans for 10 minutes. For a public wiki, consider stricter values:

maxretry = 3
findtime = 300
bantime  = 86400

This bans an IP for 24 hours after 3 failures within 5 minutes. Progressive banning is enabled by default in the provided configuration — each repeated offence doubles the ban duration up to a maximum of one week. Progressive banning requires Fail2Ban ≥ 0.10.

After making changes, reload Fail2Ban:

sudo systemctl reload fail2ban

Troubleshooting

To capture detailed debug log messages from Wiki2Ban, add the following to LocalSettings.php:

$wgShowExceptionDetails = true;
$wgDebugLogGroups['Wiki2Ban'] = "/var/log/mediawiki/Wiki2Ban-{$wgDBname}.log";

Additional file

f2bconf/wiki2ban.json is a format definition for the Log Navigator application, which allows interactive exploration and filtering of the Wiki2Ban log file. See the lnav format documentation for installation instructions.