Skip to content

README.md

Latest commit

 

History

History
159 lines (116 loc) · 6.9 KB

README.md

File metadata and controls

159 lines (116 loc) · 6.9 KB

goubus

OpenWrt ubus Go Client

CI Status Coverage Go Report Card Go Reference

Release Go Version License Contributors

Issues Pull Requests Stars Repo Size

goubus provides an interface to interact with OpenWrt's ubus (micro bus) system, using a Profile system to support hardware-specific differences (like CMCC RAX3000M) while maintaining a consistent base implementation.

中文文档 | Examples | Documentation

Key Features

  • Device Profiles: Native support for hardware-specific dialects (e.g., CMCC RAX3000M, X86 Generic).
  • Selective Imports: Import only what you need, avoiding overhead.
  • Dual Transport: Supports both HTTP JSON-RPC (remote) and Unix Socket (local).
  • Type-Safe API: Fully typed requests and responses.
  • Context Aware: Support for context.Context cancellation and timeouts.

Installation

go get github.com/honeybbq/goubus/v2

Quick Start

1. Initialize Transport

import (
    "context"
    "github.com/honeybbq/goubus/v2"
)

ctx := context.Background()

// Remote via RPC (Requires rpcd and proper ACLs)
caller, _ := goubus.NewRpcClient(ctx, "192.168.1.1", "root", "password")

// Local via Unix Socket (Running on the device)
caller, _ := goubus.NewSocketClient(ctx, "/var/run/ubus/ubus.sock")

2. Use Device Specific Managers

Import the profile matching your hardware:

import (
    "github.com/honeybbq/goubus/v2/profiles/cmcc_rax3000m/system"
    "github.com/honeybbq/goubus/v2/profiles/cmcc_rax3000m/network"
)

// Initialize Managers
sysSvc := system.New(caller)
netSvc := network.New(caller)

// Fetch System Board Info
board, _ := sysSvc.Board(ctx)
fmt.Printf("Model: %s, Kernel: %s\n", board.Model, board.Kernel)

// Dump all network interfaces
ifaces, _ := netSvc.Dump(ctx)

3. Debugging & Logging

goubus natively supports log/slog. You can inject your own logger to see raw ubus interactions (requests and responses):

import "log/slog"

// Create a debug logger
logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))

// Inject it into the transport
caller.SetLogger(logger)

Implemented Objects

Object Description
System Board, Info, Reboot, Watchdog, Signal, Sysupgrade
Network Interface control, Device status, Routing, Namespaces
Wireless IWInfo (Scan, Assoclist), Wireless radio control
UCI Full CRUD, Commit/Rollback, State tracking
DHCP IPv4/v6 Leases, IPv6 RA, Static Lease management
Service Service lifecycle, Validation, Custom data
Session Login, Access control, Grant/Revoke
Container LxC container management, Console access
Hostapd Low-level AP management (Kick clients, Switch channels)
RPC-SYS Package management, Factory reset, Firmware validation

Project Architecture

goubus is designed with a multi-layer architecture for code reuse:

  • Core Layer (goubus/): Contains the transport implementations (HTTP RPC and Unix Socket), raw ubus message handling (blobmsg), results parsing, and error definitions.
  • Base Layer (goubus/internal/base/): Provides generic, reusable implementations for standard ubus objects (e.g., system, network, uci). This layer encapsulates the common logic that applies to most OpenWrt devices.
  • Profile Layer (goubus/profiles/): The public API entry point. Profiles (e.g., cmcc_rax3000m, generic) use Dialects to handle hardware-specific quirks (like parameter types or special method names) while exposing a consistent, high-level interface.
  • Examples & TestData (examples/, internal/testdata/): Full integration tests using real hardware data and usage examples.

Comparison

Feature HTTP (JSON-RPC) Unix Socket
Use Case Remote management On-device apps
Auth Required Not required
Performance Network overhead Low latency

Contributing & Device Support

This repository includes Profiles for RAX3000M and x86. The x86 Profile is derived from virtual machine data; given the diversity of x86 hardware and drivers, the implementation is undergoing further refinement.

Contributions of Profiles or testdata for other hardware are welcome.

How to help out

  1. Copy: Copy profiles/x86_generic to a new folder.
  2. Test: Run tests using your real hardware data to find parsing errors.
  3. Fix: Use a Dialect to handle the differences.

Guide on how to dump test data: Contributing Test Data Guide.

License

MIT License - See LICENSE file for details.

Acknowledgments

Inspired by Kubernetes client-go and moby/moby.