Traefik IP Geolocation Plugin for IPGeolocation.io

Overview

Geo-blocking, VPN and proxy detection, and IP intelligence headers for Traefik, powered by IPGeolocation.io MMDB databases. This Traefik middleware plugin reads the databases from local disk and answers every lookup inside the Traefik process, 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 at the edge, route visitors by region, and add country, city, ASN and threat data to requests and access logs.

# Block Tor and known attackers, refuse high risk addresses, tell the backend where visitors are
http:
  middlewares:
    geo:
      plugin:
        ipgeolocation:
          databases:
            - /etc/traefik/ipgeo/db-ip-location.mmdb
            - /etc/traefik/ipgeo/db-ip-security.mmdb
          headerPreset: standard
          blockTor: true
          blockKnownAttacker: true
          blockThreatScoreAbove: 80

Jump to: Installation | Quick start | Databases | Configuration | Fields | Client IP | Troubleshooting | FAQ

Why use this plugin

Most Traefik geolocation setups call a remote API on every request or put a GeoIP library inside each application. This plugin loads IPGeolocation.io databases into Traefik once and answers each lookup locally in about ten microseconds ( benchmarks).

• No API calls and no per-request billing. Every lookup is a read from a local file.
• Decisions at the edge. Block, redirect or route in Traefik before the request reaches your backend.
• One middleware, many databases. Location, Security, Company, ASN, Abuse Contact, Hosting and Residential Proxy all load through one list, and the plugin layers them.
• Works with every database tier. Security v1, v3 and v4 all resolve without configuration changes.
• Zero dependencies. The MMDB reader is written using only the Go standard library, so it runs inside Traefik's plugin interpreter.
• Safe by default. Forwarded headers are ignored unless you trust them, private addresses skip the lookup, failures fail open, and client supplied X-IPGeo-* headers are stripped.

How it works

You list one or more .mmdb files under databases. The plugin opens each file at startup and, for every request:

1. Resolves the client IP address (see Client IP selection).
2. Looks that address up in each database, in the order you declared them.
3. For each field, takes the value from the first database that has it. Declaration order is priority order.
4. Sets the headers you asked for, evaluates the rules you enabled, 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.

Requirements

• Traefik v3.x (tested against v3.3). Traefik v2.x is not supported.
• One or more IPGeolocation.io .mmdb databases, or an API key for API mode.
• Read access to the database files from inside the Traefik process or container.

No Go toolchain is needed. Traefik downloads and interprets the plugin.

Getting the databases

Download the .mmdb files from your IPGeolocation.io account and point databases at them. Each database has its own static download link that never changes, so the same link serves the first download and every update.

Load only what you need. Fields from a database you did not load stay empty, so referencing them is safe. Bundles that ship two databases in one archive work the same way: list both files. Tiers are on the pricing page, the field schemas show what each database contains.

Configuration reference

Every option is a camelCase key under plugin.ipgeolocation . The tables give the short version; OPTIONS.md explains what each value does in detail.

---

1. Data source

Option	Default	Description
mode	mmdb	mmdb reads local files, api calls the REST API
databases		List of .mmdb paths. Declaration order is priority order
loadInMemory		Read each file into RAM. Set false for multi gigabyte files, see Performance
refreshInterval	0	Reload a database when its file changes, for example 1h . See Keeping databases up to date

---

3. Access control

Option	Default	Description
allowedCountries / blockedCountries		ISO 3166-1 alpha-2 codes. Set one list, not both
allowedContinents / blockedContinents		AF , AN , AS , EU , NA , OC , SA
allowedASNs / blockedASNs		AS1257 or 1257
allowedIPs		CIDRs that skip every check. Evaluated first
blockedIPs		CIDRs refused before any lookup
blockTor , blockVPN , blockProxy , blockRelay		Anonymizer flags from the Security database
blockResidentialProxy , blockAnonymous		Residential proxy and combined anonymity flags
blockKnownAttacker , blockSpam		Threat flags
blockBot		Known bots. Crawlers marked as known good bots are spared, see Troubleshooting
blockKnownGoodBots		Make blockBot apply to search engines and monitors too
blockCloudProvider		Cloud and hosting infrastructure. Also catches corporate VPN exits and CI runners
blockCorporateGateway		Corporate egress gateways (Security v4)
blockThreatScoreAbove	-1	Block when the score is above this value, for example 80 . 0 counts as off, use 1 to block everything above zero
allowPrivate		Skip private and loopback addresses instead of treating them as unknown
allowUnknown		Allow addresses no database covers
dryRun		Evaluate and log without blocking

---

4. Block response and failure handling

Option	Default	Description
blockStatusCode	403	451 is conventional for legal restrictions
blockMessage	Access denied.	Plain text body
blockRedirectURL		Send a 302 to this URL instead of a status. Do not point it at a route behind the same middleware
failOpen		Forward the request when a lookup fails. false blocks instead

---

5. Client IP, cache, API and logging

Option	Default	Description
trustForwardedHeader		Read the client address from a forwarded header, see Client IP selection
forwardedHeaderName	X-Forwarded-For	For example CF-Connecting-IP behind Cloudflare
forwardedDepth	0	Take the Nth address counting from the right. 0 means leftmost
trustedProxies		Your proxy CIDRs. The first address from the right that is not yours is used
cacheSize	10000	Cached addresses. 0 disables the cache
cacheTTL	1h	Lifetime of a cached lookup. Use 24h in API mode
apiKey , apiEndpoint , apiInclude , apiFields , apiTimeout		API mode settings
logLevel	info	error , warn , info or debug

