saltext.uci_ubus._internal.rpc

JSON-RPC client for the OpenWrt ubus API.

Pure Python, no Salt dependency. Handles session authentication, token refresh, and ubus method dispatch over HTTP or HTTPS (auto-detected).

exception saltext.uci_ubus._internal.rpc.UbusError(code, message=None)[source]

Raised when a ubus call returns a non-zero status code.

exception saltext.uci_ubus._internal.rpc.JsonRpcError(code, message)[source]

Raised when the JSON-RPC envelope contains an error.

class saltext.uci_ubus._internal.rpc.UbusRpcClient(host, username, password, port=None, scheme=None, verify_ssl=False, server_name=None, timeout=30, session_timeout=None)[source]

Client for the OpenWrt ubus JSON-RPC API.

Parameters:

  • host – Device hostname or IP address.

  • username – rpcd login username.

  • password – rpcd login password.

  • port – Port number. Omit to auto-detect (default).

  • scheme – URL scheme, "https" or "http". Omit to auto-detect (default). Discovery explicitly handles: stock OpenWrt uhttpd (plain HTTP on 80), and a same-origin redirect to a TLS-terminating reverse proxy (e.g. Caddy with ACME, typically HTTPS on 443) — since uhttpd serves both LuCI and /ubus on the same listener, fronting one fronts the other. Anything past that (nonstandard ports, a proxy in front of a different backend, multi-hop redirects) is out of scope for discovery — set scheme and port explicitly instead.

  • verify_ssl – Whether to verify the TLS certificate (default False because OpenWrt uses self-signed certs by default). Set to True when the target has a CA-signed cert (e.g. Caddy with ACME).

  • server_name – Override TLS SNI and the HTTP Host header to this name instead of host. Needed when host is a generic alias used only to resolve the device’s address, but a reverse proxy in front of it (e.g. Caddy) routes by a specific domain name tied to its certificate — both its TLS layer (SNI) and its HTTP layer (Host header) need that real name to find the right site, independent of whichever name got you to its IP.

  • timeout – HTTP request timeout in seconds.

  • session_timeout – rpcd session timeout in seconds, passed to session login. rpcd’s compiled-in default is 300s.

login()[source]

Authenticate and store the session token.

Returns the session token string.

property session_timeout

Return the session timeout reported by rpcd at login.

call(ubus_object, ubus_method, params=None)[source]

Call a ubus method and return the result data.

Parameters:

  • ubus_object – ubus object path (e.g., “uci”, “system”).

  • ubus_method – Method name (e.g., “get”, “board”).

  • params – Dict of method parameters (default empty).

Returns:

The result data dict, or None for methods that return no body.

Raises:

  • UbusError – If the ubus status code is non-zero.

  • JsonRpcError – If the JSON-RPC envelope has an error.