Configure the Ubiquiti UniFi Network Controller via CLI

Most UniFi configuration happens in the graphical UniFi Network controller, but the command line is essential when a device will not adopt automatically, when you adopt across networks (Layer 3), or when you self-host the controller. This SKYLINE guide covers the real, verified commands — nothing invented. Always confirm syntax against your firmware version before running anything in production.

Before you start: how UniFi adoption works

UniFi devices (access points, USW switches, UCG/UDM gateways) report to a controller using the inform protocol on TCP port 8080. The controller web UI for the legacy self-hosted application runs on port 8443 (HTTPS). When a device and its controller are on the same Layer 2 network, adoption is usually automatic via Layer 2 discovery. When they are on different subnets or sites, you point the device at the controller manually with the set-inform command.

Step 1 — SSH into the UniFi device

SSH must be enabled (it is on by default for factory-fresh devices, and configurable under controller Settings → System → Device Authentication). Connect with the default credentials ubnt / ubnt unless they have been changed:

ssh ubnt@192.168.1.20

When prompted, enter the password (default ubnt). You are now on the device’s BusyBox-style shell.

Step 2 — Point the device at your controller with set-inform

Run set-inform with the inform URL of your controller. The format is always http://<controller-ip-or-fqdn>:8080/inform:

set-inform http://192.168.1.10:8080/inform

For a Layer 3 / remote adoption, use a reachable IP or FQDN of the controller (for example a public DNS name or VPN-reachable address):

set-inform http://unifi.example.com:8080/inform

The default inform target on a fresh device is http://unifi:8080/inform, where unifi is a DNS name many networks publish for the controller.

Step 3 — Adopt in the controller, then confirm

After the first set-inform, the device appears under UniFi Devices as Pending Adoption. Click Adopt in the controller. The device will briefly show Adopting, then it provisions. If it gets stuck, return to the SSH session and run the same command a second time to finalise the link:

set-inform http://192.168.1.10:8080/inform

This two-step pattern (set-inform → Adopt → set-inform again) is the standard way to complete a Layer 3 adoption.

Step 4 — Verify the device state

Confirm the configuration with the info command, which prints the device model, firmware version, the current inform URL and the management status:

info

Look for the inform URL matching your controller and a status of Connected once adoption completes.

Resetting a device for re-adoption

A device that was previously adopted will not accept a new inform URL until it is back in a factory-default, unmanaged state. If a device is stuck, factory reset it — either by holding the physical reset button for about 10 seconds, or from the SSH shell:

set-default

After the reset, repeat Steps 1–3. Treat factory reset as a last resort, because it clears all on-device configuration.

Installing a self-hosted UniFi Network Application on Linux

If you run your own controller instead of a Cloud Gateway, the legacy self-hosted UniFi Network Application installs from Ubiquiti’s APT repository on Debian/Ubuntu. First install the base dependencies:

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https -y

Add Ubiquiti’s signing key and repository:

wget -qO - https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/unifi-repo.gpg > /dev/null

echo 'deb [signed-by=/usr/share/keyrings/unifi-repo.gpg] https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/unifi.list

Then install (or upgrade) the application:

sudo apt-get update
sudo apt-get install unifi -y

UniFi requires a compatible MongoDB; if it is not provided by your distribution you must add the MongoDB repository per MongoDB’s Debian instructions before installing unifi. Once installed, the controller runs as a service (no local GUI) and is reachable at https://<server-ip>:8443. Manage it with the service tooling, for example:

sudo systemctl status unifi
sudo systemctl restart unifi

About UniFi OS Server (the newer option)

Ubiquiti’s newer self-hosting path is UniFi OS Server, which runs the UniFi applications in containers using Podman on Ubuntu 23.04+ / Debian 12+ via an official installation script, rather than the legacy MongoDB + APT package. Choose UniFi OS Server for new builds where you want the same multi-application experience as a Cloud Gateway on your own hardware.

Quick command reference

• ssh ubnt@<device-ip> — connect to the device (default password ubnt).
• set-inform http://<controller>:8080/inform — point the device at the controller.
• info — show model, firmware, inform URL and status.
• set-default — factory reset the device (last resort).
• sudo apt-get install unifi -y — install the self-hosted Network Application.
• sudo systemctl restart unifi — restart the self-hosted controller service.

Need help?

SKYLINE installs, configures, supports and troubleshoots Ubiquiti UniFi across Saudi Arabia. For hands-on help, see our UniFi installation and support service, browse the software licensing marketplace, or contact our engineers on +966 50 993 9334.