benya/rmm-openwrt

Fork 0

Files

benya e6236f505c feat: add multi-user management and secure LuCI access

2026-07-19 23:10:07 +03:00

11 KiB

Raw Blame History

API

Base URL examples use http://127.0.0.1:8080.

Operator Authentication

Browser users sign in with username/password. The server returns a random, revocable HttpOnly, SameSite=Strict session cookie. Normal users are scoped to their own devices; the bootstrap account has the admin role.

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "operator-password"
}

Check the current browser session:

GET /api/auth/me

Sign out:

POST /api/auth/logout

Operator API automation may continue using:

Authorization: Bearer <operator-api-token>

The bearer token is optional and administrator-scoped.

Users and enrollment grants

Administrators can list, create, disable, re-enable and reset passwords for accounts:

GET /api/users
POST /api/users
PATCH /api/users/{user_id}

Every authenticated user can create a 60-second to 24-hour one-time enrollment grant (15 minutes by default):

POST /api/enrollment-grants
Content-Type: application/json

{"dns_label":"office-1","expires_seconds":900}

The response returns enrollment_token once. The agent exchanges it for its device ID and token; a second exchange is rejected.

Health

GET /healthz

Response:

{"status":"ok"}

Agent Enrollment

POST /api/agent/enroll
Content-Type: application/json

Request:

{
  "enrollment_token": "one-time-enrollment-grant",
  "hostname": "openwrt-router-1",
  "openwrt_version": "OpenWrt 23.05.3"
}

Response:

{
  "device_id": "dev_...",
  "device_token": "tok_..."
}

Agent Heartbeat

POST /api/agent/heartbeat
Authorization: Bearer tok_...
Content-Type: application/json

Request:

{
  "device_id": "dev_...",
  "inventory": {
    "hostname": "openwrt-router-1",
    "openwrt_version": "OpenWrt 23.05.3",
    "wan_ip": "203.0.113.10/24",
    "dhcp_leases": [],
    "wifi_clients": []
  },
  "metrics": {
    "loadavg": "0.00 0.01 0.00 1/80 1234",
    "memory": {"total_kb": 262144, "used_kb": 131072},
    "disk": {"total_kb": 65536, "used_kb": 20000, "used_percent": "31%"},
    "interface_counters": [],
    "connectivity_checks": [
      {
        "target": "1.1.1.1",
        "reachable": true,
        "packet_loss_percent": 0,
        "latency_ms": 12.4
      }
    ]
  }
}

Response:

{
  "commands": [
    {
      "id": "cmd_...",
      "device_id": "dev_...",
      "type": "ping",
      "args": {"target": "1.1.1.1"},
      "status": "queued",
      "created_at": "2026-06-01T12:00:00Z"
    }
  ]
}

Agent Next Command

This endpoint is optimized for the MVP shell agent and returns at most one queued command as plain text.

POST /api/agent/commands/next
Authorization: Bearer tok_...
Content-Type: application/json

Request:

{
  "device_id": "dev_..."
}

Response:

cmd_...	ping	{"target":"1.1.1.1"}

If there are no queued commands, the server returns 204 No Content.

Command Result

POST /api/agent/commands/{command_id}/result
Authorization: Bearer tok_...
Content-Type: application/json

Request:

{
  "device_id": "dev_...",
  "status": "completed",
  "exit_code": 0,
  "output": "PING 1.1.1.1 ...",
  "result": {}
}

List Devices

GET /api/devices
Authorization: Bearer <operator-api-token>

Response:

{
  "devices": []
}

Get Device

GET /api/devices/{device_id}
Authorization: Bearer <operator-api-token>

Update Device Fleet Metadata

PATCH /api/devices/{device_id}/fleet
Authorization: Bearer <operator-api-token>
Content-Type: application/json

Request:

{
  "group": "home",
  "tags": ["edge", "vpn"]
}

Metrics History

GET /api/devices/{device_id}/metrics-history?limit=100
Authorization: Bearer <operator-api-token>

