Skip to main content
ALTCHA®

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

FeatureFields it needs
country rule conditionCountry
network rule conditionNetwork flags (mobile, hosting, proxy, tor)
risk rule condition and GET /v2/inspectNetwork 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 dashboardCountry (countryCode) and network (network)
AI decidercountry and network signals
root_login_country alertCountry
POST /v2/ipEvery field

Without a provider

With no provider configured, every location field and the mobile and hosting flags stay unknown:

  • The country condition never matches with = (and always matches with !=), so country allow or deny rules do nothing. See Condition fields.
  • The network condition matches only proxy and tor, and only when a threat list of that kind lists the IP. hosting, mobile, and fixed never match.
  • HOSTING never triggers, and LOCATION_DISTANCE has no coordinates to compare.
  • HIGH_RISK_COUNTRY and the location category fall back to the country of the timeZone the widget or your backend sent. risk has no time zone, so its location part stays 0.
  • Request logs show countryCode only for verifications that carried a time zone, and network only from threat lists.

Threat-list rules (MALICIOUS, BOT, THREAT_SCORE, the threat and threatVerdict conditions) don't need a provider.

Provider types

typeSourceDataCredentialsDownloads as a remote fileDefault cache_ttl
maxmindLocal .mmdb file or URLDepends 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 theseMaxMind account ID and license key, for downloadsWith url"0s" (off)
ipinfo-mmdbLocal .mmdb file or URLLite: country and network owner. Core and Plus: location and network flagsIPinfo token, for downloadsWith url"0s" (off)
ip-apiip-api.com HTTP API, per IPLocation, 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 onlyNo"1h"
ipstackipstack.com HTTP API, per IPLocation 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"
ipinfoipinfo.io HTTP API, per IPapi = "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 2025API token (required)No"1h"
cloudflareCF-IPCountry request headerCountry, or tor when the value is T1NoneNoNever cached
headersX-IP-* request headers set by your proxy or edgeWhatever the upstream sends: country, region, city, coordinates, network owner, network flagsShared secretNoNever 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_dir

Sentinel 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 url

Keep 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
HeaderValue
X-IP-Country-CodeTwo letters, e.g. GB
X-IP-Country, X-IP-Region, X-IP-City, X-IP-ASNameText (UTF-8)
X-IP-Lat, X-IP-LonDecimal degrees
X-IP-Mobile, X-IP-Hosting, X-IP-Proxy, X-IP-Tor1, ?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 IPs
  • cache_ttl defaults to "1h" for the HTTP APIs and to "0s" (off) for local databases, which are fast enough without one. cache_size defaults to 10000.
  • "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.
  • cloudflare and headers are 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

  1. Validate the file. doctor --config-only checks the provider keys (names, path or url, 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-only

    A 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.
  2. 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 doctor in the running container) also reports local .mmdb files 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.

  3. Look up an IP. POST /v2/ip runs the IP through every provider and the threat lists. Call it from your server with a restricted or full API 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.

Start typing to search...

↑ ↓ Navigate ↵ Select