Apache HTTP Server IP Geolocation and VPN Blocking with IPGeolocation.io

Overview

With the open source mod_maxminddb module, Apache HTTP Server looks up the client address of every request in IPGeolocation.io databases and exposes the answers as environment variables. Because this happens inside the web server, before your application runs, you can log, forward, block or redirect requests by location and risk without changing application code.

This guide works with three databases. The IP Geolocation Database answers where a visitor is: country, region, city, coordinates and time zone. The IP Security Database answers whether the connection hides behind a VPN, a proxy or Tor, and how risky it is overall. The IP to ASN Database names the autonomous system that announces the address and the organization behind it.

Apache can read any IPGeolocation.io IP database in MMDB format the same way. Besides the three above, that covers the IP to Country, IP to City and IP to ASN databases, the IP to Company Database, IP Abuse Contact Database, IP WHOIS Database, IP to Hosting Database and Residential Proxy Database, and combined databases that hold several datasets in a single file.

Every lookup reads a file on the web server itself, so it costs no API call and no network time, and visitor addresses are never sent anywhere. If you are still weighing the options, read IP geolocation API vs database.

What Apache can do with the variables

Where it pays off

• Credential stuffing and fake sign-ups. Turn away anonymized connections at the sign-in page before they reach your login code.
• Localized landing pages. Redirect by country in one rewrite rule, with no JavaScript and no extra request.
• Older applications. Give a legacy PHP or CGI application country and risk data through variables it can already read.
• Log analysis. Write location and network data into the access log, where existing log tools pick it up.

About mod_maxminddb

mod_maxminddb is an open source module for Apache 2.4, released under the Apache License 2.0, that reads any file in the MMDB format. Ubuntu and Debian do not package it, so you build it from source; Fedora and EPEL ship it as the mod_maxminddb package.

The module adds five directives. MaxMindDBFile opens a database, MaxMindDBEnv maps a value to an environment variable, and MaxMindDBEnable switches lookups on. MaxMindDBNetworkEnv and MaxMindDBSetNotes are optional extras covered in the reference below.

How a request gets its variables

1. If mod_remoteip is set up, it replaces a trusted proxy's address with the visitor's address.
2. Early in request processing, mod_maxminddb looks that address up in every file declared with MaxMindDBFile .
3. For each MaxMindDBEnv whose path exists in the record, it sets an environment variable. It also sets MMDB_ADDR and MMDB_INFO .
4. Later modules use the variables: mod_rewrite , access rules, mod_headers , the access log, and PHP or CGI programs.

mod_maxminddb runs before mod_rewrite and mod_setenvif , so rewrite conditions and SetEnvIf rules can already see the values.

1{
2  "asn": {
3    "as_number": "9009",
4    "country_code": "RO",
5    "domain": "m247.com",
6    "organization": "M247 Europe SRL",
7    "type": "HOSTING"
8  }
9}

Requirements

Quick start

These steps add location, security and network variables to every request on a Debian or Ubuntu server, then show them with a test request.

1/usr/local/share/ipgeolocation/
2├── db-ip-asn.mmdb
3├── db-ip-location.mmdb
4└── db-ip-security.mmdb

# Use the visitor's address when a proxy or load balancer sits in front of
# Apache. List only proxies you control.
RemoteIPHeader X-Forwarded-For
RemoteIPInternalProxy 127.0.0.1

MaxMindDBEnable On
MaxMindDBFile LOCATION /usr/local/share/ipgeolocation/db-ip-location.mmdb
MaxMindDBFile SECURITY /usr/local/share/ipgeolocation/db-ip-security.mmdb
MaxMindDBFile ASN      /usr/local/share/ipgeolocation/db-ip-asn.mmdb

MaxMindDBEnv IPGEO_COUNTRY_CODE LOCATION/location/country/code2
MaxMindDBEnv IPGEO_COUNTRY_NAME LOCATION/location/country/name/en
MaxMindDBEnv IPGEO_REGION       LOCATION/location/state/name/en
MaxMindDBEnv IPGEO_CITY         LOCATION/location/city/name/en
MaxMindDBEnv IPGEO_LATITUDE     LOCATION/location/coordinates/latitude
MaxMindDBEnv IPGEO_LONGITUDE    LOCATION/location/coordinates/longitude
MaxMindDBEnv IPGEO_TIME_ZONE    LOCATION/time_zone

