libreCMC/package/luci/documentation/JsonRpcHowTo.md

LuCI provides some of its libraries to external applications through a JSON-RPC API. This Howto shows how to use it and provides information about available functions.

Basics

LuCI comes with an efficient JSON De-/Encoder together with a JSON-RPC-Server which implements the JSON-RPC 1.0_' and 2.0 (partly) specifications. The LuCI JSON-RPC server offers several independent APIs. Therefore you have to use '_different URLs for every exported library. Assuming your LuCI-Installation can be reached through /cgi-bin/luci' any exported library can be reached via '''/cgi-bin/luci/rpc/''LIBRARY.

Authentication

Most exported libraries will require a valid authentication to be called with. If you get an HTTP 403 Forbidden' status code you are probably missing a valid authentication token. To get such a token you have to call the function '''login''' of the RPC-Library '''auth'''. Following our example from above this login function would be provided at '/cgi-bin/luci/rpc/auth. The function accepts 2 parameters: username and password (of a valid user account on the host system) and returns an authentication token.

If you want to call any exported library which requires an authentication token you have to append it as an URL parameter auth''''' to the RPC-Server URL. So instead of calling '''/cgi-bin/luci/rpc/''LIBRARY''''' you have to call '''/cgi-bin/luci/rpc/''LIBRARY''?auth=''TOKEN.

If your JSON-RPC client is Cookie-aware (like most browsers are) you will receive the authentication token also with a session cookie and probably don't have to append it to the RPC-Server URL.

Exported Libraries

uci

The UCI-Library /rpc/uci offers functionality to interact with the Universal Configuration Interface. Exported Functions:

• (string) add(config, type)
• (integer) apply(config)
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.changes (object) changes([config])]
• (boolean) commit(config)
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.delete (boolean) delete(config, section[, option])]
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.delete_all (boolean) delete_all(config[, type])]
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.foreach (array) foreach(config[, type])]
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.get (mixed) get(config, section[, option])]
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.get_all (object) get_all(config[, section])]
• [http://luci.subsignal.org/api/luci/modules/luci.model.uci.html#Cursor.get (mixed) get_state(config, section[, option])]
• (boolean) revert(config)
• (name) section(config, type, name, values)
• (boolean) set(config, section, option, value)
• (boolean) tset(config, section, values)

uvl

The UVL-Library /rpc/uvl offers functionality to validate UCI files and get schemes describing UCI files. Exported Functions:

• (array) get_scheme(scheme)
• (array) validate(config, section, option)
• (array) validate_config(config)
• (array) validate_section(config, section)
• (array) validate(config, section, option)

fs

The Filesystem library /rpc/fs offers functionality to interact with the filesystem on the host machine. Exported Functions:

• Complete luci.fs library Note: All functions are exported as they are except for readfile'' which encodes its return value in base64 and ''writefile'' which only accepts base64 encoded data as second argument. Note that both functions will only be available when the ''luasocket packet is installed on the hostsystem.

sys

The System library /rpc/sys offers functionality to interact with the operating system on the host machine. Exported Functions:

• Complete luci.sys library
• Complete luci.sys.group library with prefix group.
• Complete luci.sys.net library with prefix net.
• Complete luci.sys.process library with prefix process.
• Complete luci.sys.user library with prefix user.
• Complete luci.sys.wifi library with prefix wifi.

ipkg

The IPKG library /rpc/ipkg offers functionality to interact with the package manager (IPKG or OPKG) on the host machine. Exported Functions:

• Complete luci.model.ipkg library