Lunar - Quickstart

Step 1: start the simulator in verbose mode

$ /opt/lunar/bin/lunar_backend_sim -V
Listening on 127.0.0.1:5555 (workers=512, auth_sleep=0ms, verbose=on)

In -V mode it pretty-prints every HTTP request lunar makes and every reply it sends back. It serves one fixed virtual (TEST / client-test / testing123, auth 1812 / acct 1813 / CoA 3799) and always accepts auth, mirroring the request attributes onto the reply. See Tools for the full behavior.

Step 2: start lunar

Start (or restart) lunar with the subscriber service enabled and its backend endpoint pointing at the simulator. As lunar comes up it performs its config fetch: it calls the backend for its virtuals:

GET /v1/lunar/<server_id>/virtuals

The simulator returns the one TEST virtual. Lunar binds that virtual's three UDP ports and is now serving. In the simulator's verbose output you will see this GET and the virtual JSON it returned. This is exactly the same fetch lunar does against a real backend. The simulator just always answers with the test virtual.

Step 3: send a request and watch the flow

Fire an Access-Request at the virtual:

$ /opt/lunar/bin/radtest --username alice --password secret 127.0.0.1 testing123

Now watch the simulator's verbose log. Lunar decoded the UDP packet and POSTed it to the backend auth route as JSON:

POST /v1/lunar/<server_id>/auth/TEST

{
  "code": "access-request",
  "attributes": {
    "user-name": {"values": ["alice"]},
    "user-password": {"values": ["secret"]},
    "nas-ip-address": {"values": ["127.0.0.1"]}
  }
}

The simulator replies access-accept, mirroring the attributes back:

{
  "code": "access-accept",
  "attributes": {
    "user-name": {"values": ["alice"]}
  }
}

Lunar builds the Access-Accept on the RADIUS wire back to radtest, which prints radtest: Success. You have now seen the whole path end to end: UDP in -> decode -> backend POST -> decision -> encode -> UDP out.

Step 4: try accounting and a disconnect

The same flow drives the other functions. An accounting Start POSTs to .../acct/TEST and gets an accounting-response. An outbound Disconnect is a single API call to lunar that relays a disconnect-request to the NAS (see the coapod route below and in the RADIUS Integration guide). Watch each in the simulator's verbose log to see the request/response shapes.

Endpoints your backend must serve (lunar -> backend)

These are the calls lunar originates. Implement them and lunar works. Each route's full request and response spec is shown inline below it.

Return this server's virtuals (with their clients). Lunar calls this on startup and on reload. This is the config fetch you saw the simulator answer.

[
  {
    "id": "1A2B3C",
    "domain": "acme",
    "name": "acme-jhb",
    "ip4_address": "203.0.113.5",
    "radius_auth_port": 1812,
    "radius_acct_port": 1813,
    "radius_coa_port": 3799,
    "clients": [
      {
        "id": "c1",
        "name": "bras-01",
        "type": "nas",
        "profile": "default",
        "ip4_address": "203.0.113.10",
        "secret": "shared-secret",
        "coa_port": 3799,
        "req_message_auth": false,
        "message_auth_reply": true
      }
    ]
  }
]

Return one virtual's current config (used when a single virtual is reloaded).

{
  "id": "1A2B3C",
  "domain": "acme",
  "name": "acme-jhb",
  "ip4_address": "203.0.113.5",
  "radius_auth_port": 1812,
  "radius_acct_port": 1813,
  "radius_coa_port": 3799,
  "clients": [
    {
      "id": "c1",
      "ip4_address": "203.0.113.10",
      "secret": "shared-secret"
    }
  ]
}

Decide an Access-Request (or Status-Server). Return access-accept / access-reject with any reply attributes.

{
  "code": "access-request",
  "id": 7,
  "authenticator": "0x9a1c...",
  "attributes": {
    "user-name": {"values": ["alice"]},
    "nas-ip-address": {"values": ["203.0.113.10"]},
    "nas-port": {"values": [12]}
  }
}

{
  "code": "access-accept",
  "attributes": {
    "class": {"values": ["0x6f70616b7565"]},
    "session-timeout": {"values": [3600]}
  }
}

Receive an accounting record. Return accounting-response (a simple acknowledgment).

{
  "code": "accounting-request",
  "id": 12,
  "authenticator": "0x3f2a...",
  "attributes": {
    "user-name": {"values": ["alice"]},
    "acct-status-type": {"values": ["start"]},
    "acct-session-id": {"values": ["5f3c9a01"]},
    "framed-ip-address": {"values": ["100.64.0.5"]},
    "nas-ip-address": {"values": ["203.0.113.10"]}
  }
}

