GeoIP Lookup

liwan can derive a visitor’s country and city during request processing. The IP address itself is not stored.

Location data can come from an automatically maintained MaxMind database, a local MaxMind-compatible .mmdb file, or headers supplied by a trusted proxy. MaxMind values take precedence over header values when available.

Trusted Proxy Headers

Use a provider preset when your reverse proxy already supplies location headers:

[geoip]
headers = "cloudflare"

Multiple presets and custom mappings can be evaluated in order:

[geoip]
headers = [
  "cloudflare",
  { country = "X-Country", city = "X-City" },
]

Preset	Country source	City source
`akamai`	`country_code` in `X-Akamai-Edgescape`	`city` in `X-Akamai-Edgescape`
`cloudflare`	`CF-IPCountry`	`CF-IPCity`
`cloudfront`	`CloudFront-Viewer-Country`	`CloudFront-Viewer-City`
`netlify`	`/country/code` in `X-NF-Geo`	`/city` in `X-NF-Geo`
`vercel`	`X-Vercel-IP-Country`	`X-Vercel-IP-City`

liwan accepts these headers only when the direct peer matches trusted_proxies.

MaxMind Database

MaxMind provides GeoLite2 country and city databases. Follow the MaxMind account setup guide, then use the account dashboard to generate a license key and find your account ID.

To let liwan download and update the database:

[geoip]
maxmind_account_id = "MY_ACCOUNT_ID"
maxmind_license_key = "MY_LICENSE_KEY"
maxmind_edition = "GeoLite2-City"

To use a local compatible database instead:

[geoip]
maxmind_db_path = "/path/to/GeoLite2-City.mmdb"

liwan reloads the database when the file changes. A scheduled job can therefore update a file from another compatible source, including:

Check each source’s update schedule, data quality, file compatibility, and licensing information.