A Traefik middleware plugin that blocks or allows requests based on geographic location, using the IPInfo Lite database with automatic updates.

• Allowlist or blocklist mode via country codes (ISO 3166-1 alpha-2)
• Automatic database updates on a configurable interval
• Private/reserved IP handling — optionally pass through RFC1918 and loopback addresses
• Configurable fallback when an IP is not found in the database
• Custom HTTP status code for blocked requests (default: 403)
• Optional request logging
• Country header — write X-Geoblock-Country and X-Geoblock-City on every response for visibility in Traefik access logs

Add the plugin to your Traefik static configuration:

experimental:
  plugins:
    geoblock:
      moduleName: github.com/leardev/traefik-geoblock-plugin
      version: v0.1.9

Traefik 3.5 introduced unsafe plugin loading, which allows running plugins directly from a local directory without going through the Plugin Catalog. This is useful for self-hosted setups or forks:

# traefik.yml (static config)
experimental:
  localPlugins:
    geoblock:
      moduleName: github.com/leardev/traefik-geoblock-plugin

# Mount the plugin source into the Traefik container:
# /plugins-local/src/github.com/leardev/traefik-geoblock-plugin/

Note: Local/unsafe plugins are not signed or vetted by Traefik Labs. Only load plugin source you trust.

For local development, use localPlugins instead (see test/docker-compose.yml).

The plugin supports two database backends. Set either databaseMMDBPath (MMDB, default) or databasePath (CSV) — not both.

The MMDB backend is recommended for production and multi-replica deployments.

Exactly one of allowedCountries or blockedCountries must be set.

http:
  middlewares:
    my-geoblock:
      plugin:
        geoblock:
          allowedCountries:
            - DE
            - AT
            - CH
          token: "your-ipinfo-token"
          databaseMMDBPath: "/data/ipinfo_lite.mmdb"
          updateInterval: 24
          allowPrivate: true
          defaultAllow: false
          logEnabled: true

http:
  middlewares:
    my-geoblock:
      plugin:
        geoblock:
          allowedCountries:
            - DE
            - AT
            - CH
          token: "your-ipinfo-token"
          databasePath: "/data/ipinfo_lite.csv.gz"
          updateInterval: 24
          allowPrivate: true
          defaultAllow: false
          logEnabled: true

Traefik's access log shows the HTTP status code but not why a request was blocked. Enable addCountryHeader: true to write an X-Geoblock-Country response header on every request (plus X-Geoblock-City when using the MMDB backend), then tell Traefik to include them in access log lines.

Plugin config:

http:
  middlewares:
    my-geoblock:
      plugin:
        geoblock:
          addCountryHeader: true
          # ... other options

Traefik static config:

accessLog:
  fields:
    headers:
      defaultMode: drop
      names:
        X-Geoblock-Country: keep
        X-Geoblock-City: keep

Blocked access log lines will then include the country (and city, if available) that triggered the block:

"GET / HTTP/1.1" 403 ... "X-Geoblock-Country: CN" "X-Geoblock-City: Shanghai"

Header values:

The header is set on all requests — allowed and blocked alike — so it can also be used for metrics or access log analysis, not just debugging 403s.

Note: The Docker Compose setup in test/ is for integration testing only, not for production use.

IPINFO_TOKEN=your-token docker compose -f test/docker-compose.yml up

Traefik will be available at http://localhost:80 and the dashboard at http://localhost:8080.

MIT