IP resolvers
IP resolvers add location and network data to each client IP address: its country, region, city, coordinates, network owner, and whether it belongs to a mobile, hosting, proxy, or Tor network. Country rules, network rules, risk, and several classifier rules depend on this data. Sentinel ships with no provider, so configure at least one before you rely on those features.
You configure providers in sentinel.toml under [[ip_resolver.providers]]. Changes take effect at the next restart.
What uses the data
| Feature | Fields it needs |
|---|---|
country rule condition | Country |
network rule condition | Network flags (mobile, hosting, proxy, tor) |
risk rule condition and GET /v2/inspect | Network flags (HOSTING, PROXY, TOR) and country (HIGH_RISK_COUNTRY) |
Classifier IP and location rules (POST /v2/classifier, POST /v2/verify) | Network flags for HOSTING, PROXY, TOR; country for HIGH_RISK_COUNTRY and TIMEZONE_MISMATCH; coordinates for LOCATION_DISTANCE |
| Request logs and dashboard | Country (countryCode) and network (network) |
| AI decider | country and network signals |
root_login_country alert | Country |
POST /v2/ip | Every field |
Without a provider
With no provider configured, every location field and the mobile and hosting flags stay unknown:
- The
countrycondition never matches with=(and always matches with!=), so country allow or deny rules do nothing. See Condition fields. - The
networkcondition matches onlyproxyandtor, and only when a threat list of that kind lists the IP.hosting,mobile, andfixednever match. HOSTINGnever triggers, andLOCATION_DISTANCEhas no coordinates to compare.HIGH_RISK_COUNTRYand thelocationcategory fall back to the country of thetimeZonethe widget or your backend sent.riskhas no time zone, so its location part stays0.- Request logs show
countryCodeonly for verifications that carried a time zone, andnetworkonly from threat lists.
Threat-list rules (MALICIOUS, BOT, THREAT_SCORE, the threat and threatVerdict conditions) don't need a provider.
Provider types
type | Source | Data | Credentials | Downloads as a remote file | Default cache_ttl |
|---|---|---|---|---|---|
maxmind | Local .mmdb file or URL | Depends on the database: City and Country give location; ASN and ISP give the network owner; Anonymous-IP gives proxy, tor, hosting; Connection-Type gives mobile; Enterprise gives all of these | MaxMind account ID and license key, for downloads | With url | "0s" (off) |
ipinfo-mmdb | Local .mmdb file or URL | Lite: country and network owner. Core and Plus: location and network flags | IPinfo token, for downloads | With url | "0s" (off) |
ip-api | ip-api.com HTTP API, per IP | Location, network owner, mobile, proxy, hosting; never tor (ip-api.com counts Tor exits as proxies) | Optional Pro key. Without one: the free endpoint, HTTP only, 45 requests/min, non-commercial use only | No | "1h" |
ipstack | ipstack.com HTTP API, per IP | Location on every plan. Paid plans add the ISP as network owner and mobile. security = true adds proxy, tor, hosting (Professional Plus plan) | Access key (required) | No | "1h" |
ipinfo | ipinfo.io HTTP API, per IP | api = "lite" (default, free): country and network owner. "lookup" (Core, Plus, Max): adds location, mobile, hosting; Plus and Max add proxy and tor. "legacy": plans from before 2025 | API token (required) | No | "1h" |
cloudflare | CF-IPCountry request header | Country, or tor when the value is T1 | None | No | Never cached |
headers | X-IP-* request headers set by your proxy or edge | Whatever the upstream sends: country, region, city, coordinates, network owner, network flags | Shared secret | No | Never cached |
Every provider needs a unique name (1–64 characters of a-z, 0-9, _, -, starting with a letter or digit). For a downloaded database, the name is also its remote file name. Each type's keys are listed in the Configuration reference: maxmind, ip-api, ipstack, ipinfo, ipinfo-mmdb, cloudflare, headers.
Local databases answer in microseconds and send no client IPs to a third party. The HTTP APIs send each uncached IP to the provider and add a network round trip (up to 10 seconds per request) to the first lookup of each IP.
cloudflare and headers describe the client of the current request, so they only answer for that request's own client IP. They give nothing when your backend passes a visitor's IP to POST /v2/classifier or POST /v2/ip.
Private addresses (RFC 1918, loopback, link-local, IPv6 unique-local) are never looked up. IPv4-mapped IPv6 addresses resolve as the IPv4 address.
Common setups
MaxMind GeoLite2, downloaded automatically
Create a free GeoLite2 account at MaxMind, generate a license key, and point the providers at MaxMind's download permalinks. Sentinel downloads each archive, keeps the .mmdb inside it, and checks for updates daily. This setup gives the country, location, and network owner, but no network flags; add an Anonymous-IP or Connection-Type database, or an API provider, if your rules use network.
[[ip_resolver.providers]]
type = "maxmind"
name = "geolite2-city"
url = "https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz"
account_id = "${MAXMIND_ACCOUNT_ID}"
license_key = "${file:/run/secrets/maxmind_license_key}"
[[ip_resolver.providers]]
type = "maxmind"
name = "geolite2-asn"
url = "https://download.maxmind.com/geoip/databases/GeoLite2-ASN/download?suffix=tar.gz"
account_id = "${MAXMIND_ACCOUNT_ID}"
license_key = "${file:/run/secrets/maxmind_license_key}"Set both account_id and license_key, or neither; Sentinel sends them as HTTP Basic auth. The default schedule is "@daily". Update checks use HEAD requests, which don't count against MaxMind's daily download limit.
To use a database you update yourself, for example with geoipupdate or in an air-gapped deployment, set path instead of url:
[[ip_resolver.providers]]
type = "maxmind"
name = "geoip2-city"
path = "/usr/share/GeoIP/GeoIP2-City.mmdb" # relative paths resolve inside data_dirSentinel checks the file every check_interval (default "1m") and reloads it when its modification time or size changes. With Docker, mount the directory that holds the file, not the file itself, so replaced files are seen. A path that can't be loaded stops startup.
IPinfo Lite database
IPinfo Lite is free and gives the country and network owner for every IP:
[[ip_resolver.providers]]
type = "ipinfo-mmdb"
name = "ipinfo-lite"
url = "https://ipinfo.io/data/ipinfo_lite.mmdb"
token = "${IPINFO_TOKEN}" # sent as HTTP Basic auth; keep it out of urlKeep the token in token, not in the URL: the remote files API lists URLs. The same provider type reads IPinfo Core and Plus databases, and the legacy location, privacy, carrier, ASN, and country-ASN databases.
Behind Cloudflare
With IP geolocation turned on in Cloudflare, every proxied request carries CF-IPCountry. The cloudflare provider reads it, at no cost and with no lookup:
[server]
client_ip_header = "CF-Connecting-IP"
trusted_proxies = ["173.245.48.0/20", "103.21.244.0/22", "2400:cb00::/32"] # every range from https://www.cloudflare.com/ips/
[[ip_resolver.providers]]
type = "cloudflare"
name = "cloudflare"Set client_ip_header so the client IP is the visitor's, not Cloudflare's edge server; the header describes the visitor. How Sentinel picks the client IP is covered in Listeners & reverse proxy.
The header gives the country only. Add a database or API provider after it for location and network flags.
Headers from your proxy or edge function
If your proxy, CDN, or edge function already knows the visitor's location, it can pass it in X-IP-* headers. Sentinel uses them only when the request also carries an X-IP-Secret equal to the provider's secret:
[[ip_resolver.providers]]
type = "headers"
name = "edge"
secret = "${IP_HEADERS_SECRET}"X-IP-Secret: <the configured secret>
X-IP-Country-Code: GB
X-IP-City: London
X-IP-Lat: 51.5142
X-IP-Lon: -0.0931
X-IP-Hosting: 0
X-IP-Proxy: ?1| Header | Value |
|---|---|
X-IP-Country-Code | Two letters, e.g. GB |
X-IP-Country, X-IP-Region, X-IP-City, X-IP-ASName | Text (UTF-8) |
X-IP-Lat, X-IP-Lon | Decimal degrees |
X-IP-Mobile, X-IP-Hosting, X-IP-Proxy, X-IP-Tor | 1, ?1, or true for true; any other value is false |
Empty headers and values that don't fit, such as a three-letter country code or a latitude above 90, are unknown. A wrong secret counts as a failed lookup: the headers are ignored and the provider's name appears in errors of POST /v2/ip.
Combining providers
List providers in priority order. For each field, the first provider that has a value wins; later providers only fill the fields that are still empty. Sentinel stops querying once every field is known. A provider that fails (network error, rate limit, wrong secret) is skipped, and the next ones still run.
This chain takes location from a City database, network flags from an Anonymous-IP database, and fills anything still missing from ip-api.com:
[[ip_resolver.providers]]
type = "maxmind"
name = "city"
path = "GeoIP2-City.mmdb"
[[ip_resolver.providers]]
type = "maxmind"
name = "anonymous-ip"
path = "GeoIP2-Anonymous-IP.mmdb"
[[ip_resolver.providers]]
type = "ip-api"
name = "ip-api"
key = "${IP_API_COM_KEY}"
cache_ttl = "6h"Network flags combine into the network value. Each flag that is set counts on its own (a Tor exit in a data center is both tor and hosting); fixed means a provider knows the flags and none is set. An Anonymous-IP database reports every IP it doesn't list as fixed. A threat list of kind proxy or tor sets that flag when no provider knows it.
Caching
Each provider has its own in-memory lookup cache, per replica, keyed by IP:
[[ip_resolver.providers]]
type = "ipinfo"
name = "ipinfo"
token = "${IPINFO_TOKEN}"
cache_ttl = "12h" # "0s" turns the cache off
cache_size = 50000 # maximum cached IPscache_ttldefaults to"1h"for the HTTP APIs and to"0s"(off) for local databases, which are fast enough without one.cache_sizedefaults to10000.- "No data" answers are cached too; errors are not, so a failed lookup is retried on the next request.
- Concurrent lookups of the same uncached IP share one request to the provider.
cloudflareandheadersare never cached; they read the current request.
When the free ip-api.com endpoint runs out of requests, lookups fail without contacting it until its rate-limit window resets.
Downloads and updates
A maxmind or ipinfo-mmdb provider with a url is a remote file named after the provider. It's stored under <data_dir>/remote-files, checked on the provider's schedule, and downloaded again only when it changed. The URL can serve a plain .mmdb or a .tar.gz, .tar, .zip, or .gz archive holding one. Each download must open as a MaxMind DB file; otherwise the previous database stays in use.
Until the first download finishes, the provider answers nothing, and the next provider in the list takes over. A failing download doesn't stop startup. You can see each database's status and trigger a check with the remote files API.
For air-gapped deployments, use path with a file you copy in, and leave out the HTTP API providers. See Outbound proxy & air-gapped deployments.
Verify it works
Validate the file.
doctor --config-onlychecks the provider keys (names,pathorurl, credentials) without loading any database. Run it in a one-off container with the server's mounts:docker run --rm \ -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \ -v "$PWD/secrets:/run/secrets:ro" \ ghcr.io/altcha-org/sentinel:2.0.0-beta.1 doctor --config-onlyA mistake fails the check, for example:
FAIL config.valid (ip_resolver) ip_resolver provider "geolite2-city": set both or neither of account_id and license_key.Check the startup log. Each provider logs a line when it starts, and each database when it loads:
INFO altcha_sentinel::ip_resolver::mmdb: ip resolver database loaded provider=city database_type=GeoIP2-City INFO altcha_sentinel::ip_resolver: ip resolver provider provider=city kind="maxmind"The full
doctor(docker exec sentinel /usr/local/bin/altcha-sentinel doctorin the running container) also reports local.mmdbfiles that are missing or older than 30 days (data.mmdb), API providers on free or plain-HTTP endpoints (config.ip_resolver), and whether the API hosts are reachable (network.host). See the CLI reference.Look up an IP.
POST /v2/ipruns the IP through every provider and the threat lists. Call it from your server with arestrictedorfullAPI key:curl https://sentinel.example.com/v2/ip \ -u 'key_…:sec_…' \ -H 'Content-Type: application/json' \ -d '{"ip": "81.2.69.142"}'With the City and Anonymous-IP databases from Combining providers, the response looks like this:
{ "data": { "countryCode": "gb", "country": "United Kingdom", "region": "England", "city": "London", "lat": 51.5142, "lon": -0.0931, "asname": null, "mobile": null, "hosting": true, "proxy": true, "tor": true, "networks": ["tor", "proxy", "hosting"], "threats": [], "action": null, "threatScore": null, "errors": [], "time": … } }
Fields no provider knows are null; for a private IP or with no provider configured, every provider field is null. networks lists the flags most specific first and is what the network rule condition matches. errors names the providers whose lookup failed, so their fields may be missing. time is the lookup duration in milliseconds. The full schema is in the API reference.
POST /v2/ip is a functional endpoint: it needs an active license (403 LICENSE_NOT_ACTIVE otherwise) and refuses public keys (403 NON_PUBLIC_API_KEY_REQUIRED). See Configure the license and API keys & access levels.