Run the UniFi Controller headless on Mac
I’m running a UniFi network here with wireless access points, the Security Gateway and a PoE switch. It seems to be a robust system and is almost certainly overkill, but reliability is high on my lists after bad experiences with a NetGear WiFi router.
The UniFi system software is called the Controller and runs on a various operating systems. As I have a Mac mini here, I decided to run it on there. Weirdly, however it runs as a GUI application which means that I have to be logged in. There’s no need for that though as by scouring the Internet I discovered that we can run it headless via launchd.
Firstly we create /Library/LaunchDaemons/com.unifi.controller.service.plist. This file has to be owned by root with group of wheel:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin:/usr/local/sbin</string> </dict> <key>KeepAlive</key> <true/> <key>Label</key> <string>com.unifi.controller.service.plist</string> <key>EnableGlobbing</key> <true/> <key>ProgramArguments</key> <array> <string>/bin/bash</string> <string>-c</string> <string>exec "/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java" -Djava.awt.headless=true -Xmx1024M -jar /Applications/UniFi.app/Contents/Resources/lib/ace.jar start</string> </array> <key>RunAtLoad</key> <true/> <key>WorkingDirectory</key> <string>/Applications/UniFi.app/Contents/Resources/</string> </dict> </plist> |
This is a fairly standard launchd plist file file. However, the controller software is written in Java, but as Ubiquiti no longer bundle a copy of Java, we need to install our own copy of Java 8:
|
1 2 3 4 5 6 |
<key>ProgramArguments</key> <array> <string>/bin/bash</string> <string>-c</string> <string>exec "/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java" -Djava.awt.headless=true -Xmx1024M -jar /Applications/UniFi.app/Contents/Resources/lib/ace.jar start</string> </array> |
(You may need change the path to where your Java 8 is installed.)
This means that when Ubiquiti updates the bundled Java, our service continues to work. We also need to set the working directory to the Resources directory of the app bundle as it doesn’t work otherwise…
Update: Since this post was written, Ubiquiti no longer bundle Java, I have updated appropriately based on the comment from Wade Gibson.
Secondly, we install the service:
|
1 |
$ sudo launchctl load -w com.unifi.controller.service.plist |
Now, the Controller is always running and we can access it on https://localhost:8443 and manage our UniFi network to our heart’s content!
Hi Rob….
What an amazing article….. I have read pages and pages worth of complex solutions and articles on Unifi forum but your methos got me up and running less than 2min.
Thanks million for this post
Forgive a silly question:
First install and get the controller working, as gui, no?
Does it matter the controller version?
Thank You!
Yes, I got it working in GUI mode first. I used the latest version as at the time of the post.
this is great. worked right out of the box.
Thanks for sharing.
Hello all,
it indeed worked.
Just to add, maybe it will help somebody –
to create plist owned by root and with group wheel you have to manually create plist file with that name (lets say on desktop), copy it to LaunchDaemons and use terminal:
and then start service
Thanks rob for quick help.
Hi all, I have rolled the above including Raul’s comments. Only difference is using folder LaunchAgents.
Does not load on reboot, but wors when I sign in, I don’t have to launch app.
I would like it to run on reboot, without logging in. please help
Ubiquiti stopped bundling Java. Any recommendations to modify the plist?
It took a little digging around, but changing this line in the plist with the new Java path seems to work. You have to put quotes around it since the path has a space.
Thanks for reporting back Wade!
You are a life saver! Every time the controller is updated, I've literally been copying and pasting the bundled version of Java from an older versions of the Controller into the new UniFi.app package. I knew there had to be a way to point to the manually installed version of Java.
Still really frustrating the Ubiquiti unbundled Java (though it appears to be due to Oracle's terrible licensing), and even worse that the Controller is still written in Java…
Rob- I've been looking, for weeks now, for a fix to my UniFi.app not launching on my mac. I tried everything on the Ubiquity community pages and zilch. This did the trick – along with additional feedback from Raul and Wade. Thank you all!
To run UniFi controller as a faceless app with version 5.12.66 simply did the change in Info.plist file
change "ui" to "start"
From:
JVMOptions
To:
JVMOptions
Then run:
After that you can do whatever you want, e.g. use launchd
Mine:
Label
com.ubiquiti.unifi
Disabled
RunAtLoad
ProgramArguments
/Applications/UniFi.app/Contents/MacOS/JavaAppLauncher
UserName
put_user_name_here
ServiceDescription
Unifi Manager
That last bit, enabling it from launchd – a few questions:
Do you remove the LaunchDaemon plist file that we created based on this post?
You have the settings, but I'm using old school editor (vi) so it would help see all the xml tags, can you put your contents of com.ubiquiti.unifi.plist in this thread?
Thank You
Could we get an update on above? I tried multiple things but can't get it working (macOs 10.15.7)
Optimus, My Mac mini runs High Sierra and the above works for me. Not sure how to help with Catalina.