This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 24 24" class="iconify mr-1" data-icon="mdi:arrow-left" style="vertical-align: -0.125em; transform: rotate(360deg);"><path d="M20 11v2H8l5.5 5.5l-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5L8 11h12z" fill="currentColor"></path></svg>====== ubus (OpenWrt micro bus architecture) ====== See also: [[https://hackmd.io/@rYMqzC-9Rxy0Isn3zClURg/H1BY98bRw|What is UBUS?]] To provide [[wp>Inter-process_communication|Inter-process communication]] between various daemons and applications in OpenWrt a project called ''ubus'' has been developed. It consists of several parts including daemon, library and some extra helpers. The heart of this project is the ''ubusd'' daemon. It provides an interface for other daemons to register themselves as well as sending messages. For those curious, this interface is implemented using Unix sockets and it uses [[wp>Type-length-value|TLV (type-length-value)]] messages. To simplify development of software using ''ubus'' (connecting to it) a library called ''libubus'' has been created. Every daemon registers a set of paths under a specific namespace. Every path can provide multiple procedures with any number of arguments. Procedures can reply with a message. The code is published under [[wp>GNU_Lesser_General_Public_License|LGPL 2.1 license]] and can be found via git at [[https://git.openwrt.org/project/ubus.git]]. ===== Command-line ubus tool ===== The ''ubus'' command line tool allows to interact with the ''ubusd'' server (with all currently registered services). It's useful for investigating/debugging registered namespaces as well as writing shell scripts. For calling procedures with parameters and returning responses it uses the user-friendly JSON format. Below is an explanation of its commands. ==== Help output ==== <code> # ubus Usage: ubus [<options>] <command> [arguments...] Options: -s <socket>: Set the unix domain socket to connect to -t <timeout>: Set the timeout (in seconds) for a command to complete -S: Use simplified output (for scripts) -v: More verbose output -m <type>: (for monitor): include a specific message type (can be used more than once) -M <r|t> (for monitor): only capture received or transmitted traffic Commands: - list [<path>] List objects - call <path> <method> [<message>] Call an object method - listen [<path>...] Listen for events - send <type> [<message>] Send an event - wait_for <object> [<object>...] Wait for multiple objects to appear on ubus - monitor Monitor ubus traffic </code> ==== list ==== To find out which services are currently running on the bus simply use the ''ubus list'' command. This will show a complete list of all namespaces registered with the RPC server: <code> # ubus list dhcp dnsmasq file iwinfo log luci luci-rpc network network.device network.interface network.interface.lan network.interface.loopback network.interface.wan network.interface.wan6 network.rrdns network.wireless service session system uci </code> You can filter the list by specifying a service path: <code> # ubus list network.interface.* network.interface.lan network.interface.loopback network.interface.wan network.interface.wan6 </code> To find out which procedures/methods and their argument signatures a specific service provides add ''-v'' in addition to the namespace path: <code> # ubus -v list network.interface.lan 'network.interface.lan' @099f0c8b "up": { } "down": { } "status": { } "prepare": { } "add_device": { "name": "String" } "remove_device": { "name": "String" } "notify_proto": { } "remove": { } "set_data": { } </code> ==== call ==== Calls a given procedure within a given namespace and optionally pass arguments to it: <code bash> # ubus call network.interface.wan status { "up": true, "pending": false, "available": true, "autostart": true, "uptime": 86017, "l3_device": "eth1", "device": "eth1", "address": [ { "address": "178.25.65.236", "mask": 21 } ], "route": [ { "target": "0.0.0.0", "mask": 0, "nexthop": "178.25.71.254" } ], "data": { } } </code> The arguments must be a valid JSON string, with keys and values set according to the function signature: <code bash> # ubus call network.device status '{ "name": "eth0" }' { "type": "Network device", "up": true, "link": true, "mtu": 1500, "macaddr": "c6:3d:c7:90:aa:da", "txqueuelen": 1000, "statistics": { "collisions": 0, "rx_frame_errors": 0, "tx_compressed": 0, "multicast": 0, "rx_length_errors": 0, "tx_dropped": 0, "rx_bytes": 0, "rx_missed_errors": 0, "tx_errors": 0, "rx_compressed": 0, "rx_over_errors": 0, "tx_fifo_errors": 0, "rx_crc_errors": 0, "rx_packets": 0, "tx_heartbeat_errors": 0, "rx_dropped": 0, "tx_aborted_errors": 0, "tx_packets": 184546, "rx_errors": 0, "tx_bytes": 17409452, "tx_window_errors": 0, "rx_fifo_errors": 0, "tx_carrier_errors": 0 } } </code> ==== listen ==== Set up a listening socket and observe incoming events: <code bash> # ubus listen & # ubus call network.interface.wan down { "network.interface": { "action": "ifdown", "interface": "wan" } } # ubus call network.interface.wan up { "network.interface": { "action": "ifup", "interface": "wan" } } { "network.interface": { "action": "ifdown", "interface": "he" } } { "network.interface": { "action": "ifdown", "interface": "v6" } } { "network.interface": { "action": "ifup", "interface": "he" } } { "network.interface": { "action": "ifup", "interface": "v6" } } </code> ==== send ==== Send an event notification: <code bash> # ubus listen & # ubus send foo '{ "bar": "baz" }' { "foo": { "bar": "baz" } } </code> ===== Access to ubus over HTTP ===== There is an ''uhttpd'' plugin called ''uhttpd-mod-ubus'' that allows ''ubus'' calls using HTTP protocol. For example this is used in [[docs:techref:luci2|LuCI2]]. Requests have to be sent to the ''/ubus'' URL (unless changed by ''ubus_prefix'' option) using the ''POST'' method. This interface uses [[https://www.jsonrpc.org/specification|jsonrpc v2.0]] There are a few steps that you will need to understand. If uhttpd-mod-ubus is installed, uhttpd automatically configures it and enables it, by default at /ubus, but you can [[docs:guide-user:services:webserver:uhttpd|configure this]] Also if you want to use the ''/ubus'' directly from a web client you need to specify ''ubus_cors=1'' option. If you are using Nginx then you may try [[https://github.com/Ansuel/nginx-ubus-module|nginx-ubus-module]]. For other web servers like Lighttpd you may use the [[https://github.com/yurt-page/cgi-ubus|ubus as CGI]]. See the [[https://documenter.getpostman.com/view/5972215/TVzNHeej#154b5d84-4065-4887-a5a8-c1f3b51fe9a6|Postman collection]] with some examples of calling UBUS over HTTP ==== ACLs ==== While logged in via ssh, you have direct, full access to ubus. When you're accessing the ''/ubus'' url in uhttpd however, uhttpd first queries whether your call is allowed, and whoever is providing the ubus ''session.*'' namespace is in charge of implementing the access control: <code bash> ubus call session access '{ "ubus_rpc_session": "xxxxx", "object": "requested-object", "function": "requested-method" }' </code> This happens to be ''rpcd'' at the moment, with the ''http-json'' interface, for friendly operation with browser code, but this is just one possible implementation. Because we're using rpcd to implement the ACLs at this time, this allows/requires (depending on your point of view) ACLs to be configured in ''/usr/share/rpcd/acl.d/*.json''. The __names__ of the files in ''/usr/share/rpcd/acl.d/*.json'' don't matter, but the top level keys define roles. The default ACL, listed below, __only__ defines the login methods, so you can log in, but you still wouldn't be able to do anything. <code yaml> { "unauthenticated": { "description": "Access controls for unauthenticated requests", "read": { "ubus": { "session": [ "access", "login" ] } } } } </code> An example of a complicated ACL, allowing quite fine grained access to different ubus modules and methods is [[https://git.openwrt.org/?p=project/luci2/ui.git;a=blob;f=luci2/share/acl.d/luci2.json|available in the Luci2 project]] An example of a "security is for suckers" config, where a ''superuser'' ACL group is defined, allowing unrestricted access to everything, is shown below. This illustrates the usage of ''*'' definitions in the ACLs, but keep reading for better examples. Placing this file in ''/usr/share/rpcd/acl.d/superuser.json'' will help you move forward to the next steps. <code yaml> { "superuser": { "description": "Super user access role", "read": { "ubus": { "*": [ "*" ] }, "uci": [ "*" ], "file": { "*": ["*"] } }, "write": { "ubus": { "*": [ "*" ] }, "uci": [ "*" ], "file": { "*": ["*"] }, "cgi-io": ["*"] } } } </code> Below is an example of an ACL definition that only allows access to some specific ubus modules, rather than unrestricted access to everything. <code yaml> { "lesssuperuser": { "description": "not quite as super user", "read": { "ubus": { "file": [ "*" ], "log": [ "*" ], "service": [ "*" ], }, }, "write": { "ubus": { "file": [ "*" ], "log": [ "*" ], "service": [ "*" ], }, } } } </code> **Note:** Before we leave this section, you may have noticed that there's both a ''ubus'' and a ''uci'' section, even though ubus has a uci method. The ''uci'' scope is used for the [[docs:techref:uci|uci api]] provided by rpcd to allow defining per-file permissions because using the ubus scope you can only say ''uci set'' is allowed or not, but not specify that it is allowed to e.g. modify ''/etc/config/system'' but not ''/etc/config/network''. If your application/ACL doesn't need UCI access, you can just leave out the UCI section altogether. ==== Authentication ==== Now that we have an ACL that allows operations beyond just logging in, we can actually try this out. As mentioned, ''rpcd'' is handling this, so you need an entry in ''/etc/config/rpcd'' <code bash> config login option username 'root' option password '$p$root' list read '*' list write '*' config login option username 'blaer' option password '$p$blaer' list read lesssuperuser list write lesssuperuser </code> The ''$p'' magic means to look in ''/etc/shadow'' and the ''$root'' part means to use the password for the root user in that file. The list of read and write sections, those map ACL roles to user accounts. So ''list read *'' means the read credential of any group listed in the merged ACLs. Write implies read. You can also use ''$1$<hash>'' which is a [[wp>Crypt_(Unix)|crypt]] hash, using SHA1, exactly as used in ''/etc/shadow''. You can generate these with ''uhttpd -m secret''. ==== Session management ==== To login and receive a session id: <code bash> $ curl -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "call", "params": [ "00000000000000000000000000000000", "session", "login", { "username": "root", "password": "secret" } ] }' http://your.server.ip/ubus {"jsonrpc":"2.0","id":1,"result":[0,{"ubus_rpc_session":"c1ed6c7b025d0caca723a816fa61b668","timeout":300,"expires":299,"acls":{"access-group":{"superuser":["read","write"],"unauthenticated":["read"]},"ubus":{"*":["*"],"session":["access","login"]},"uci":{"*":["read","write"]}},"data":{"username":"root"}}]} </code> The session id ''00000000000000000000000000000000'' (32 zeros) is a special null-session which only has the rights from the ''unauthenticated'' access group, only enabling the ''session.login'' ubus call. A session has a timeout that can be specified when you login, otherwise it defaults to 5 minutes. If you ever receive a response like ''{"jsonrpc":"2.0","id":1,"result":[6]}'', that is a valid jsonrpc response, 6 is the ubus code for ''UBUS_STATUS_PERMISSION_DENIED'' (you'll get this if you try and login before setting up the ''superuser'' file, or any file that gives you more rights than just being allowed to attempt logins). To list all active sessions, try ''ubus call session list'' The session timeout is automatically reset on every use. There are plans to use these sessions even for luci1, but at present, if you use this interface in a luci1 environment, you'll need to manage sessions yourself. ==== Actually making calls ==== Now that you have a ''ubus_rpc_session'' you can make calls, based on your ACLs and the available ubus services. ''ubus -v list'' is your primary documentation on what can be done, but see the rest of this page for more information. For example, ''ubus -v list file'' returns <code javascript> 'file' @ff0a2c92 "read":{"path":"String","base64":"Boolean"} "write":{"path":"String","data":"String","append":"Boolean","mode":"Integer","base64":"Boolean"} "list":{"path":"String"} "stat":{"path":"String"} "md5":{"path":"String"} "exec":{"command":"String","params":"Array","env":"Table"} </code> The RPC-JSON container format is: <code javascript> { "jsonrpc": "2.0", "id": <unique-id-to-identify-request>, "method": "call", "params": [ <ubus_rpc_session>, <ubus_object>, <ubus_method>, { <ubus_arguments> } ] } </code> The "id" key is merely echo'ed by the server, so it needs not be strictly unique, it's mainly intended for client software to easily correlate responses to previously made requests. Its type is either a string or a number, so it can be an UUID, sha1 hash, md5 sum, sequence counter, unix timestamp, etc. An example request to read a file ''/etc/board.json'' which contains device info would be: <code bash> $ curl -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "call", "params": [ "c1ed6c7b025d0caca723a816fa61b668", "file", "read", { "path": "/etc/board.json" } ] }' http://your.server.ip/ubus {"jsonrpc":"2.0","id":1,"result":[0,{"data":"{\n\t\"model\": {\n\t\t\"id\": \"innotek-gmbh-virtualbox\",\n\t\t\"name\": \"innotek GmbH VirtualBox\"\n\t},\n\t\"network\": {\n\t\t\"lan\": {\n\t\t\t\"ifname\": \"eth0\",\n\t\t\t\"protocol\": \"static\"\n\t\t}\n\t}\n}\n"}]} </code> Here the first param ''c1ed6c7b025d0caca723a816fa61b668'' is the ''ubus_rpc_session'' received during the login call. If you received a response like ''{"jsonrpc":"2.0","id":1,"error":{"code":-32002,"message":"Access denied"}}'' then probably your session token was expired and you need to request a new one. To beautify output you can use [[https://stedolan.github.io/jq/|jq]] utility: <code bash> curl -s -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "call", "params": [ "c1ed6c7b025d0caca723a816fa61b668", "file", "read", { "path": "/etc/board.json" } ] }' http://your.server.ip/ubus | jq { "jsonrpc": "2.0", "id": 1, "result": [ 0, { "data": "{\n\t\"model\": {\n\t\t\"id\": \"innotek-gmbh-virtualbox\",\n\t\t\"name\": \"innotek GmbH VirtualBox\"\n\t},\n\t\"network\": {\n\t\t\"lan\": {\n\t\t\t\"ifname\": \"eth0\",\n\t\t\t\"protocol\": \"static\"\n\t\t}\n\t}\n}\n" } ] } </code> In the response JSON document in the ''result[1].data'' field contains escaped JSON with the ''model'' and ''network'' objects. To fetch the concrete model name you can parse the response with the [[https://stedolan.github.io/jq/|jq]] program: <code> curl -s -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "call", "params": [ "c1ed6c7b025d0caca723a816fa61b668", "file", "read", { "path": "/etc/board.json" } ] }' http://your.server.ip/ubus | jq -r '.result[1].data' | jq .model.name "innotek GmbH VirtualBox" </code> As you can see in the example the router model is in fact just a OpenWrt runned on [[docs:guide-user:virtualization:virtualbox-vm|virtual machine in VirtualBox]]. ===== Lua module for ubus ===== This is even possible to use ''ubus'' in ''lua'' scripts. Of course it's not possible to use native libraries directly in ''lua'', so an extra module has been created. It's simply called ''ubus'' and is a simple interface between ''lua'' scripts and the ''ubus'' (it uses ''libubus'' internally). <code lua> -- Load module require "ubus" -- Establish connection local conn = ubus.connect() if not conn then error("Failed to connect to ubusd") end -- Iterate all namespaces and procedures local namespaces = conn:objects() for i, n in ipairs(namespaces) do print("namespace=" .. n) local signatures = conn:signatures(n) for p, s in pairs(signatures) do print("\tprocedure=" .. p) for k, v in pairs(s) do print("\t\tattribute=" .. k .. " type=" .. v) end end end -- Call a procedure local status = conn:call("network.device", "status", { name = "eth0" }) for k, v in pairs(status) do print("key=" .. k .. " value=" .. tostring(v)) end -- Close connection conn:close() </code> Optional arguments to ''connect()'' are a path to use for sockets (pass nil to use the default) and a per call timeout value (in milliseconds) <code lua> local conn = ubus.connect(nil, 500) -- default socket path, 500ms per call timeout </code> ===== Namespaces & Procedures ===== As explained earlier, there can be many different daemons (services) registered in ''ubus''. Below you will find a list of the most common projects with namespaces, paths and procedures they provide. **Path only contains the first context, e.g. network for network.interface.wan** ^ path ^ Description ^ Package ^ | [[docs:guide-developer:ubus:dhcp]] | dhcp server | odhcpd | | [[docs:guide-developer:ubus:file]] | file | rpcd | | [[docs:guide-developer:ubus:hostapd]] | acesspoints | wpad/hostapd | | [[docs:guide-developer:ubus:iwinfo]] | wireless informations | rpcd iwinfo | | [[docs:guide-developer:ubus:log]] | logging | procd | | [[docs:guide-developer:ubus:mdns]] | mdns avahi replacement | mdnsd | | [[docs:guide-developer:ubus:network]] | network | netifd | | [[docs:guide-developer:ubus:service]] | init/service | procd | | [[docs:guide-developer:ubus:session]] | Session management | rpcd | | [[docs:guide-developer:ubus:system]] | system misc | procd | | [[docs:guide-developer:ubus:uci]] | Unified Configuration Interface | rpcd | ==== procd ==== Project [[docs:techref:procd|procd: Procd system init and daemon management]] {{page>docs:guide-developer:ubus:system&nofooter}} {{page>docs:guide-developer:ubus:service&nofooter}} {{page>docs:guide-developer:ubus:log&nofooter}} ==== netifd ==== Project [[docs:techref:netifd|netifd: Network Interface Daemon]] {{page>docs:guide-developer:ubus:network&nofooter}} ==== rpcd ==== Project [[docs:techref:rpcd|rpcd: OpenWrt ubus RPC daemon for backend server]] is a set of small plugins providing sets of ''ubus'' procedures in separated namespaces. These plugins are not strictly related to any particular software (like ''netifd'' or ''dhcp'') so it wasn't worth it to implement them as separated projects. rpcd and the desired plugins must be available or installed via opkg. After installing remember to enable and start the service via ''service rpcd enable'' and ''service rpcd start'' . {{page>docs:guide-developer:ubus:file&nofooter}} {{page>docs:guide-developer:ubus:iwinfo&nofooter}} Always included in ''rpcd'': {{page>docs:guide-developer:ubus:session&nofooter}} {{page>docs:guide-developer:ubus:uci&nofooter}} ===== What's the difference between ubus vs dbus? ===== [[wp>D-Bus|D-Bus]] is bloated, its C API is very annoying to use and requires writing large amounts of boilerplate code. In fact, the pure C API is so annoying that its own API documentation states: "If you use this low-level API directly, you're signing up for some pain." ''ubus'' is tiny and has the advantage of being easy to use from regular C code, as well as automatically making all exported API functionality also available to shell scripts with no extra effort. ===== Examples ===== ==== FHEM ==== === User mapping === In this example we map username ''root'' to ''fhem_acl'' for [[docs:guide-user:services:automation:fhem|FHEM]] server. Edit ''/etc/config/rpcd'': <code bash /etc/config/rpcd> # /etc/config/rpcd config login option username 'root' option password '$p$root' list read '*' list write '*' config login option username 'fhem' # # '$p$<username> => reference to user passowrd on /etc/shadow # '$1$<hash>' => crypt() hash, using SHA1. generate via 'uhttpd -m fhem' # # password: fhem # option password '$1$$xEODf2fNSQ0ArfkJu4L2i1' # # map username to rpcd acl name "fhem_acl" # list read 'fhem_acl' list write '' </code> Then reload rpcd config: <code bash> uci commit rpcd </code> === User ACL === All files under ''/usr/share/rpcd/acl.d/'' will be merge by ''rpcd'' to one config file!! <code bash> ubus call hostapd.wlan0 get_clients ubus call hostapd.wlan1 get_clients </code> Example permissions to run ubus calls remote by fhem over http/json. <code yaml /usr/share/rpcd/acl.d/fhem.json> { "fhem_acl": { "description": "FHEM PRESENCE Module User.. https://github.com/janLo/OpenWRT-Wifi-Clients-POC", "read": { "ubus": { "hostapd.wlan0": [ "get_clients" ], "hostapd.wlan1": [ "get_clients" ] } } } } </code> FHEM Server - show all connected wireless clients: <code bash> $ python wifi_clients.py Usage: wifi_clients.py.orig <OpenWrt_Host> <User> <Pass> <WiFi_1> [<WiFi2> ...] $ python wifi_clients.py 192.168.1.71 fhem fhem wlan0 wlan1 c8:f6:50:e1:a9:10, 2c:f0:a2:e2:c0:15, 8c:a9:82:f1:9c:2a, 7c:c3:a1:b8:d2:1e, 64:9a:be:6a:6c:13, 00:1d:63:a3:8f:4a </code> ==== Getting firmware version ==== Get firmware version with [[https://github.com/openwrt/luci/wiki/JsonRpcHowTo|JSON RPC]]. <code bash> luci_rpc() { local LIB="${1}" local DATA="${2}" local URL="https://${HOST}/\ cgi-bin/luci/rpc/${LIB}?auth=${TOKEN}" curl -s -k -d "${DATA}" "${URL}" \ | jsonfilter -e "$['result']" } HOST="localhost" USER="root" PASS="" DATA="{ \"id\": 1, \"method\": \"login\", \"params\": [ \"${USER}\", \"${PASS}\" ] }" TOKEN="$(luci_rpc auth "${DATA}")" DATA="{ \"id\": 2, \"method\": \"exec\", \"params\": [ \"ubus call system board\" ] }" VERSION="$(luci_rpc sys "${DATA}" \ | jsonfilter -e "$['release']['version']")" echo "${VERSION}" </code> Get firmware version with ubus RPC. <code bash> ubus_rpc() { local DATA="${1}" local URL="https://${HOST}/ubus" curl -s -k -d "${DATA}" "${URL}" \ | jsonfilter -e "$['result']" } HOST="localhost" USER="root" PASS="" DATA="{ 'jsonrpc': '2.0', 'id': 1, 'method': 'call', 'params': [ '00000000000000000000000000000000', 'session', 'login', { 'username': '${USER}', 'password': '${PASS}' } ] }" SESSION="$(ubus_rpc "${DATA}" \ | jsonfilter -e "$[*]['ubus_rpc_session']")" DATA="{ 'jsonrpc': '2.0', 'id': 2, 'method': 'call', 'params': [ '${SESSION}', 'system', 'board', {} ] }" VERSION="$(ubus_rpc "${DATA}" \ | jsonfilter -e "$[*]['release']['version']")" echo "${VERSION}" </code>