Requirements

The plugin works with any theme and page builder. On the front end it loads no CSS or JavaScript, and when no rule applies to a request it adds no database queries.

Installation and upgrade

1. Upload the plugin ZIP through Plugins → Add New Plugin → Upload Plugin, then activate it.
2. Open Country Access → License and activate your license key.
3. The free DB-IP country database downloads automatically in the background a few seconds after activation (check Country Access → Geolocation).
4. Create your rules under Country Access → Rules & settings — or start from a preset.

License and updates

Go to Country Access → License, paste the key from your Amazing WP Plugins receipt and select Activate License. The page shows the activation state and renewal date, a Check for updates now button and an automatic-updates toggle. Licensed sites receive updates in the normal Plugins screen.

Quick start

The most common goal — “only my team’s countries may log in to wp-admin” — takes under a minute.

1. Open Country Access → Rules & settings. The status bar shows your IP and detected country.
2. Choose Quick start from a preset… → Allow wp-admin + login only from my country. Two Allow only rules are added with your country and a 1-day server ban.
3. Add any other countries your team logs in from (or use a group such as EU (27)).
4. Optional: add your office / VPN IPs under Settings → Always allow these IPs as a safety net.
5. Select Save rules. Done — visitors from any other country now get a block page on wp-admin and a refusal on login.

Test first if you prefer

Switch on Monitor mode (Settings) to log what would be blocked without blocking anyone, check the Activity log for a day, then switch it off.

How rules work

A rule combines where (a website section and, for some sections, specific targets), who (a list of countries) and what happens (block page, redirect or 404 — plus optional server ban).

• Order matters: rules are checked top to bottom; the first rule that denies the visitor decides the response. Drag rules by the handle to reorder.
• A rule with no countries is inactive (shown with a warning), so a half-finished rule never blocks anyone.
• Use the switch to disable a rule without deleting it; duplicate it to create variations.
• Always-allow IPs bypass every rule; always-block IPs are refused everywhere.
• If a visitor’s country can’t be determined (private IP, lookup failure) the Unknown country setting decides — allowed by default.

Website sections

Every rule targets one section. Some sections let you pick specific targets.

Countries & groups

Type in the country field to search by name or ISO code; each country is shown with its flag and two-letter code. Press Enter to add the highlighted one, Backspace to remove the last.

One-click groups: EU (27) EEA + CH + UK All Europe US + Canada Five Eyes, plus Add my country and Clear. Developers can add their own groups with the awcab_country_groups filter.

Response & messages

Under Response, exceptions & logging each rule chooses what a blocked visitor gets:

Login, registration, comments, checkout, REST and XML-RPC can’t show a page, so they answer with an inline error using the same message. Messages accept basic HTML and the placeholders {country}, {country_code}, {ip} and {site}; a rule’s custom message overrides the default from Settings.

Exceptions & roles

Never block these users exempts selected roles — or any logged-in user — from a rule. On login rules the plugin checks the role of the account being logged into, so you can let customers sign in from anywhere while administrators and editors can only sign in from your country.

Other exceptions: always-allow IPs (Settings), verified search-engine crawlers on content rules (Settings), and per-request logic via the awcab_user_is_exempt and awcab_is_whitelisted filters.

wp-admin & login protection

Most brute-force and credential-stuffing traffic comes from countries your team never logs in from.

XML-RPC & REST API

XML-RPC is a favourite brute-force target (one request can try hundreds of passwords). An Allow only XML-RPC rule — the preset Block XML-RPC for every country except mine — answers everyone else with an XML-RPC fault and a 403, plus a 7-day server ban in the preset.

For the REST API, leave the routes empty to cover the whole API, or protect specific routes such as wp/v2/users to stop user enumeration. Keep in mind that the block editor and many plugins use the REST API, so prefer route-specific rules.

Pages, posts & terms

Content rules run when WordPress decides what to show, so they understand your site’s structure:

• Pages — with child pages, the posts page and the WooCommerce shop page.
• Posts / products / CPT items — any public post type.
• Post types — singles and archives.
• Terms — category, tag, product-category or custom-taxonomy archives, with child terms, and optionally every item assigned to them.
• URL patterns — anything WordPress serves, matched very early (e.g. downloads, landing pages, custom endpoints).