MaxMindDBEnv IPGEO_THREAT_SCORE SECURITY/threat_score
MaxMindDBEnv IPGEO_IS_VPN       SECURITY/is_vpn
MaxMindDBEnv IPGEO_IS_PROXY     SECURITY/is_proxy
MaxMindDBEnv IPGEO_IS_TOR       SECURITY/is_tor
MaxMindDBEnv IPGEO_IS_ANONYMOUS SECURITY/is_anonymous

MaxMindDBEnv IPGEO_ASN          ASN/asn/as_number
MaxMindDBEnv IPGEO_AS_ORG       ASN/asn/organization

sudo a2enconf ipgeolocation
sudo apachectl configtest && sudo systemctl reload apache2

# Testing only: echo some of the values back as response headers.
Header set X-IPGeo-Country "%{IPGEO_COUNTRY_CODE}e" env=IPGEO_COUNTRY_CODE
Header set X-IPGeo-City    "%{IPGEO_CITY}e"         env=IPGEO_CITY
Header set X-IPGeo-VPN     "%{IPGEO_IS_VPN}e"       env=IPGEO_IS_VPN
Header set X-IPGeo-Threat  "%{IPGEO_THREAT_SCORE}e" env=IPGEO_THREAT_SCORE
Header set X-IPGeo-ASN     "%{IPGEO_ASN}e"          env=IPGEO_ASN

curl -s -o /dev/null -D - -H 'X-Forwarded-For: 37.120.202.92' http://localhost/ | grep -i '^x-ipgeo'

1X-IPGeo-Country: US
2X-IPGeo-City: Secaucus
3X-IPGeo-VPN: true
4X-IPGeo-Threat: 50
5X-IPGeo-ASN: 9009

Recipes

Each recipe builds on the quick start configuration.

LogFormat "%a %t \"%r\" %>s country=%{IPGEO_COUNTRY_CODE}e city=\"%{IPGEO_CITY}e\" vpn=%{IPGEO_IS_VPN}e threat=%{IPGEO_THREAT_SCORE}e asn=%{IPGEO_ASN}e" ipgeo
CustomLog ${APACHE_LOG_DIR}/access-ipgeo.log ipgeo

37.120.202.92 [06/Oct/2026:13:11:05 +0500] "GET / HTTP/1.1" 200 country=US city="Secaucus" vpn=true threat=50 asn=9009

<?php
$country = $_SERVER['IPGEO_COUNTRY_CODE'] ?? null;
$isVpn   = ($_SERVER['IPGEO_IS_VPN'] ?? '') === 'true';

# Drop any copy the client sent, then add the value Apache looked up.
RequestHeader unset X-IPGeo-Country
RequestHeader set X-IPGeo-Country "%{IPGEO_COUNTRY_CODE}e" env=IPGEO_COUNTRY_CODE

# Refuse every request with a threat score of 80 or more.
<Location "/">
    <RequireAll>
        Require all granted
        Require not expr "-n %{ENV:IPGEO_THREAT_SCORE} && %{ENV:IPGEO_THREAT_SCORE} -ge 80"
    </RequireAll>
</Location>

# On the sign-in page, also refuse VPNs, proxies and Tor.
<Location "/login">
    AuthMerging And
    <RequireAll>
        Require all granted
        Require not expr "%{ENV:IPGEO_IS_ANONYMOUS} == 'true'"
    </RequireAll>
</Location>

RewriteEngine On
RewriteCond %{ENV:IPGEO_COUNTRY_CODE} ^(DE|AT|CH)$
RewriteRule ^/$ /de/ [R=302,L]

Working with the values

Lists. Provider names are lists. A path that ends at the list, such as SECURITY/vpn_provider_names , sets nothing and writes Database error: unknown data type to the error log on every request. Add an index, SECURITY/vpn_provider_names/0 , to read the first name.

Languages. Place names exist in cs , de , en , es , fa , fr , it , ja , ko , pt , ru and zh . Change the last part of the path, as in LOCATION/location/city/name/de . A missing translation gives an empty value.

Keeping the databases up to date

IPGeolocation.io issues new database releases daily or weekly, depending on your plan. Apache opens each file when it reads its configuration, so a replaced file is used only after a graceful restart. apachectl graceful lets current requests finish while new workers pick up the new files.

Each release arrives as a ZIP archive. It holds the MMDB file of the database, or several files for a combined plan, along with a README.md and a checksum.txt with the SHA-256 hash of every file. Installing a release safely takes four steps:

