Install Unifi under TrueNAS

Deutsche Version hier


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.



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:

  • 04.02.2024: Final Version, minor adjustments
  • 23.01.2024: Initial Version


  • TrueNAS Core or pure FreeBSD Server
    • A jail (e.g. with the name unifi) is set up
    • IP address of the UNIFI jail is known (e.g.
    • Hostname of the UNIFI 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.


The local setup looks like this:

                          │ TrueNAS                                   │
                          │        Optional:          │
                          │ ┌──────────────────┐  ┌─────────────────┐ │
                          │ │ Jail: unifi      │  │ tank/jail_data  │ │
                          │ │  │  │                 │ │
                          │ │                  │  │                 │ │
      LAN:  ─┼─┼─► unifi  ────────┼──┼─► unifi/data    │ │
                          │ └──────────────────┘  └─────────────────┘ │

Optional external data directories

The data directory /usr/local/share/java/unifi/data can be stored in a separate dataset outside the jail. This means that this data is stored independently of the jail. If the jail is damaged or deleted for any reason, we are able to restore the previous configuration and data with minimal effort. The backups created are also stored outside the jail. I have described how this can be achieved (generically) here and can be implemented with the following information.

└── /mnt/tank/jails_data
    └── unifi
        └── data  # Ablage für die MongoDB Datenbank und Konfiguration (im Jail: /usr/local/share/java/unifi/data)
  • SOURCEDIRECTORY = /mnt/tank/jails_data/unifi/data
  • DESTINATIONDIRECTORY = /mnt/tank/iocage/jails/unifi/root/usr/local/share/java/unifi/data
  • Name of the Unifi user = unifi
  • ID of the Unifi user = 975

This is intended more for advanced users who already have some experience. To go into this in detail would go beyond the scope here. But the most important thing is: A new directory (dataset) is required, which contains everything relevant to UNIFI. However, there is no reason not to do it without this step. Unifi can alternatively be restored excellently from a backup (unf) file.

JAIL start

DThe webshell in TrueNAS is sufficient for simple configurations, so SSH remains deactivated this time.

  • Jail start: TrueNAS / Jails / unifi / Start
  • Jail Shell open: TrueNAS / Jails / unifi / Shell

Adjust package source

First, we adjust the package sources to the latest so that the latest packages are actually obtained

Install packages & activate services

Now update the package source with pkg update and then install the required packages with pkg install -y unifi8.
Activate the service with service unifi enable so that it starts automatically when the jail is started.


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.


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://UNIFIIP:8443 oder http://UNIFIHOSTNAME:8443



Backups are performed automatically once a week by the UNIFI software.
These are stored in the folder /usr/local/share/java/unifi/data/backup.


  • Create jail
  • OPT: Mount daten directory, if the data directory should be outside
    • ex. /mnt/tank/jails_data/unifi/data to /mnt/jails/iocage/jails/unifi/root/usr/local/share/java/unifi/data
  • Start jail
  • Adjust package source
  • Unifi install pkg install -y unifi8
  • Unifi activate and start service unifi enable && service unifi start

This starts the Unifi service and accesses the existing configuration and database in /usr/local/share/java/unifi/data.
Without the external directory, a previously saved unifi.unf file can be read in again at the first start. This also works very well.


tank = The name of the ZFS pool, please adapt

iocage create -b -n "unifi" -r 13.2-RELEASE vnet="on" bpf="on" dhcp="on"

zfs create -p tank/jails_data/unifi/data
iocage exec -f unifi "install -d -g 975 -o 975 /usr/local/share/java/unifi/data"
iocage stop unifi
iocage fstab -a unifi /mnt/tank/jails_data/unifi/data /usr/local/share/java/unifi/data nullfs rw 0 0

iocage console -f unifi
mkdir -p /usr/local/etc/pkg/repos
sed -e 's|quarterly|latest|g' /etc/pkg/FreeBSD.conf > /usr/local/etc/pkg/repos/FreeBSD.conf
pkg install -y unifi8
service unifi enable
service unifi start