Set Up Geo-Blocking

Setup

Via the UI

The toggle sits in the route wizard in Step 4 — Access (together with Peer ACL, Rate Limiting and Uptime Monitoring).

1. Create or edit a route
2. In Step 4 enable the IP Access Control toggle
3. Choose mode: Whitelist or Blacklist
4. Add rules:
   • Select type (IP, CIDR, Country)
   • Enter value (e.g. 203.0.113.50, 10.0.0.0/8, DE)
5. Save

For country-based filtering: enter the Settings → Advanced → ip2location.io API Key. Country matching additionally requires the license feature geo_ip_filtering to be unlocked for the installation; without a key the server logs a warning and ignores the country rule.

Via the API

# Enable IP filter with whitelist
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ip_filter_enabled": true,
    "ip_filter_mode": "whitelist",
    "ip_filter_rules": [
      { "type": "cidr", "value": "185.10.20.0/24" },
      { "type": "ip", "value": "203.0.113.50" }
    ]
  }'

# IP filter with country blacklist
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ip_filter_enabled": true,
    "ip_filter_mode": "blacklist",
    "ip_filter_rules": [
      { "type": "country", "value": "CN" },
      { "type": "country", "value": "RU" }
    ]
  }'

Important notes

• Difference from Peer ACL: ACL only filters WireGuard peer IPs (10.8.0.x). IP Access Control filters any arbitrary IP address.
• Country lookup requires an ip2location.io API key. Without a key, country rules are ignored.
• The GeoIP cache stores up to 10,000 entries for 24 hours. On cache miss an API call is made (max 5 seconds timeout).
• IPv6-mapped IPv4 addresses (::ffff:192.168.1.1) are automatically reduced to IPv4.
• IP Access Control only works with Route Auth or as a standalone forward-auth check. With Basic Auth the IP filter is not available.
• An empty whitelist allows nobody. An empty blacklist blocks nobody.
• IP filter is only available for HTTP routes, not for L4 (TCP/UDP).

See also

• PEER-ACCESS-CONTROL.md — ACL at the WireGuard peer level
• RATE-LIMITING.md — complementary per-client-IP
• concepts/routing.md — Placement in the access tiers