GEO Location Filtering and Database Licensing

VNetArmor can apply security policy based on the geographic location associated with a client IP address. This feature is useful for country-based access control, regional application restrictions, administrative access protection, and security monitoring.

External GEO database requirement

VNetArmor performs GEO policy enforcement, but country lookup requires a compatible GEO database or trusted upstream GEO metadata. Commercial GEO databases are not bundled with VNetArmor. Customers are responsible for obtaining, licensing, updating, and operating any third-party GEO database they choose to use.

When to Use GEO Filtering

Common use cases include:

• Allowing traffic only from approved countries.
• Blocking traffic from selected countries.
• Applying different policies to public, API, and admin routes.
• Restricting administrative applications to known regions.
• Adding country fields to logs for investigation and reporting.

GEO filtering should be treated as a policy control, not as the only security control. Combine it with L4 ACLs, trusted proxy validation, rate limiting, WAF rules, authentication, and monitoring.

Request Flow

graph TD
  A[Client request] --> B[Trusted proxy validation]
  B --> C[Client IP extraction]
  C --> D[GEO database or trusted GEO metadata lookup]
  D --> E[Country code determined]
  E --> F[GEO policy evaluation]
  F --> G{Decision}
  G -->|Allow or Monitor| H[Continue to route, rate limit, WAF, backend]
  G -->|Block| I[Return block response and log event]

Text view:

Client
  |
  v
Trusted proxy validation
  |
  v
Client IP extraction
  |
  v
GEO database lookup
  |
  v
Country determined
  |
  v
GEO policy evaluation
  |
  v
Allow / Block / Monitor
  |
  v
Application

GEO Data Sources

VNetArmor deployments can use one or more GEO data inputs depending on the licensed edition and deployment model.

Source	Typical use	Notes
Local GEO database file	Production or offline deployments	Preferred when the customer wants local control of database files and update timing.
Trusted proxy or CDN GEO header	Deployments behind an approved proxy/CDN	Only accept GEO headers from trusted proxy CIDRs. Never trust GEO headers from the public internet.
Manual CIDR-to-country map	Labs, exceptions, and controlled internal ranges	Useful for testing and small controlled mappings. Not a replacement for a full GEO database.
UNKNOWN fallback	Missing or unresolved country	Use explicit policy for unknown countries. Do not assume unknown traffic is safe.

GEO Database Licensing

The VNetArmor license controls access to VNetArmor capabilities. The GEO database license is separate.

Customers are responsible for:

• Choosing an approved GEO data provider.
• Purchasing a commercial database license where required.
• Complying with the GEO data provider's redistribution, download, update, and usage terms.
• Maintaining update subscriptions if the provider requires them.
• Keeping proof of entitlement according to their internal compliance process.

VNetArmor documentation uses generic examples only. Do not publish real GEO provider credentials, license keys, account IDs, or download URLs in public tickets, screenshots, or shared documents.

Free vs Commercial GEO Databases

Option	Suitable for	Considerations
Free or community database	Labs, demos, development, proof-of-concept work	Accuracy, coverage, and update frequency may be limited. Review license terms before production use.
Commercial database	Production, regulated, customer-facing, or enterprise deployments	Usually provides better coverage, update cadence, and vendor support. Requires a valid third-party license.

For production, use a regularly updated commercial or organization-approved GEO data source.

Suggested File Locations

Package deployments:

/etc/vnetarmor/geo/GeoIP-country.mmdb
/etc/vnetarmor/geo/geo_ip_map.conf
/etc/vnetarmor/geo/geo_rules.conf

Container deployments:

/config/geo/GeoIP-country.mmdb
/config/geo/geo_ip_map.conf
/config/geo/geo_rules.conf

Recommended permissions:

