UniFi OS Server

Highly experimental: Ubiquiti UniFi OS Server on FreeBSD — runs the full UniFi management stack (unifi-core, UniFi Network) using FreeBSD jails and linuxulator.

Version Tags

Linux binary compatibility must be loaded on the host. unifi-core, uos-agent and uid-agent are Linux ELF binaries run through linuxulator, and a jail cannot load kernel modules itself:

1
2

sysrc linux_enable=YES
service linux start

Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions, including the security model for host vs. container privileges.

Deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

services:
  unifi-os-server:
    image: "ghcr.io/daemonless/unifi-os-server:latest"
    container_name: unifi-os-server
    volumes:
      - "/containers/unifi-os-server/data:/data"
      - "/containers/unifi-os-server/data:/compat/linux/data"
    annotations:
      org.freebsd.jail.allow.mlock: "true"
      org.freebsd.jail.allow.sysvipc: "true"
    # always (not unless-stopped) so FreeBSD's podman rc.d auto-starts it at boot
    restart: always

1
2
3

# .env

DIRECTOR_PROJECT=unifi-os-server

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# appjail-director.yml

options:
  - alias:
  - ip4_inherit:
services:
  unifi-os-server:
    name: unifi_os_server
    options:
      - container: 'args:--pull'
      - template: !ENV '${PWD}/template.conf'
    volumes:
      - UNIFI_OS_SERVER_DATA_PATH: /data
      - UNIFI_OS_SERVER_DATA_PATH: /compat/linux/data
volumes:
  UNIFI_OS_SERVER_DATA_PATH:
    device: '/containers/unifi-os-server/data'
  UNIFI_OS_SERVER_DATA_PATH:
    device: '/containers/unifi-os-server/data'

1
2
3
4
5
6
7

# Makejail

ARG tag=latest

OPTION container=boot
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/unifi-os-server:${tag}

1
2
3
4
5
6
7
8

# template.conf

exec.start: "/bin/sh /etc/rc"
exec.stop: "/bin/sh /etc/rc.shutdown jail"
mount.devfs
persist
allow.mlock
allow.sysvipc

1
2
3
4
5
6
7
8
9

services:
  unifi-os-server:
    name: unifi-os-server
    image: "ghcr.io/daemonless/unifi-os-server:latest"
    network:
      - mode: host
    volumes:
      - "/containers/unifi-os-server/data:/data"
      - "/containers/unifi-os-server/data:/compat/linux/data"

Setup Instructions

Networking. The compose file in this repo runs with network_mode: host so UniFi's L2 device discovery works; add that line if your snippet lacks it. The server listens on 443 (web UI), 8080 (device inform), 8443 (Network HTTPS) and 3478/udp (STUN). On a bridge network instead, map those ports (-p 443:443 -p 8080:8080 -p 8443:8443 -p 3478:3478/udp); discovery will not work, so point devices at the controller yourself with set-inform http://<host-ip>:8080/inform or DHCP option 43.

First start. Open https://<host-ip>/ and complete the setup wizard. Its "restore from backup" step only lists cloud backups; to restore a Network .unf file, finish setup first, then use Settings → Backups → Restore in the console. The bundled Network application is the current standalone release, so backups from an up-to-date controller restore.

Moving devices from another controller. Adopted devices keep working and follow their inform URL. Move one with set-inform http://<host-ip>:8080/inform over SSH (the device SSH credentials are in the old controller's Device SSH Authentication settings), or move all of them by setting the old controller's Inform Host override to the new address. Shut the old controller down once everything is online.

Double /data mount. The Linux services open SQLite databases under the Linux compat root, so the same data directory must be mounted at both /data and /compat/linux/data.

Interactive Configuration

Parameters

Volumes

Need help? Join our Discord community.