{"code": "accounting-response"}

Decide an inbound CoA / Disconnect from a NAS.

{
  "code": "disconnect-request",
  "id": 30,
  "authenticator": "0x77b1...",
  "attributes": {
    "user-name": {"values": ["alice"]},
    "acct-session-id": {"values": ["5f3c9a01"]}
  }
}

{
  "code": "disconnect-nak",
  "attributes": {
    "error-cause": {"values": ["session-context-not-found"]}
  }
}

Receive lunar's remote log lines (accept and store/forward).

{
  "virtual_id": "1A2B3C",
  "client_ip": "203.0.113.10",
  "message": "coapod relay failed (client:bras-01) (error:timeout)",
  "level": "warning",
  "time": 1751932800
}

Health probe, answer 200 when your backend is ready.

The request and response bodies use lunar's packet/attribute JSON, a top-level code and an attributes object keyed by attribute name. That format, including data types, enums and credential handling, is documented once in The JSON request format, and the emitted (lower-case) form is shown throughout Kafka when using Kafka event streaming.

Endpoints on lunar you can call (backend -> lunar)

These are the calls you make on lunar, all under /v1 and gated by the x-secret header. Each route's full spec is shown inline below it.

Lunar's health and vitals (also checks the backend).

{
  "status": "ok",
  "hostname": "lunar-1.domain.com",
  "system_uptime_seconds": 1503244,
  "lunar_started_time": 1753246800,
  "lunar_running_seconds": 86400,
  "os": "Ubuntu 24.04.1 LTS",
  "kernel": "6.8.0-31-generic",
  "load_avg_1m": 0.42,
  "load_avg_5m": 0.55,
  "load_avg_15m": 0.61,
  "total_mem_mib": 32021,
  "free_mem_mib": 24817,
  "disks": [
    {
      "filesystem": "/dev/sda1",
      "mount": "/",
      "fstype": "ext4",
      "size_mib": 480000,
      "used_mib": 125000,
      "available_mib": 330000,
      "use_percent": 28
    }
  ]
}

List the virtuals lunar currently serves.

[
  {"id": "1a2b3c", "domain": "acme", "name": "acme-jhb"},
  {"id": "4d5e6f", "domain": "acme", "name": "acme-cpt"}
]

Fetch one virtual's live record.

{
  "id": "1a2b3c",
  "domain": "acme",
  "name": "acme-jhb",
  "ip4_address": "203.0.113.5",
  "radius_auth_port": 1812,
  "radius_acct_port": 1813,
  "radius_coa_port": 3799
}

List a virtual's clients.

[
  {"id": "c1", "name": "bras-01", "type": "cisco"},
  {"id": "c2", "name": "bras-02", "type": "juniper"}
]

Fetch one client's live record.

{
  "id": "c1",
  "name": "bras-01",
  "type": "cisco",
  "profile": "default",
  "ip4_address": "203.0.113.10",
  "secret": "shared-secret",
  "coa_port": 3799,
  "req_message_auth": true,
  "message_auth_reply": true
}

(Re)load a virtual. Lunar re-fetches that virtual from your backend and applies it in place, with no restart and no disruption to live traffic.

Stop a virtual.

Relay a CoA / Disconnect to a NAS in one call, returning the decoded ACK / NAK (see the Overview and the RADIUS Integration guide).

{
  "code": "disconnect-request",
  "attributes": {
    "user-name": {"values": ["alice"]},
    "acct-session-id": {"values": ["5f3c9a01"]},
    "nas-ip-address": {"values": ["203.0.113.10"]}
  }
}

{
  "code": "disconnect-ack",
  "id": 55,
  "authenticator": "0x1b9f...",
  "attributes": {}
}

Run a packet through the backend without touching the RADIUS wire. Returns the backend's reply verbatim. Ideal for integration testing.

{
  "code": "access-request",
  "attributes": {
    "user-name": {"values": ["alice"]},
    "user-password": {"values": ["secret"]},
    "nas-ip-address": {"values": ["203.0.113.10"]}
  }
}

{
  "code": "access-accept",
  "attributes": {
    "class": {"values": ["0x6f70616b7565"]},
    "session-timeout": {"values": [3600]}
  }
}

A full-path liveness probe that builds a Status-Server, sends it through the whole engine and back, and returns 200 {"status": "ok"} when the entire chain is alive.

{"status": "ok"}

The typical lifecycle: you create a virtual and its clients in your backend, then call POST /v1/subscriber/radius/virtual/<virtual_id> on lunar so it fetches and starts that virtual. From then on lunar serves the wire and posts every decision to your backend.