Article

Table of Contents
Theme:
Was this article helpful?
Try Vultr Today with

$50 Free on Us!

Want to contribute?

You could earn up to $600 by adding new articles.

Install UniFi Cloud Controller on a Debian Cloud Server

Author: Christian Kintu

Last Updated: Fri, Oct 21, 2022
Server Apps

Introduction

Unifi Cloud Controller, also known as Unifi Network Application, is a cloud service that allows you to manage Ubiquiti network devices through a single web interface. The application allows you to plan, scale, map, and manage multiple network topologies for your linked devices. This article describes how you can install Unifi Cloud Controller on a Debian Cloud server hosted on Vultr.

Prerequisites

Before you begin, be sure to:

Installation

  1. SSH and Login to your Debian server. Replace 192.0.2.2 with your actual Server IP.

     $ ssh example-user@192.0.2.2
    
  2. Add the MongoDB repository for version 3.6 or below to your sources list because Unifi Controller supports versions below 4.0 for now.

     $ echo "deb http://repo.mongodb.org/apt/debian stretch/mongodb-org/3.6 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.6.list
    
  3. Download the MongoDB 3.6 repository verification key.

     $ sudo wget -O /etc/apt/trusted.gpg.d/mongodb-3.6.asc https://www.mongodb.org/static/pgp/server-3.6.asc
    
  4. Add the Java 8 repository to your sources list.

     $ echo "deb https://adoptopenjdk.jfrog.io/adoptopenjdk/deb bullseye main" | sudo tee /etc/apt/sources.list.d/java8.list
    
  5. Download the Java GPG key.

     $ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-key add -
    
  6. Update the server.

     $ sudo apt update
    
  7. Install the Java development kit (JDK).

     $ sudo apt install adoptopenjdk-8-hotspot
    
  8. Add the Unifi Controller Debian repository to the sources list.

     $ echo 'deb http://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/unifi.list
    
  9. Download the repository GPG verification key.

     $ sudo wget -O /etc/apt/trusted.gpg.d/unifi.gpg https://dl.ubnt.com/unifi/unifi-repo.gpg
    
  10. Update the server.

     $ sudo apt update
    
  11. Install Unifi Controller on your server.

     $ sudo apt install unifi -y
    
  12. Enable Unifi Controller to start at boot time.

     $ sudo systemctl enable unifi
    
  13. Enable MongoDB to start at boot time.

     $ sudo systemctl enable mongod
    
  14. Verify the Unifi Controller status.

     $ sudo service unifi status
    
  15. Your Output should look like the one below.

     ● unifi.service - unifi
    
       Loaded: loaded (/lib/systemd/system/unifi.service; enabled; vendor preset:>
    
       Active: active (running) since Mon 2022-09-19 22:22:05 UTC; 13min ago
    
       Process: 17948 ExecStartPre=/usr/sbin/unifi-network-service-helper init (co>
    
       Process: 17964 ExecStartPre=/usr/sbin/unifi-network-service-helper init-uos>
    
       Process: 17970 ExecStartPost=/usr/sbin/unifi-network-service-helper healthc>
    
       Main PID: 17969 (java)
    
          Tasks: 88 (limit: 2340)
    
       Memory: 586.5M
    
          CPU: 30.008s
    
       CGroup: /system.slice/unifi.service
    
           ├─17969 /usr/bin/java -Dfile.encoding=UTF-8 -Djava.awt.headless=tr>
    
           └─18019 bin/mongod --dbpath /usr/lib/unifi/data/db --port 27117 -->
    

Security

Unifi Cloud Controller requires the following ports open on your server:

  • 8443: Controller dashboard access.

  • 3478: UDP STUN port.

  • 8080: Inform port for device and application communications.

  1. Verify that the default UFW firewall is active on your server.

     $ sudo ufw status
    
  2. Allow each of the Unifi Cloud Controller ports through the firewall.

     $ sudo ufw allow 8443/tcp
    
    
    
     $ sudo ufw allow 3478/udp
    
    
    
     $ sudo ufw allow 8080/tcp
    
  3. Open the HTTP port 80 to allow Let's Encrypt verifications.

     $ sudo ufw allow 80/tcp
    
  4. Restart the firewall.

     $ sudo ufw reload
    

Setup SSL Certificates

  1. Install the Certbot Let's Encrypt client on your server.

     $ sudo apt install certbot -y
    
  2. Request a new SSL certificate for your domain name in standalone mode. Replace unifi.example.com with your actual domain name.

     $ sudo certbot certonly -d unifi.example.com --agree-tos
    
  3. To import your Let's Encrypt SSL Certificates to the Unifi Cloud Controller, create a new bash script using a text editor such as Nano.

     $ nano unifi.sh
    
  4. Add the following contents to the file. Replace unifi.example.com with your actual domain name. This MIT-licensed example from Steve Jenkins is available at https://github.com/stevejenkins/unifi-linux-utils.

     #!/usr/bin/env bash
    
    
    
     # UniFi Controller SSL Certificate Import Script for Unix/Linux Systems
    
     # by Steve Jenkins <http://www.stevejenkins.com/>
    
    
    
    
    
     # CONFIGURATION OPTIONS 
    
     UNIFI_HOSTNAME=unifi.example.com
    
     UNIFI_SERVICE=unifi
    
    
    
    
    
     UNIFI_DIR=/var/lib/unifi
    
     JAVA_DIR=/usr/lib/unifi
    
     KEYSTORE=${UNIFI_DIR}/keystore
    
    
    
    
    
     LE_MODE=true
    
     LE_LIVE_DIR=/etc/letsencrypt/live
    
    
    
    
    
    
    
    
    
     # CONFIGURATION OPTIONS YOU PROBABLY SHOULDN'T CHANGE
    
     ALIAS=unifi
    
     PASSWORD=aircontrolenterprise
    
    
    
     #### SHOULDN'T HAVE TO TOUCH ANYTHING PAST THIS POINT ####
    
    
    
     printf "\nStarting UniFi Controller SSL Import...\n"
    
    
    
     # Check to see whether Let's Encrypt Mode (LE_MODE) is enabled
    
    
    
     if [[ ${LE_MODE} == "YES" || ${LE_MODE} == "yes" || ${LE_MODE} == "Y" || ${LE_MODE} == "y" || ${LE_MODE} == "TRUE" || ${LE_MODE} == "true" || ${LE_MODE} == "ENABLED" || ${LE_MODE} == "enabled" || ${LE_MODE} == 1 ]] ; then
    
     LE_MODE=true
    
     printf "\nRunning in Let's Encrypt Mode...\n"
    
     PRIV_KEY=${LE_LIVE_DIR}/${UNIFI_HOSTNAME}/privkey.pem
    
     CHAIN_FILE=${LE_LIVE_DIR}/${UNIFI_HOSTNAME}/fullchain.pem
    
     else
    
     LE_MODE=false
    
     printf "\nRunning in Standard Mode...\n"
    
     fi
    
    
    
     if [[ ${LE_MODE} == "true" ]]; then
    
     # Check to see whether LE certificate has changed
    
         printf "\nInspecting current SSL certificate...\n"
    
     if md5sum -c "${LE_LIVE_DIR}/${UNIFI_HOSTNAME}/privkey.pem.md5" &>/dev/null; then
    
     # MD5 remains unchanged, exit the script
    
         printf "\nCertificate is unchanged, no update is necessary.\n"
    
         exit 0
    
     else
    
     # MD5 is different, so it's time to get busy!
    
        printf "\nUpdated SSL certificate available. Proceeding with import...\n"
    
        fi
    
       fi
    
    
    
     # Verify required files exist
    
      if [[ ! -f ${PRIV_KEY} ]] || [[ ! -f ${CHAIN_FILE} ]]; then
    
         printf "\nMissing one or more required files. Check your settings.\n"
    
         exit 1
    
      else
    
     # Everything looks OK to proceed
    
       printf "\nImporting the following files:\n"
    
       printf "Private Key: %s\n" "$PRIV_KEY"
    
       printf "CA File: %s\n" "$CHAIN_FILE"
    
       fi
    
    
    
     # Create temp files
    
     P12_TEMP=$(mktemp)
    
    
    
     # Stop the UniFi Controller
    
     printf "\nStopping UniFi Controller...\n"
    
     service "${UNIFI_SERVICE}" stop
    
    
    
     if [[ ${LE_MODE} == "true" ]]; then
    
    
    
      # Write a new MD5 checksum based on the updated certificate
    
      printf "\nUpdating certificate MD5 checksum...\n"
    
    
    
      md5sum "${PRIV_KEY}" > "${LE_LIVE_DIR}/${UNIFI_HOSTNAME}/privkey.pem.md5"
    
    
    
      fi
    
    
    
     # Create double-safe keystore backup
    
     if [[ -s "${KEYSTORE}.orig" ]]; then
    
         printf "\nBackup of original keystore exists!\n"
    
         printf "\nCreating non-destructive backup as keystore.bak...\n"
    
         cp "${KEYSTORE}" "${KEYSTORE}.bak"
    
     else
    
         cp "${KEYSTORE}" "${KEYSTORE}.orig"
    
         printf "\nNo original keystore backup found.\n"
    
         printf "\nCreating backup as keystore.orig...\n"
    
     fi
    
    
    
     # Export your existing SSL key, cert, and CA data to a PKCS12 file
    
     printf "\nExporting SSL certificate and key data into temporary PKCS12 file...\n"
    
    
    
     #If there is a signed crt we should include this in the export
    
     if [[ -f ${SIGNED_CRT} ]]; then
    
        openssl pkcs12 -export \
    
        -in "${CHAIN_FILE}" \
    
        -in "${SIGNED_CRT}" \
    
        -inkey "${PRIV_KEY}" \
    
        -out "${P12_TEMP}" -passout pass:"${PASSWORD}" \
    
        -name "${ALIAS}"
    
     else
    
         openssl pkcs12 -export \
    
         -in "${CHAIN_FILE}" \
    
         -inkey "${PRIV_KEY}" \
    
         -out "${P12_TEMP}" -passout pass:"${PASSWORD}" \
    
         -name "${ALIAS}"
    
      fi
    
    
    
     # Delete the previous certificate data from keystore to avoid "already exists" message
    
     printf "\nRemoving previous certificate data from UniFi keystore...\n"
    
     keytool -delete -alias "${ALIAS}" -keystore "${KEYSTORE}" -deststorepass "${PASSWORD}"
    
    
    
     # Import the temp PKCS12 file into the UniFi keystore
    
     printf "\nImporting SSL certificate into UniFi keystore...\n"
    
     keytool -importkeystore \
    
     -srckeystore "${P12_TEMP}" -srcstoretype PKCS12 \
    
     -srcstorepass "${PASSWORD}" \
    
     -destkeystore "${KEYSTORE}" \
    
     -deststorepass "${PASSWORD}" \
    
     -destkeypass "${PASSWORD}" \
    
     -alias "${ALIAS}" -trustcacerts
    
    
    
     # Clean up temp files
    
     printf "\nRemoving temporary files...\n"
    
     rm -f "${P12_TEMP}"
    
    
    
     # Restart the UniFi Controller to pick up the updated keystore
    
     printf "\nRestarting UniFi Controller to apply new Let's Encrypt SSL certificate...\n"
    
     service "${UNIFI_SERVICE}" start
    
    
    
     # That's all, folks!
    
     printf "\nDone!\n"
    
    
    
     exit 0
    

    Save the file.

  5. Make the script executable.

     $ sudo chmod +x unifi.sh
    
  6. Run the script.

     $ sudo ./unifi.sh
    

The script converts and imports the Let's Encrypt certificated to your Unifi Cloud Controller.

Setup the Unifi Cloud Controller

  1. Visit your domain name through a web browser of your choice.

     https://unifi.example.com
    
  2. Enter a name for your Network Application profile, check the agree to the product terms of service box, and click Next to proceed.

    Unifi Cloud Controller Web Page

  3. Enter your active Ubiquiti Account username and password to sync your account.

  4. Keep Auto Backup ON to enable automatic backups for your controller.

  5. On the Devices Setup page, click Next to set up your devices later.

  6. Set up your Wi-Fi network SSID and Password, or click Skip to set it up later.

  7. Review your Unifi Cloud Controller configurations and click Finish to configure the controller.

  8. When complete, the Unifi Cloud Controller dashboard displays. Use the left navigation menu to adopt Ubiquiti network devices and tweak your controller settings

  9. To connect Ubiquiti devices to your controller, log in to each device and set the Inform address to your domain name as below.

     set-inform https://unifi.example.com:8080/inform
    

Conclusion

You have installed Unifi Cloud Controller on a Debian 11 Server. You can use the controller to harness the power of your connected network devices with multiple features, optimization, user control, and captive portal settings.

Want to contribute?

You could earn up to $600 by adding new articles.