WP-Ban

1. 01Install and activate the plugin.
2. 02Go to WP-Admin -> Settings -> Ban and fill in the lists you want on the Settings tab.
3. 03If your site sits behind a proxy or a CDN, set the visitor IP header on that same tab. Without it every visitor arrives carrying the proxy’s address, so an IP ban catches everybody or nobody.

Every visitor shows the same IP address, or IP bans do not apply

Your site is behind a reverse proxy, a load balancer or a CDN such as Cloudflare, so WordPress sees the proxy’s address on every request rather than the visitor’s.

By default WP-Ban only trusts REMOTE_ADDR , because every other header carrying an IP address is set by the client — trusting them unconditionally means anyone can walk past an IP ban by sending a different value on each request. There are two ways to opt in, narrowest first:

1. 01Name the exact header in the Header That Contains The IP field on the Settings tab, for example HTTP_X_FORWARDED_FOR , or HTTP_CF_CONNECTING_IP on Cloudflare. Only that header is trusted, and this is the option to use. Ask your host or your CDN’s documentation which header they set if you are not sure.
2. 02Define the constant in wp-config.php , which trusts the usual set of forwarding headers rather than one you choose:

define( 'WP_BAN_TRUST_PROXY', true );

For per-request control, filter it. The filter defaults to the constant, so the constant keeps working and the filter gets the last word:

add_filter( 'wp_ban_trust_proxy', function ( $trust ) { // Only trust the header when the request really came from your balancer. return '10.0.0.5' === $_SERVER['REMOTE_ADDR']; } );

Do not enable either of these if there is no proxy in front of WordPress: it makes every IP ban trivial to bypass. Naming the one header your own proxy sets and overwrites is always safer than the constant, which trusts seven headers because it cannot know which one is yours.

My monitoring or SEO tool reports the site returning 403

That is deliberate as of 2.0.0. The ban page used to be served as 200 OK , which told search engines and caches that the ban page was your site’s real content. It is now 403 Forbidden .

If you need the old behaviour back:

add_filter( 'wp_ban_status_code', function () { return 200; } ); Where did my settings go after updating to 2.0.0?

Nowhere — they were moved, not lost. WP-Ban used to keep its settings in eight separate rows in the options table, under names with no plugin prefix on them at all. 2.0.0 consolidates them into one row called wp_ban_options . The move runs automatically the first time an administrator loads wp-admin after the update, and it also repairs two long-standing storage faults on the way through (see the changelog).

An IP range I entered was rejected

A range must be two valid addresses of the same type, separated by a hyphen, with no wildcards — 192.168.1.1-192.168.1.255 or 2001:db8::1-2001:db8::ffff . Anything else is refused at save time and the screen says which entry it dropped. Before 2.0.0 a malformed range was accepted and then matched every visitor, so if you had one stored, everybody was being banned.

What variables can I use in the banned message?

%SITE_NAME%, %SITE_URL% , %USER_IP% , %USER_HOSTNAME% , %USER_ATTEMPTS_COUNT% and %TOTAL_ATTEMPTS_COUNT% . Your message must sit inside <div id="wp-ban-container"></div> so the preview button can find it.

What does the plugin store in my database?

Three rows: wp_ban_options for the settings, wp_ban_version for the version it last ran, and wp_ban_stats for the attempt counters. Only the first two are autoloaded. Deleting the plugin from the Plugins screen removes all three, and every pre-2.0.0 row as well.