This article describes additional features of the UISP installation process. It includes instructions on how to change ports in order to have access through the GUI; how to set ports for communication with devices; how to work behind a proxy and other initial configurations. See the table of contents below for a list.
- See the Installation Guide article for the UISP installation prerequisites.
- Unfortunately, proper operation, smooth backups, and upgrades of critical Docker containers cannot be ensured on Windows and macOS systems.
- At this time we recommend that you install a virtualization program such as VirtualBox to run the latest version of Ubuntu 18.04.3 (Bionic Beaver) 64-bit and then follow the Linux instructions provided below.
Table of Contents
- Installing Prerequisites
- Managing the SSL Certificate for Access Via HTTPS
- Changing the HTTP and HTTPS Ports
- Changing the Device Inform Port
- Changing the Suspension Port
- Running UISP Behind a Reverse Proxy
- Changing the UISP Container's IP Address
- Changing NetFlow Listening Port
- Setting the Number of Workers
- Limit access to GUI/API
- UISP Data
- Devices Latency and Outage Statistics
- Related Articles
Run the following commands on the Ubuntu or Debian system to ensure that all required tools are installed:
sudo apt-get update sudo apt-get install curl sudo bash
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
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
curl -fsSL https://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_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
to configure the UISP server to listen on non-standard ports. Defaults are 80 (HTTP) and 443 (HTTPS).
curl -fsSL https://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_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
to configure the UISP WebSocket server to use a separate port for communication with your devices.
curl -fsSL https://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_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://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_inst.sh --suspend-port 8081
Running UISP Behind a Reverse Proxy
Use installation script arguments
--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
(as mentioned in the section above) to separate the inform port from the HTTPS port.
curl -fsSL https://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_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
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://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_inst.sh --subnet 126.96.36.199/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://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_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 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://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_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://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_inst.sh --ip-whitelist "188.8.131.52,ff::ff/25"
- AWS, EC2 instance, t2.small (2 GB RAM), Ubuntu 16.04.1 LTS (Xenial Xerus)
- DigitalOcean, basic droplet (2 GB RAM), Ubuntu 16.04.1 LTS (Xenial Xerus)
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 (
). 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.