Skip to content

Data sources

The IP Mapper does not discover IP mappings on its own — it is fed by other components and integrations. Each source has different guarantees, and understanding them explains why the session model works the way it does.

RADIUS

RADIUS accounting is the primary source in most deployments. The RADIUS Listener receives accounting events from the network's RADIUS infrastructure and turns them into IP Mapper sessions.

Characteristics of RADIUS feeds

RADIUS feeds are noisy and lossy, which shapes the reconciliation the IP Mapper has to do:

  • Start, Interim-Update, and Stop, but you cannot rely on getting the Start or the Stop. In principle a session opens with an Accounting-Start, is refreshed by Interim-Updates, and closes with an Accounting-Stop. In practice either the Start or the Stop can be missing (dropped, never sent, or lost across a restart), so the platform cannot treat them as guaranteed bookends.
  • Periodic reannouncements extend existing sessions. Interim-Updates arrive regularly for the life of a session and push its expiry out. A session that keeps being reannounced stays alive; one that stops being reannounced expires on its own. This is what makes missing Stops survivable.
  • No ordering guarantees, combined with imprecise timestamps. Events can arrive out of order, and their timestamps are not precise enough to order them reliably. The IP Mapper therefore applies reconciliation logic where, in a conflict, the newest information wins — including the allocation-stealing and muting behavior described in Sessions.

See the RADIUS Listener docs for how events are received, matched, and forwarded.

Organization Manager

The Organization Manager (2.11+) serves a specific use case: organizations that need hierarchical, nested filter overrides provisioned through a REST API — an organization-wide policy, with narrower overrides for departments and for individual users within the organization. It manages these overrides per organization rather than per network session.

Each override is expressed as an IP prefix allocation, and the nesting is resolved by a most-specific-CIDR-wins rule: a department's or user's narrower prefix overrides the broader organization prefix that contains it. The Organization Manager computes the effective non-overlapping ranges from this hierarchy and deploys the result to the IP Mapper.

See the Organization Manager REST API for how allocations are provisioned.

Admin static mappings

Mappings can also be provisioned by hand through the admin Opaque ID REST API. There are two distinct things an operator can provision this way, and they are not equivalent.

Static opaque-ID mappings provision the opaque-ID-to-username half of the indirection. Provisioning opaque-ID mappings without pinning a static IP is fully supported for production deployments.

Static IP mappings additionally pin a fixed IP address or CIDR to an opaque ID. Static IP mappings are meant for testing and special cases, not for production use, and they come with real limitations:

  • No overlap checks. Uniqueness is enforced only on the static mapping itself; there is no check against other allocations.
  • A dynamic RADIUS session can steal the static IP. A static IP is not protected from the normal allocation-stealing logic.
  • No IPv4 port-range support, so static IP mappings cannot express CG-NAT allocations.

Neither form is intended to carry high update volumes. They fit provisioning-time workflows rather than a stream of dynamic IP allocations.

HTTP API

The IP Mapper's HTTP API accepts the same session operations as NATS. It is the straightforward integration point for systems that already speak HTTP and want to create, update, query, or clean sessions directly.

Source locality

IP mapping can be handled as one global picture or as several independent local ones, depending on how the deployment is structured:

  • A single global source of truth. One control-plane IP Mapper owns all sessions, and Redis distributes them to every user-plane location. Every location sees the same mappings.
  • Regional islands or edge deployments. IP mapping is handled separately per region, with a local feed populating each region's own IP mapper and Redis. This suits cases where the address space is only meaningful locally (for example CG-NAT islands with overlapping IPv4 ranges), or where a region must keep operating independently of a central control plane.

Custom integrations

Any of the above can be replaced or supplemented by a custom integration. Because the IP Mapper's NATS and HTTP APIs accept the same session operations, an integration can push sessions from whatever system already knows which subscriber owns which IP (a provisioning database, a mobile core, or a BNG management layer) without going through RADIUS.