Skip to content

UniFi

UniFi

Networking hardware (switches, APs) is Ubiquiti UniFi, managed by UniFi OS Server — the current combined controller package (not the older standalone Java unifi-controller) — running on a dedicated Ubuntu VM on the LAN (10.10.10.5).

Official download

UniFi Network Application / UniFi OS Server downloads — always current release; the install script (below) pulls whatever version is current at run time rather than a pinned one.

Why a VM instead of a UDM/hardware controller

Running the controller as a VM keeps it inside the same Terraform/Packer/Ansible provisioning story as everything else in the lab, rather than being a standalone appliance that has to be backed up and reasoned about differently.

Install automation (install-unifi-os.sh)

A single script (kept in the VM's home directory) takes the lab from a fresh Ubuntu 26.04 LTS install to a running, TLS-terminated UniFi OS Server:

sudo ./install-unifi-os.sh <unifi-os-download-url> [cert-file] [key-file]

What it does:

  1. Installs podman (UniFi OS Server runs as a Podman container, not bare-metal), plus slirp4netns and iptables-persistent.
  2. Verifies Podman is at least 4.3.1, adding the kubic repo to upgrade it if the distro's default is older.
  3. Downloads and runs the official UniFi OS Server installer, then waits for the uosserver container to report healthy.
  4. Redirects port 443 → 11443 via iptables NAT, since UniFi OS Server binds to 11443 on the host due to its slirp4netns networking.
  5. Optionally installs a TLS cert/key pair straight into the container (podman cp ... uosserver:/data/unifi-core/config/unifi-core.{crt,key}), then restarts the service to pick it up.

PREROUTING only — never add an OUTPUT-chain redirect here

An OUTPUT-chain REDIRECT was tried once and must not come back. OUTPUT matches all locally-generated packets — including the container's own outbound calls (via slirp4netns) to Ubiquiti's cloud SSO (sso.ui.com) for account login. That looped cloud-auth requests back into the container's own self-signed cert instead of reaching the real internet, breaking login with a generic "check your ISP" error even with correct credentials. PREROUTING only redirects genuinely inbound connections from other LAN hosts, which is all that's actually needed.

Certificates

Certs are the same ones ACME issues for devhome.cloud via pfSense (DNS-01 against Azure Public DNS — see ACME Certificates), copied to the VM and installed with the script's optional cert-file arguments — not a separate self-signed cert or a second ACME client.

Restoring config

After a fresh install, restore the .unf backup (produced by backup-playbook.yml — see Playbook Reference) via Settings → Backup → Restore in the UniFi OS Server UI, then confirm APs and switches reconnect to the new controller.