Combine with Pretend it does not exist (404) to hide region-specific promotions completely.

WooCommerce checkout

A WooCommerce: placing orders rule lets visitors from anywhere browse and add to cart, but refuses the order from countries you don’t sell to — on the classic checkout and the block (Store API) checkout. The visitor sees your message as a checkout error.

Server-level bans

Turn a rule violation into a ban: the attacker is refused by the web server for the whole site, before WordPress or PHP even starts.

Switch on Ban the IP at server level when this rule blocks someone, for [1 hour … permanently] in any rule (recommended for wp-admin, login, XML-RPC and registration). The first request is blocked by WordPress; from then on the IP is refused by:

Automatic (the default method) uses both where possible. Bans expire on schedule (hourly cleanup), the list is capped (default 2,000 IPs, oldest first), and the files are removed when the plugin is deactivated and restored on reactivation.

Always allow / always block IPs

Under Settings, two lists accept single IPs, CIDR ranges (IPv4 and IPv6) and wildcards (10.0.*.*), one per line, with # comments:

• Always allow — bypasses every rule and every ban. Add your office, VPN, uptime monitors and payment-gateway callbacks. Adding an IP here also lifts its server ban.
• Always block — refused everywhere (front end, wp-admin and APIs) regardless of country.

Both lists can also be managed from the IP details popup with one click.

Settings

Geolocation

The country is detected in layers and cached per IP:

1. CDN / server headers (optional) — Cloudflare CF-IPCountry, CloudFront, Fastly, Sucuri or server GeoIP modules. Fastest; enable only if your site really is behind such a service.
2. Local database — DB-IP Country Lite (free, no account, downloaded and refreshed weekly), MaxMind GeoLite2 Country (free account + license key) or any custom .mmdb file. Read by a built-in reader — no extra PHP extensions.
3. WooCommerce geolocation (if active).
4. Remote API fallback (optional) — country.is, ipwho.is, ipapi.co or ipinfo.io, only for IPs nothing else could place. Choose None to never contact an outside service.

Visitor IP source

Choose where the visitor IP is read from: REMOTE_ADDR (direct connection, safest), CF-Connecting-IP (Cloudflare), X-Forwarded-For, X-Real-IP, True-Client-IP, X-Sucuri-ClientIP or a custom header. Tools → Request headers shows what your server receives.

IP geolocation by DB-IP (CC BY 4.0). Country flags by flag-icons (MIT).

Page caching & SEO

Page caching

A page cache serves stored copies without running WordPress, so a page cached for an allowed visitor could be served to a blocked one (or vice versa). With Send no-cache headers / DONOTCACHEPAGE on (default), pages covered by a content rule tell WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache and others not to cache them. Purge your page cache after adding a content rule so older copies are cleared. Server-level caches (Varnish, Cloudflare APO) may need these URLs excluded.

wp-admin, login, XML-RPC, REST, comments and checkout are never page-cached, so their rules are unaffected.

Search engines

With Let verified search-engine crawlers through content rules on, Google, Bing, Apple, Yandex, Baidu, DuckDuckGo and others can index country-restricted content. Crawlers are verified by reverse + forward DNS, so fake “Googlebot” user agents are still blocked. Login, admin and API rules always apply to everyone.

Activity log

Every block is logged with time, country, IP, section and rule, URL and user agent. Repeated hits from the same IP on the same rule within 10 minutes are grouped into one row with a hit counter, so floods don’t bloat the table. The top shows totals and the top blocked countries for the last 30 days; click a country to filter.

Filter by country, section or text (IP, URL, user agent), Export CSV, or Clear log. Entries older than the retention period (default 30 days) are pruned daily. In monitor mode, entries are tagged monitor.

IP details popup

Click any IP — in the log, the server bans list, the status bar or the IP tester — to open its details: country (flag + ISO code) and lookup source, reverse-DNS hostname, list and ban status, total blocks with first / last seen, which rules blocked it, recent requests and user agents.

Act right there: Always block this IP, Always allow this IP, Ban at server level (choose a duration) or Lift server ban, jump to the IP in the activity log, or look it up on whatismyipaddress.com in a new tab.

