All dispatches/Databases

NGINX, OpenResty & Go Edge Middleware: Using Downloadable MMDB Databases for IP Geolocation and VPN Blocking

Production configuration guide for loading ipscope downloadable MMDB v2.0 databases into NGINX (ngx_http_geoip2_module) and Go/Node.js edge proxies to inject country, BGP ASN, and VPN/Tor headers in microseconds.

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 NeedField Path in ipscope .mmdbIncluded in Free ipscope Lite ($0)?Commercial Edition (from $20/mo)
Effective Country (ISO-2)geo country_codeYesCountry ($20/mo), City ($63/mo), Complete ($250/mo)
Declared RIR Country (ISO-2)geo declared_country_codeYesCountry ($20/mo), City ($63/mo), Complete ($250/mo)
Virtual Location Flaggeo is_virtual_locationYesCountry ($20/mo), City ($63/mo), Complete ($250/mo)
City, Region & Timezonegeo city, geo subdivision, geo timezoneNoCity ($63/mo), City+ASN ($94/mo), Complete ($250/mo)
BGP Origin ASN & Orgnetwork asn, network organizationYesASN ($36/mo), City+ASN ($94/mo), Complete ($250/mo)
Connection Type & Mobile CGNATconnection connection_type, connection is_mobileNoASN & Connection ($36/mo), Complete ($250/mo)
VPN, Proxy, Tor & Hosting Flagssecurity is_vpn, security is_proxy, security is_tor_exit, security is_hosting, security anonymizer_typeNoPrivacy, VPN & Hosting ($138/mo), Complete ($250/mo)
Abuse Score (0–100) & Scannersecurity_extensions abuse_velocity_score, security_extensions is_known_scannerNoComplete ($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.mmdb

If 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.mmdb

Step 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.

Start with 30K free lookups a month.

No card, no trial clock. Upgrade when your traffic does, or download the database when you would rather keep it in-house.