Skip to content

IP Mapper

The PowerDNS Platform Filter IP Mapper (pdns-pf-ipmapper) maintains the authoritative mapping of subscriber IP addresses to active sessions. It receives session updates from the RADIUS Listener, Admin Portal, or orgmanager and holds the full state in memory, backed by Redis for persistence.

What it does

  • Accepts session create, update, renew, and stop events from multiple sources.
  • Indexes each session by IP allocation, session ID, opaque ID, username, org, and region, so any of those can be used to look up a session.
  • Serves the DNS filtering side of Platform Filter: when the Recursor or Proxy receives a DNS query from a client IP, it asks the IP Mapper which subscriber that IP belongs to.
  • Persists all state to Redis on every change and reloads it on startup, so a restart does not drop the session table.

Interfaces

The IP Mapper exposes three interfaces, which can be enabled or disabled independently by setting (or omitting) their listen address in the config:

NATS micro-service — the primary API for programmatic access. Commands: set-session, set-session-batch, get-sessions, clean-sessions. Callers use the itsy NATS micro-service framework to reach the service under the name ipmapper.

RESP (Redis protocol emulation) — listens on a TCP port and speaks the Redis wire protocol. It implements the legacy Lua script interface used by the RADIUS Listener's redis-script mode, and also supports the IPMAPPER command family for direct access.

HTTP — serves a status page at / and Prometheus metrics at /metrics, and can optionally expose a session API under /api/v1/sessions that mirrors the NATS operations (set-session, set-session-batch, get-sessions, clean-sessions) as JSON POST endpoints, secured with TLS/mTLS and an optional X-API-Key token.

Where it fits in Platform Filter

The IP Mapper sits at the centre of the subscriber-tracking pipeline:

  • Session sources (RADIUS Listener, Admin Portal, orgmanager) push session events into the IP Mapper.
  • DNS resolution (Recursor, Proxy) queries the IP Mapper to identify which subscriber owns a given client IP.

See Architecture for the data-flow diagrams.

Next steps

  • Architecture: how the IP Mapper fits into Platform Filter, the session lifecycle, and core concepts.
  • Configuration: full YAML reference.
  • Operations: systemd unit, CLI flags, status page, and performance notes.
  • Metrics: Prometheus metric reference and operator guidance.