# IP resolvers

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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 `country` condition never matches with `=` (and always matches with `!=`), so country allow or deny rules do nothing. See [Condition fields](/docs/sentinel/v2/reference/rules/#condition-fields).
- The `network` condition matches only `proxy` and `tor`, and only when a [threat list](/docs/sentinel/v2/features/threat-intelligence/) 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

| `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](/docs/sentinel/v2/reference/configuration/#ip_resolverproviders): [`maxmind`](/docs/sentinel/v2/reference/configuration/#type--maxmind), [`ip-api`](/docs/sentinel/v2/reference/configuration/#type--ip-api), [`ipstack`](/docs/sentinel/v2/reference/configuration/#type--ipstack), [`ipinfo`](/docs/sentinel/v2/reference/configuration/#type--ipinfo), [`ipinfo-mmdb`](/docs/sentinel/v2/reference/configuration/#type--ipinfo-mmdb), [`cloudflare`](/docs/sentinel/v2/reference/configuration/#type--cloudflare), [`headers`](/docs/sentinel/v2/reference/configuration/#type--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`.

```toml
[[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`:

```toml
[[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:

```toml
[[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](/docs/sentinel/v2/configure/remote-files/) 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:

```toml
[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](/docs/sentinel/v2/configure/listeners/).

The header gives the country only. Add a database or API provider after it for location and network flags.

> **Warning:**
>
> Sentinel trusts `CF-IPCountry` as received, and `X-IP-*` headers from anyone who sends the right `X-IP-Secret`. A client that reaches Sentinel directly can set its own country. Expose Sentinel only through Cloudflare (firewall rules that allow only Cloudflare's IP ranges, Authenticated Origin Pulls, or Cloudflare Tunnel), and make your proxy remove any `X-IP-*` headers sent by clients before it adds its own.

### 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`:

```toml
[[ip_resolver.providers]]
type   = "headers"
name   = "edge"
secret = "${IP_HEADERS_SECRET}"
```

```http
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:

```toml
[[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.

> **Tip:**
>
> An API provider at the end of the chain is queried whenever an earlier provider leaves any field empty, which is almost every IP: no single database fills all eleven fields. Put the API first only if it's your main source, and give it a long `cache_ttl` to stay within the provider's quota.

## Caching

Each provider has its own in-memory lookup cache, per replica, keyed by IP:

```toml
[[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](/docs/sentinel/v2/configure/remote-files/) 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](/docs/sentinel/v2/configure/air-gapped/).

## 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:

```bash
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:

```text
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:

```text
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](/docs/sentinel/v2/reference/cli/).

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:

```bash
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](#combining-providers), the response looks like this:

```json
{
 "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](/sentinel-api-docs-v2.html#tag/ip/POST/v2/ip).

`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](/docs/sentinel/v2/configure/licensing/) and [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/#credential-matrix).

## Related

- [`[ip_resolver]` in the Configuration reference](/docs/sentinel/v2/reference/configuration/#ip_resolver)
- [Rules reference: `country`, `network`, and `risk` conditions](/docs/sentinel/v2/reference/rules/#condition-fields)
- [Classifier rules: IP](/docs/sentinel/v2/reference/classifier-rules/#ip) and [Location](/docs/sentinel/v2/reference/classifier-rules/#location)
- [Scores, risk & penalty](/docs/sentinel/v2/concepts/scoring/)
- [Threat intelligence](/docs/sentinel/v2/features/threat-intelligence/)
- [Remote files & data sources](/docs/sentinel/v2/configure/remote-files/)
- [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/)
