ubus — IPC Message Bus

OpenWrt’s Unix domain socket IPC bus: architecture, CLI usage, and API overview.

ubus is OpenWrt’s inter-process communication (IPC) framework. It provides a lightweight message bus over Unix domain sockets, allowing daemons and system components to expose services and communicate without direct dependencies on each other.

Architecture

ubus consists of two main components:

Component	Package	Description
ubusd	ubusd	The central broker daemon. All IPC traffic passes through it. Runs as the ubus user (UID 81).
libubus	libubus	Client library for C programs. Provides the API to connect, register objects, and invoke methods.
ubus	ubus	Command-line utility to interact with the bus.
libubus-lua	libubus-lua	Lua bindings for libubus.

ubusd listens on a Unix socket (by default /var/run/ubus/ubus.sock) and routes messages between connected clients.

Object and Method Model

ubus uses an object/method model:

• A daemon registers one or more named objects on the bus (e.g., system, network.interface.lan).
• Each object exposes a set of named methods with typed input/output parameters.
• Other processes call those methods or subscribe to event notifications.

All data is encoded using blobmsg (a binary/JSON serialization format from libubox).

CLI Reference

List Objects

# List all registered objects
ubus list

# List objects with their method signatures
ubus list -v

# List a specific object
ubus list network.interface.lan

Call Methods

# Call a method on an object (params are optional JSON)
ubus call <object> <method> ['{"key":"value"}']

# Examples:
ubus call system board
ubus call system info
ubus call network.interface.lan status
ubus call service list

Events

# Subscribe to all events (Ctrl+C to stop)
ubus listen

# Subscribe to events matching a pattern
ubus listen 'network.*'

# Broadcast an event with optional JSON data
ubus send myapp.event '{"status":"ready"}'

Wait for Object

# Block until an object appears on the bus (timeout in ms)
ubus wait_for network.interface.lan
ubus wait_for -t 5000 network.interface.wan

Usage Examples

Get Board Information

$ ubus call system board
{
    "kernel": "6.12.10",
    "hostname": "OpenWrt",
    "system": "Atheros AR9344 rev 2",
    "model": "TP-Link Archer C7 v2",
    "board_name": "tplink,archer-c7-v2",
    "rootfs_type": "squashfs"
}

Get Interface Status

$ ubus call network.interface.lan status
{
    "up": true,
    "pending": false,
    "available": true,
    "proto": "static",
    "ipv4-address": [ { "address": "192.168.1.1", "mask": 24 } ],
    "device": "br-lan"
}

List Running Services

$ ubus call service list
{
    "dnsmasq": { "instances": { "instance1": { "running": true, "pid": 1234 } } },
    "dropbear": { "instances": { "instance1": { "running": true, "pid": 1235 } } }
}

Writing a ubus Client in Shell

Shell scripts can use the ubus CLI with JSON output parsed by jsonfilter (from the jsonfilter package):

#!/bin/sh
HOSTNAME=$(ubus call system board | jsonfilter -e '@.hostname')
echo "Running on: $HOSTNAME"

Writing a ubus Client in C

A minimal C client using libubus:

#include <libubus.h>
#include <libubox/blobmsg_json.h>

static struct ubus_context *ctx;

static void result_handler(struct ubus_request *req,
                            int type, struct blob_attr *msg)
{
    char *json = blobmsg_format_json_indent(msg, true, 0);
    printf("%s\n", json);
    free(json);
}

int main(void)
{
    uint32_t id;
    ctx = ubus_connect(NULL); /* NULL = default socket path */
    ubus_lookup_id(ctx, "system", &id);
    ubus_invoke(ctx, id, "board", NULL, result_handler, NULL, 3000);
    ubus_free(ctx);
    return 0;
}

The ubus socket path defaults to /var/run/ubus/ubus.sock. Earlier OpenWrt versions used /var/run/ubus.sock. Pass the path explicitly with ubus -s <path> if needed.