sudo chown root:vnetarmor /etc/vnetarmor/geo/*
sudo chmod 0640 /etc/vnetarmor/geo/*

Container mounts should be read-only where possible:

volumes:
  - /opt/vnetarmor/config:/config:ro
  - /opt/vnetarmor/geo:/config/geo:ro

Configuration Example

Example server.conf entries:

geo_enabled=true
geo_rules_file=/etc/vnetarmor/geo/geo_rules.conf
geo_db_path=/etc/vnetarmor/geo/GeoIP-country.mmdb
geo_ip_map_file=/etc/vnetarmor/geo/geo_ip_map.conf
geo_trusted_proxy_cidrs=10.0.0.0/8,192.0.2.0/24
geo_trusted_headers=CF-IPCountry,X-Geo-Country
geo_unknown_action=MONITOR

Container example:

geo_enabled=true
geo_rules_file=/config/geo/geo_rules.conf
geo_db_path=/config/geo/GeoIP-country.mmdb
geo_ip_map_file=/config/geo/geo_ip_map.conf
geo_trusted_proxy_cidrs=10.0.0.0/8,192.0.2.0/24
geo_unknown_action=MONITOR

Note

Configuration key names may vary by release. Always compare against the shipped sample configuration for your version under Sample Configs.

GEO Rule Examples

Allow only selected countries:

RULE=allow_approved_countries
ACTION=ALLOW
IF COUNTRY=GB,US,CA

Block selected countries:

RULE=block_selected_countries
ACTION=BLOCK
IF COUNTRY=KP,RU

Monitor unresolved countries before enforcement:

RULE=monitor_unknown_country
ACTION=MONITOR
IF COUNTRY=UNKNOWN

Route-specific example:

ROUTE=admin.example.com:/admin
RULE=admin_allow_gb
ACTION=ALLOW
IF COUNTRY=GB

ROUTE=admin.example.com:/admin
RULE=admin_block_other_regions
ACTION=BLOCK
IF COUNTRY=*

Trusted Proxy and Header Safety

Only trusted infrastructure should be allowed to provide client IP or GEO headers.

Recommended approach:

1. Define trusted proxy CIDRs.
2. Extract client IP from approved headers only when the request came from a trusted proxy.
3. Ignore public client-supplied country headers.
4. Log the resolved client IP, proxy IP, and country decision.

Example safe pattern:

Internet client
  -> approved load balancer or CDN
  -> VNetArmor
  -> app01.example.local

Unsafe pattern:

Internet client
  -> VNetArmor trusting arbitrary X-Geo-Country header

Updating GEO Databases

Use the GEO provider's supported update mechanism. A typical controlled update process is:

sudo install -d -m 0750 -o root -g vnetarmor /etc/vnetarmor/geo
sudo cp GeoIP-country.mmdb.new /etc/vnetarmor/geo/GeoIP-country.mmdb.new
sudo chown root:vnetarmor /etc/vnetarmor/geo/GeoIP-country.mmdb.new
sudo chmod 0640 /etc/vnetarmor/geo/GeoIP-country.mmdb.new
sudo mv /etc/vnetarmor/geo/GeoIP-country.mmdb.new /etc/vnetarmor/geo/GeoIP-country.mmdb
sudo systemctl reload vnetarmor-core

Container deployment example:

sudo cp GeoIP-country.mmdb.new /opt/vnetarmor/geo/GeoIP-country.mmdb
cd /opt/vnetarmor/compose
docker compose exec core vnetarmorctl reload || docker compose restart core

Recommended update cadence:

Environment	Suggested cadence
Lab	Monthly or before testing.
Standard production	Weekly.
Security-sensitive production	Daily or according to provider guidance.

Validation

After loading or updating a GEO database:

sudo journalctl -u vnetarmor-core -n 100 --no-pager | grep -i geo
vnetarmorctl --server manager01.example.local:9443 status
curl -kI https://www.example.com/

Validate representative countries in monitor mode before enabling broad blocking.

Logging Fields

GEO-related events should include enough data for operations and support teams to understand the decision.

Example allowed event:

{
  "module": "geo",
  "client_ip": "203.0.113.10",
  "country": "GB",
  "decision": "ALLOW",
  "rule_id": "geo_allow_approved_countries",
  "host": "www.example.com"
}

Example blocked event:

{
  "module": "geo",
  "client_ip": "198.51.100.10",
  "country": "RU",
  "decision": "BLOCK",
  "rule_id": "geo_block_selected_countries",
  "host": "admin.example.com"
}

Best Practices

• Use monitor mode before enforcing new country blocks.
• Keep GEO database updates in change control.
• Use a paid or approved GEO database for production deployments.
• Do not treat country data as identity or authentication.
• Always configure trusted proxy CIDRs when behind a CDN, load balancer, or reverse proxy.
• Create an emergency access path for administrators before enforcing strict country allow lists.
• Log UNKNOWN countries and review before deciding whether to block them.
• Combine GEO with L4 ACLs, rate limits, WAF rules, authentication, and alerting.

Troubleshooting

Symptom	Likely cause	Resolution
GEO country is UNKNOWN	Missing database, unsupported format, private IP, or lookup miss.	Verify database path, permissions, and update status.
All traffic appears from one country	VNetArmor is using proxy IP instead of real client IP.	Configure trusted proxy CIDRs and client IP extraction.
Rules do not match expected countries	Outdated GEO database or incorrect rule syntax.	Update the database and validate geo_rules.conf.
GEO headers are ignored	Request did not come from trusted proxy CIDR.	Add only approved proxy CIDRs. Do not trust public sources.
Core fails to reload	Invalid file path, permissions, or config syntax.	Check Core logs and run config validation before reload.
Production traffic blocked unexpectedly	Strict rule enforced without monitor validation.	Roll back rule, switch to monitor mode, then review logs.

See also GEO Rules, Configuration Reference, and Troubleshooting.