How to Protect MediaWiki Against Brute-Force Logins with Fail2Ban

Why Brute‑Force Protection Matters for MediaWiki

MediaWiki powers thousands of public wikis, from community projects to corporate knowledge bases. A public login form is an obvious target for credential‑spraying and dictionary attacks. Even if you enforce strong passwords, an attacker can still lock out legitimate users or overload your database with repeated failed attempts. The most efficient way to mitigate this on a Linux server is to let Wiki2Ban generate a concise log of every failed authentication and feed that log into Fail2Ban, which then bans the offending IP at the firewall level.

Prerequisites

• A recent MediaWiki installation (≥ 1.39 is recommended).
• Root or sudo access to the host machine.
• Fail2Ban installed from your distro’s package manager (e.g. apt install fail2ban or yum install fail2ban).
• Composer available for MediaWiki extensions.

Step 1 – Install the Wiki2Ban Extension

Wiki2Ban is the modern replacement for the long‑abandoned Fail2banlog extension. It hooks into AuthManagerLoginAuthenticateAudit and writes a single line for each failed login attempt.

# In the root of your MediaWiki installation
cat >> composer.local.json <<'EOF'
{
    "require": {
        "lucamauri/wiki2ban": "~1.0"
    }
}
EOF
composer install --no-dev

After Composer finishes, enable the extension in LocalSettings.php:

wfLoadExtension( 'Wiki2ban' );

Step 2 – Configure the Log File

Choose a location that Fail2Ban can read but that is not world‑writable. A common choice is /var/log/mediawiki/wiki2ban.log:

$wgW2BlogFilePath = '/var/log/mediawiki/wiki2ban.log';

Make sure the directory exists and is owned by the web‑server user (usually www-data or apache).

mkdir -p /var/log/mediawiki
chown www-data:www-data /var/log/mediawiki
chmod 750 /var/log/mediawiki

Step 3 – Create Fail2Ban Filter and Jail

Wiki2Ban ships two example files: w2bfilter.conf and w2brule.conf. Copy them to the appropriate Fail2Ban directories and adjust the logpath.

# Copy filter
cp /path/to/mediawiki/extensions/Wiki2Ban/f2bconf/w2bfilter.conf /etc/fail2ban/filter.d/wiki2ban.conf

# Copy rule (jail) – you can keep it in jail.d for modularity
cp /path/to/mediawiki/extensions/Wiki2Ban/f2bconf/w2brule.conf /etc/fail2ban/jail.d/wiki2ban.local

# Edit the jail file to point at the log you configured above
sed -i "s|logpath = .*|logpath = /var/log/mediawiki/wiki2ban.log|" /etc/fail2ban/jail.d/wiki2ban.local

The default filter looks for lines that contain the IP address of the client, the word failed and the username that was tried. It is deliberately simple:

^.*\[AuthManagerLoginAuthenticateAudit\] \[FAIL\] \[IP: <HOST>\] .*$

If you have customized the log format, adjust the regular expression accordingly.

Step 4 – Tune Fail2Ban Parameters

Typical values for a public wiki are:

• maxretry: 5 – number of failed attempts before a ban.
• findtime: 600 – 10 minutes window for counting retries.
• bantime: 86400 – one day; set to permanent for persistent bans.

These settings live in the [wiki2ban] section of the jail file:

[wiki2ban]
enabled = true
filter = wiki2ban
logpath = /var/log/mediawiki/wiki2ban.log
maxretry = 5
findtime = 600
bantime = 86400

After editing, restart Fail2Ban:

systemctl restart fail2ban

Step 5 – Verify the Setup

1. Attempt a login with an incorrect password from a test machine.
2. Run fail2ban-client status wiki2ban – the IP should be listed under Currently banned after the configured number of retries.

Check that a line appears in /var/log/mediawiki/wiki2ban.log.

tail -f /var/log/mediawiki/wiki2ban.log

Step 6 – Troubleshooting Common Issues

• Log file not created: Ensure the web‑server user has write permission to the directory.
• False positives: Add an ignoreip entry for your own office IPs or for trusted crawlers.

No bans appear: Verify the filter regex matches the actual log line. You can test a line with fail2ban-regex:

fail2ban-regex /var/log/mediawiki/wiki2ban.log /etc/fail2ban/filter.d/wiki2ban.conf

Step 7 – Best Practices for Long‑Term Security

• Whitelist critical IPs – use ignoreip = 127.0.0.1/8,192.168.0.0/16 in /etc/fail2ban/jail.local.
• Combine with two‑factor authentication (e.g. TwoFactorAuth) to make brute‑force attacks ineffective even if the IP isn’t blocked.
• Enforce strong password policies via $wgPasswordPolicy in MediaWiki.
• Monitor ban logs – Fail2Ban writes /var/log/fail2ban.log. Periodically review for patterns that might indicate a distributed attack.

Rotate the Wiki2Ban log – set up logrotate to avoid uncontrolled growth.

/var/log/mediawiki/wiki2ban.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
    create 640 www-data adm
}

Alternative Extensions (Legacy)

The older Fail2banlog extension is archived and no longer compatible with recent MediaWiki releases. If you run an older wiki (≤ 1.31) you may still find it useful, but the recommended path for all modern installations is Wiki2Ban.

Putting It All Together

With just a few lines in LocalSettings.php and a modest Fail2Ban jail, you gain automatic, kernel‑level protection against credential‑guessing attacks. The approach scales well: Fail2Ban only touches the firewall, so even a massive flood of failed logins has negligible impact on your database. Combined with good password policies and optional two‑factor authentication, your MediaWiki site becomes significantly harder to compromise.

Next Steps

• Enable email alerts in Fail2Ban (action = %(action_mwl)s) to stay informed about new bans.
• Consider integrating with external blocklists (e.g. abuseipdb) for shared intelligence.
• Regularly update both MediaWiki and the Wiki2Ban extension to benefit from security patches.

By following this guide you’ll have a robust, low‑maintenance defence against brute‑force login attempts on your MediaWiki installation.