Kong IP Geolocation Plugin for IPGeolocation.io

Overview

Geo-blocking, VPN and proxy detection, and IP intelligence headers for Kong Gateway, powered by IPGeolocation.io MMDB databases. The plugin reads the databases from local disk and answers every lookup inside Kong's worker processes, with no API calls and no per-request cost.

Use it to block traffic by country, stop Tor exit nodes, VPNs, proxies and known attackers before they reach your services, route visitors by region, and add country, city, ASN and threat data to upstream requests and access logs.

1# Block Tor and known attackers on /login, and tell every backend where visitors are
2plugins:
3  - name: ipgeolocation
4    route: login
5    config:
6      databases:
7        - /usr/local/share/ipgeolocation/db-ip-location.mmdb
8        - /usr/local/share/ipgeolocation/db-ip-security.mmdb
9      headers:
10        preset: standard
11      policy:
12        block_tor: true
13        block_known_attacker: true
14        block_threat_score_above: 80

Jump to: Installation | Quick start | Databases | Configuration | Headers | Security policy | Client IP | Updates | Troubleshooting | FAQ

Why use this plugin

Most Kong geolocation setups either call a remote API on every request or need a custom Kong build with a GeoIP library compiled in. This plugin ships as plain Lua, loads IPGeolocation.io databases once per worker, and answers each lookup locally in microseconds ( benchmarks).

• No API calls and no per-request billing. Every lookup is a read from a local file.
• Nothing to compile. The MMDB reader is pure LuaJIT, so it runs on a stock Kong Gateway with no libmaxminddb , Redis or extra Lua rocks.
• Decisions at the edge. Block or route in Kong before the request reaches authentication or your upstream.
• One plugin, many databases. Location, Security, Company, ASN, Abuse Contact, Hosting and Residential Proxy all load through one list, and the plugin layers them.
• Headers your backend can trust. The plugin removes every client supplied X-IPGeo-* header before it adds its own.
• Kong native. Global, Service and Route scopes, DB-less, PostgreSQL and hybrid mode, KongPlugin and KongClusterPlugin .
• The same field names, header names and presets as the IPGeolocation.io Nginx module and Traefik plugin, so a backend sees the same headers whichever gateway sits in front of it.

How it works

You list one or more .mmdb files under databases. Kong opens each file in every worker when the configuration loads, then for every request the plugin:

1. Takes the client address that Kong's own trusted proxy handling produced (see Client IP selection).
2. Removes any X-IPGeo-* header the client sent, so it cannot fake its location or reputation.
3. Looks the address up in each database, in the order you listed them.
4. For each field, takes the value from the first database that has it. List order is priority order.
5. Sets the headers you asked for, shares the result with other plugins, evaluates the policy, then forwards or blocks.

Because the first match wins, databases layer: load a Location and a Security database together, and country_code comes from the first while is_vpn comes from the second.

The files are memory mapped. The kernel shares the mapped pages between all workers, and only the pages that lookups touch are read from disk.

Requirements

• Kong Gateway 3.x on Linux. Tested end to end on Kong Gateway OSS 3.9.3 (DB-less) and with Kong's test harness on 3.9.2 against PostgreSQL and DB-less. Kong Gateway 3.10 LTS and 3.14 LTS use the same plugin APIs and are expected to work, but have not been tested yet.
• One or more IPGeolocation.io .mmdb databases.
• Read access to the database files for Kong's worker user ( kong in the official packages and images), including every directory above them.

Installation

Install the plugin on every Kong node that runs it. In hybrid mode that includes the control planes, which validate the configuration. Only the data planes need the database files.

luarocks install kong-plugin-ipgeolocation

git clone https://github.com/IPGeolocation/kong-plugin-ipgeolocation.git
cd kong-plugin-ipgeolocation
luarocks make kong-plugin-ipgeolocation-0.1.0-1.rockspec

docker build -f examples/docker/Dockerfile -t kong-ipgeolocation .

kubectl create configmap kong-plugin-ipgeolocation -n kong --from-file=kong/plugins/ipgeolocation

