Installing the Ubiquiti UniFi Controller Software on pfSense 2.2

By · Published · howto, networking, pfsense

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 "UniFi.unix.zip." Copy the link.
  2. On your pfSense box: cd ~
  3. wget http://www.ubnt.com/downloads/unifi/3.2.10/UniFi.unix.zip (or whatever the URL you have is).
  4. unzip UniFi.unix.zip
  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.

( Comments )

Did something I wrote 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 Amazon.com wishlist.


Related Posts

Scheduled Throttling with pfSense

More collectd and pfSense Fun!


comments powered by Disqus