OpenWrt
OpenWrt API credentials setup: connect through the legacy luci-mod-rpc JSON-RPC API on a compatible OpenWrt release, using its root-only session behind restricted HTTPS.
On this page
OpenWrt API credentials permissions
- Credential type
- Legacy LuCI root login
- Preview access
- Legacy LuCI JSON-RPC root session with full router-configuration access
- Apply access
- The same unscoped root session; luci-mod-rpc has no read/write permission separation
- API endpoint
- You provide a public API endpoint.
Additional access
DNSControl id
{
"TYPE": "OPENWRT"
}Create credentials
Connect through the legacy luci-mod-rpc JSON-RPC API on a compatible OpenWrt release, using its root-only session behind restricted HTTPS.
Access you'll grant
Legacy LuCI JSON-RPC root session with full router-configuration access
The same unscoped root session; luci-mod-rpc has no read/write permission separation
Before you start
- An OpenWrt release/feed that still provides luci-mod-rpc; LuCI upstream removed the package on 2026-08-07.
- Root shell access and a strong root password. The legacy endpoint does not support a scoped rpcd ACL user.
- A public hostname with trusted TLS and a firewall or reverse proxy restricted to our egress IP.
Setup steps
0 of 6 done
Check package compatibility
Refresh the package index and confirm
luci-mod-rpcappears in the feed before proceeding. If it is absent, this connector cannot support that build: do not substitute the modern/ubusendpoint, because the adapter calls/cgi-bin/luci/rpc/*.Check the feedopkg update opkg list luci-mod-rpcInstall the legacy RPC module
Install
luci-mod-rpcfrom the release's signed feed and restart uHTTPd so the auth and uci JSON-RPC routes are registered.Install and restartopkg install luci-mod-rpc /etc/init.d/uhttpd restartSet a strong root password
The final upstream module hard-codes the RPC route's
sysauthuser toroot; rpcd login sections and fine-grained ACL groups do not scope this legacy API. Set a unique root password and treat it as a full-router credential.Change root passwordpasswd rootPublish only the RPC paths over HTTPS
Use a reverse proxy with a publicly trusted certificate and allow only
our egress IPto/cgi-bin/luci/rpc/authand/cgi-bin/luci/rpc/uci; avoid exposing the general LuCI UI. DNSMigrator calls over the public Internet. Its SSRF guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses, validates every DNS answer, and pins one validated IP.Required auth path/cgi-bin/luci/rpc/authRequired UCI path/cgi-bin/luci/rpc/uciTest the authentication route
Request a session token through the public endpoint. A JSON response with a non-empty
resultconfirms the legacy route and root password; avoid leaving the real password in shared shell history.JSON-RPC logincurl --fail-with-body https://router.example.com/cgi-bin/luci/rpc/auth --data '{"id":1,"method":"login","params":["root","<root-password>"]}'Enter the LuCI connection
Set Router URL to the public HTTPS origin, Username to
root, and Password to the root password. A URL containing/cgi-bin/luciis accepted and normalized to the origin. Check access, then review the dnsmasq-derived zones before applying.Router URLhttps://router.example.com
Troubleshooting
luci-mod-rpc is absent from the feed
LuCI removed it from upstream on 2026-08-07. Use a supported released feed that still carries the package or choose another source; current HTTP ubus is not implemented by this adapter.
404 from /cgi-bin/luci/rpc/auth
Confirm luci-mod-rpc is installed for this exact firmware architecture/feed and restart uhttpd. A modern /ubus endpoint does not satisfy this route.
403 or an empty login result
Use username root, verify the root password locally, and make sure the proxy preserves POST bodies and the auth query parameter on UCI calls.
The check passes but records do not resolve
The adapter writes dnsmasq sections in /etc/config/dhcp. Inspect dnsmasq logs and configuration, and remember that all managed records use the router's global behavior with a reported TTL of 300 seconds.
Official documentation
- LuCI: legacy JSON-RPC guide
- LuCI: luci-mod-rpc removal
- OpenWrt: uHTTPd webserver
- DNSControl: OpenWrt provider
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| Router URLurl | Required | Public trusted-HTTPS origin for LuCI. DNSMigrator appends /cgi-bin/luci/rpc itself. |
| Usernameusername | Required | Use root. The legacy luci-mod-rpc controller hard-codes root for authenticated RPC libraries. |
| Passwordpassword | Required | The OpenWrt root password. This is an unscoped full-router credential, not an API token. |
Capabilities
- Create zones
- No
- List zones
- Yes
- DNSSEC
- Not available through this connection
- Minimum TTL
- 300 seconds
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- MX
- SRV
Caveats
- Routers usually sit on a private network; we refuse private and internal addresses by design, so LuCI must be exposed publicly over HTTPS with a trusted certificate (ideally allow-listed to our egress IPs).
- dnsmasq local records have no per-record TTL, so every record is reported and written with a fixed TTL of 300 seconds.
- Records live in one flat list on the router, so a zone is simply the set of names under that domain; wildcard CNAMEs, null MX and null-target SRV records are not supported.
Troubleshooting
- luci-mod-rpc is absent from the feed
- LuCI removed it from upstream on 2026-08-07. Use a supported released feed that still carries the package or choose another source; current HTTP ubus is not implemented by this adapter.
- 404 from /cgi-bin/luci/rpc/auth
- Confirm luci-mod-rpc is installed for this exact firmware architecture/feed and restart uhttpd. A modern /ubus endpoint does not satisfy this route.
- 403 or an empty login result
- Use username root, verify the root password locally, and make sure the proxy preserves POST bodies and the auth query parameter on UCI calls.
- The check passes but records do not resolve
- The adapter writes dnsmasq sections in /etc/config/dhcp. Inspect dnsmasq logs and configuration, and remember that all managed records use the router's global behavior with a reported TTL of 300 seconds.