https://github.com/eterline/geo-filt
https://github.com/eterline/geo-filt
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/eterline/geo-filt
- Owner: eterline
- License: agpl-3.0
- Created: 2025-09-21T16:39:13.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-22T01:50:55.000Z (10 months ago)
- Last Synced: 2025-09-22T02:29:20.109Z (10 months ago)
- Language: Go
- Size: 5.01 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# geo-filt
**geo-filt** is a [Traefik](https://traefik.io/) middleware plugin that filters incoming HTTP requests by IP address and geographic location (country, subnet, custom rules). Written in 
## Features
- Extracts client IP from standard headers: `Forwarded`, `X-Forwarded-For`, `X-Real-IP`.
- IPv4 and IPv6 support.
- Option to allow private ranges (RFC1918, RFC4193, loopback).
- Country-based access filtering (ISO codes).
- IP or subnet allow-list.
- Fully compatible with the [Traefik Plugin System](https://doc.traefik.io/traefik/plugins/overview/).
## Installation
Enable the local plugin in your `traefik.yaml` or `config.yaml`:
```yaml
experimental:
localPlugins:
traefik-plugin-geo-filt:
moduleName: github.com/eterline/geo-filt
```
### Configuration
Example middleware configuration (dynamic.yaml):
```yaml
http:
middlewares:
geofilter:
plugin:
traefik-plugin-geo-filt:
enabled: true # Turn on filter plugin
headerBearer: false # Search request IP in headers "Forwarded", "X-Forwarded-For", "X-Real-IP"
allowPrivate: true # Allows RFC 1918 (IPv4 addresses), RFC 4193 (IPv6 addresses) and loopback IPs
codeFile: "./plugins/github.com/eterline/geo-filt/dataset/locations.csv"
geoFile:
- "./plugins/github.com/eterline/geo-filt/dataset/subnets_ipv4.csv"
- "./plugins/github.com/eterline/geo-filt/dataset/subnets_ipv6.csv"
tags: ["ru"] # Country allow code
defined: ["216.58.211.0/24", "142.250.74.142"] # IP or subnet allow
```
Default parameters usage:
| Option | Type | Default | Description |
| -------------- | --------- | ------- | --------------------------------------------------------------------- |
| `enabled` | bool | `false` | Enable or disable the filter |
| `headerBearer` | bool | `false` | If `true`, try to resolve IP from headers; otherwise use `RemoteAddr` |
| `allowPrivate` | bool | `false` | Allow private and loopback IPs |
| `codeFile` | string | — | Path to CSV with country codes |
| `geoFile` | \[]string | — | Paths to IP subnets CSV | |
| `tags` | \[]string | — | Allowed country ISO codes |
| `defined` | \[]string | — | Additional allowed IPs or subnets |
Example router usage:
```yaml
http:
routers:
my-app:
rule: "Host(`example.com`)"
service: my-app-svc
middlewares:
- geofilter@file
```
## Update database
1. Go to [Site](https://www.iplocate.io).
2. Register in site. 
3. Copy api key. 
4. go to address: `https://www.iplocate.io/download/ip-to-country-geolite2.csv?apikey=`\.
5. Unzip archive. 
6. Move it to container mounted dir and set path in config.
## License
[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.txt)