Response:

{
  "samples": [
    {
      "id": "met_...",
      "device_id": "dev_...",
      "inventory": {},
      "metrics": {},
      "created_at": "2026-06-01T12:00:00Z"
    }
  ]
}

Device Alerts

GET /api/devices/{device_id}/alerts
Authorization: Bearer <operator-api-token>

Alerts are computed from current device state, recent metric samples, and recent commands. The MVP alert types are:

offline
memory_high
disk_high
wan_ip_changed
command_attention
wan_down
packet_loss_high
latency_high

Alert statuses:

active
acknowledged
resolved

Response:

{
  "alerts": [
    {
      "id": "disk_high:dev_...",
      "device_id": "dev_...",
      "type": "disk_high",
      "severity": "warning",
      "status": "active",
      "message": "Disk usage is high",
      "details": {"used_percent": 88},
      "first_seen_at": "2026-06-01T12:00:00Z",
      "last_seen_at": "2026-06-01T12:03:00Z",
      "created_at": "2026-06-01T12:00:00Z"
    }
  ]
}

Acknowledge Alert

POST /api/devices/{device_id}/alerts/{alert_id}/acknowledge
Authorization: Bearer <operator-api-token>

Acknowledged alerts remain open while the condition still exists. When the condition disappears, the server marks the alert as resolved.

Create Command

POST /api/devices/{device_id}/commands
Authorization: Bearer <operator-api-token>
Content-Type: application/json

Request:

{
  "type": "ping",
  "args": {"target": "1.1.1.1"}
}

Allowed command types:

ping
traceroute
route_show
interfaces_show
reboot
service_restart
pkg_list_installed
pkg_update
pkg_list_upgradable
pkg_install
pkg_remove
uci_show
uci_backup
uci_preview
uci_set
uci_commit
uci_commit_confirmed
uci_revert
uci_restore
remote_ssh_reverse
remote_ssh_close

Package commands are package-manager aware on the agent. OpenWrt 25.12+ uses apk; older releases usually use opkg. Legacy opkg_* command names are still accepted for compatibility, but the UI uses pkg_*.

UCI Commands

UCI commands are queued through the same command endpoint:

POST /api/devices/{device_id}/commands
Authorization: Bearer <operator-api-token>
Content-Type: application/json

Show a config:

{
  "type": "uci_show",
  "args": {"config": "network"}
}

Create a backup:

{
  "type": "uci_backup",
  "args": {"config": "network"}
}

Preview a value without leaving staged changes:

{
  "type": "uci_preview",
  "args": {
    "config": "network",
    "section": "lan",
    "option": "ipaddr",
    "value": "192.168.1.1"
  }
}

Stage a value:

{
  "type": "uci_set",
  "args": {
    "config": "network",
    "section": "lan",
    "option": "ipaddr",
    "value": "192.168.1.1",
    "commit": "false"
  }
}

Commit or revert staged changes:

{"type": "uci_commit", "args": {"config": "network"}}

{"type": "uci_revert", "args": {"config": "network"}}

Commit with connectivity confirmation:

{
  "type": "uci_commit_confirmed",
  "args": {"config": "network", "confirm_seconds": "15"}
}

The agent commits, waits, checks server reachability, and restores the latest local backup if the server is unreachable.

uci_preview includes a DIFF section when the router has the diff command available. It still returns CHANGE, BACKUP, BEFORE, and AFTER sections for routers without diff.

Restore the latest local backup captured by uci_backup, uci_preview, or uci_set:

{"type": "uci_restore", "args": {"config": "network"}}

The MVP agent only allows these UCI config packages:

network
wireless
dhcp
firewall
system

The MVP UI exposes presets for:

LAN IP: network.lan.ipaddr
hostname: system.@system[0].hostname
Wi-Fi SSID: wireless.@wifi-iface[0].ssid
Wi-Fi password: wireless.@wifi-iface[0].key
LAN DHCP toggle: dhcp.lan.ignore

