Overview

This article describes how to install a fresh copy of UISP or update an existing installation on a console (self-hosted server/cloud platform). This is a guide for a Linux installation, see the following note for Windows and macOS operating systems:

Table of Contents

1. Installation Guide
   1. Prerequisites
   2. Installation Instructions
   3. Updating an Existing Installation
   4. Uninstalling UISP
2. Optional Installation Steps
   1. Managing the SSL Certificate for Access Via HTTPS
   2. Changing the HTTP and HTTPS Ports
   3. Changing the Device Inform Port
   4. Changing the Suspension Port
   5. Running UISP Behind a Reverse Proxy
   6. Changing the UISP Container's IP Address
   7. Changing NetFlow Listening Port
   8. Setting the Number of Workers
   9. Limit access to GUI/API
   10. UISP Data
   11. Devices Latency and Outage Statistics
3. How to Install a Specific UISP Version (ex. Beta)
4. UISP Backup Management
5. How to Restore UISP Backup
6. How to Install UISP on Cloud-Hosted Platform (ex. DigitalOcean, AWS)
7. Related Articles

Installation Guide

Back to Top

Generally speaking, Ubiquiti recommends running the UISP Application via the UISP Portal (uisp.ui.com), Ubiquiti's cloud-hosted platform for remote management. Conveniently, Ubiquiti hosts your UISP Application on our secure cloud platform for free using a name of your choice (ex. mydomain.uisp.com). After visiting the UISP Portal, you can instantly load the UISP Application in a matter of seconds to begin managing devices on your network.

The remainder of this article describes how to install a fresh copy of UISP or update an existing installation on a console (self-hosted server/cloud platform). This is a guide for a Linux installation, see the following note for Windows and macOS operating systems:

Prerequisites

• Supported Distros (LXC virtualization is not officially supported. Please use KVM):
  
  • Ubuntu 18.04 LTS (Bionic Beaver) 64-bit
  • Ubuntu 20.04 LTS (Focal Fossa) 64-bit
  • Debian 11 64-bit
