Installing the Ubiquiti UniFi Controller Software on pfSense 2.2

This is an old post!

This post is over 2 years old. Solutions referenced in this article may no longer be valid. Please consider this when utilizing any information referenced here.

Note: I am leaving this here for the reference and posterity, but for a variety of reasons, I no longer recommend doing this. It is a neat hack, but tends to be a bit of a pain to live with as you end up having to troubleshoot or reinstall it every time you update pfSense or Unifi. When you can install it on a Raspberry Pi for less than $50, there’s really no need to do this.

I personally have switched to running this on a stock Ubuntu system that runs a few other network services in my house.

This is a short tutorial on how to install the Ubiquiti Networks’ UniFi Enterprise Wifi controller software on pfSense 2.2. These directions are derived from these directions for 2.1-RC, but have been updated to work on 2.2.

Note that this is a somewhat advanced tutorial. If you are not comfortable working in a Unix command line or editing system files, this is probably not the best thing you could do. But I’m putting it out here in case it will help others.

Initial Setup

  1. Optional: If you already have the UniFi software installed on another computer, you will need to dump a backup. Log in and go to Admin (at the bottom) and click “Download Backup Settings.” Then shut down that instance of the software.
  2. Enable Shell Access. Go to System -> Advanced, under “Secure Shell,” select “Enable Secure Shell.”
  3. SSH to your pfSense machine and enter shell. As of this writing, that’s option 8 once you’ve connected and logged in.
  4. Optional: Make a complete backup. Type /etc/rc.create_full_backup and let it run.
  5. cp /etc/skel/dot.tcshrc /root/.tcshrc
  6. source ~/.tcshrc

Install Prerequisites

  1. Type pkg. This will ask you if you want to install pkg. Type “Y” and wait.
  2. pkg install unzip
  3. pkg install wget
  4. pkg install mongodb
  5. pkg install openjdk
  6. rehash

Setup Prerequisites

  1. mount -t fdescfs fdesc /dev/fd
  2. Edit your /etc/fstab as instructed by the message generated by the OpenJDK installation.

Here, I rebooted pfSense. Not strictly necessary, but I wanted to be sure that everything I had done up to this point (such as editing the fstab file) had not made the system unbootable.

Install the UniFi Software

  1. From the UniFi update blog, find the most recent update (as of this time, it’s 3.2.10). Scroll down until you find “” Copy the link.
  2. On your pfSense box: cd ~
  3. wget (or whatever the URL you have is).
  4. unzip
  5. mv UniFi /usr/local/
  6. cd /usr/local/UniFi/bin
  7. ln -s /usr/local/bin/mongod mongod
  8. /usr/local/etc/rc.d/mongod onestart
  9. cd /usr/local/UniFi/lib
  10. java -jar ace.jar start &

Now wait 3-5 minutes. When it comes up, it will come up on port 8443. You can check to see if it’s up or not by running netstat -an | grep 8443. For some unknown reason, their controller software is just very slow to come up on Unix.

Eventually, when it does, you can use “https://<your ip here>:8443” to reach it. Note the HTTPS. It won’t redirect you to secure and will just send garbage. You have to directly use https.

Optional: If you downloaded a backup as above, you can restore it now. Instead of setting up a new controller, use the link at the bottom of the window that says “Restore a backup” or something similar. If you do this, after it finishes restoring, you will need to manually relaunch the controller.

  1. java -jar ace.jar start &

Final Setup

This final step insures the UniFi controller software restarts if you reboot pfSense.

  1. Install the “shellcmd” package. Go to System -> Packages, Available Packages. Find “Shellcmd” and install it.
  2. Go to Services -> Shellcmd.
  3. Add a new shell command. The command is /usr/local/openjdk7/bin/java -jar /usr/local/UniFi/lib/ace.jar start & and the type is shellcmd.
  4. Press save.

That’s it! You now have a working UniFi controller installation on your pfSense machine!

A Note About pfSense Ugrades

Incremental upgrades to pfSense haven’t seemed to affect this at all. However, major point upgrades (2.1 to 2.2 for instance) will often remove some of all of this. When I upgraded to 2.2, it didn’t work at first, but it turned out that I just needed to reinstall OpenJDK. So it is probably best, before doing an upgrade, to dump a backup of your UniFi settings in case you need to reinstall.

Upgrading UniFi

To upgrade UniFi, make a backup from the existing UniFi installation (step 1 at the top) and start over under “Install the UniFi Software” above. Then restore your settings, restart the controller software, and apply the updates to your access points.

Did this article help you out?

That's great! I don't earn any money from this site - I run no ads, sell no products and participate in no affiliate programs. I do this solely because it's fun; I enjoy writing and sharing what I learn.

All the same, if you found this article helpful and want to show your appreciation, here's my wishlist.

Read More

Scheduled Throttling with pfSense

Apple has launched a new Photos App for OS X, along with the ability to upload your entire library to iCloud. And with prices that are so cheap, there’s almost no reason not to. $3.99 a month is cheap insurance to know that every photo I’ve ever taken of my family won’t be wiped out in a tornado. But with this comes a problem - namely, how do you upload a 150 gigabytes of photos over a 5 megabit network connection? Well, you wait a really long time for it to upload. Which is fine, really, because I’m not in any particular hurry to finish. But, once I started the upload, I noticed that surfing the web became pretty much impossible because the upload to iCloud was saturating my upstream bandwidth.

Using Realtek NICs in pfSense

In the year 2021 there are a lot of things that you just take for granted. Remember when you used to have to use jumpers to set things on your computer? Or worrying about IRQ conflicts? Or whether you could get the the drivers you needed to work? These are all parts of the “bad old days” of computers that I don’t miss very much. These days if I plug things into my computer - any of them - I expect them to “just work.” And very often, surprisingly, this is the case. Especially common, well supported things like network cards. So it is notable when I encounter something where that isn’t the case. But first, let’s back up a little bit.