plugins = bundled,ipgeolocation

Quick start

These examples use DB-less declarative configuration. The same settings work through the Admin API ( POST /plugins with name=ipgeolocation ) and as a Kubernetes KongPlugin resource.

1_format_version: "3.0"
2services:
3  - name: api
4    url: http://api.internal:8080
5    routes:
6      - name: api
7        paths: [/]
8plugins:
9  - name: ipgeolocation
10    config:
11      databases:
12        - /usr/local/share/ipgeolocation/db-ip-location.mmdb
13        - /usr/local/share/ipgeolocation/db-ip-asn.mmdb
14      headers:
15        preset: standard

X-IPGeo-Country-Code: PK
X-IPGeo-Country-Name: Pakistan
X-IPGeo-Continent-Code: AS
X-IPGeo-State-Code: PK-PB
X-IPGeo-City-Name: Lahore
X-IPGeo-Zip-Code: 54000
X-IPGeo-Latitude: 31.54972
X-IPGeo-Longitude: 74.34361
X-IPGeo-Time-Zone: Asia/Karachi
X-IPGeo-ASN: AS64500
X-IPGeo-Organization-Name: Example Telecom PK

1plugins:
2  - name: ipgeolocation
3    service: shop
4    config:
5      databases: [/usr/local/share/ipgeolocation/db-ip-country.mmdb]
6      headers: { preset: none }
7      policy:
8        allowed_countries: [DE, AT, CH]
9        allow_unknown: false
10        status_code: 451
11        message: This service is not available in your region

1plugins:
2  - name: ipgeolocation
3    route: login
4    config:
5      databases: [/usr/local/share/ipgeolocation/db-ip-security.mmdb]
6      headers: { preset: none }
7      policy:
8        block_tor: true
9        block_vpn: true
10        block_proxy: true
11        block_residential_proxy: true
12        block_known_attacker: true
13        block_threat_score_above: 80

trusted_ips = 10.0.0.0/8
real_ip_header = X-Forwarded-For
real_ip_recursive = on

Getting the databases

Download the .mmdb files from your IPGeolocation.io account and point databases at them. Each database has a static download link that never changes, so the same link serves the first download and every update. The link contains your API key, so keep it in a secret and out of your Kong configuration.

Combined products ship two files in one archive, for example City + Security as db-ip-city.mmdb and db-ip-security.mmdb . List both files. Some combined files hold several data sets in one file, such as db-ip-city-company-asn.mmdb .

Load only what you need. Fields from a database you did not load stay empty, so referencing them is safe. docs/DATABASES.md lists every file, the products that ship it and the fields it provides. Tiers and bundles are on the pricing page, and the database documentation shows the full schemas.

Configuration reference

The plugin can be applied globally, to a Service or to a Route. It cannot be scoped to a Consumer, because it runs before authentication, when the consumer is not known yet. Supported protocols are http , https , grpc and grpcs .

---

3. Policy

