UISP - First Time Setup & Installation
Installation Guide
Short Version
If your server is running Ubuntu 22.04, or Debian 12, you can install UISP by running the command below:
curl -fsSL https://uisp.ui.com/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh
Notes
- The remainder of this article describes in more detail how to install a fresh copy of the UISP Application or update an existing installation on a self-hosted Linux platform. Unfortunately, proper operation, smooth backups, and upgrades of critical Docker containers cannot be ensured on Windows/MacOS systems so the UISP application works exclusively on Linux. For Windows/MacOS users we recommend that you install a virtualization program such as VirtualBox to run the latest version of supported Linux distribution, and then follow the Linux instructions provided below.
- It is recommended to install UISP on a console (server) that is equipped with a public IP address and FQDN, which is directly connected to the main gateway of the network. In this setup, UISP will automatically use a valid trusted certificate through Let's Encrypt, will report outages in the most precise manner, and all of its advanced functions will perform optimally. It is certainly possible to place the UISP console (server) in a different spot in a topology, but there may be some limitations involved.
- While it is not mandatory for UISP itself, using a UISP-branded gateway device (ex. UISP Console, UISP Router) provides the best experience with UISP Application. UISP-branded gateway devices (ex. UISP Console, UISP Router) or EdgeRouter devices running EdgeOS 2.0.2+ are also supported. UISP will work with other routers, including third-party hardware but some advanced features won't be enabled, e.g. easy shaping and suspension automatically linked to customers’ services.
Prerequisites
- Supported Distros (LXC virtualization is not officially supported. Please use KVM):
- Ubuntu 20.04 LTS (Focal Fossa) 64-bit
- Ubuntu 22.04.2 LTS (Jammy Jellyfish) 64-bit
- Debian 11 64-bit
- Debian 12 64-bit
- 3 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)
- 8089 (Local Web Interface Remote Access)
- Allow ping (see Devices Latency and Outage Statistics)
- A kernel with overlay2 storage driver (see Docker Storage Drivers)
- bash, curl, sudo
Installation Instructions
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/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.
NOTE: The installation script needs to use sudo permissions to install Docker in case it is not available in the OS already. The permissions are also needed to create the UISP user, under which the UISP application runs as well as to set up a cron task that manages the UISP updates.
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
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
ATTENTION:If you want UISP to use the default LetsEncrypt certificate please do not use any of these attributes.
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/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
ATTENTION: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.
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/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --http-port 8080 --https-port 8443
Changing the Device Inform Port
User Tip:The Inform port is the port that your devices are using for connecting to UISP.
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/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/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/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
User Tip: If you are using the private address range 172.x.x.x. in your network, you may prefer to change the default address of UISP docker containers in order to avoid any possible collision.
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/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/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --netflow-port 2205
Setting the Number of Workers (0.13.0+)
ATTENTION: Please do not set more workers than there are cores in your CPU. Make sure you have at least 0,5Gb memory for each worker as well. NOTE: Since 1.2.1+ it is possible to manually set up to 50 workers. This option is only suggested for UISP instances with several thousands of devices, CPU with more than 8 cores, and suffering from performance issues. Always make sure to follow the instructions from above.
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/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --workers auto
Limit access to GUI/API (0.14.0+)
NOTE: This only limits access to GUI/API. All devices can still connect to the UISP console (server) from any IP address, and this whitelist doesn't affect that connection at all.
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/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 reported as offline. This results in outage statistics being generated. Ping must be allowed to the UISP Host for this feature to work properly.
How to Install a Specific UISP Version
ATTENTION: Always read the release notes carefully. Release notes contain important information about known issues with the latest release. Sometimes it may be necessary to perform specific actions before the update to be safe. For safety reasons, we also strongly recommend creating a backup of UISP before any update. User Tip: All issues regarding non-final UISP versions are being discussed in the Early Access section of our community forum. You have to be subscribed to Early Access.
Use installation script argument --version <version> to install a specific UISP version other than the latest official release. This is for testing purposes only. In case it is necessary to go back to an earlier version, it is necessary to uninstall UISP, perform a clean install of the lower version, and apply the backup from that version. It is not possible to apply a higher version of the backup to a lower version of the application. Upgrading to a newer version, before it is officially released, can cause errors that will prevent further upgrades.
Use the --update flag to preserve the existing UISP configuration without having to specify all the installation arguments again.
curl -fsSL https://uisp.ui.com/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh --update --version x.x.x
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
User Tip: It is possible to use UISP API in order to create scripts for automated actions, like downloading a fresh backup to a remote location.
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.
NOTE: Regardless of the way the backup is created (automatic or full backup) it will always combine databases from both Network and CRM modules.
How to Restore UISP Backup
ATTENTION: For large instances, it can take dozens of minutes to apply the backup. Please, be patient and do not interrupt the process.
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/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>
User Tip: It is also possible to download a backup file and use it to restore the original instance during the UISP initial wizard. Look for the Have a backup line at the bottom of the first screen.
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/install > /tmp/uisp_inst.sh && sudo bash /tmp/uisp_inst.sh