Why edge proxies use local .mmdb databases instead of remote HTTP calls
Every request that enters your infrastructure passes through an edge reverse proxy or load balancer—typically NGINX, OpenResty, HAProxy, Envoy, or a custom Go / Rust gateway.
If you want to:
- Route visitors to the nearest regional upstream using physical country geolocation (
X-Geo-Country), - Flag cross-border leased IPv4 ranges where the RIR registration country differs from physical routing (
X-Geo-Virtual), - Rate-limit aggressive autonomous systems (
X-Network-ASN) while exempting mobile 5G CGNAT gateways (X-Connection-Mobile), or - Challenge Tor exit nodes, public SOCKS/HTTP proxies, and commercial VPNs (
X-Security-VPN,X-Abuse-Score) before they hit your application servers,
making an external HTTP call on every incoming request adds network tail latency. By loading a downloadable MMDB database directly into NGINX (ngx_http_geoip2_module) or your Go/Rust edge worker via POSIX mmap, every lookup completes in microseconds (5.6 µs p50) inside the process's memory space with $0 per-lookup fees.
This guide shows how to wire ipscope .mmdb v2.0 files (starting with the free $0 ipscope Lite database or commercial editions from $20/mo) directly into NGINX and edge middleware.
Why a single unified ipscope .mmdb simplifies NGINX geoip2 configs
If you have configured NGINX's ngx_http_geoip2_module with MaxMind GeoIP2 or GeoLite2 before, you had to declare and maintain multiple geoip2 blocks pointing to separate .mmdb files—one for GeoIP2-City.mmdb, a second for GeoIP2-ASN.mmdb, and a third for GeoIP2-Anonymous-IP.mmdb.
Because ipscope compiles all of your licensed field families into a single unified .mmdb v2.0 file, your nginx.conf only needs one geoip2 database block to extract geolocation, BGP origin ASN, connection type, VPN/proxy/Tor flags, and abuse scores in a single radix-tree walk.
| NGINX Header Need | Field Path in ipscope .mmdb | Included in Free ipscope Lite ($0)? | Commercial Edition (from $20/mo) |
|---|---|---|---|
Effective Country (ISO-2) | geo country_code | Yes | Country ($20/mo), City ($63/mo), Complete ($250/mo) |
Declared RIR Country (ISO-2) | geo declared_country_code | Yes | Country ($20/mo), City ($63/mo), Complete ($250/mo) |
| Virtual Location Flag | geo is_virtual_location | Yes | Country ($20/mo), City ($63/mo), Complete ($250/mo) |
| City, Region & Timezone | geo city, geo subdivision, geo timezone | No | City ($63/mo), City+ASN ($94/mo), Complete ($250/mo) |
| BGP Origin ASN & Org | network asn, network organization | Yes | ASN ($36/mo), City+ASN ($94/mo), Complete ($250/mo) |
| Connection Type & Mobile CGNAT | connection connection_type, connection is_mobile | No | ASN & Connection ($36/mo), Complete ($250/mo) |
| VPN, Proxy, Tor & Hosting Flags | security is_vpn, security is_proxy, security is_tor_exit, security is_hosting, security anonymizer_type | No | Privacy, VPN & Hosting ($138/mo), Complete ($250/mo) |
Abuse Score (0–100) & Scanner | security_extensions abuse_velocity_score, security_extensions is_known_scanner | No | Complete ($250/mo) or Custom Builder (+$50/mo) |
Step 1: Download ipscope Lite (Free) or your commercial .mmdb
To test immediately with Country + BGP ASN at zero cost, download ipscope Lite (CC BY 4.0, no API key required):
mkdir -p /var/lib/ipscope
curl -fsSL "https://api.ipscope.io/v1/lite/ipscope-lite.mmdb" \
-o /var/lib/ipscope/ipscope.mmdbIf you have licensed a commercial preset or custom database (for example, Complete Mega Database or a custom Country + ASN + Privacy build on the Pricing page), pull it with your download-scoped key using atomic staging (see our full zero-downtime hot-reload script):
URL="$(curl -fsS -H "Authorization: Bearer ${IPSCOPE_DOWNLOAD_KEY}" \
"https://api.ipscope.io/v1/mmdb/releases/latest/download?format=mmdb" | jq -er '.download_url')"
curl -fsS -H "Authorization: Bearer ${IPSCOPE_DOWNLOAD_KEY}" "$URL" \
-o /var/lib/ipscope/.stage.ipscope.mmdb
mv -f /var/lib/ipscope/.stage.ipscope.mmdb /var/lib/ipscope/ipscope.mmdbStep 2: Production nginx.conf with ngx_http_geoip2_module
Install libmaxminddb and the NGINX GeoIP2 dynamic module (apt install libnginx-mod-http-geoip2 on Debian/Ubuntu, or apk add nginx-mod-http-geoip2 on Alpine).
In /etc/nginx/nginx.conf, map ipscope's nested .mmdb dictionary keys directly to NGINX variables and forward them to your upstream services:
load_module modules/ngx_http_geoip2_module.so;
http {
# Open the single unified ipscope MMDB file (auto_reload checks inode changes)
geoip2 /var/lib/ipscope/ipscope.mmdb {
auto_reload 5m;
# 1. Geolocation fields (available in Lite, Country, City & Complete)
$ipscope_country_code source=$remote_addr geo country_code;
$ipscope_declared_country source=$remote_addr geo declared_country_code;
$ipscope_is_virtual source=$remote_addr geo is_virtual_location;
$ipscope_city source=$remote_addr geo city;
$ipscope_accuracy_radius source=$remote_addr geo accuracy_radius_km;
# 2. BGP Origin ASN & Organization (available in Lite, ASN, City+ASN & Complete)
$ipscope_asn source=$remote_addr network asn;
$ipscope_asn_org source=$remote_addr network organization;
# 3. Connection classification (available in ASN & Connection, Complete, or Custom)
$ipscope_conn_type source=$remote_addr connection connection_type;
$ipscope_is_mobile source=$remote_addr connection is_mobile;
# 4. Privacy & Threat flags (available in Privacy, Complete, or Custom)
$ipscope_is_vpn source=$remote_addr security is_vpn;
$ipscope_is_proxy source=$remote_addr security is_proxy;
$ipscope_is_tor source=$remote_addr security is_tor_exit;
$ipscope_is_hosting source=$remote_addr security is_hosting;
$ipscope_anonymizer_type source=$remote_addr security anonymizer_type;
# 5. Blocklist Abuse Score 0-100 (available in Complete or Custom +$50/mo)
$ipscope_abuse_score source=$remote_addr security_extensions abuse_velocity_score;
$ipscope_is_scanner source=$remote_addr security_extensions is_known_scanner;
}
# Optional: Flag high-risk anonymizers (Tor exits or open proxies) for sensitive routes
map "$ipscope_is_tor:$ipscope_is_proxy" $block_sensitive_mutation {
default 0;
"~^1:" 1;
"~:1$" 1;
}
server {
listen 443 ssl http2;
server_name app.example.com;
# Protect login & checkout POST mutations from Tor exits and public proxies
location ~ ^/(api/auth/login|api/checkout) {
if ($block_sensitive_mutation = 1) {
return 403 '{"error":"anonymizer_restricted","type":"$ipscope_anonymizer_type"}';
}
proxy_pass http://backend_upstream;
}
location / {
# Inject zero-latency IP intelligence headers for upstream microservices
proxy_set_header X-IPScope-Country $ipscope_country_code;
proxy_set_header X-IPScope-Declared-Country $ipscope_declared_country;
proxy_set_header X-IPScope-Virtual-Location $ipscope_is_virtual;
proxy_set_header X-IPScope-City $ipscope_city;
proxy_set_header X-IPScope-Accuracy-Km $ipscope_accuracy_radius;
proxy_set_header X-IPScope-ASN $ipscope_asn;
proxy_set_header X-IPScope-ASN-Org $ipscope_asn_org;
proxy_set_header X-IPScope-Connection-Type $ipscope_conn_type;
proxy_set_header X-IPScope-Is-Mobile $ipscope_is_mobile;
proxy_set_header X-IPScope-Is-VPN $ipscope_is_vpn;
proxy_set_header X-IPScope-Anonymizer-Type $ipscope_anonymizer_type;
proxy_set_header X-IPScope-Abuse-Score $ipscope_abuse_score;
proxy_pass http://backend_upstream;
}
}
}Why ngx_http_geoip2_module shares memory across all NGINX workers
When NGINX loads /var/lib/ipscope/ipscope.mmdb via libmaxminddb, the file is mapped into memory with mmap(2) (MAP_SHARED / read-only page cache). Whether your server runs 4 NGINX worker processes or 64 worker processes, the Linux kernel backs all workers with one shared copy of the .mmdb file in physical RAM.
Step 3: Enriching structured JSON access logs for SIEM ingestion
Because NGINX now resolves $ipscope_country_code, $ipscope_asn, $ipscope_anonymizer_type, and $ipscope_abuse_score in memory on every request, you can write those fields directly into your NGINX JSON access log at zero extra cost:
log_format json_enriched escape=json
'{'
'"time":"$time_iso8601",'
'"remote_addr":"$remote_addr",'
'"method":"$request_method",'
'"uri":"$uri",'
'"status":$status,'
'"country":"$ipscope_country_code",'
'"declared_country":"$ipscope_declared_country",'
'"asn":"$ipscope_asn",'
'"conn_type":"$ipscope_conn_type",'
'"anonymizer":"$ipscope_anonymizer_type",'
'"abuse_score":"$ipscope_abuse_score"'
'}';
access_log /var/log/nginx/access_enriched.json json_enriched;And if you ever need to backfill historical un-enriched logs in your data warehouse, every paid ipscope database subscription also includes the GZIP-compressed Apache Parquet (.parquet) file from the exact same release (see our DuckDB & ClickHouse Parquet join guide).
Frequently asked questions (FAQ)
Does ngx_http_geoip2_module work with ipscope .mmdb files without patching NGINX?
Yes. ngx_http_geoip2_module uses libmaxminddb under the hood, which reads any standard MaxMind DB v2.0 binary file. Unlike legacy modules that hard-code GeoIP2 key paths, ngx_http_geoip2_module lets you specify the exact dictionary path (geo country_code, network asn, security is_vpn) in nginx.conf.
What if my client traffic arrives behind Cloudflare, AWS ALB, or Fastly?
Either configure NGINX's ngx_http_realip_module (set_real_ip_from + real_ip_header CF-Connecting-IP; or X-Forwarded-For) so $remote_addr holds the real visitor IP, or pass source=$http_x_forwarded_for on each field in the geoip2 block.
Why shouldn't I hard-block every is_vpn = 1 or is_mobile = 1 request in NGINX?
Commercial VPNs are widely used by privacy-conscious consumers, and cellular 4G/5G gateways (is_mobile = 1) share a single public IPv4 address across hundreds of subscribers via CGNAT (read our 5G CGNAT engineering guide). Instead of returning 403 to VPNs on read-only pages, pass X-IPScope-Is-VPN and X-IPScope-Anonymizer-Type (apple_private_relay vs vpn vs tor_exit) to your application so it can trigger step-up MFA or a CAPTCHA only on sensitive actions like sign-up or checkout.
How much does an ipscope .mmdb database license cost for NGINX servers?
ipscope Lite (Country + BGP ASN) is Free ($0/mo) under CC BY 4.0. Commercial databases (.mmdb + .csv.gz + .parquet included together) start at $20/mo for Country, $36/mo for ASN & Connection, $63/mo for City Geolocation, $138/mo for Privacy, VPN & Hosting, and $250/mo for the Complete Mega Database on the Pricing page. Each commercial subscription includes 1 internal server by default (+20% per additional server up to 10 servers; 10+ servers cost the same as 10), with $0 per-lookup fees.