UniFi Controller Setup Wizard

Improved Startup Script for Ubiquiti UniFi Controller on Unix / Linux 1

If you’re running the Ubiquiti UniFi Controller on a Linux box (I run mine on CentOS), the default instructions from UBNT walk you through building a simple SysV init script to run the Java .jar file as a service. I was in a tinkering mood, so I re-wrote the SysV startup script on my system using /etc/rc.d/init.d/functions to allow for the pretty green and red “OK” and “FAILURE” messages, and had the script create a .pid file on startup, which allows a “status” option and smarter start/stop/restart decisions based on whether the service is already running.

For my CentOS 7 box, as well as for Debian / Ubuntu users, I also wrote a systemd UniFi.service file for systemd-based systems.

Both scripts also set a 1024M limit (which you can edit to your liking) on the amount of RAM the UniFi Controller can use… as I’ve seen cases where it gets a little crazy and starts affecting other system services.

SysV Users

My SysV UniFi init script is stored as a Gist:

Save the “raw” version of the startup script as /etc/rc.d/init.d/UniFi, do a chkconfig UniFi on, and you’re all set.

IMPORTANT: If you have a previous version of the init script already in place and the UniFi Controller already running as a service, I recommend shutting down the UniFi Controller service (service UniFi stop) before replacing the old init script with this one, so the new script doesn’t get confused (since a .pid file won’t exist yet).

systemd Users

If you’re running a Linux variant that relies on systemd (such as CentOS 7, Debian, or Ubuntu), do the following:

Create a new ‘ubnt’ user with:

useradd -M ubnt

(I personally edit the /etc/password file and change the login to /sbin/nologin)

Give the ubnt user ownership of the UniFi Controller directory:

chown -R ubnt:ubnt /opt/UniFi

Save the following UniFi.service file in your systemd folder of choice (such as /etc/systemd/system):

Auto-start the service with:

systemctl enable unifi.service

Now you can start, stop, and check service status with your standard systemd commands, such as:

systemctl status

Suggestions for script improvements are always welcome!


  • Loving it. 5.0.8 fixed a few probs that were nagging in 5.0.7.