Skip to main content

Best — Ubios-udapi-server

The ubios-udapi-server is a core internal process used in Ubiquiti's UniFi OS devices, such as the UniFi Dream Machine (UDM), UDM Pro, and UniFi Cloud Gateways. It serves as an API server and management layer between the UniFi Network application and the underlying operating system. Core Functions

Configuration Management: It processes configuration changes from the UniFi Network UI and applies them to the system, specifically handling firewall rules, routing, and interface settings.

Internal Communication: It acts as a bridge for UDAPI (Ubiquiti Device API) requests, facilitating communication between different software components within the device.

Network Services: It manages sub-processes like udhcpc for WAN IP acquisition and handles neighbor updates and Deep Packet Inspection (DPI) stats. Common Troubleshooting Scenarios

Recent logs and community discussions highlight several performance and stability issues related to this process:

CPU and Memory Spikes: Users have reported cases where ubios-udapi-server gets stuck in polling loops, consuming over 70% of a CPU core and leading to WAN throughput collapses. Memory leaks can also occur, sometimes resulting in device reboots. Log Errors to Monitor:

Unexpected upd_neighbor(): Frequently seen in logs, often resolved by upgrading to the latest stable or release candidate firmware.

Failed to apply firewall/filter configuration: This can occur due to invalid syntax in internal system calls, such as incorrect date formats for firewall rules.

Failed to read file: Often identified as a benign error in older versions that can be safely ignored according to Ubiquiti Community support.

WAN Issues: The process manages DHCP requests for the WAN interface. Bugs in this server can cause persistent WAN disconnects or failures to obtain a new IP address from an ISP. Resolution Steps

Firmware Updates: Many known ubios-udapi-server bugs are addressed in UniFi OS updates. Check for the latest releases on the Ubiquiti Releases Page. ubios-udapi-server

Service Restart: If the server becomes non-responsive (returning 404 or 500 errors), a full device reboot is typically the first step to clear the stuck process.

Support Files: For persistent high CPU or crashes, generate a UniFi OS support file (not just a Network app log) to provide to Ubiquiti Support for detailed analysis.

Are you experiencing a specific error message in your logs or a performance drop on your UniFi gateway? Cloud Gateways - UniFi OS - Ubiquiti Community

The ubios-udapi-server is the core configuration engine for modern Ubiquiti UniFi gateways like the Dream Machine (UDM), UDM Pro, and UXG series. It acts as a bridge between the high-level UniFi Network Application and the low-level Linux system services that manage your internet, firewall, and VPN.

While Ubiquiti does not officially support manual modification of this server, power users often "make features" by manipulating its state files or scripts to bypass official software limitations. 🛠️ Common Manual Enhancements

Users typically "make features" by targeting these specific areas:

Custom WAN Configurations: Forcing specific DHCP options (like Option 60) for ISPs like Swisscom that require a vendor-class-identifier not always exposed in the UI.

Persistent Custom Rules: Using tools like myconfig_gateway_json to merge manual JSON configs into the /data/udapi-config/ubios-udapi-server/ubios-udapi-server.state file.

Security Tweaks: Manually editing Suricata IPS configs located at /usr/share/ubios-udapi-server/ips/config/ to fine-tune threat detection.

Dual WAN Stability: Editing state files to change how dpinger monitors internet health, preventing the gateway from incorrectly flagging a link as down. ⚠️ Critical Risks The ubios-udapi-server is a core internal process used

Overwritten on Reboot: Many changes in /run/ or /tmp/ disappear after a restart.

Provisioning Conflicts: The UniFi Controller may overwrite your manual changes during its next "provisioning" cycle unless you use a persistent boot script.

System Stability: Improperly formatted ubios-udapi-server.state files can cause the server to crash, resulting in high CPU usage (~70% on a single core) and 404 errors on API endpoints. 📂 Key File Locations

If you are attempting to modify or debug the server via SSH: Main State File

/data/udapi-config/ubios-udapi-server/ubios-udapi-server.state IPS/IDS Config

/usr/share/ubios-udapi-server/ips/config/suricata_ubios_high.yaml DHCP Scripts /usr/share/ubios-udapi-server/ubios-udhcpc-script VPN Secrets /etc/ipsec.d/tunnels/lns-l2tp-server.ipsec.l2tp.secret

Could you tell me what specific functionality you're trying to add? (e.g., IPTV routing, a custom DNS setup, or VPN tweaks?) I can provide the specific commands or scripts needed for your exact UniFi model. Adventures in Ubiquiti Routing and Switching | Page 3

Why It Matters for Developers & Power Users

Use Case 1: Auto-VLAN Assignment

Scenario: When a MAC address belonging to an IoT device connects, move it to VLAN 30 (IoT).

Logic: WebSocket listener -> Detect new client -> Check OUI prefix -> Send PUT to update usergroup_id.

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.

Common Issues and Debugging

A common failure point in the UDM ecosystem is the "Adoption Loop" or "Settings not applying."

Common Issues & Troubleshooting

| Problem | Likely Fix | |---------|-------------| | API returns 403 Forbidden | Check API key permissions or session expiry | | Endpoint not found (404) | Confirm the correct URL path (UAPI paths changed in v3.x) | | Service crashes on boot | Check logs: journalctl -u ubios-udapi-server -f | | High memory usage | Restart service: systemctl restart ubios-udapi-server (safe to do) |

What Exactly is ubios-udapi-server?

To put it simply, ubios-udapi-server is a local microservice running on your UniFi OS console. It acts as a middleware layer that translates high-level API calls into actionable commands for the underlying UniFi Network Application.

Before the ubios-udapi-server, interacting with the UniFi API was a fragile process. Developers had to reverse-engineer the session-based endpoints used by the legacy UniFi controller. It worked, but it was clunky, session-dependent, and prone to breaking with firmware updates.

The ubios-udapi-server changes this by providing a structured, modern, stateless API gateway native to UniFi OS. It allows external clients (Python scripts, Node-RED, Home Assistant, or custom dashboards) to query and modify network settings via HTTP/HTTPS using standard methods like GET, POST, PUT, and DELETE.

Key functions of ubios-udapi-server include:

Workflow Example: Changing a DNS Server

When a user changes the DNS server for a LAN network in the UniFi UI:

  1. User Input: The user enters the new DNS IP in the UniFi Network Application UI and clicks "Apply."
  2. Controller Action: The Network Application formats this change into a JSON payload and sends a request (usually HTTPS) to the ubios-udapi-server endpoint (typically listening on localhost or a specific Unix socket).
  3. UDAPI Processing: ubios-udapi-server receives the payload. It validates the request and identifies which system service needs updating (e.g., dnsmasq or systemd-resolved).
  4. System Execution: The server executes the necessary shell commands or writes to configuration files to update the DNS settings.
  5. Network Restart: It triggers a network reload to apply the changes.
  6. Confirmation: ubios-udapi-server returns a success code to the controller, updating the UI.

Register Online