Ubios-udapi-server <DIRECT | 2024>

The ubios-udapi-server is a critical backend service in Ubiquiti's UniFi OS, primarily responsible for managing and applying network configurations on devices like the UniFi Dream Machine (UDM), UDM Pro, and Next-Generation Gateway (UXG). It acts as a bridge between the high-level UniFi Network application settings and the low-level system execution. Core Functions and Architecture

This server handles the "heavy lifting" for several key network subsystems:

Interface Configuration: Dynamically configures physical and virtual interfaces (VLANs), including starting DHCP clients on WAN ports like eth8 or eth9.

Security & Firewall: It orchestrates the configuration of NAT, firewall filters, and IP sets. It specifically manages the Suricata configuration files used for IDS/IPS (Threat Management).

Service Management: Controls the lifecycle of various internal services, including the dnsForwarder, dpi (Deep Packet Inspection), radius-profiles, and geoipFiltering.

Socket Communication: It listens on a UNIX socket at /var/run/ubnt-udapi-server.sock to receive commands from other system components. Configuration and Troubleshooting

While usually automated, power users and administrators may interact with it for advanced tasks or troubleshooting: ubios-udapi-server

Configuring Advanced Security: You can manually adjust Suricata’s threat detection by editing the configuration file at /usr/share/ubios-udapi-server/ips/config/suricata_ubios_high.yaml using tools like the VI editor.

Monitoring Logs: System logs often show ubios-udapi-server activity during startup, revealing if specific services like the L2TP VPN server failed to start because an interface wasn't ready.

Identifying Issues: Periodic WAN link drops or "commit errors" during configuration changes are often traced back to how this server applies settings or monitors link health. Modern Context: UniFi OS Server

Ubiquiti has recently introduced the UniFi OS Server (e.g., version 4.3.6), which allows users to run the full UniFi OS experience—including features previously exclusive to consoles like Site Magic SD-WAN—on their own Windows, macOS, or Linux hardware. This new architecture replaces the legacy "UniFi Network Server" to provide a more unified experience. UniFi OS Server 4.3.6 - Ubiquiti Community

ubios-udapi-server — Report (summary)

What it is

  • A Ubiquiti UbiOS service (part of UniFi/UDM family) that provides the “udapi” management/config layer used to generate runtime configs and hooks for services like dnsmasq, DHCP, RADIUS and captive portal; configuration changes are written under /run and /mnt/data/udapi-config (paths vary by device/firmware).

Key behaviors

  • Generates dnsmasq configuration fragments (e.g., /run/dnsmasq.conf.d/*.conf) and dhcp scripts (/run/dnsmasq.script).
  • Manages RADIUS certs and raddb files used by the system RADIUS server.
  • Writes persistent config into udapi-config so settings survive reboots/firmware updates when supported.
  • Can trigger other components (restart services, create cron jobs) as part of provisioning tasks.

Common issues & symptoms

  • “process: Failed to read file” or other errors in system logs when generated files are missing, have bad permissions, or the udapi service crashes.
  • Firmware upgrades that change UbiOS internals may break udapi behavior or downstream scripts (e.g., dnsmasq or captive portal).
  • Custom scripts or third-party packages that rely on udapi-generated files can be disrupted by changes in file layout or format.

Where to look (typical paths)

  • Runtime/generated files: /run/, /run/dnsmasq.conf.d/, /run/dnsmasq.script
  • Persistent udapi config: /mnt/data/udapi-config or /data/udapi-config (device-dependent)
  • RADIUS certs: /data/udapi-config/raddb/certs or similar under udapi-config
  • Logs: system journal (journalctl) or /var/log/ubios-udapi-server if present; UbiOS-specific logs exposed via console.

Troubleshooting steps (ordered, concise)

  1. Check service status and logs:
    • journalctl -u ubios-udapi-server (or inspect system log output).
  2. Inspect generated files and permissions:
    • ls -l /run/dnsmasq.conf.d/ /run/dnsmasq.script /mnt/data/udapi-config
  3. Validate file contents for syntax errors (dnsmasq.conf fragments, RADIUS cert paths).
  4. Confirm persistence: verify files under udapi-config are present and not overwritten on reboot.
  5. Temporarily stop conflicting third‑party scripts/packages, reboot, and observe whether udapi regenerates correct files.
  6. If firmware recently updated, check community/GitHub issues for breaking changes (look for related uDM/UDM-Pro firmware notes).
  7. Backup existing certs/config, then attempt controlled redeploy or reconfigure via udapi endpoints or supported scripts.

References & sources

  • Ubiquiti community threads and issue reports describing runtime files and common failures.
  • GitHub projects and community scripts (examples: ubios-cert, ubios-related utilities) that interact with udapi-generated files.

If you want, I can:

  • Produce a detailed diagnostic checklist with exact commands for your device (assume UDM/UDM‑Pro); or
  • Search for recent, firmware-specific breaking changes for a specific UbiOS version (provide the version).

Or system-level

journalctl -u ubios-udapi-server -f

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:

  1. UniFi OS (Podman/Docker containers): The API server runs inside a container named unifi-core.
  2. Port Binding: By default, it listens on 127.0.0.1:443 (inside the container). This is reverse-proxied to the host’s NGINX.
  3. Authentication: Uses a short-lived JWT token obtained via the local login endpoint (/api/auth/login).
  4. WebSocket Stream: wss://<UDM-IP>/ws/events for real-time updates.

Common Issues and Debugging

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

  • Symptom: You change a setting in the UI, it spins for a long time, and reverts, or the UDM shows "Adoption Failed" / "Provisioning" indefinitely.
  • Root Cause: Often, ubios-udapi-server has crashed or hung, preventing the controller from talking to the OS.
  • Fix: Restarting the service via SSH (systemctl restart ubios-udapi-server) or rebooting the UDM usually resolves the sync issue.

1. Check if the service is running

# SSH into your Uni OS device
systemctl status ubios-udapi-server

What is ubios-udapi-server?

In short: UbiOS UDAPI Server stands for Ubiquiti Operating System Unified Device API Server.

It is a local service running on your UniFi OS device that acts as a bridge between:

  • The UniFi Network application (your controller UI)
  • The actual physical devices (APs, switches, gateways)

Think of it as a real-time, lightweight API gateway specifically for device discovery, adoption, and status updates. The ubios-udapi-server is a critical backend service in