Field reference

Use any of these names in the headers map. They match the Nginx module's $ip_* variables without the prefix.

Booleans render as true or false (or 1 and 0 with booleanFormat: one_zero ), lists are joined with listSeparator , AS numbers are normalized to AS1257 , and a field with no data is omitted rather than sent empty.

The Residential Proxy and Hosting databases have no boolean column, since a record existing is the signal, so is_residential_proxy and is_cloud_provider become true when those databases contain the address. A flag from a database declared earlier still wins.

Client IP selection

The plugin geolocates one address per request. By default that is the address of the TCP connection, which is correct when Traefik faces the internet directly. Behind a load balancer or CDN, every visitor would look like the balancer, so you need the forwarded header:

# Behind exactly one proxy you control
trustForwardedHeader: true
forwardedDepth: 1

# Behind a variable number of your own proxies
trustForwardedHeader: true
trustedProxies: [10.0.0.0/8, 172.16.0.0/12]

# Behind Cloudflare
trustForwardedHeader: true
forwardedHeaderName: CF-Connecting-IP

When testing locally, a plugin that loads cleanly but enriches nothing is almost always this. Set logLevel: debug and look for 127.0.0.1 is private or loopback, skipping the lookup .

Private, loopback, link local and carrier grade NAT ranges are absent from every public database. With allowPrivate: true they skip the lookup and pass through untouched.

Keeping databases up to date

IPGeolocation.io publishes fresh releases daily. The plugin never downloads anything itself. It watches the files you gave it, and a scheduled job replaces them:

refreshInterval: 1h

When a file's size or modification time changes, the plugin opens the new file, swaps it in atomically, clears the lookup cache, and closes the old one after a short grace period. If the new file will not open, it keeps serving the old one and logs a warning. No restart, no failed requests.

The download side is yours to run, from cron, a systemd timer, a Kubernetes CronJob or your existing pipeline. Each database has its own static link with its own apiKey parameter, and each archive holds the .mmdb , a README.md and a checksum.txt . A good refresh job verifies the checksum, confirms the file really is an MMDB before installing it, and handles bundles holding two databases.

Performance and memory

Measured with go test -bench on a 2.8 GHz Xeon, one request end to end through the middleware:

Cost scales with the number of fields you resolve, not with database size. The plugin resolves only the fields your headers and rules reference, and picks a lookup strategy at startup to match: with eight fields or fewer it seeks to each field inside the record and skips the rest, and with more it decodes the record once.

Memory depends on loadInMemory. With true the whole file is resident and a lookup takes 9.9 µs. With false only the search tree stays in memory and each record is read from disk in one windowed read, at 11.1 µs. During a refresh with true , both copies are briefly resident, so size the container for twice the largest database.

Leave the cache on. Real traffic repeats addresses constantly, and a cached request costs less than half of an uncached one.

API mode

When you cannot ship database files, the plugin can call the IPGeolocation.io REST API instead:

http:
  middlewares:
    geo:
      plugin:
        ipgeolocation:
          mode: api
          apiKey: YOUR_API_KEY
          apiInclude: security
          cacheTTL: 24h
          headerPreset: standard
          failOpen: true

Every cache miss is an outbound HTTPS request that costs a credit and adds a round trip, so keep cacheTTL high and failOpen on, and prefer MMDB mode for production traffic. Field names and rules are identical in both modes, so switching later is a configuration change.

Troubleshooting

Traefik will not start and logs a plugin error. Check that moduleName is exactly github.com/IPGeolocation/traefik-plugin-ipgeolocation and that the version tag exists.

A field is always empty. Confirm you loaded a database that carries it. Security fields need the Security database, ASN fields need the ASN database. The startup log prints one loaded line per database with its type and build date. To inspect a file directly, use mmdbio: mmdbio read --db db-ip-security.mmdb --ip 2.56.188.34 .

Everything is blocked, or nothing is. Turn on dryRun and read the reasons in the log. Remember that allowPrivate skips internal traffic and allowUnknown decides what happens to addresses no database covers.

All visitors look like one address. Traefik is behind a proxy. See Client IP selection.

blockBot lets Googlebot through. By design. Crawlers are flagged as bots and as known good bots in Security v4, and blocking them removes you from search results. Set blockKnownGoodBots: true if you really want them blocked.

Frequently asked questions

Development

make test       # unit tests, including MMDB fixtures built byte by byte
make yaegi      # load the plugin through Yaegi, the interpreter Traefik uses
make try        # end to end inside a real Traefik binary
make check      # all of the above

Traefik does not compile plugins. It interprets them with Yaegi, which supports a subset of Go, so code that passes go test can still fail to load. Run make yaegi before every release. The reader is also checked against the official MMDB Go reader on real databases.

Two Yaegi rules for contributors, documented where they apply in the code: never assign a concrete type to an interface variable in a multi value assignment from a call, and never convert a value to an interface inside a loop body (return it from a function instead, see newMMDBRecord in provider.go ). Neither fails under go test . Third party dependencies are not allowed.

Related tools and links

IPGeolocation.io tools

• Nginx module, the same databases as native $ip_* variables ( docs)
• mmdbio, a command line tool for reading and inspecting MMDB files
• IPGeolocation CLI, IP intelligence from your terminal and shell scripts
• n8n community node, IP lookups inside n8n workflows
• 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
• Contact support
• Service status

Traefik and format references

• Traefik plugin documentation and the Plugin Catalog
• Traefik HTTP middleware overview
• Yaegi, the Go interpreter Traefik runs plugins with

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.