• 2 GB RAM (Minimal)
• 16 GB of fast SSD storage (Minimal)
• 64-bit (x64) CPU with SSE 4.2 (Please note that SSE 4a is not sufficient)
• Locally used ports (see Changing the HTTP and HTTPS Ports for custom ports) 
  • 80 (Let's Encrypt certificate automation)
  • 81 (Suspension page)
  • 443 (UI, API, Devices connector)
• Allow ping (see Devices Latency and Outage Statistics)
• A kernel with overlay2 storage driver (see Docker Storage Drivers)
• bash, curl, sudo (see Installing Prerequisites)

Installation Instructions

Back to Top

Run the command below on the host to install and start UISP (it will automatically install Docker if it is not installed already). If a UISP installation already exists, it will be overwritten, but all data will be kept. It is possible to use the --update attribute if the new installation needs to have the same parameters as the old one. 

The command below will always install the newest, stable version that is listed in the Software Releases section on the Ubiquiti Community. To view, select the Stable status, followed by the UISP tag in the General section.

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh

During the installation process, the script will check if TCP port 80 and TCP port 443 are open/available. If the ports are in use, the script will pause and ask which ports should be used by UISP. The same applies to the overcommit memory settings. If the vm.overcommit_memory is not set to '1', the installation script asks for permission to enable it. In case those interrupts are unwanted in the installation process it is possible to suppress them with --unattended attribute which lets the installation script do all the necessary arrangements by itself.

When the process is complete, UISP will be accessible at the https://<ip or hostname> address. Please do not use localhost to connect to UISP.

Registering new devices to UISP can be done by following the steps in the UISP Site & Device Management article. If it is necessary to customize the installation process, follow the Optional Installation Steps listed below. If you wish to install a UISP version that is not the current/stable version (ex. Beta), follow the steps in the How to Install a Specific UISP Version (ex. Beta) section below.

Updating an Existing Installation

Back to Top

Once installed, UISP will periodically check for new updates and prompts for installation. Verify whether UISP is up to date and the version that is installed in the    Settings > Maintenance section. It is also possible to manually check for updates in this section.

We recommend using the Web UI update method over manually updating through the CLI. It is highly suggested to create a full backup of UISP before using the CLI method.

Uninstalling UISP

Here we discuss how to uninstall a self-hosted UISP console and optionally, delete all data. This also assumes that the administrator has access to the server command line.

NOTE: The UISP Cloud controller is deleted from the Cloud Access Portal.

Run the command below as a sudo user to completely stop the UISP service and remove all UISP docker containers.

sudo /home/unms/app/unms-cli stop

This command will not remove your settings or data. If you want to remove everything, delete or rename the /home/unms/data and /home/unms/app directories. Please be aware that UISP backups are located in the /home/unms/data/unms-backups/backups/ folder so make sure not to delete them by accident.

Optional Installation Steps

Managing the SSL Certificate for Access Via HTTPS

By default, UISP uses Let's Encrypt to automatically create and manage an SSL certificate for its domain name. The certificate is saved under /home/unms/data/cert/live .
If you need to use your own certificate you can use the following installation script arguments to do it:
--ssl-cert-dir <DIRECTORY> : This is a path to a directory where the certificate is located.
--ssl-cert <FILENAME> : This is the filename of the certificate.
--ssl-cert-key <FILENAME> : This is the filename of the certificate key.
Some older certificates have a separate certification authority key. Use this optional attribute to set it:
--ssl-cert-ca <FILENAME> : This is the filename of a certification authority's key.
Make sure that UISP has read-permission on the certificate directory and all files. Remember that you can have each file in a custom folder as long as those folders are subfolders of --ssl-cert-dir

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --http-port 8080 --https-port 8443 --ssl-cert-dir /etc/certificates --ssl-cert fullchain.pem --ssl-cert-key privkey.pem

Changing the HTTP and HTTPS Ports

Use installation script arguments --http-port <NUMBER> and --https-port <NUMBER> to configure the UISP console (server) to listen on non-standard ports. Defaults are 80 (HTTP) and 443 (HTTPS).

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --http-port 8080 --https-port 8443

Changing the Device Inform Port

Please be aware that UISP must be accessible from the internet via HTTP port 80 if you want to use automatic SSL certificate management via Let's Encrypt. Using a separate inform port is useful when you need to expose the port outside your private network, but don't want to expose the UISP GUI. Use installation script argument --ws-port <NUMBER> to configure the UISP WebSocket server to use a separate port for communication with your devices.

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --ws-port 8444

Changing the Suspension Port

The suspension page is by default set to port 81. That port can be changed with this optional tag:

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --suspend-port 8081

Running UISP Behind a Reverse Proxy

Use installation script arguments --public-https-port <NUMBER>and --public-ws-port <NUMBER> if you plan to run UISP behind a reverse proxy server. The setting --public-https-port is only necessary if the proxy listens for HTTPS on a different port than UISP. The setting --public-ws-port is only necessary when you use --ws-port (as mentioned in the section above) to separate the inform port from the HTTPS port.

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --public-https-port 443 --http-port 8080 --https-port 8443

Please be aware that this puts the responsibility of managing an SSL certificate on the reverse proxy and disables the automatic certificate management via Let's Encrypt. The reverse proxy must still use HTTPS for communication with UISP, optionally with a custom SSL certificate. HTTP-only communication between UISP and the reverse proxy is not supported. The UISP - Reverse Proxy article shows working reverse proxy configurations for Nginx and Apache.

Changing the UISP Container's IP Address

Use the installation script argument --subnet <CIDR> to change the UISP container's subnet if you experience IP address conflicts. It should be enough to specify /27 subnet, which is then split in half. One half is used by the Docker for internal and the second one for external connections. 

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --subnet 172.45.0.1/24

You may also wish to change the IP address of the docker0 bridge created by Docker. See the docker user guide for more information. Please note that this may affect containers other than UISP running on your system.

Changing NetFlow Listening Port (0.13.0+)

In order to change the listening port for NetFlow use --netflow-port PORT custom installation attribute.

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --netflow-port 2205

Setting the Number of Workers (0.13.0+)

It is possible to set how many parallel processes should be used to communicate with devices with the install argument --workers COUNT. The value of COUNT can be either a number from 1 to 50 or auto. The auto tag means that UISP will decide how many workers to use depending on the number of CPU cores and available memory. Please note that the auto value will not set up more than 8 cores. 

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --workers auto

Limit access to GUI/API (0.14.0+)

You can create a whitelist of IP addresses that are allowed to access UISP GUI and API. When this tag is used UISP GUI will be inaccessible from any address which is not defined in the whitelist.

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --ip-whitelist "193.86.83.186,ff::ff/25"

UISP Data

By default, the installation script ensures that the application settings and data (logs, site images, encryption key, etc.) are stored outside of the docker container (/home/unms/data ). This will enable you to back up that data, and more importantly, this will enable you to perform any future UISP upgrades without any data loss.

Devices Latency and Outage Statistics

By default, all devices connected to UISP will ping the UISP host to check for latency if any devices are being reported as offline. This results in outage statistics being generated. Ping must be allowed to the UISP Host for this feature to work properly.

curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --version 1.1.0-beta.3 --update

How to Backup UISP Application Data

Automatic/manual backup

For most users, it may be most convenient to use the automatic backup feature available since version 1.0.0. The list of automatic backups is available under Settings > Backups. At the same place, a fresh manual backup can be initialized in case the automatic one is too old. It is also possible to apply older backup here. These backups are automatically stored at /home/unms/data/unms-backups in this format:
2020101502000000-auto-1.2.7.unms 
Date - auto/manual - unms version.unms

Full backup (Archive)

In order to keep the size of automatic backups manageable, only the essential data is stored. For example, automatic backup doesn't contain stored firmware files. It is possible to create a full backup with absolutely everything on the UISP system, by making an archive from the /data folder. The folder is located on this path /home/unms/data on the Docker host and includes settings, logs, statistics, images, backups, and SSL certificates. In order to back up this data, it is necessary to pause the running containers. Then go to the directory, where docker-compose.yml is located (probably /home/unms). Then archive the data and save it somewhere safe. As the final step, unpause the containers.

# go to your UISP home directory
cd /home/unms
#stop docker containers 
sudo /home/unms/app/unms-cli stop
# pack the data directory 
sudo tar -cvjSf uisp-data.tar.bz2 data 
# start docker containers 
sudo /home/unms/app/unms-cli start

This set of commands will create an archive for all UISP settings and data. Then it can be moved to another machine or archive.

How to Restore UISP

Restore Automatic/manual backup

In the UISP user interface, just go to the section Settings > Backups and click on the Restore from file button. 

If the UISP GUI is not available here is a process on how to restore it from CLI.

# stop docker containers 
sudo /home/unms/app/unms-cli stop
# rename the current data folder
sudo mv /home/unms/data /home/unms/data_old
# run the installation script (make sure to include any optional tag that was used in previous installation)
sudo curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh
# show a list of all older automatic/manual backups
sudo ls -l /home/unms/data_old/unms-backups/backups/
# select the desired backup's name and restore it
sudo /home/unms/app/unms-cli restore-backup --file /home/unms/data_old/unms-backups/backups/<selected filename>

Restore Full backup (Archive)

Only the automatic/manual backup can be applied through GUI. Each full backup (archive) has to be applied through the command line. Please note that the archive 'uisp-data.tar.bz2' from the section above will be needed.

# go to your UISP home directory
cd /home/unms
#stop docker containers 
sudo /home/unms/app/unms-cli stop
#rename the current data folder
sudo mv data data_old
#create the empty data folder
sudo mkdir data
# extraxt the data directory 
sudo tar -xvjSf uisp-data.tar.bz2 data 
# run the installation script (make sure to include any optional tag that was used in previous installation)
sudo curl -fsSL https://uisp.ui.com/v1/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh

Related Articles

Back to Top

UISP - Site & Device Management