Parameter	Type	Default	Description
policy.allowed_countries	array of strings	[]	Only these ISO 3166-1 alpha-2 country codes may pass. Cannot be combined with blocked_countries .
policy.blocked_countries	array of strings	[]	These country codes are blocked.
policy.allowed_continents	array of strings	[]	Only these continents may pass: AF , AN , AS , EU , NA , OC , SA . Cannot be combined with blocked_continents .
policy.blocked_continents	array of strings	[]	These continents are blocked.
policy.allowed_asns	array of strings	[]	Only these autonomous systems may pass ( AS15169 or 15169 ). Cannot be combined with blocked_asns .
policy.blocked_asns	array of strings	[]	These autonomous systems are blocked.
policy.block_tor	boolean		Block Tor exit nodes ( is_tor ).
policy.block_vpn	boolean		Block VPN endpoints ( is_vpn ).
policy.block_proxy	boolean		Block proxies ( is_proxy ).
policy.block_relay	boolean		Block privacy relays such as iCloud Private Relay ( is_relay ).
policy.block_residential_proxy	boolean		Block residential proxies ( is_residential_proxy , from the Security or Residential Proxy database).
policy.block_anonymous	boolean		Block any anonymizing service ( is_anonymous ).
policy.block_known_attacker	boolean		Block known attackers ( is_known_attacker ).
policy.block_bot	boolean		Block bots ( is_bot ). Known good bots such as search engine crawlers are spared.
policy.block_known_good_bots	boolean		Make block_bot apply to known good bots as well.
policy.block_spam	boolean		Block known spam sources ( is_spam ).
policy.block_cloud_provider	boolean		Block cloud and hosting provider addresses ( is_cloud_provider , from the Security or Hosting database).
policy.block_corporate_gateway	boolean		Block corporate egress gateways such as secure web gateways ( is_corporate_gateway ).
policy.block_threat_score_above	integer	unset	Block when threat_score (0 to 100, higher is riskier) is greater than this value.
policy.exempt_ips	array of strings	[]	Addresses or CIDRs that skip every policy rule. They are still enriched. To deny addresses, use Kong's ip-restriction plugin.
policy.allow_private	boolean		Pass private, loopback and link-local clients without a lookup and without headers.
policy.allow_unknown	boolean		For allow lists only: let a request pass when its country, continent or ASN is not in the databases. While a database is unavailable and fail_open is true , unknown values always pass.
policy.fail_open	boolean		When a database is missing, unreadable or corrupt, or the client address cannot be parsed, allow the request ( true ) or block it ( false ).
policy.dry_run	boolean		Evaluate and log the policy but never block. Adds X-IPGeo-Dry-Run with the reason to the upstream request.
policy.status_code	integer	403	Status code for blocked requests, 400 to 599. For example 451 for legal geo restrictions.
policy.message	string	Access denied	Message for blocked requests. The reason is never shown to the client.

---

4. Logging

Parameter	Type	Default	Description
log_serialize	boolean		Add the lookup result and policy decision to Kong's log serializer under ipgeolocation , for http-log, file-log, tcp-log and similar plugins.

Validation rejects relative paths, .. segments, refresh intervals between 1 and 59 seconds, unknown presets and fields, invalid header names, headers the plugin must not set ( Host , Content-Length , Authorization , Cookie and other hop-by-hop or framing headers), malformed country codes, continents, ASNs and CIDRs, combined allow and block lists, and status codes outside 400 to 599.

Request headers

Header names are X-IPGeo- followed by the field name in title case, with common acronyms in capitals. country_code becomes X-IPGeo-Country-Code , is_vpn becomes X-IPGeo-Is-VPN and asn becomes X-IPGeo-ASN . These are the headers the Traefik plugin sets.

full leaves out the ASN routing lists ( asn_routes , asn_peers , asn_upstreams , asn_downstreams ), which can hold thousands of entries. Map them with headers.custom if you need them. All 85 fields, their headers and the database paths they are read from are in docs/FIELDS.md.

Security policy

Rules are evaluated in a fixed order, and the first rule that blocks decides:

1. countries ( allowed_countries or blocked_countries )
2. continents ( allowed_continents or blocked_continents )
3. autonomous systems ( allowed_asns or blocked_asns )
4. security flags, in the order of the policy table
5. threat score ( block_threat_score_above )

How the plugin treats missing data:

• Block lists, flags and the threat score block only on positive evidence. The Security Database covers flagged ranges, so an address without a record is not flagged.
• Allow lists need a known value. When the country, continent or ASN is unknown, allow_unknown decides: pass by default, block when set to false .
• The threat score must be greater than the threshold. block_threat_score_above: 80 blocks 81 and above, never 80.
• Known good bots are spared by block_bot unless block_known_good_bots is set.
• Exempt and private clients skip the policy ( exempt_ips , allow_private ).
• A missing or broken database is never treated as a reason to block. It follows fail_open.

Blocked requests receive policy.status_code with Kong's standard error body containing policy.message , formatted for the client's Accept header like Kong's other plugins. The reason is logged at info level and available to log plugins.

