Lunar - Kafka

Where the data comes from

Every event ultimately originates from a NAS, the Network Access Server the subscriber connects through. In a broadband network this is typically a BNG / BRAS (Cisco, Juniper, Nokia, NetElastic, ...). On Wi-Fi it is a wireless controller. The NAS speaks RADIUS: it sends binary UDP packets to ask "may this subscriber connect?" (authentication) and to report "here is what this subscriber used" (accounting).

Those packets are in RADIUS wire format (RFC 2865 for authentication, RFC 2866 for accounting), a compact binary encoding, not something you would read directly. Lunar (our RADIUS proxy) receives them and parses them using RADIUS dictionaries, the definitions that map each attribute's numeric code to a human name and a data type. It then re-serializes the result as the readable JSON you receive in these events. So by the time an event reaches you the binary packet has already been decoded into named fields with typed values.

RADIUS in a nutshell (for consumers new to RADIUS)

You do not need to know the RADIUS wire protocol to consume these events. Lunar has already parsed the raw UDP packets into readable JSON. A few concepts make the payloads obvious:

• A RADIUS message is a packet. Each packet has a short code naming its kind (access-request, access-accept, access-reject, accounting-request, ...) and carries a flat list of attributes.

• An attribute is a named field, e.g. user-name, nas-ip-address, acct-session-id. On the wire each attribute is just a number. The RADIUS dictionary resolves that number to the human name and tells lunar its data type. Attributes you consume are therefore keyed by name. Lunar always emits that name in lower case (user-name, nas-ip-address). Match keys case-insensitively.

• The same attribute may appear more than once in one packet. That is how RADIUS represents a multi-valued field (it has no list type). So every attribute's decoded values are given as an array, in the order they appeared, even when there is only one value.

• Authentication is a request/response exchange: the NAS sends an access-request. The platform answers access-accept (allowed) or access-reject (denied), optionally with reply attributes (e.g. a session class or bandwidth limits). The authentication event carries both sides so you see the question and the answer together.

• Accounting is one-way reporting: the NAS sends an accounting-request whose acct-status-type says start (session began), interim-update (periodic usage) or stop (session ended). A subscriber's session is tracked by its acct-session-id. Usage counters such as acct-input-octets / acct-output-octets and acct-session-time arrive on interim-update and stop.

Standard vs vendor-specific attributes

Attributes fall into two groups, and this matters a lot when you consume them:

• Standard attributes are defined by the RADIUS RFCs, chiefly RFC 2865 (authentication) and RFC 2866 (accounting). Their names and meanings are the same regardless of which vendor's NAS sent them: user-name, nas-ip-address, calling-station-id, acct-status-type, acct-session-id, acct-input-octets, etc. Prefer these whenever a piece of information you need is available as a standard attribute.

• Vendor-specific attributes (VSAs) carry data the RFCs do not define. Every vendor (Cisco, Juniper, Nokia, NetElastic, ...) publishes its own set, so different NAS devices express the same idea with different attributes. For example the subscriber's assigned data rate, remaining quota or service profile may be a Cisco AV-Pair on one network and a Juniper or Nokia attribute on another.

Practical guidance when writing a consumer:

• Decide what information you need (username, session id, MAC, usage, rate limit, ...) and first look for it as a standard RFC 2865 / RFC 2866 attribute. That path works across all vendors.

• Do not assume a different vendor's device uses the same attributes as the one you tested against. If you rely on a vendor attribute, gate it on the vendor/device it comes from.

• Normalize at consumption time: you know what you are looking for, so map the various vendor attributes onto your own internal fields and work with those downstream. That keeps the rest of your system independent of which NAS produced the event.

The attribute names, types and value formats are detailed under "Attribute value format".

Enabling

Event shipping is optional and configured on the lunar proxy. Two independent streams can be enabled, each with its own Kafka topic:

• accounting topic: RADIUS accounting events.

• authentication topic: RADIUS authentication events.

Either, both or neither may be enabled. A stream with no topic ships nothing. Ask your platform operator which topics carry which stream.

The two event streams

The two streams become "complete" at different moments, so they are emitted at different times:

Accounting events

Emitted as soon as an accounting request arrives from the NAS. An accounting record is self-contained, so there is nothing to wait for.

Authentication events

Emitted once the platform has decided the request, because the event pairs the request with that decision. Only requests that produced a valid decision are shipped. A request that could not be answered ships no event.

Both streams are best-effort: under extreme load an event may be dropped rather than delay answering the NAS. Do not treat the stream as a guaranteed, gap-free ledger. Use it for analytics, billing feeds, audit and similar, and reconcile against session ids where completeness matters.

Common envelope

Every event (accounting or authentication) is a single JSON object with the same outer envelope. Only the event name and the data payload differ between the two streams:

{
  "timestamp": 1751932800123,
  "event": "radius-accounting",
  "source": {
    "hostname": "radius-proxy-1.domain.com",
    "server-id": "your-lunar-server-id"
  },
  "metadata": {
    "virtual_id": "...",
    "radius_client_id": "...",
    "radius_client_ip": "...",
    "radius_nas_id": "...",
    "radius_nas_ip": "..."
  },
  "data": { ... }
}

Envelope fields:

timestamp

Unix time in milliseconds at the moment lunar enqueued the event.

event

The stream name: radius-accounting or radius-authentication.

source

Which lunar proxy produced the event: its hostname and its server-id (the identifier assigned to your lunar instance). Use this to tell apart events when several lunar proxies feed the same topic.

metadata

Identity fields describing where the packet came from (see below). Omitted entirely when empty. In practice always present for RADIUS events.

data

