Introduction
The UniFi Controller Management interface enables the management of UniFi devices and the display of network statistics. The software is often installed on a Windows or Mac PC, but does not provide a solid foundation for long-term operation. Since FreeBSD jails are so lean and FreeBSD is also supported by Ubiquiti, it makes sense to install it there. If we're going to do it, let's do it right.
Goals
The aim of this guide is to operate a Unifi controller based on TrueNAS or FreeBSD. Without jail, a pkg install unifi8 is sufficient and the topic is done. However, to make it even more perfect, especially with regard to the independence of the settings from the jail, we will go into more detail here.
NEW: For the very impatient I have a console only section. There are only commands, no explanations.
Last update:
- 18.01.2026: Revision. Removal of TrueNAS and rewrite to pure FreeBSD. Jails with Bastille
- 04.02.2024: Final Version, minor adjustments
- 23.01.2024: Initial Version
Requirements
- A FreeBSD server is set up and prepared
- Bastille is installed and ready for use
- IP address of the jail is known and preferably reserved in DHCP
- Hostname of the jail is known (e.g. unifi.domain.local) and accessible via internal DNS
In general, such services should be set up in a separate environment. This makes not only security but also maintenance much easier. Jails can be backed up relatively easily and only the packages that are absolutely necessary are installed.
Diagram
The local setup looks like this:
┌──────────────────────┐
│ FreeBSD │
│ ┌──────────────────┐ │
│ │ jail/unifi │ │
LAN: 0.0.0.0:8443 ──┼─┼─► unifi │ │
│ └──────────────────┘ │
└──────────────────────┘Create jail
A separate jail is required. Here we take unifi as the jail name and the option allow_sysvipc is required in any case.
Unifi can alternatively be restored excellently from a backup (unf) file.
Set up jail
Either use bastile console unifi to start a console in the created jail, or log in via SSH (if activated) with ssh USERNAME@IP or ssh USERNAME@HOSTNAME to then gain root rights with su.
Customise package source
Package sources should be customized, see separate article.
Install packages & activate services
Now update the package source with pkg update and then install the required packages with pkg install -y unifi9.
Activate the service with service unifi enable so that it starts automatically when the jail is started.
Unifi
Create configuration
Hooray, no configuration is required, everything is created automatically at the first start.
Start services
We have now reached the end of the preparations and Unifi is started with service unifi start.
Registration
Unifi is now called up for the first time to set up the network.
To do this, use your favourite browser to call up the IP or host name of the Gitea jail:
https://IP:8443 oder http://HOSTNAME:8443
Backup
Backups are performed automatically once a week by the UNIFI software.
These are stored in the folder /usr/local/share/java/unifi/data/backup.
Console
Voilá
