Ubiquiti UniFi controller setup on Raspberry Pi 3

Hey! Listen! This post is part of a series on the Ubiquiti EdgeRouter Lite. Check them all out!

2019-06-28Migrating away from the Ubiquiti EdgeRouter Lite
  • Migrated to a Netgate SG-1100
  • 2019-02-03EdgeRouter CNAME records
  • Setup CNAME records
  • 2017-10-03Dyn DDNS on EdgeRouter
  • Setup DynDNS
  • 2017-04-25DuckDNS on EdgeRouter
  • Setup DuckDNS
  • 2017-01-08Ubiquiti EdgeRouter serial console settings
  • Serial console settings
  • 2016-11-29Ubiquiti UniFi controller setup on Raspberry Pi 3
  • Install UniFi Controller
  • 2016-08-30EdgeRouter Lite Dnsmasq setup
  • Setup dnsmasq
  • 2016-06-13EdgeRouter Lite software upgrade
  • Firmware upgrade
  • 2016-05-12EdgeRouter Lite OpenVPN setup
  • OpenVPN server setup
  • 2016-04-29Ubiquiti EdgeRouter Lite setup
  • Initial setup
  • Introduction

    As you know, I love my Ubiquiti EdgeRouter Lite. Since I bought it, I’ve been wanting to purchase one of the UniFi wireless APs ever since I saw the Ars Technica review of them. I ended up picking up the UniFi AC Pro on a Black Friday deal on Jet.com.

    The UniFi AP itself does not have a web interface (however, you can SSH to it). To manage the APs, you need to use the UniFi controller software. The software is only needed for the initial setup, and can then be turned off afterwards (which means you can do the setup on your laptop, then disable the software after the initial setup). However, if you want to enable statistic gathering or guest portal, the controller software needs to be running at all times. The controller software is available for Windows, Mac, Linux, which means it’s perfect to run on a small Linux server (like a Raspberry Pi 3).

    Controller setup


    I’m going to assume you’re running this on a Raspberry Pi 3, running Raspbian. However, any Debian-based distribution should follow the same instructions.

    First, we need to add the repository to apt.

    echo "deb http://www.ubnt.com/downloads/unifi/debian stable ubiquiti" | sudo tee /etc/apt/sources.list.d/100-ubnt.list

    Note – You can also specify the version of UniFi to use, as this commenter did, since the stable repository is still on v4. Thanks for submitting this!

    Then, add the GPG key.

    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50

    Next, update your repositories and install Unifi.

    sudo apt-get update && sudo apt-get install unifi

    Now, start Unifi.

    sudo systemctl enable unifi
    sudo systemctl start unifi

    Finally, we need to disable MongoDB, since UniFi will run its own instance.

    sudo systemctl stop mongodb
    sudo systemctl disable mongodb

    Package hold

    If you read around r/Ubiquiti and the UniFi forums, you’ll learn that the controller releases (and AP firmware) can be hit-or-miss. Because we’ve added the UniFi repository, every time we do a sudo apt-get update && sudo apt-get upgrade, we might update the UniFi controller software, even if we don’t want it updated. To get around this, we’ll hold back the unifi package from being updated automatically.

    sudo apt-mark hold unifi

    To verify it is held back, use dpkg.

    sudo dpkg -l | grep ^h

    Here, you can see the results.

    hi  unifi                                 4.8.20-8422                     all          Ubiquiti UniFi server

    The h as the first character means the package is held, and the i as the second character means the package is currently installed.

    If you ever need to remove the hold, use the command below.

    sudo apt-mark unhold unifi

    Manually update

    To check for a new release of the unifi package in the repository, use the command below.

    sudo apt-get update && sudo apt-cache policy unifi

    If there is a newer version, update to it manually.

    sudo apt-get install --only-upgrade unifi

    Oracle Java 8 (optional)

    Oracle changed the Java licensing model (as-of January 2019) to start charging for Oracle Java. Instead, you should stick with OpenJDK as it is open-source.

    OpenJDK has been known to have performance issues on the Pi, so I’m running Oracle’s Java 8 instead. You can find your current Java packages with the command below.

    sudo dpkg --get-selections |grep -e "java\|jdk\|jre"

    If you try to find your Java version, you’ll probably be using OpenJDK.

    --> java -version
    java version "1.7.0_111"
    OpenJDK Runtime Environment (IcedTea 2.6.7) (7u111-2.6.7-2~deb8u1+rpi1)
    OpenJDK Zero VM (build 24.111-b01, interpreted mode)

    Start by installing Oracle Java 8.

    sudo apt-get install oracle-java8-jdk -y

    Next, update your environment to use the new Java.

    sudo update-alternatives --config java

    Check your Java version again to make sure you’re on Java 8.

    --> java -version
    java version "1.8.0_65"
    Java(TM) SE Runtime Environment (build 1.8.0_65-b17)
    Java HotSpot(TM) Client VM (build 25.65-b01, mixed mode)

    Now, copy the systemd service file so we can edit it, then update it to point at the new Java location.

    sudo cp -p /lib/systemd/system/unifi.service /etc/systemd/system
    sudo sed -i '/^\[Service\]$/a Environment=JAVA_HOME=/usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt' /etc/systemd/system/unifi.service

    Now, restart systemd and UniFi.

    sudo systemctl daemon-reload
    sudo systemctl restart unifi.service

    Log rotation (optional)

    Because I’m running the controller on a Raspberry Pi 3, I have limited space on the SD card. To make sure the log files don’t fill the card, I’m going to rotate them using logrotate. Credit to Kevin Burdett for this idea.

    First, install logrotate.

    sudo apt-get update && sudo apt-get install logrotate

    Then, create the configuration file to rotate your UniFi and MongoDB logs.

    sudo bash -c 'cat >> /etc/logrotate.d/unifi << EOF
    /var/log/unifi/*.log {
        rotate 5

    The logrotate options are explained below:

    • Rotate any files ending in /var/log/unifi ending in .log
    • Save 5 log files before deleting older files
    • Rotate the log files daily
    • If the log is missing, go onto the next one without error
    • Do not rotate the log if it is empty
    • Compress the log files (into gzip format)
    • Delay compression until the log file is rotated (so processes won’t be trying to log to a compressed file)
    • Truncate the original log file in place after creating a copy, instead of moving the old log file and optionally creating a new one

    Access controller

    You can now access the controller by going to the IP of your device, over port 8443.


    If everything is working, you should see the setup wizard. Since there are many different ways to do the setup, I won’t be covering that here.


    Controller alternatives

    There are a few alternatives to running the controller software on the Raspberry Pi on your local network:

    1. As mentioned earlier, run the controller software on your PC (Windows/Mac/Linux) for initial setup. You can either turn it off after the setup, or leave it running to gather statistics.
    2. Download the UniFi app (iOS or Android) to setup the AP. The app provides limited setup functionality, with more advanced options requiring the controller.
    3. Purchase the Unifi Cloud Key ($80). This device sits on your network and runs the controller software locally, but is accessible from anywhere at https://unifi.ubnt.com. Instructions are here.
    4. Run the controller in a VPS or AWS instance. See instructions here for installation and adoption.


    Here, you can see my signal strength on the old access point (TP-Link Archer C7 running OpenWrt Chaos Calmer) on the 2.4GHz and 5GHz networks, respectively.




    Then, the same measurements with the new UniFi access point. Again, on the 2.4GHz and 5GHz networks, respectively.



    Hope this helps!


    47 thoughts on “Ubiquiti UniFi controller setup on Raspberry Pi 3”

    1. Controller alternatives:

      5. Run the controller on an always-on PC server on your local network. Use dynamic DNS to access your controller from anywhere.

      Also, both your screenshots look like they’re on 2.4GHz.

    2. I have sucessfully built this using a RPi3 and it works great. However, everytime the Pi reboots I have to login on the browser in order to have Cloud Access. Is there a way I can have automatic login? This device won’t have any ports open to WAN except for the black magic Cloud Key uses.

    3. Is there a way to install the controller’s .deb file from a local folder or a server that I own and not from Ubiquity’s server?
      I will download the .deb file from Ubiquity prior to the installation.

      • I’m confused on what you’re asking. Are you trying to setup your own repo? Or wget the file and then dpkg -i it?

    4. Hey Folks,

      I’m a long ways away from Linux/Debian guru status, and ran into a problem when I ran apt-get update . . .

      Anyone have any idea as to what would cause this error?
      Given that its worked for everyone else, I’m guessing the repo is fine . . .

      W: Failed to fetch http://www.ubnt.com/downloads/unifi/debian/dists/unifi5/Release Unable to find expected entry ‘ubiquiti/binary-arm64/Packages’ in Release file (Wrong sources.list entry or malformed file)

      E: Some index files failed to download. They have been ignored, or old ones used instead.

      Note: I’ve tried both stable and unifi5.

    5. Hi Logan,

      tried your guide an lowefamily.com.au guide on a Pi3. Everything installs fine. But unifi server won’t start. With netstat I can see there’s no open port 8443 and with ps aux | grep uni I couldn’t find a process like unifi. Any idea?


      • Did you start the Unifi service?
        sudo systemctl enable unifi
        sudo systemctl start unifi

        What does the status tell you?
        sudo systemctl status unifi

    6. Great article.
      I’ve already got an always on RPi 2 running an OSMC media centre.
      I’ve successfully installed it on that – I’ve not tried watching anything yet though, so yet to see how well they (osmc and the controller) really get on together. The UniFi web site seems to run OK though.

    7. Hi thanks for this awsome how to.. got an RPI3 up and running in minutes!
      One question though, I have connected to t with my browser and all looks good but its says it an’t find any devices.
      On my test network I have a Unifi AC LR that is managed by another controller but shouldn’t it still show up?


      • To be honest, I’m not sure if an AP can be adopted by more than one controller. I would think you’re not seeing it because it’s already managed…

    8. Good article. This helped me get my RPi 3 running fast. Only issue I ran into and not part of your instructions. I moved a backup of my config from controller on Mac Laptop to the RPi. I needed to SSH into each of the APs and issue this command: set-inform is the IP of the RPi. This was needed because all the AP’s detected as Detached.

    9. After trying multiple guides and reading a lot of positive comments here I tought this was really going to work, but unfortunately I cannot login to the webinterface.

      When I check the status it says its active (sudo systemctl status unifi)

      ● unifi.service – unifi
      Loaded: loaded (/etc/systemd/system/unifi.service; enabled)
      Active: active (running) since Sun 2017-09-24 16:04:55 CEST; 2min 54s ago
      Process: 14814 ExecStop=/usr/lib/unifi/bin/unifi.init stop (code=exited, status=0/SUCCESS)
      Process: 14844 ExecStart=/usr/lib/unifi/bin/unifi.init start (code=exited, status=0/SUCCESS)
      Main PID: 14857 (jsvc)
      CGroup: /system.slice/unifi.service
      ├─14857 unifi -home /usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt -cp /usr/share/java/commons-daemon.jar:/usr/lib/unifi/lib/ace.jar -pidfile /var/run/unifi/unifi.pid -procname unifi -outfile SYSLOG -errfile SYSLOG -Dunifi.datadi…
      ├─14858 unifi -home /usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt -cp /usr/share/java/commons-daemon.jar:/usr/lib/unifi/lib/ace.jar -pidfile /var/run/unifi/unifi.pid -procname unifi -outfile SYSLOG -errfile SYSLOG -Dunifi.datadi…
      ├─14859 unifi -home /usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt -cp /usr/share/java/commons-daemon.jar:/usr/lib/unifi/lib/ace.jar -pidfile /var/run/unifi/unifi.pid -procname unifi -outfile SYSLOG -errfile SYSLOG -Dunifi.datadi…
      └─15192 /usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre/bin/java -Xmx1024M -XX:ErrorFile=/usr/lib/unifi/logs/hs_err_pid%p.log -Dapple.awt.UIElement=true -jar /usr/lib/unifi/lib/ace.jar start

      Sep 24 16:04:55 raspberrypi unifi.init[14844]: Starting Ubiquiti UniFi Controller: unifi.
      Sep 24 16:04:55 raspberrypi systemd[1]: Started unifi.

      Any suggestions? I’m running this next to domoticz, which is on port 8080

      • According to this, UniFi needs port 8080. Try checking this to change the default ports.

        Also, try to tail the UniFi logs out (as root).
        tail -f /usr/lib/unifi/logs/server.log

    10. After a few restarts, domotics was not working anymore and at that moment I tried to open the unifi site and it was working!. So this confirmed to me that there was a port conflict. I changed the domoticz ports and now both are working.

    11. Logan,

      If I turn the raspberry off, will I have to “systemctl start unifi” again? Is there any way to set it on startup?

      I’m a newbbie on Linux.

      • This will start unifi once…
        sudo systemctl start unifi

        This will start unifi at boot…
        sudo systemctl enable unifi

    12. Since this article is almost two years old, are the performance issues with Java still present?
      As in, is it still better to use oracle-jdk instead of open-jdk?

    13. I ran into an issue on a Raspberry Pi 4 where I could not get Oracle java 8 installed (using the latest version of Raspbian as I write this). The error was that there was no installation candidate. So I used this site (https://openjdk.java.net/install/) and installed version 8. Then I used your tip on changing the version (alternates) to change to the openjdk 8 version of Java. This worked and my controller is now installed and running fine.

      Thank you for this writeup it was immensely helpful in getting me started.

      • Glad you’re using OpenJDK. I don’t typically update my articles when things change (otherwise, this entire site would need to be rewritten), but I went back and removed my recommendation for Oracle Java.

        Oracle started charging for Oracle Java back in 2019, so I now recommend you stick with OpenJDK. It is open-source and performs much better than it used to.


    Leave a Comment

    This site uses Akismet to reduce spam. Learn how your comment data is processed.