1. Download and unpack the archive in a temporary folder on the same disk as the live databases.
2. Check every file against checksum.txt , and check each database with the mmdbio command-line tool. A failed check stops the update and leaves the live files untouched.
3. Move each new MMDB file over the old one. A rename within one disk is atomic, so Apache never reads a half-written file.
4. Run apachectl configtest , then apachectl graceful .

This script performs all four. Set DOWNLOAD_URL to the MMDB download link from your IPGeolocation.io account; it needs curl , unzip , sha256sum and mmdbio :

#!/bin/sh
# Install a new IPGeolocation.io database release and restart Apache gracefully.
set -eu

DB_DIR=/usr/local/share/ipgeolocation
DOWNLOAD_URL="<MMDB download link from your IPGeolocation.io account>"

# 1. Download and unpack the release next to the live databases.
WORK=$(mktemp -d "$DB_DIR/.release.XXXXXX")
trap 'rm -rf "$WORK"' EXIT
curl -fsSL -o "$WORK/release.zip" "$DOWNLOAD_URL"
# -DD stamps the unpacked files with the current time, not the archive's.
unzip -q -DD "$WORK/release.zip" -d "$WORK"
rm "$WORK/release.zip"

# 2. Check the files against the release checksums, then check each database.
(cd "$WORK" && sha256sum --quiet -c checksum.txt)
for db in "$WORK"/*.mmdb; do
    mmdbio verify --db "$db"
done

# 3. Swap the databases in. Each rename is atomic.
for db in "$WORK"/*.mmdb; do
    mv "$db" "$DB_DIR/"
done

# 4. Restart gracefully, but only if the configuration still loads.
apachectl configtest && apachectl graceful

The archive keeps the same file names from release to release, so the paths in MaxMindDBFile never change. For a combined plan, the script installs every MMDB file in the archive in one run.

Run it as root from cron, on the same schedule as your plan's releases. If any check fails, the script exits with an error, deletes the temporary folder and leaves Apache serving the previous release.

Production checklist

• Trust only your own proxies. RemoteIPInternalProxy and RemoteIPTrustedProxy decide whose X-Forwarded-For header Apache believes. A proxy missing from the list makes every visitor look like the proxy; an address that should not be on it lets clients choose their own location.
• Never forward client-supplied copies. Always RequestHeader unset an X-IPGeo-* header before setting it.
• Load the module explicitly. Keep the directives outside <IfModule> , so a missing module stops apachectl configtest instead of quietly disabling your access rules.
• Mind the order of <Location> sections. A later section replaces earlier access rules unless it uses AuthMerging And .
• Remove test headers. The X-IPGeo-* response headers from the quick start are for testing only.

Troubleshooting

No variables are set, and nothing appears in the error log. The module is not loaded, but its directives sit inside <IfModule mod_maxminddb.c> , so Apache skips them. Run apachectl -M | grep maxminddb , and enable the module with a2enmod maxminddb .

Invalid command 'MaxMindDBEnable', perhaps misspelled or defined by a module not included in the server configuration . The module is not loaded. Enable it as above.

MaxMindDBFile: Failed to open ... . Apache cannot open the file at that path. Check the spelling and the file permissions.

Database error: unknown data type . A MaxMindDBEnv path ends at a list or a group, such as SECURITY/vpn_provider_names or LOCATION/location/country/name . Add an index ( /0 ) or a language ( /en ).

Every visitor gets the location of your load balancer. mod_remoteip is not enabled, RemoteIPHeader names the wrong header, or the load balancer is missing from RemoteIPInternalProxy .

negative Require directive has no effect in <RequireAny> directive . A Require not line stands on its own. Wrap it in <RequireAll> together with Require all granted .

The /login rule never blocks anything. A later <Location "/"> section replaced it. Put the broader section first and add AuthMerging And to the narrower one.

MMDB_INFO says lookup success but other variables are missing. The address is not in that database. Check it with mmdbio:

mmdbio read --db /usr/local/share/ipgeolocation/db-ip-location.mmdb --ip 37.120.202.92

A new database release has no effect. Apache still holds the previous file. Run apachectl graceful .

FAQ

Related

• IPGeolocation.io MMDB field reference
• IP Geolocation Database documentation
• IP Security Database documentation
• IP to ASN Database documentation
• IP to Company Database documentation
• IPGeolocation.io Nginx module, for sites that run Nginx
• All IPGeolocation.io integrations