Sessions

The IP Mapper models everything it knows about a subscriber's presence on the network as a session. A session ties one or more IP allocations to a subscriber and carries the metadata the filter needs. The IP Mapper is the authoritative owner of this model; the other stages in the pipeline just distribute and read what it produces.

Session life cycle

A session moves through a small number of states. The IP Mapper applies them:

• Start. A new session is created with one or more IP allocations.
• Update. Metadata or allocations change. Merge semantics apply to fields like username, org and revision: an empty or zero incoming value leaves the stored value unchanged. The opaque ID is the exception: it cannot change after creation, and an update that tries to change it is rejected.
• Renew. The session's expiry is extended without any other change.
• Stop. The session is moved to a muted state for a short grace period (default 30 seconds) before removal. Muting absorbs out-of-order messages that arrive after the Stop, so a late update cannot resurrect a dead session or let it reclaim an address a newer session has taken over.
• Expiry. Sessions that pass their TTL are removed by a background cleanup sweep.

The reason both Stop and Expiry exist is that the IP Mapper cannot assume it will ever be told a session ended. Data sources like RADIUS routinely miss Stop messages, so every session also carries a TTL and is renewed by periodic updates. A session nobody refreshes eventually expires on its own.

Session attributes

Beyond its IP allocations, a session carries metadata used during filtering and for lifecycle management:

• Session ID. A stable identifier for the session, assigned by the source.
• Opaque ID. An indirection key between the IP allocation and the username; see Opaque-ID indirection below. Defaults to the session ID when not set.
• Username. The subscriber the session belongs to. May be known at Start or filled in later.
• Location. An optional site identifier for tiered filtering, where the location's rules are applied first and then the subscriber's.
• Device ID. An optional device identifier bound to the session, used for per-device filtering.
• Org and revision. Optional fields for org-level lifecycle management, used mainly by the Organization Manager to clean up sessions in bulk. See Org and revision.
• Region. An optional CG-NAT region; see CG-NAT.
• Allocations. The IP addresses and ranges the session owns; see Allocations below.

Opaque-ID indirection

Traditionally an IP address is not mapped straight to a username. It is mapped to an opaque ID, and the opaque ID is mapped to a username:

IP allocation  →  opaque ID  →  subscriber username

The opaque ID is a free-format string. It exists as a join key so the two halves — who owns which IP right now, and which subscriber an identity belongs to — can be maintained independently and by different systems. One convention does carry meaning: an opaque ID of the form base~suffix~ (2.7.9+) lets one base opaque ID hold several concurrent sessions, so a single subscriber identity can appear under multiple sessions at once (for example, CG-NAT port blocks).

There are two ways the opaque-ID-to-username mapping is provided:

• Provided with the allocation. When the IP allocation is added (for example from RADIUS), the username can be supplied directly if it is already known.
• Statically, through the Opaque ID REST API. Admin opaque-ID mappings can be provisioned and managed through a REST API. See static mappings.

Skipping the indirection

When the username is already known at the time the session is created, the indirection adds nothing. In that case the mapping can point directly at the username, so a lookup resolves the IP straight to the subscriber:

IP allocation  →  subscriber username

This is the common case when the source (such as RADIUS) already carries the username on the session.

Allocations

A session owns one or more allocations. An allocation can be:

• a single IP address (IPv4 or IPv6),
• a CIDR subnet prefix (for example 2001:db8::/48), or
• an IPv4 address with a port range, to support CG-NAT deployments where several subscribers share one IPv4 address. See CG-NAT.

A single session can hold more than one allocation at once.

Stealing allocations

IP addresses get reused, and updates about that reuse can arrive late or out of order. The IP Mapper resolves these conflicts so the newest information wins:

• A newer session steals an allocation from an older one. When a new session claims an address that an existing session still holds, the allocation is transferred to the new session. The older session is not deleted outright; it records that the allocation was taken from it. See stolen allocations.
• A smaller, newer allocation can deallocate a larger one that contains it. If a new, more specific allocation falls inside a larger range held by an older session, that larger encompassing allocation is removed. If this leaves the older session with no allocations at all, that session is ended and muted, so a delayed message cannot immediately steal the address back.

An out-of-order guard protects all of this: if the incoming update is older than the session currently holding an address, the steal is refused. This is what lets the IP Mapper stay correct even when a data source delivers conflicting updates with imprecise timestamps. The guard compares the message timestamps (with an allowance for clock skew), so it only works for sources that supply a timestamp with their updates.

APIs

Sessions are created and managed through the IP Mapper's modern interfaces. The NATS API is the primary one; an HTTP API exposes the exact same operations with the same JSON request and response bodies, so a caller can move between the two transports without changing any payload.

Operation	NATS command	HTTP endpoint (POST)
Create or update one session	set-session	/api/v1/sessions
Create or update many sessions	set-session-batch	/api/v1/sessions/batch
Query sessions by username or IP	get-sessions	/api/v1/sessions/query
Remove sessions for an org	clean-sessions	/api/v1/sessions/clean

See IP Mapper → Interfaces for connection details, request and response schemas, and authentication.

Note

The IP Mapper also exposes a legacy Redis-protocol (RESP) interface, including the script commands the older redis-script backend used. That interface exists for backward compatibility and is not covered here; new integrations should use NATS or HTTP. See Legacy redis-script.