SSP — Block Website Access by Region Lite (Docs)

SSP Documentation

Block Website Access by Region Lite

Admin Screens

The plugin adds a new menu item in your WordPress admin sidebar called Plug and Play Geoblocker Lite. Inside are three tabs:

Control tab

Enable or disable blocking globally.
Option to allow search crawlers like Googlebot.
Block data centers, VPNs, and hosting providers (strict ASN mode).
Choose policy for unknown IP locations (allow or block).
Enter MaxMind license key to enable local database lookups.
Select which countries are blocked (country-level only in Lite).

Logs tab

View past access attempts with location & decision.
Entries include hashed IP, country code, reason, and timestamp.
Option to clear logs with one click.
Automatic pruning runs daily based on retention settings (default 30 days).

Get Pro tab

Learn about Pro features.
State/province-level blocking for 7 countries.
Complete block page customization.
CSV export and advanced analytics.
Priority support and lifetime updates.

Navigation

Menu Location	Plug and Play Geoblocker Lite (shield icon) in the WP admin sidebar.
Permissions	Only roles with `manage_options` can see and change settings.
Settings Page	admin.php?page=bsas-settings

How It Works

This Lite version provides country-level geoblocking with the same powerful enforcement engine as Pro:

Early gate: Runs during plugins_loaded at priority 0, before theme output and most other plugins.
Multi-tier geo lookup: Uses local MaxMind DB if available. Falls back to Cloudflare headers, then rotates through multiple public APIs (ipwho.is, ip-api.com, ipapi.co, ipinfo.io) for redundancy.
Circuit breaker: Automatically disables failing APIs for 15 minutes to prevent cascading failures.
ASN screening: Detects suspicious Autonomous Systems (cloud/VPN/proxy providers) and can block them when strict mode is enabled.
Cookie bypass: Approved visitors get a signed short-lived cookie (30 minutes), avoiding repeated lookups.
Emergency bypass: Add ?bsas_unblock=1 to any URL to set bypass cookie manually.
No-cache headers: Block pages include comprehensive no-store headers so proxies/CDNs never cache them.
Admin/login exemptions: WordPress admin, login, AJAX, cron, and XML-RPC endpoints are always allowed.

Geo Lookup Priority

MaxMind GeoLite2 City DB (local, fastest, ~99% accurate) – requires license key
Cloudflare CF-IPCountry header (if site is behind Cloudflare)
Public APIs (with circuit breaker and SSL verification): ipwho.is, ip-api.com, ipapi.co, ipinfo.io

Performance: Geo lookups are cached for 24 hours using WordPress transients. Circuit breaker prevents wasting time on broken APIs.

Lite vs Pro Differences

Blocking Granularity	Lite: Country-level only Pro: State/province level for 7 countries (US, Canada, UK, China, Australia, India, Germany)
Block Page Customization	Lite: Fixed design with basic message Pro: Full customization (colors, HTML editor, CSS, redirects, placeholders)
Log Export	Lite: View logs only Pro: CSV export up to 10,000 entries
Support	Lite: Community support Pro: Priority email support

Privacy & Data

The plugin is designed with GDPR and privacy compliance in mind:

Logs Table: wp_bsas_logs stores access attempts with location and decision data.
IP Hashing: By default, IPs are stored as SHA-256 hashes salted with WordPress AUTH_SALT constant.
Optional Plain IP: Can be enabled for debugging, but disabled by default. Stored as VARBINARY(16) for efficiency.
Retention: Logs older than the configured retention (default 30 days) are automatically deleted daily via WP-Cron.
Rate limiting: Prevents excessive log rows from single IPs (default: 20 entries per IP per day).
Crawler exclusion: Major search engine crawlers are excluded from logging to reduce noise.
Cache management: Log counts and queries are cached to minimize database load.

Data Collected

IP Hash	SHA-256 hash of visitor IP (always stored)
IP Plain	Binary representation of IP (optional, disabled by default)
Location Code	2-character country code or “–” for unknown
Decision	blocked, allowed, bypassed, or error
Reason	Why the decision was made (e.g., “country_blocked”, “suspicious_asn”)
Timestamp	MySQL datetime of access attempt

Troubleshooting

Visitors from a blocked country still get through

Verify blocking is enabled in Control tab.
Check if visitor is using a crawler user-agent and “Allow Crawlers” is enabled.
Confirm your host is passing the real visitor IP (check for proxy headers: CF-Connecting-IP, X-Real-IP, X-Forwarded-For).
For higher accuracy, add a MaxMind license key and wait for the weekly database update (or trigger manually).
Check Logs tab to see what country was detected for that visitor.

