geoip-http |

geoip-http is a fast GeoIP lookup service in Rust, using the Axum web framework. It provides one possible server for tzupdate.

Features

Fast, uses Axum web framework
Simple, less than 300 lines of code
Safe hot reload of GeoIP DB without restarting
Correct cache behaviour for implicit/explicit IP lookup
Direct dump of GeoIP data: no filtering
Support for both explicit and implicit (client IP) queries
Support for X-Forwarded-For, X-Real-IP, CloudFront, etc
Sequence based logging for debugging

Usage

Download GeoLite2-City.mmdb from here, and extract it.

By default, the server runs on TCP 0.0.0.0:3000. You can change this with the --ip and --port options. You can also set the GeoIP database file location with the --db option.

You can then query / to get data for the connecting IP (respecting things like X-Real-IP, X-Forwarded-For, and the like), or /8.8.8.8 to get details for (for example) 8.8.8.8:

% curl --silent http://127.0.0.1:3000/8.8.8.8 | jq '.location'
{
  "accuracy_radius": 5,
  "latitude": 34.0544,
  "longitude": -118.2441,
  "metro_code": 803,
  "time_zone": "America/Los_Angeles"
}

The format matches that of the maxminddb crate's City struct, represented as JSON by its Serialize trait.

Logging

To see debug info, run with RUST_LOG=geoip_http=debug,tower_http=debug.

Rate limiting

geoip-http is designed to be run behind a local reverse proxy, so rate limiting generally should happen there. It can also be added via tower-governor.

Performance

On my T14s Gen 2:

% wrk -t"$(nproc)" -c400 -d30s http://127.0.0.1:3000/8.8.8.8
Running 30s test @ http://127.0.0.1:3000/8.8.8.8
  8 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.28ms    1.11ms  29.11ms   87.45%
    Req/Sec    42.99k    10.07k  158.55k    75.56%
  10269395 requests in 30.09s, 1.44GB read
Requests/sec: 341246.16
Transfer/sec:     49.14MB

Example server config

Nginx proxy config

Fill in ssl_certificate and ssl_certificate_key.

http {
    limit_conn_zone $binary_remote_addr zone=geoip_conn_limit:2m;
    limit_req_zone $binary_remote_addr zone=geoip_rate_limit:2m rate=100r/m;

    upstream geoip-backend {
        server 127.0.0.1:3000;
        keepalive 16;
    }

    server {
        listen 80;
        listen [::]:80;
        server_name geoip.chrisdown.name;

        client_body_timeout 2s;
        client_header_timeout 2s;

        location / {
            limit_req zone=geoip_rate_limit;
            limit_conn addr 5;
            return 301 https://$host$request_uri;
        }
    }

    server {
        listen 443 ssl;
        listen [::]:443 ssl;
        server_name geoip.chrisdown.name;

        client_body_timeout 2s;
        client_header_timeout 2s;

        ssl_certificate ...;
        ssl_certificate_key ...;

        location / {
            limit_req zone=geoip_rate_limit;
            limit_conn addr 50;
            proxy_pass http://geoip-backend;
        }
    }
}

Systemd unit for geoip-http

Fill in --db.

[Service]
ExecStart=/usr/bin/geoip-http --db ...
ExecReload=/usr/bin/curl -v http://127.0.0.1:3000/reload/geoip
Restart=always

Attribution

This product is designed to use GeoLite2 data created by MaxMind, available from https://maxmind.com.

cdown/geoip-http