Technical Report: Ubios UDAPI Server Architecture and Analysis Date: October 26, 2023 Subject: Analysis of the UDAPI (UniFi Dream API) Server in UniFi OS Target Audience: Network Administrators, DevOps Engineers, Ubiquiti Developers 1. Executive Summary The ubios-udapi-server is a critical backend service operating within the UniFi OS environment. It serves as the primary translation layer between the UniFi Network Application (Controller) and the underlying hardware drivers of Ubiquiti networking devices (Switches, Access Points, and Gateways). By implementing a standardized JSON-RPC and WebSocket API, the UDAPI server abstracts hardware complexities, enabling centralized management, real-time telemetry, and high-speed configuration deployment across the UniFi ecosystem. 2. Introduction and Background Ubiquiti Networks utilizes a proprietary architecture known as UniFi OS to power its Dream Machine (UDM, UDM-Pro, UDR), UniFi Cloud Key Gen2, and high-end Enterprise hardware. Unlike traditional standalone devices, UniFi OS runs a containerized operating system where the control plane (the Network Application) is decoupled from the data plane (the hardware switching/routing logic). The ubios-udapi-server acts as the glue in this architecture. Before the introduction of UDAPI, interaction with devices often relied on low-level system calls or custom scripts. UDAPI standardizes this into a uniform API, allowing the UniFi Network Application to manage devices regardless of the specific chipset or firmware version, provided they support the UniFi OS architecture. 3. Architectural Overview The ubios-udapi-server operates as a daemon (background service) within the UniFi OS container environment. Its architecture can be described in three distinct layers: 3.1. Transport Layer The server listens primarily on specific TCP ports (typically internal to the UniFi OS instance to prevent external tampering). It utilizes:
HTTP/HTTPS: For RESTful configuration calls and file uploads (e.g., firmware updates). WebSockets: For stateful, real-time event streaming (alerts, client associations, traffic stats). Raw Sockets: For low-level packet injection or sniffing required for Deep Packet Inspection (DPI) and Intrusion Detection Systems (IDS).
3.2. Protocol Layer UDAPI implements a JSON-RPC 2.0 compliant interface for structured command execution. This ensures that commands sent from the controller (e.g., "Change Port 5 to VLAN 20") are executed transactionally.
Message Format: JSON structures containing method , params , and id . Serialization: Google Protocol Buffers (Protobuf) may be utilized for high-throughput telemetry streams to reduce bandwidth overhead between the kernel and the control plane. ubios-udapi-server
3.3. Hardware Abstraction Layer (HAL) This is the most critical function of the UDAPI server. It translates abstract API calls into hardware-specific instructions.
Broadcom SDK Integration: On devices utilizing Broadcom switch ASICs, UDAPI communicates with the Switch Development Kit (SDK) to program VLAN tables, LAGG groups, and spanning tree protocols. Wireless Drivers: On U6/U7 Access Points, it
The Heart of UniFi OS: Understanding ubios-udapi-server In the world of Ubiquiti networking, specifically for devices running UniFi OS, the ubios-udapi-server is a critical backend component. Often operating behind the scenes, this daemon acts as the primary interface between the high-level UniFi Network application and the low-level UbiOS operating system. What is ubios-udapi-server? The ubios-udapi-server is the management engine responsible for translating configuration changes made in the UniFi Network interface into actual system states on the hardware. It handles several core functions: Provisioning : Applying firewall rules, VLAN configurations, and port settings. State Management : Monitoring the health and status of the router, including WAN failover events. API Gateway : Providing the endpoints (UDAPI) that other local services use to query or update device information. Common Role in Troubleshooting Because it is central to the device's operation, it often appears in system logs ( /var/log/messages ) when issues arise. WAN Issues : Logs frequently show ubios-udapi-server managing WAN failover transitions, marking interfaces as "up" or "down". CPU Spikes : In some firmware versions, such as certain builds of UniFi OS 5.0.x , users have reported the process entering an "ioctl polling loop," causing sustained high CPU usage (up to 70% on a single core) and significantly reduced throughput . Memory Usage : Historical reports have linked memory leaks in the server to periodic system reboots or UI crashes. Managing the Service For advanced users using SSH access, the state of the server can be inspected in /config/ubios-udapi-server/ubios-udapi-server.state . While manually stopping or modifying this service is generally discouraged—as it can "break" the router's ability to process traffic—it is a primary point of investigation for the Ubiquiti Community and support teams when diagnosing persistent connectivity "ghosts". Are you currently experiencing high CPU usage or WAN disconnections that you suspect are linked to this service? By implementing a standardized JSON-RPC and WebSocket API,
Mastering the ubios-udapi-server: The Backbone of Ubiquiti’s API Ecosystem In the rapidly evolving world of network management, automation is no longer a luxury—it is a necessity. For administrators managing fleets of Ubiquiti devices (UniFi, EdgeMAX, and UFiber), the bridge between manual configuration and programmatic control is often an unsung hero: the ubios-udapi-server . If you have ever used a third-party dashboard, integrated Ubiquiti hardware with Home Assistant, or built a custom billing portal for a WISP, you have indirectly interacted with the ubios-udapi-server . This article provides a deep dive into what this service is, how it works, how to install and configure it, and advanced use cases to unlock true network automation. What is the ubios-udapi-server? At its core, the ubios-udapi-server (UniFi OS Universal Data API Server) is a middleware daemon running on Ubiquiti’s UniFi OS consoles (like the Dream Machine Pro, Cloud Key Gen2+, or Network Video Recorders). Its primary function is to translate high-level API requests into low-level device commands. While Ubiquiti provides a public, cloud-mediated API (UniFi API), the ubios-udapi-server works locally . It listens for RESTful calls on the local loopback or LAN interface of the UniFi OS device, allowing native applications and scripts to interact with the hardware without round-tripping through Ubiquiti’s cloud. Key Functions:
Device Provisioning: Pushing SSIDs, VLANs, and firewall rules to access points and switches. State Extraction: Pulling real-time statistics (CPU load, memory, client signal strength, traffic flows). Event Subscriptions: Providing a WebSocket endpoint for real-time events (e.g., "Client connected to AP-23"). Cross-Service Integration: Bridging UniFi Network, Protect (cameras), and Access (door locks) under a single API schema.
Why Use the Local API Instead of the Cloud API? Many administrators default to Ubiquiti’s cloud API ( https://unifi.ui.com ), but the ubios-udapi-server offers distinct advantages for power users: | Feature | Cloud API | Local ubios-udapi-server | | :--- | :--- | :--- | | Latency | High (150-300ms) | Very Low (<10ms) | | Internet Dependency | Required | Not required (works offline) | | Rate Limits | Strict (120 req/min) | Configurable / None (hardware limited) | | Data Granularity | Aggregated | Raw, per-packet telemetry | | Use Case | Remote monitoring | Real-time automation & local integration | If you need to turn off a port instantly when an intrusion is detected on a local server, the ubios-udapi-server is the only viable path. Technical Architecture Understanding the stack helps in troubleshooting. The ubios-udapi-server is not a monolithic binary; it is a collection of Node.js and Go services managed by systemd on UniFi OS. The Stack: Unlike traditional standalone devices, UniFi OS runs a
UniFi OS (Podman/Docker containers): The API server runs inside a container named unifi-core . Port Binding: By default, it listens on 127.0.0.1:443 (inside the container). This is reverse-proxied to the host’s NGINX. Authentication: Uses a short-lived JWT token obtained via the local login endpoint ( /api/auth/login ). WebSocket Stream: wss://<UDM-IP>/ws/events for real-time updates.
Installation and Access Contrary to typical Linux software, you do not "install" ubios-udapi-server manually. It ships pre-installed on all UniFi OS consoles running firmware 2.x or higher. However, you must enable local API access. Step-by-Step Activation: