Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Integrations › GeoIP

GeoIP

GeoIP integration

Status: SUPPORTED when a GeoIP database is loadedAudience: security engineer

What it does

Maps source IPs to ISO country codes and applies GEOIP_BLOCK / GEOIP_ALLOW rules. Lookup is admin-only (POST /api/v1/geoip/lookup). Agents can pull config/database for local detection.

Edition

SHARED. Enterprise writes may be license-gated.

Prerequisites

  • Manager with security.geoip configured
  • MaxMind or DB-IP MMDB file at database_path
  • Optional MaxMind account id + license key for auto-update
  • Admin JWT for API

Required permissions / credentials

  • Filesystem read of the MMDB
  • MaxMind license key if auto_update (secret)
  • Admin role for rule CRUD and lookup

Configuration

security.geoip.*: enabled, database_type (maxmind or db-ip), database_path, maxmind_account_id, maxmind_license_key, update_interval, auto_update, cache_size, allow_on_lookup_failure.

Agent: geoip.enabled / geoip.database_path for local DB, or pull via Agent sync APIs.

Setup

  1. Place MMDB on the Manager host; set database_path.
  2. Set enabled: true; keep license key in systemd credentials.
  3. Restart Manager.
  4. Create a rule:
{"rule_type":"GEOIP_BLOCK","country_code":"CN","action":"block","enabled":true,"scope":"global"}
  1. Lookup a documentation IP: {"ip":"203.0.113.10"} (may be unallocated; use a known public IP in lab only if policy allows).

Verification

  • GET /api/v1/geoip/settings → database_status loaded or error
  • GET /api/v1/geoip/status → enabled, database_loaded, rules_count
  • GET /api/v1/geoip/rules lists countries

Settings probe uses lookup of 8.8.8.8 internally to test DB load.

Expected signals / results

Blocked countries generate GeoIP-related security logs on enforcement Agents after sync. allow_on_lookup_failure fail-opens on DB errors.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomMeaning
503 GeoIP service not availablelookup service nil
503 GeoIP lookup failedDB missing/corrupt
400 country codenot 2-letter ISO
database_status: not_loadedpath/permissions

Troubleshooting

  • Confirm file readable by zwall-manager
  • Disable auto-update if MaxMind HTTP is blocked
  • Agents: GET /api/v1/agent-geoip-database with Agent JWT

Security considerations

Lookup is admin-only. Do not publish it as an unauthenticated geolocation API. License keys are secrets. Account id may appear in settings JSON.

Limitations

  • Not a full MaxMind Insights product
  • Country rules are coarse; RFC1918 lookups depend on DB content
  • No published accuracy SLA