Lunar - Integration

Lunar hosts multiple services. Each service is enabled independently in config, and a single Lunar instance can run one, several or all of them at once. Today the subscriber service (a RADIUS server) is available. More services will be added over time.

Lunar exposes a small HTTP/JSON control API. It is how an operator (or an upstream backend API) inspects a running Lunar instance and drives whatever services it is running. Such a backend API is the system that manages instances on Lunar. For example, the NebularStack Subscriber Management module, which manages Lunar and its subscriber (RADIUS) service.

This document describes the top-level, service-agnostic API. The routes that belong to the Lunar process itself rather than to any one service. The only top-level route today is GET /v1/status. Everything a specific service adds is documented alongside that service, never here, so that this document stays independent of which services exist:

Subscriber (RADIUS) API. See the RADIUS Integration guide.

Where the API listens

The API server is a single embedded HTTP server on every lunar instance. It is shared by every enabled service (each service attaches its own routes to it), so there is one listener regardless of how many services are running. Its listen address and worker pool come from config:

lunar.api_host: The bind address. Default 127.0.0.1, which is loopback only, reachable from the same host (or over an SSH tunnel or private overlay). Set it to a routable address only behind a trusted network boundary.
lunar.api_port: The TCP port. Default 1337.
lunar.api_threads: The number of HTTP worker threads. Default 4.

All routes are versioned under /v1 and speak JSON.

Authentication

Every route is gated by a single shared secret. The caller must send it in the x-secret request header:

x-secret: <the value of lunar.secret>

The value is whatever lunar.secret is set to in config. It is compared in constant time, so a wrong or missing secret is rejected with 401 Unauthorized and no body. The same secret gates every route, top-level and service. There is no other authentication scheme (no cookies, no bearer tokens). Protect the API by keeping the listener private and the secret secret.

GET /v1/status

A core health + vitals endpoint and it is service-agnostic. It reports this host's vitals, probes whatever backend health checks the enabled services registered at startup, and reports the instance's license health. Each service that needs a backend to be reachable contributes its own check. The route itself knows nothing about any particular service.

Use it as a load-balancer / monitoring probe and as a quick "is this instance healthy and licensed?" check. It always returns 200 OK when the secret is valid, whether the instance is healthy or not: the body's status field carries the verdict (ok or bad), so poll the JSON, not the HTTP status code, for health. When status is bad the same object also carries an errors array (one human-readable string per failure), only present when non-empty:

{
  "status": "bad",
  "hostname": "lunar-1.domain.com",
  "...": "...",
  "errors": [
    "<service>: https://backend.example.com/health failed: Connection timed out after 5000 ms",
    "license: license expired"
  ]
}

GET

/v1/status

(lunar)

Instance Health and Vitals.

Service
lunar

Request Parameters

Name	In	Type	Description	MUST include
x-secret	header	string	Lunar shared secret (config lunar.secret). Compared in constant time. A missing or wrong value returns 401 with no body.	X

Response Status Codes

Code	Meaning
200	OK
401	Unauthorized / Require Authentication
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
disks	body	array	One entry per real mounted filesystem, mirroring df but in MiB. Each entry carries filesystem, mount, fstype, size_mib, used_mib, available_mib and use_percent.
errors	body	array	Present only when status is bad. One human-readable string per failure, either a failed backend probe or a license problem.
free_mem_mib	body	integer	Memory usable by new workloads without swapping, in MiB (the kernel MemAvailable estimate).
hostname	body	string	The host's fully-qualified domain name.
kernel	body	string	Full kernel release string.
load_avg_15m	body	decimal	Fifteen minute load average.
load_avg_1m	body	decimal	One minute load average.
load_avg_5m	body	decimal	Five minute load average.
lunar_running_seconds	body	integer	How long this lunar instance has been running, in seconds.
lunar_started_time	body	integer	Unix epoch second (UTC) at which this lunar instance started.
os	body	string	Human OS description.
status	body	string	Overall verdict. ok when every health check passed and the license is healthy, otherwise bad. This is the single field to alert on. The HTTP status is 200 either way, so poll this field, not the status code.
system_uptime_seconds	body	integer	Seconds since the host booted.
total_mem_mib	body	integer	Total system memory in MiB.

Response Example

{
  "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
    }
  ]
}

What "healthy" means

The verdict combines two things:

Backend health checks. Each enabled service registers zero or more backend endpoints that must answer 200 OK. Each is probed with a 5 second timeout. Anything other than a 200 (a non-200 status, a timeout, a DNS or connection failure) is one entry in errors, prefixed with the service it belongs to. Which checks exist depends entirely on which services are enabled and is documented with each service.
License health. A missing, invalid or expired-past-grace license is a single license: error (no per-service license lines are then added). Only when the license is otherwise valid is each enabled service checked for coverage (for example that subscriber is licensed), and any gap is its own license: line.