Skip to content

IP mapping

Personalized filtering is keyed on the subscriber, but a DNS server or proxy only sees a client IP address at query time. IP mapping is how Platform Filter bridges that gap: it keeps an up-to-date picture of which subscriber owns which IP address, so that when a query arrives the filtering code can resolve the client IP to a subscriber username and apply that subscriber's filter settings.

The Recursor, DNSdist, and the proxies all rely on this lookup. Without a current IP mapping a query cannot be attributed to a subscriber, and only the default filter settings can be applied.

This guide explains how IP mappings move through the platform end to end, where they come from, and the advanced topics (per-device filtering, CG-NAT, and observability) that operators run into once the basics are in place.

The data plane

IP mappings flow through four stages, from the components that learn about subscriber sessions on the write side, to the filtering code that reads them on the query side:

flowchart LR
    RL[RADIUS Listener] -- sessions --> IM[(IP Mapper)]
    OM[Organization Manager] -- sessions --> IM
    AP[Admin Portal] -- sessions --> IM
    IM -- persist + publish --> R[(Redis)]
    R -- bulk load + pubsub --> SS[Settings Syncer]
    SS -- write --> DB[(LMDB)]
    DB -. lookup .-> REC[Recursor]
    DB -. lookup .-> DD[DNSdist]
    DB -. lookup .-> SIM[Simulator]
    DB -. lookup .-> PX[Proxies]

IP Mapper. The IP Mapper holds all session state in memory. It is backed by Redis session storage for persistence across restarts, and it distributes every IP-mapping update through Redis. It applies the reconciliation logic that keeps the mapping correct as sessions start, move, and stop. See the IP Mapper component docs for the write side.

Redis. Redis is the platform's main data plane for IP mappings. The IP Mapper writes changes to Redis, and Redis distributes them to every user-plane data center that subscribes to it.

Settings Syncer. In each user-plane location, the Settings Syncer picks the data up from Redis (a subscription for live changes plus a full bulk load) and writes it into a local LMDB. The same pipeline also carries the subscriber and global filter settings; this guide covers the IP-mapping part.

LMDB. LMDB is a local, memory-mapped database. Because it is mapped into the filter process and lives next to it on the same host, it gives the filtering code very fast lookups with no network round-trip.

The lookup. The filtering code (the Lua that runs inside the Recursor, DNSdist, and the proxies) does its IP-to-subscriber lookup against that local LMDB on every query. Some proxies do not read LMDB directly and instead perform the lookup remotely through the Simulator API.

The split around Redis matters: the expensive reconciliation happens once, centrally, and every read-side location gets its own local copy to query.

Where to go next

  • Sessions — the session model the IP Mapper maintains: lifecycle, attributes, the opaque-ID indirection, allocations, and the APIs.
  • Data sources — where IP mappings come from: RADIUS, the Organization Manager, static admin mappings, and custom integrations.
  • Per-device filtering — device IDs and device profiles for applying different settings to different devices behind one subscriber.
  • CG-NAT — mapping subscribers that share an IPv4 address, and regions for overlapping address ranges.
  • Legacy redis-script — what changed relative to the older redis-script backend.
  • Observability — how to watch the pipeline and the tools for inspecting what a lookup will return.