Sensitive command output keys are redacted before storage and display. Current redaction targets include:

private_key
password
passwd
secret
psk
token

Remote Sessions

Remote sessions create a short-lived SSH reverse tunnel command for the agent.

POST /api/devices/{device_id}/remote-sessions
Authorization: Bearer <operator-api-token>
Content-Type: application/json

Request:

{
  "target": "ssh",
  "server_host": "10.10.10.2",
  "server_port": 22,
  "remote_port": 22022,
  "local_port": 22,
  "luci_scheme": "https",
  "duration_seconds": 900
}

Response:

{
  "id": "ras_...",
  "device_id": "dev_...",
  "target": "ssh",
  "status": "queued",
  "server_host": "10.10.10.2",
  "server_port": 22,
  "remote_port": 22022,
  "luci_port": 22122,
  "luci_scheme": "https",
  "local_host": "127.0.0.1",
  "local_port": 22,
  "command_id": "cmd_...",
  "created_at": "2026-06-01T12:00:00Z",
  "expires_at": "2026-06-01T12:15:00Z"
}

List sessions:

GET /api/devices/{device_id}/remote-sessions?limit=25
Authorization: Bearer <operator-api-token>

Close a session and queue tunnel termination on the agent:

POST /api/devices/{device_id}/remote-sessions/{session_id}/close
Authorization: Bearer <operator-api-token>

Open LuCI for an active session through the authenticated RMM proxy:

GET /luci/{device_id}/{session_id}/  # legacy lab-only compatibility route

Create Bulk Command

POST /api/devices/bulk-commands
Authorization: Bearer <operator-api-token>
Content-Type: application/json

Request:

{
  "device_ids": ["dev_..."],
  "type": "ping",
  "args": {"target": "1.1.1.1"}
}

The server creates one command per unique device id.

List Device Commands

GET /api/devices/{device_id}/commands?limit=50
Authorization: Bearer <operator-api-token>

Response:

{
  "commands": [
    {
      "id": "cmd_...",
      "device_id": "dev_...",
      "type": "ping",
      "args": {"target": "1.1.1.1"},
      "status": "completed",
      "result": {},
      "output": "PING ...",
      "exit_code": 0,
      "attempt_count": 1,
      "max_attempts": 3,
      "created_at": "2026-06-01T12:00:00Z",
      "expires_at": "2026-06-02T12:00:00Z",
      "claimed_at": "2026-06-01T12:00:01Z",
      "completed_at": "2026-06-01T12:00:03Z",
      "expired_at": null
    }
  ]
}

Command lifecycle defaults:

new commands expire after 24 hours;
claimed commands are returned to queued after the server-side claim timeout while attempts remain;
claimed commands transition to expired after max_attempts is reached;
expired and cancelled commands no longer accept agent results.

Get Command

GET /api/devices/{device_id}/commands/{command_id}
Authorization: Bearer <operator-api-token>

Cancel Command

POST /api/devices/{device_id}/commands/{command_id}/cancel
Authorization: Bearer <operator-api-token>

Only queued and claimed commands can transition to cancelled.

List Audit Events

GET /api/audit-events?device_id=dev_...&limit=50
Authorization: Bearer <operator-api-token>

Response:

{
  "audit_events": [
    {
      "id": "aud_...",
      "actor": "operator",
      "action": "command.create",
      "device_id": "dev_...",
      "command_id": "cmd_...",
      "details": {"type": "ping"},
      "created_at": "2026-06-01T12:00:00Z"
    }
  ]
}

11 KiB Raw Blame History

API

Operator Authentication

Users and enrollment grants

Health

Agent Enrollment

Agent Heartbeat

Agent Next Command

Command Result

List Devices

Get Device

Update Device Fleet Metadata

Metrics History

Device Alerts

Acknowledge Alert

Create Command

UCI Commands

Remote Sessions

Create Bulk Command

List Device Commands

Get Command

Cancel Command

List Audit Events

11 KiB

Raw Blame History