The stream-specific payload, embedded as a JSON object (see each stream below).

metadata fields (identical for both streams):

virtual_id

The virtual RADIUS server inside lunar that received the packet. A single lunar proxy can host several virtual RADIUS servers (for example one per customer or region). This is the one that handled this event.

radius_client_id / radius_client_ip

The RADIUS client that sent the packet to lunar: the name configured for it on our platform (typically the BNG/BRAS name) and the source IP the packet arrived from.

radius_nas_id / radius_nas_ip

The NAS the subscriber actually connected through, taken from the request's nas-identifier / nas-ip-address attributes (empty when the request carried neither).

auth (authentication events only)

The authentication method(s) the request used, as a comma-separated list, e.g. "pap", "eap" or "pap,eap" when more than one is present. Detected from which credential attributes the request carried: pap (user-password), chap (chap-password), mschap (ms-chap-response), mschapv2 (ms-chap2-response) and eap (eap-message). Absent when no known method was recognized. Use this to know how the subscriber authenticated without inspecting credential attributes yourself (which are redacted, see below). Accounting events never carry auth.

Why both a client and a NAS identity? Usually they are the same device: the BNG both terminates the subscriber and talks RADIUS to lunar, so radius_client_* and radius_nas_* match. But the RADIUS client can also be another RADIUS proxy that forwards traffic on behalf of a NAS sitting behind it. In that case radius_client_* identifies the proxy that connected to lunar, while radius_nas_* identifies the real NAS further downstream. Key your subscriber/session logic off the NAS identity, and use the client identity to know which device delivered the packet to us.

Partition key

Each event's Kafka partition key is chosen from the request attributes, in this order of preference, using the first attribute present (and its first value when multi-valued):

1. user-name

2. calling-station-id

3. class

4. acct-session-id

This keeps all records for one subscriber / station / session on the same partition, so a consumer sees them in order. When none of those attributes is present the key is empty (keyless) and the event is spread across partitions by Kafka's default partitioner.

Accounting event

• event: radius-accounting

• data: the decoded accounting packet (see "Attribute value format").

Example:

{
  "timestamp": 1751932800123,
  "event": "radius-accounting",
  "source": {
    "hostname": "radius-proxy-1.domain.com",
    "server-id": "your-lunar-server-id"
  },
  "metadata": {
    "virtual_id": "1a2b3c",
    "radius_client_id": "bras-01",
    "radius_client_ip": "203.0.113.10",
    "radius_nas_id": "bras-01",
    "radius_nas_ip": "203.0.113.10"
  },
  "data": {
    "code": "accounting-request",
    "attributes": {
      "user-name": {"values": ["alice"], "type": "text", "code": "1"},
      "acct-status-type": {"values": ["interim-update"],
                           "type": "integer", "code": "40"},
      "acct-session-id": {"values": ["5f3c..."], "type": "text",
                          "code": "44"},
      "acct-input-octets": {"values": [15315], "type": "integer",
                            "code": "42"},
      "acct-output-octets": {"values": [5877], "type": "integer",
                             "code": "43"}
    }
  }
}

Note how acct-input-octets / acct-output-octets are bare numbers (15315, 5877) while the acct-status-type enum is a string ("interim-update"). See "Value types" for the rule, and "Accounting: sessions, counters and event types" for what these counters mean.

Authentication event

• event: radius-authentication

• data: an object pairing the request with the platform's response:

  {"request": <request packet JSON>, "response": <platform reply JSON>}

  request is the decoded access-request from the NAS. response is the platform's authentication decision for it (an access-accept or access-reject packet, with any reply attributes). Both use the same attribute format described below.

Example:

{
  "timestamp": 1751932800456,
  "event": "radius-authentication",
  "source": {
    "hostname": "radius-proxy-1.domain.com",
    "server-id": "your-lunar-server-id"
  },
  "metadata": {
    "virtual_id": "1a2b3c",
    "radius_client_id": "bras-01",
    "radius_client_ip": "203.0.113.10",
    "radius_nas_id": "bras-01",
    "radius_nas_ip": "203.0.113.10",
    "auth": "pap"
  },
  "data": {
    "request": {
      "code": "access-request",
      "attributes": {
        "user-name": {"values": ["alice"], "type": "text", "code": "1"},
        "user-password": {"values": ["--OBFUSCATED--"], "type": "text",
                          "code": "2"}
      }
    },
    "response": {
      "code": "access-accept",
      "attributes": {
        "class": {"values": ["0x6e733a..."], "type": "octets",
                  "code": "25"}
      }
    }
  }
}

Attribute value format

This section explains how to read the decoded packet in data.

{
  "code": "access-request",     // the kind of packet (see below)
  "attributes": { ... }           // the named fields, described next
}

"user-name": { "values": ["alice"], "type": "text", "code": "1" }

Accounting: sessions, counters and event types

Accounting events describe a subscriber session on the NAS/BNG over its whole lifetime. A few RADIUS accounting rules make the numbers in an radius-accounting event usable.

acct-input-octets  = 15315     // 15315 bytes in  so far this session
acct-output-octets = 5877      // 5877  bytes out so far this session

total_input_bytes  = acct-input-gigawords  * 4294967296 + acct-input-octets
total_output_bytes = acct-output-gigawords * 4294967296 + acct-output-octets

Delivery semantics

• Delivery is asynchronous and best-effort: under extreme load an event may be dropped rather than delay the RADIUS response to the NAS.

• Ordering is only guaranteed between events that share a partition key (see "Partition key"). Across different keys there is no global order.

• Every accepted accounting request produces an accounting event. Only requests that produced a valid decision produce an authentication event.