Client IP selection

The plugin looks up kong.client.get_forwarded_ip() , the client address after Kong's real IP processing. It never parses X-Forwarded-For itself. Configure Kong, not the plugin:

With real_ip_recursive = on , Kong walks X-Forwarded-For from the right and stops at the first address that is not trusted, so entries a client adds in front cannot change the result. IPv4-mapped IPv6 addresses such as ::ffff:203.0.113.7 are looked up as IPv4.

When trusted_ips is not set, Kong ignores X-Forwarded-For and uses the TCP peer. Behind a load balancer that peer is usually a private address, which the plugin skips by default ( allow_private ), so no headers appear. To check which address is being looked up, map the pseudo field ip to a header: headers.custom: { X-IPGeo-IP: ip } .

Scopes, phases and routing

• Priority 2450. The plugin runs after bot-detection (2500) and before cors (2000), every authentication plugin and ip-restriction (990). Blocked requests never reach authentication or the upstream.
• Precedence. As with every Kong plugin, a Route instance overrides a Service instance, which overrides the global instance, and only one instance runs per request.
• Routing on enrichment. A global instance enriches in the rewrite phase, before Kong routes the request, so routes can match on its headers. A spoofed header cannot steer routing because it is replaced first. Route and Service instances run in the access phase, after routing. When one of them overrides a global instance, the headers the global instance set are removed and the more specific configuration applies.

Send German traffic to a dedicated service:

1routes:
2  - name: de
3    paths: [/shop]
4    headers:
5      x-ipgeo-country-code: [DE]
6    service: shop-de
7  - name: default
8    paths: [/shop]
9    service: shop
10plugins:
11  - name: ipgeolocation          # global: runs before routing
12    config:
13      databases: [/usr/local/share/ipgeolocation/db-ip-country.mmdb]
14      headers: { preset: minimal }

Using the results in other plugins

Plugins that run later (lower priority) can read the headers and the shared context:

local geo = kong.ctx.shared.ipgeolocation
-- geo.ip        the address that was looked up
-- geo.found     true when any database had a record
-- geo.private   true when the address was skipped as private
-- geo.exempt    true when the address matched exempt_ips
-- geo.fields    typed values: geo.fields.country_code == "PK", geo.fields.is_vpn == true,
--               geo.fields.threat_score == 60, geo.fields.vpn_provider == { "Nord VPN" }
-- geo.blocked, geo.dry_run, geo.reason   the policy decision

Treat it as read only. These combinations are covered by the end to end tests:

• Rate limiting per country: rate-limiting with limit_by: header and header_name: X-IPGeo-Country-Code .
• Renaming headers: request-transformer , for example rename.headers: ["X-IPGeo-City-Name:X-City"] .
• Custom logic: post-function or your own plugin reading kong.ctx.shared.ipgeolocation .
• Logging: with log_serialize: true , http-log, file-log, tcp-log, udp-log and syslog receive an ipgeolocation object with the address, the resolved fields and the policy decision.

Use ip-restriction for static address allow and deny lists. It runs after this plugin.

Keeping databases up to date

IPGeolocation.io updates its databases daily. examples/updater/ipgeolocation-update.sh downloads them, checks checksum.txt , optionally checks IPGeolocation.io's signature with their public key, validates each file and installs it. Give it the download links through the IPGEO_URLS environment variable from a secret. It never writes the links' query strings, which hold your API key, to its log.

There are two ways to make Kong use the new files:

• kong reload , the default. New workers open the new files and old workers finish their requests with the old ones. This works everywhere, including with refresh turned off. The updater runs it for you with -r .
• database_refresh_interval . Each worker checks the file at that interval and swaps in a validated replacement without a reload. If the replacement does not validate, the database in service stays. Workers swap independently, so for up to one interval plus 10 seconds different workers can serve different releases.

On Kubernetes, prefer storage local to the pod, such as an emptyDir filled by an init container and refreshed by a sidecar as in examples/kubernetes, or a rolling restart. Do not replace files on a network filesystem shared across nodes while Kong has them mapped, because a file replaced from another node can become a stale handle on the node that maps it.

