rmm-openwrt/docs/keendns.md

RMM device names (KeenDNS-like cloud mode)

The first implementation uses cloud mode: every router receives a unique name such as office.routers.example.com, while DNS points all names to the RMM reverse proxy. The router itself keeps an outbound reverse SSH tunnel, so no public WAN address or inbound router firewall rule is required.

Request flow

1. A user creates a 15-minute, one-time enrollment grant in the RMM UI.
2. The OpenWrt agent consumes the grant and becomes owned by that user.
3. RMM assigns the requested DNS label, or generates one from the hostname.
4. The user opens a temporary LuCI tunnel and asks RMM for an access link.
5. The link is valid for 60 seconds and exchanges itself for a host-only cookie on the router subdomain. The control-panel cookie is never sent to that subdomain.

DNS

Create a wildcard record for the device domain:

*.routers.example.com.  A     203.0.113.10
*.routers.example.com.  AAAA  2001:db8::10   # only when IPv6 reaches the proxy

The wildcard target must be the public address of the reverse proxy, not a router WAN address. Keep the control panel on a separate host, for example rmm.example.com.

Wildcard TLS

Public ACME wildcard certificates require DNS-01 validation. Obtain a certificate for *.routers.example.com through your DNS provider or a Caddy build with that provider's DNS module. Store the resulting certificate and key outside Git, set:

RMM_DEVICE_DOMAIN=routers.example.com
RMM_TUNNEL_PUBLIC_HOST=rmm.example.com
RMM_TUNNEL_PUBLIC_PORT=2222
RMM_WILDCARD_CERT_PATH=./secrets/routers-wildcard.crt
RMM_WILDCARD_KEY_PATH=./secrets/routers-wildcard.key

Then validate and start the overlays:

docker compose -f compose.yaml -f compose.proxy.yaml -f compose.keendns.yaml config
docker compose -f compose.yaml -f compose.proxy.yaml -f compose.keendns.yaml up -d --build

RMM_TUNNEL_PUBLIC_HOST is the public address reached by the router's outbound SSH connection. It defaults to the hostname from RMM_PUBLIC_URL; set it explicitly when the tunnel uses another hostname. RMM_TUNNEL_PUBLIC_PORT must match the public port published for tunnel-ssh (2222 by default).

The operator UI uses /api/devices/{id}/cloud-access as a single cloud-access flow. It reuses an existing healthy tunnel, waits while a new tunnel starts, and distinguishes an offline router from a tunnel that never became reachable. Host, ports, and LuCI scheme remain available only under the expert settings.

Do not enable RMM_ALLOW_LEGACY_LUCI_PROXY in production. It exists only for migration from the old same-origin /luci/... route.

Cloud-only addressing

Device names always resolve to the RMM reverse proxy. The agent never discovers or publishes the router's public WAN addresses, and users do not need inbound firewall rules. Legacy direct-DNS database tables are retained only for non-destructive upgrades and are not exposed through the API or populated for new devices.