×

UNMS - Command Line Interface (CLI )

Overview

Readers will learn the format of certain UNMS-related CLI commands that can be used on self-hosted UNMS installations. 

NOTES & REQUIREMENTS:
  • Applicable to the latest UNMS release version on self-hosted UNMS installations.
  • Use the commands listed in this article with caution and only when there is a good reason to do so.
  • The commands listed in this article are intended to be used by network administrators that have knowledge of the Linux CLI.
  • More information on the Ubiquiti Network Management System can be found on the UNMS website.

Table of Contents

  1. Introduction
  2. Stopping and (re)starting UNMS
  3. Set the Superadmin Role
  4. Recovering Passwords and Disabling Two-Factor Authentication (2FA)
  5. Refreshing the Let's Encrypt Certificate
  6. Fixing a Rewriting a Redis Append Only File (AOF)
  7. Reducing the Device Update Frequency
  8. Clearing and Restoring UNMS and Device Backup Files
  9. Changing the Processor Worker Count
  10. Whitelisting IP Addresses for the Web UI and API
  11. Related Articles

Introduction

ATTENTION: Use the commands listed in this article with caution and only when there is a good reason to do so.

Below you will find some useful console commands for self-hosted UNMS installations. You can use these commands to restart the UNMS instance or restoring a backup. Run all the commands listed in this article from a user account that has sudo privileges. Use the --help flag at the end of a command to list the available options.

Stopping and (re)starting UNM

Run the command below to restart/rebuild all UNMS containers. 

sudo ~unms/app/unms-cli restart

Run the command below to stop all UNMS containers. 

sudo ~unms/app/unms-cli stop

Run the command below to start all UNMS containers.

sudo ~unms/app/unms-cli start

Set the Superadmin Role

The Superadmin role is necessary for access to the CRM module. The command below sets the specified user as a super admin.

sudo ~unms/app/unms-cli set-superadmin --username <username>

Running this command without the --username option will list all users that are currently set as super admin:

sudo ~unms/app/unms-cli set-superadmin

Recovering Passwords and Disabling Two-Factor Authentication (2FA)

Run the command below to change the password for a specific user:

sudo ~unms/app/unms-cli set-password --username <username>

The command below will disable two-factor authentication (2FA) for a specific user:

sudo ~unms/app/unms-cli disable-two-factor --username <username>

Running these command without the --username option will list all users:

sudo ~unms/app/unms-cli set-password
sudo ~unms/app/unms-cli disable-two-factor

Refreshing the Let's Encrypt Certificate

This command refreshes Let's Encrypt certificate. 

sudo ~unms/app/unms-cli refresh-certificate

Fixing a Rewriting a Redis Append Only File (AOF)

Run the below commands to fix a corrupted appendonly.aof Redis Append Only File (OAF), which can be located in the /home/unms/data/redis/ directory. 

sudo ~unms/app/unms-cli stop
sudo ~unms/app/unms-cli fix-redis-aof
sudo ~unms/app/unms-cli start

The below command forces the Redis AOF to recalculate. UNMS has to be running in order for this command to work.

sudo ~unms/app/unms-cli rewrite-redis-aof

This command is useful when the size of the /home/unms/data/redis/appendonly.aof file is too large.   Note that you will need a lot of free disc space in order to complete this process. If you are working with limited space, then it is recommended to delete some of the older UNMS log files before running the command.

Reducing the Device Update Frequency

This command reduces the UNMS device update frequency, which is helpful when your UNMS instance is overloaded and it is not possible log into the Web UI. 

sudo ~unms/app/unms-cli reduce-device-update-frequency

Clearing and Restoring UNMS and Device Backup Files

Use the following command to clear the backup files of devices that are connected to the UNMS server:

sudo ~unms/app/unms-cli clear-device-backups

Use the following command to restore the UNMS server from a selected backup file.

sudo ~unms/app/unms-cli restore-backup --file <backup-file>
NOTE: The most recent/latest automatic backup file is used if you do not specify the --file option.

Changing the Processor Worker Count

ATTENTION: The <count> value should not be higher than the actual number of available CPU cores. It is possible to set this value to auto in order to let UNMS decide how many workers it needs. It is recommended to have at least 0.5 Gb (500Mb) of free RAM available for each worker.

Set the number of worker processes to the desired value (count) or use auto:

sudo ~unms/app/unms-cli set-workers <count>
sudo ~unms/app/unms-cli set-workers auto

Whitelisting IP Addresses for the Web UI and API

The following commands will allow you to specify which source IP addresses are allowed to access the UNMS Web UI and API.

Show current whitelist:

sudo ~unms/app/unms-cli ip-whitelist --show

Create a new whitelist:

sudo ~unms/app/unms-cli ip-whitelist --set "203.0.113.1,198.51.100.0/25,2001:db8:12:34::/64"

Clear the whitelist to allow access from all addresses:

sudo ~unms/app/unms-cli ip-whitelist --clear
NOTE: This only limits the source IP addresses that are allowed to connect to the UNMS Web UI and API. Devices connecting to UNMS are not affected by this whitelist.

Related Articles

UNMS - How to Restart UNMS

UNMS - How to Back Up UNMS

UNMS - How to Find Logs and Report Bugs

Was this article helpful?
2 out of 4 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community