Failure handling

With fail_open: false , a request is blocked whenever the plugin cannot reach a decision, and the reason recorded is IP intelligence unavailable . Unavailability is logged at most once a minute per worker.

Performance and memory

Measured on one vCPU of an Intel Xeon at 2.1 GHz with IPGeolocation.io's sample databases (search trees of up to 9.5 million nodes) and LuaJIT 2.1 in OpenResty. Database work alone:

Inside Kong (one worker, ab on the same vCPU, Kong answering directly with request-termination at about 40,000 requests per second), the plugin adds this much CPU per request:

About half of the standard figure is database work, a fifth is setting 15 headers, and the rest is header stripping and Kong's own per plugin work. To keep the cost down, request only the headers your services use, and use preset: none where you only need the policy.

Opening 305 MiB of databases added 1.2 MiB of resident memory. Pages are read on demand and shared by all workers through the page cache, so plan for the page cache to hold the parts of your databases that traffic touches. For heavy and varied traffic that can be their full size, and the full Security Database is several GiB. bench/bench.lua reproduces the database measurements on your own databases and hardware.

Troubleshooting

Log says database ... is unavailable: ...Permission denied . Kong's worker user ( kong ) cannot read the file or a directory above it. Fix the ownership or modes, then wait 30 seconds or run kong reload .

No X-IPGeo-* headers at all. The address being looked up is private, usually your load balancer's. Configure trusted_ips and real_ip_header as described in Client IP selection, and map ip to a header to see the address.

Every request gets the same location. Same cause: Kong sees the load balancer and not the client.

One header is missing. The databases you loaded have no value for that field, or the value is empty for that address. docs/DATABASES.md lists the fields of every database file. To inspect a record directly, use mmdbio.

An updated database is not used. Refresh is off by default. Run kong reload , or set database_refresh_interval .

Log says ... was modified in place , or workers exit with signal 7 ( SIGBUS ) after an update. Your update process rewrites the file. Download to a temporary file in the same directory and rename it, as described in Keeping databases up to date.

schema violation on a path. Paths must be absolute file paths without .. . Kong does not check that the file exists when it validates the configuration.

Everything is blocked, or nothing is. Turn on dry_run and read the reasons in the log. allow_private skips internal traffic, and allow_unknown decides what happens to addresses that no database covers.

block_bot lets Googlebot through. This is by design. Crawlers are flagged as bots and as known good bots, and blocking them removes you from search results. Set block_known_good_bots: true if you really want them blocked.

Frequently asked questions

Development

luacheck .                       # lint
busted                           # unit tests (spec/unit), no Kong needed
pongo run spec/integration       # Kong's test harness: schema and proxy behavior, PostgreSQL and DB-less
python3 spec/e2e/e2e.py          # a real Kong (kong and resty on PATH), end to end

docs/DEVELOPMENT.md covers the code layout, the test fixtures, the cross check against python-maxminddb , benchmarks and the release process. Contributions are welcome, see CONTRIBUTING.md. Report vulnerabilities as described in SECURITY.md, and read docs/SECURITY_REVIEW.md for the threat model.

Related tools and links

IPGeolocation.io tools:

• Nginx module, the same databases as native nginx variables ( documentation)
• Traefik plugin, the same databases as a Traefik middleware
• mmdbio, a command line tool for reading and inspecting MMDB files
• IPGeolocation CLI, IP intelligence from your terminal and shell scripts
• Integration guides, setup guides for every integration
• All repositories

Account, data and support:

• Sign up for a free account
• Database documentation and schemas
• Database pricing and bundles
• IP geolocation API or database: which one to use
• What is IP geolocation and how does it work
• Contact support
• Service status

Kong and format references:

• Kong Gateway documentation
• Kong Pongo, the plugin test harness used by this repository

License

MIT. See LICENSE.

Built for IPGeolocation.io databases. Questions about the data, tiers or bundles are answered on the database documentation and pricing pages.