Tools

Lockout protection & emergency access

Before saving rules or settings, the plugin simulates your own access. If a wp-admin or login rule — or the always-block list — would block your current IP or country, nothing is saved: you get a clear explanation, your unsaved rules are restored, and you can fix them, whitelist your IP, exempt your role, or tick I understand I may lock myself out — save anyway.

If you are locked out anyway

Add this line to wp-config.php (above “That’s all, stop editing!”), log in, fix the rules (or whitelist your IP), then remove it:

define( 'AWCAB_DISABLE', true );

It switches off all rules and the early-ban drop-in. If a server-level ban in .htaccess is blocking you, remove the block between # BEGIN Amazing WP Country Access Blocker and # END Amazing WP Country Access Blocker, or rename the plugin folder via FTP.

Performance

On a test site a typical page that no rule targets loaded five small plugin files and ran zero plugin queries.

Developer hooks

Extend the plugin without touching its code. All extension points use the awcab_ prefix — 48 in total.

Filters

Actions

awcab_blocked

awcab_before_block_response

awcab_enforcer_booted

awcab_ip_banned

awcab_ip_unbanned

awcab_bans_synced

awcab_log

awcab_rules_saved

awcab_settings_saved

awcab_geo_database_updated

awcab_admin_tab_{key}

awcab_license_status_changed

awcab_auto_updates_changed

Define a rule in code

add_filter( 'awcab_rules', function ( $rules ) {
	$rules[] = array(
		'id'           => 'code-xmlrpc',
		'scope'        => 'xmlrpc',
		'mode'         => 'allow',
		'countries'    => array( 'GR', 'CY' ),
		'server_ban'   => true,
		'ban_duration' => WEEK_IN_SECONDS,
	);
	return $rules;
} );

Notify Slack (or a SIEM) on every block

add_action( 'awcab_blocked', function ( $rule, $visitor, $monitor_only ) {
	wp_remote_post( 'https://hooks.slack.com/services/XXX', array(
		'blocking' => false,
		'body'     => wp_json_encode( array(
			'text' => sprintf( 'Blocked %s (%s) — %s', $visitor['ip'], $visitor['country'], $rule['scope'] ),
		) ),
	) );
}, 10, 3 );

Mirror server bans to your firewall

add_action( 'awcab_bans_synced', function ( $ips, $status ) {
	// $ips = array( '203.0.113.7' => 1791234567, ... ) — expiry timestamp, 0 = permanent.
	my_firewall_sync( array_keys( $ips ) );
}, 10, 2 );

Always allow your uptime monitor

add_filter( 'awcab_is_whitelisted', function ( $allowed, $ip ) {
	return $allowed || in_array( $ip, my_uptime_monitor_ips(), true );
}, 10, 2 );

Troubleshooting

Nothing is being blocked

Check the status bar on the Rules tab: Protection must read Active — blocking. Common causes: no valid license, Monitor mode on, “Enforce rules” off, the rule has no countries or is disabled, your IP is on the always-allow list, or the country can’t be detected (see the IP tester). For content rules, purge your page cache.

Every visitor shows the same country or IP

Your site is behind a proxy or CDN. Set the correct IP source on the Geolocation tab — Tools → Request headers shows which header carries the real visitor IP.

The country database didn’t download

Open Geolocation and select Download database now; any error is shown there. The server needs outbound HTTPS to download.db-ip.com (or MaxMind) and the PHP zlib extension. Until then, WooCommerce or a remote API fallback can be used.

.htaccess shows “Not written” on the Server bans tab

The file isn’t writable by PHP. Fix its permissions and select Rewrite server rules — the early PHP drop-in keeps enforcing bans in the meantime.

I banned myself / a colleague

Lift the ban on the Server bans tab or the IP popup. If you can’t reach wp-admin, use AWCAB_DISABLE (see Lockout protection) or remove the plugin’s block from .htaccess.

A front-end feature stopped working after blocking wp-admin

Make sure Apply wp-admin rules to admin-ajax.php and admin-post.php is off (the default) in Settings.

Frequently asked questions

Changelog

Current version: 1.0.0. See readme.txt in the plugin package for the complete history.