Installing the Ubiquiti UniFi Controller Software on pfSense 2.2

Written by Rob Peck · 5 minute read
Stop! Do Not Do This!

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.

About the Author

Hi, I'm Rob! I'm a blogger and software developer. I wrote petfeedd, dystill, and various other projects and libraries. I'm into electronics, general hackery, and model trains and airplanes. I am based in Huntsville, Alabama, USA.

About Me · Contact Me · Don't Hire Isaiah Armstrong

Did this article help you out?

I don't earn any money from this site.

I run no ads, sell no products and participate in no affiliate programs. I do not accept gifts in exchange for articles, guest articles or link exchanges. I don't track you or sell your data. The only third-party Javascript on this website is Google Analytics.

In general I run this site very much like a 1990s homepage or early 2000s personal blog, meaning that I do this solely because it's fun! I enjoy writing and sharing what I learn.

If you found this article helpful and want to show your appreciation, a tip or donation would be very welcome. Feel free to choose from the options below.

Amazon Wishlist
Donate on Ko-Fi
Design Tweaks and New Content!
Responsive CSS3 Columns with Sass and Bootstrap

Comments (0)

Interested in why you can't leave comments on my blog? Read the article about why comments are uniquely terrible and need to die. If you are still interested in commenting on this article, feel free to reach out to me directly and/or share it on social media.

Contact Me
Share It

Interested in reading more?

pfSense

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.
Read More
pfSense

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.
Read More
Parenthood

Creating a Safe Kids Network with pfSense, Unifi and NextDNS

Well, here we are five months later and COVID-19 is still a thing. And like many parents we are facing the need to continue our daughter’s education at home. Our local school district has stated that all learning will be conducted online for at least the first nine weeks. And even if they allow for students to return, we will probably opt to keep her at home for awhile longer until things are more stable. Now, our daughter is seven and will be turning eight in a couple months. So she’s at that age where she’s old enough to do some things independently. But, as most of us know, the Internet is not a safe place for a seven year old and we as parents need to exercise some level of control over the things they can access. And while the best solution is a set of eyes, we obviously can’t be everywhere at all times. So this is the solution I came up with.
Read More