Everyone is blocked or showing as “Unknown”

Ensure your server can make outbound HTTPS requests to API endpoints.
Check if APIs are temporarily down (plugin will try multiple sources automatically).
Confirm you are not forcing private IPs (like 127.0.0.1) in server configs.
If using strict ASN blocking, try disabling temporarily to test.
Set Unknown IP Policy to “Allow” temporarily for debugging.
Check error logs for circuit breaker messages about API failures.

Logs not updating

Log entries are rate-limited per IP (default 20/day) – check if limit is reached.
Search crawlers are excluded from logging if “Allow Crawlers” is enabled.
Admin, login, and AJAX requests are never logged.
Check that log cache isn’t stale – try clearing it and reloading.

MaxMind DB fails to download

Confirm your MaxMind license key is valid (try regenerating it).
Check folder permissions for /wp-content/uploads/ (needs write access).
Ensure PHP Phar extension is enabled.
Remember the updater runs weekly via WP-Cron — ensure WP-Cron is functioning.
Check server firewall allows outbound HTTPS to download.maxmind.com.

I accidentally blocked myself

Don’t worry! You have several recovery options:

WordPress Login: Go to your WP login URL (always accessible) and sign in as admin. The plugin never blocks admin areas.
Emergency Bypass: Add ?bsas_unblock=1 to any URL to set a bypass cookie.
FTP/SFTP: Rename the plugin folder temporarily to disable it.
Database: Run: UPDATE wp_options SET option_value='0' WHERE option_name='bsas_enabled'

Circuit breaker keeps triggering

Check server firewall and security plugins aren’t blocking outbound API requests.
Verify DNS resolution is working for API domains.
SSL verification is enabled – ensure SSL certificates are up to date.
If behind restrictive hosting, add a MaxMind license to reduce API dependency.
Circuit breaker automatically resets after 15 minutes of no failures.

Need state/province-level blocking?

The Lite version only supports country-level blocking. For state and province blocking across 7 countries (US, Canada, UK, China, Australia, India, Germany), you’ll need to upgrade to Pro.

Learn more about Pro features →

Test / Verification

Follow these steps to confirm the plugin is configured correctly:

Go to Control tab in plugin settings.
Verify the detected information for your current connection (IP and country will be logged when you visit the site).
Block your own country temporarily.
Open the site in an incognito/private window (or different browser) and confirm you see the block page.
Unblock your country and reload. You should be granted access.
Check the Logs tab to confirm entries for your IP showing “blocked” and then “allowed” decisions.
Test the emergency bypass: add ?bsas_unblock=1 to any URL while “blocked” to verify cookie bypass works.
If using MaxMind, verify the database file exists at /wp-content/uploads/GeoLite2-City.mmdb.

Testing with VPN/Proxy

Recommended: Use VPN services or proxy tools to simulate different countries and confirm blocking behavior matches your configuration. Test both allowed and blocked countries.

Performance Testing

Monitor the impact of geoblocking on your site:

First visit (no cookie): One geo lookup, cached for 24 hours
Subsequent visits: Cookie bypass, near-zero overhead
With MaxMind: Local DB lookup, ~1-2ms
Without MaxMind: API fallback, ~100-500ms (varies by network)
Circuit breaker prevents slow APIs from affecting performance

Upgrade to Pro

Ready for more powerful geoblocking? The Pro version includes:

State/Province-Level Blocking

Block or allow specific states and provinces in 7 countries:

United States: All 50 states + DC, Puerto Rico, Guam, U.S. Virgin Islands
Canada: All 10 provinces and 3 territories
United Kingdom: England, Scotland, Wales, Northern Ireland
China: All 31 provinces and autonomous regions
Australia: All 8 states and territories
India: All 28 states and 8 union territories
Germany: All 16 federal states

Complete Block Page Customization

Custom heading and body text with full HTML editor
Full color customization (background, text, accent colors)
Redirect blocked visitors to any custom URL
Use {STATE} placeholder for dynamic region names
Custom CSS editor with syntax highlighting

Enhanced Logging & Analytics

CSV export up to 10,000 log entries
Detailed reason codes for each decision
Configurable log retention periods

Premium Support

Priority email support
14-day money-back guarantee
Lifetime updates

Special Offer: Use code GEOPRO20 for 20% off!

Upgrade to Pro Now →