Command-line reference

Every uplivra command, what it does and where to run it. The same list is built into the program: type uplivra help, or uplivra help COMMAND for one command.

How to run them

• Uplivra appliance: sign in as uplivra and type the command. No sudo: Uplivra asks for the rights a command needs by itself, and only for Uplivra's own commands.
• Server or collector you installed yourself: run them as root, or as a member of the uplivra group.
• Windows: open a command window as administrator and type uplivra the same way.

Every command

Start here

Search

DNS and time

Network and remote access

People, passwords and keys

Backups, upgrades and services

Run by the system

For scripts

• Results go to standard output and messages to standard error, so > and | only carry the results.
• Commands that list things take -json.
• Exit codes are the same for every command:

uplivra help

List the commands, or show how to use one. Run it on any computer with Uplivra.

uplivra help
uplivra help dns
uplivra help -json

uplivra setup

Install Uplivra (server, collector, log collector or MSP master), or upgrade it. Run it on a new Linux computer, or one to upgrade.

Set up this computer as an Uplivra server, collector, log collector or MSP
master collector. It asks a few questions, checks the
hardware and the network, then installs everything.

  uplivra setup                       answer the questions
  uplivra setup -answers setup.json   unattended (same questions, from a file)
  uplivra setup -dry-run              show what would be done, change nothing
  uplivra setup -appliance            the Uplivra appliance's first boot

Run it again at any time to upgrade the program; your settings are kept.

uplivra join

Connect this collector to your Uplivra server with a setup code. Run it on a collector or appliance.

Connect this collector to your Uplivra server.

In Uplivra: Settings › Sites and collectors › your site › Connect a collector.
It shows the server address, a one-time setup code and the certificate
fingerprint. Then, on this collector (over SSH you can paste):

  uplivra join                         asks for each
  uplivra join -server https://uplivra.example.com -code uv_enr_...

The collector's management page (https://<this computer>/) does the same.

uplivra version

Show which version of Uplivra this is. Run it on any computer with Uplivra.

uplivra version

uplivra terms

Show the license terms. Run it on any computer with Uplivra.

uplivra terms

uplivra devices

Find devices by name, address, maker, model, type, tags or status. Run it on the Uplivra server.

Search Uplivra from the command line (on the Uplivra server).
Run as root, as uplivra on an appliance, or as a member of the uplivra group.

  uplivra logs [WORDS] [options]     Log messages and SNMP traps, newest first
      -from DEVICE      one device (name or address)
      -since 1h         how far back: 15m, 1h, 24h (default), 7d, 30d
      -severity error   critical, error or warning (and worse)
      -kind trap        trap or syslog
      -limit 200        most messages to show
      -f                keep going: print new messages as they arrive
      -oldest           oldest first (handy with grep and tail)
    WORDS are the same plain words as the Logs page search box:
      uplivra logs failed login
      uplivra logs "link down" not test
      uplivra logs errors from lab-fw-01 last 2 hours
      uplivra logs /fail(ed|ure)/              (a regular expression)

  uplivra devices [WORDS] [-status down] [-site NAME]
      Devices whose name, address, vendor, model, type, tags or OS match.
      uplivra devices down          (the word "down" works too: up, warn, down, unknown)
      uplivra devices switch -site Lab
  uplivra alerts [-all]             Open alerts (-all: recent closed ones too)
  uplivra notices                   What Insights spotted
  uplivra ask "QUESTION"            Ask Insights (built-in analysis)
      uplivra ask "why is lab-sw-01 slow?"
      uplivra ask "what changed in the last 7 days?"
      uplivra ask -search "failed logins on the firewall today"
                                    (shows the log search it would run, and runs it)

Options for every command:
  -json             JSON instead of text, for scripts
  -org NAME         an organization other than your own (service providers)
  -config FILE      the server config (default `/etc/uplivra/server.json`)

Examples with other tools:
  uplivra logs denied -since 7d | grep -c 203.0.113.9
  uplivra logs -kind trap -since 24h | sort | uniq -c | sort -rn | head
  uplivra devices -json | jq -r '.[] | select(.status=="down") | .name'

uplivra alerts

List open alerts (-all: recent closed ones too). Run it on the Uplivra server.

Full options: see uplivra devices.

uplivra alerts
uplivra alerts -all -json

uplivra notices

List what Insights spotted. Run it on the Uplivra server.

Full options: see uplivra devices.

uplivra notices

uplivra ask

Ask Insights a question in plain words. Run it on the Uplivra server.

Full options: see uplivra devices.

uplivra ask "why is lab-sw-01 slow?"
uplivra ask "what changed in the last 7 days?"

uplivra logs

Search log messages and traps; on a log collector, read and check the archive. Run it on the Uplivra server (search) or a log collector (archive).

Full options: see uplivra devices.

uplivra logs failed login
uplivra logs -from lab-fw-01 -since 2h
uplivra logs archive -from 2026-09-01 -text denied

The log collector's archive (on the server, "uplivra logs WORDS" searches the
server's own logs instead: see above). Run these on the log collector, or on any
computer with a copy of the archive (for example files restored from the
off-site copy) and its key.

Usage:
  uplivra logs archive [-from 2026-09-01] [-to 2026-09-25] [-text words] [-source 10.0.0.1] [-limit 500]
  uplivra logs verify         Check every file against the hash chain
  uplivra logs usage          Size, oldest message and disk space
  uplivra logs read FILE      Print one archive file (.ulog) as text

Options for every command:
  -config collector.json      Find the archive and key from the collector's settings
  -dir DIR -key FILE          Or name them directly (for restored copies; the key
                              can be downloaded from the collector's page in Uplivra)

uplivra dns

Uplivra's DNS server: zones, records, CSV import and export, lookups and tests. Run it on the Uplivra server (zones and records); any computer (lookups and tests).

Uplivra's DNS server from the command line: zones and records, the DNS
servers' upstreams and forwarders, and lookups and tests.

Zones and records (on the Uplivra server):
  uplivra dns zones                                  list the zones
  uplivra dns zone add office.example.com [-ttl 300] [-auto-dhcp] [-auto-ipam] [-note TEXT]
  uplivra dns zone remove office.example.com [-yes]
  uplivra dns records office.example.com             its records (# is each one's number) and automatic names
  uplivra dns add office.example.com printer A 192.168.10.20 [-ttl 300] [-if-missing]
  uplivra dns add office.example.com @ MX mail.example.com. -priority 10
  uplivra dns add office.example.com _sip._tcp SRV pbx -priority 10 -weight 5 -port 5060
  uplivra dns add office.example.com @ TXT "v=spf1 mx -all"
  uplivra dns set office.example.com www CNAME web1  make www exactly this (adds or replaces)
  uplivra dns edit office.example.com 42 -value 192.168.10.21   change record 42
  uplivra dns delete office.example.com 42           remove record 42
  uplivra dns delete office.example.com printer A [VALUE]   remove by name and type
  uplivra dns find 192.168.10.20                     every record, in every zone, with this in its name or value
  uplivra dns import office.example.com zone.csv [-replace] [-dry-run]
      A CSV or a BIND-style zone file. -dry-run shows what would change and
      changes nothing. Exact copies of records already there are left out.
  uplivra dns import -all all-zones.csv [-dry-run]   a CSV with a zone column, into those zones
  uplivra dns export office.example.com [-csv] [-automatic] > office.csv
      A zone file (or CSV). -automatic adds the names made from DHCP leases and
      IP reservations, marked as such; importing leaves them out.
  uplivra dns export -all [-automatic] > all-zones.csv   every zone, as CSV
  uplivra dns batch changes.txt [-dry-run]           many changes at once: all of them, or none
      One change a line, the same words as above without "uplivra dns":
        add office.example.com printer A 192.168.10.20
        set office.example.com www CNAME web1
        delete office.example.com fax A
  uplivra dns secondaries office.example.com         servers allowed to copy the zone

The DNS servers (on the Uplivra server, or on a DNS appliance for itself):
  uplivra dns status                                 each DNS server: on, listening, queries, problems
  uplivra dns upstreams [-check] [-ask NAME]         where other names are looked up; -check asks each now
      (DNS over TLS with its certificate name checked, and whether answers are
      DNSSEC-checked)
  uplivra dns forwarders [-check] [-ad]              domains sent to other DNS servers; -check asks each
      one for the zone's SOA, and -ad looks for Active Directory domain controllers
  uplivra dns compare office.example.com             the zone's serial on every DNS server and secondary

Lookups and tests (any computer, no rights needed):
  uplivra dns lookup printer.office.example.com [-type AAAA] [-server 192.168.10.2]
      The answer in plain words. An IP address looks up its name.
  uplivra dns dig [@192.168.10.2] example.com [MX] [+short] [+tcp] [+tls] [+dnssec] [+norecurse] [+trace] [-x ADDRESS]
      dig's usual output. +tls asks over DNS over TLS (port 853), +trace follows
      the name down from the root servers.
  uplivra dns test printer.office.example.com [-type A] [-server 192.168.10.2]
      Ask a DNS server and explain the answer, with the reason for a block.

For scripts:
  -json        JSON instead of text (every command)
  -q           print nothing; use the exit code
  -yes         don't ask before replacing or removing (needed when no one is at the keyboard)
  -dry-run     show what would change; change nothing
  -            in place of a file name: read standard input
  -timeout 4s  how long to wait for each DNS answer
  Exit codes: 0 done, 1 failed, 2 wrong use, 3 not found or a check failed
  (a name that doesn't exist, an upstream that didn't answer, nothing found).

  uplivra dns export office.example.com -csv | grep -c ',A,'
  uplivra dns lookup www.example.com -q || echo "www.example.com doesn't resolve"
  uplivra dns upstreams -check -json | jq '.[].checks[] | select(.ok == false)'

On an appliance, sign in as uplivra and type these without sudo. Every change
is in the audit log with who made it. The same can be done from anywhere with
the management API (/api/v1/dns/...) and a token.

uplivra ntp

Uplivra's NTP server: is it passing the time on, to how many devices; test any NTP server. Run it on a collector or appliance that serves time (status); any computer (test).

Uplivra's NTP server: a collector hands its clock to the devices on its
networks. Turn it on in the web interface (Network › NTP server).

  uplivra ntp status                 the NTP server on this computer (on the Uplivra
                                     server: every collector's): passing the time on
                                     or not and why, stratum, the time server it is
                                     compared with, devices in the last hour, answers
  uplivra ntp test SERVER            ask any NTP server (a name or address, :port if
                                     not 123) and say how far its time is from this
                                     computer's, its stratum and reference

Options: -json (JSON), -q (print nothing; use the exit code), -timeout 4s.
Exit codes: 0 fine, 1 failed, 2 wrong use, 3 the server didn't answer, or an
NTP server here isn't passing the time on.

  uplivra ntp test 192.168.10.2 -q || echo "no time from 192.168.10.2"

uplivra firewall

Open the firewall for a while, for a vulnerability scan. Run it on an Uplivra appliance.

Open this appliance's firewall for a while, for a vulnerability scan that
needs every port reachable. Every window closes by itself.

  uplivra firewall                        show the firewall and any open window
  uplivra firewall open PORTS [-from ADDRESS] [-for 4h] [-reason TEXT]
                                          open ports: 22,443/tcp,1000-2000/udp or all
                                          (-from: only from the scanner's address or network)
  uplivra firewall off [-for 4h] [-reason TEXT]
                                          turn the firewall off completely
  uplivra firewall close                  close the window now

-for is 10m to 7d (default 4h). Administrators can do the same in the web
interface (Settings › Firewall for scans). Type it without sudo: Uplivra asks
for the rights for this command only.

uplivra ports

The ports this computer needs open, in and out. Run it on any computer with Uplivra.

Shows the ports this computer needs open, incoming and outgoing, from its
settings. Give these to whoever manages your firewalls.

Usage:
  uplivra ports                  this computer
  uplivra ports -mode msp-master another kind of computer
  uplivra ports -all             every kind

uplivra remote-access

Remote support through this collector: on, off, approval. Run it on a collector or appliance.

Remote support through this collector: SSH, Remote Desktop and web pages to
this computer or to devices on its network, from the Uplivra web interface,
carried inside the collector's own HTTPS connection (nothing new is opened in
the firewall). Off until turned on here.

  uplivra remote-access                 show the settings
  uplivra remote-access on              turn it on (asks a few questions)
  uplivra remote-access network         this computer and devices on its network
  uplivra remote-access this-computer   this computer only
  uplivra remote-access off             turn it off
Options (with any of the above):
  -approval always      technicians connect without asking (default)
  -approval ask         every session needs approval (in Uplivra, or on this
                        collector's management page)
  -approval ask-local   every session needs approval on this collector's
                        management page, and only there
  -ports 22,3389,443    which ports sessions may reach
  -local-only yes       only this computer may change these settings; the Uplivra
                        web interface can't turn remote access on (no = allow it)

Administrators can also turn it on or off in the web interface (Remote access
› Collectors), unless -local-only is set. A change made here replaces one made
there.

uplivra connect

Connect your own program (Remote Desktop, PuTTY, a browser) through a remote session. Run it on your own computer.

Connects your own program (Remote Desktop, SecureCRT, PuTTY, a browser) to a
device through an approved Uplivra remote session.

  uplivra connect "https://uplivra.example.com/remote/.../connect#t=..."

Copy the whole command from the session's page in Uplivra. Leave this window
open while you work; press Ctrl+C to stop.

uplivra status-page

The collector's own HTTPS management page: port, password, who may open it. Run it on a collector or appliance. Also called uplivra management-page.

The collector's management page: a small HTTPS page on the collector itself
that shows whether it can reach your Uplivra server, its clock, disk, roles
and log storage. Useful exactly when the server can't be reached.
("uplivra management-page" is the same command.)

Usage:
  uplivra status-page -port 443             turn it on (asks for a password)
  uplivra status-page -port 9443            move it to another port
  uplivra status-page                       set a new password
  uplivra status-page -allow 10.0.0.0/24    only allow these networks
  uplivra status-page -port 0               turn it off
  uplivra status-page -certbot status.example.com
                                                 a trusted Let's Encrypt certificate
                                                 through certbot (renewed automatically)
  uplivra status-page -certbot off          back to the certificate chosen in Uplivra

Then open https://<this computer>/ in a browser (add :<port> if it isn't 443).
On an MSP master collector the page shares its port with customer collectors;
moving the page moves where they connect only if the relay uses the same port.

uplivra cert

Company certificates: make a signing request, check a certificate, store one in Uplivra. Run it on any computer with Uplivra.

Company certificates for Uplivra. The same things can be done in the web
interface under Settings > Certificates.

On any computer (makes files; no server needed):
  uplivra cert csr   -cn NAME [-san "name2,10.0.0.5"] [-org "Acme"] [-country US] [-key-type ecdsa-p384] [-out DIR]
                     Makes a private key (NAME.key.pem) and a signing request (NAME.csr)
                     to send to your certificate authority.
  uplivra cert check -cert FILE [-key FILE]
                     Shows a certificate and checks it matches the key and is in date.

On the server (stored in Uplivra, key kept encrypted):
  uplivra cert list   [-config server.json]
  uplivra cert import -name NAME -cert FILE -key FILE [-use web|relay|web,relay] [-config server.json]
  uplivra cert use    -name NAME -use web|relay|web,relay|none [-config server.json]

For a relay collector, put the files in collector.json instead:
  "relay": {"tls_cert": "/etc/uplivra/relay.pem", "tls_key": "/etc/uplivra/relay.key.pem"}

Key types: ecdsa-p384 (default), ecdsa-p256, rsa-4096, rsa-3072.

uplivra user

Who can sign in to the web interface: add, reset a password, turn off. Run it on the Uplivra server.

Manage the people who can sign in to the Uplivra web interface.
Run these on the server computer.

Usage:
  uplivra user <command> [options]

Commands:
  add              Create a sign-in (asks for the password)
  list             Show everyone who can sign in
  reset-password   Set a new password for someone (signs them out everywhere)
  reset-two-step   Turn off someone's two-step sign-in (lost or replaced phone)
  disable          Turn off someone's sign-in
  enable           Turn it back on

Roles:
  admin    can change settings, devices and alerts
  viewer   can look but not change anything (good for office staff)

Examples:
  uplivra user add -email you@yourcompany.com -name "Your Name" -role admin
  uplivra user add -email frontdesk@yourcompany.com -name "Front Desk" -role viewer
  uplivra user reset-password -email you@yourcompany.com
  uplivra user reset-two-step -email you@yourcompany.com
  uplivra user list

Every command accepts -config (default server.json).

uplivra token

API tokens for scripts and other software. Run it on the Uplivra server.

API tokens let scripts and other software use the Uplivra API.

Usage:
  uplivra token create -name "backup script" [-read-only] [-days 90]   make one (shown once)
  uplivra token list                                        see them (never their values)
  uplivra token revoke -id 3                                stop one working at once

A read-only token can only read (GET). Tokens expire after -days (default 90,
at most 365). Keep tokens like passwords.

Tokens only work while the management API is turned on (Settings › API in the
web interface; it is off on new servers). Tokens can also be made there, with
access profiles, sites and address limits.

uplivra vault

The passwords this collector uses to log in to devices. Run it on a collector or appliance.

Manage the passwords this collector uses to log in to devices.
Passwords are stored encrypted on this machine and are never sent to the server.

Usage:
  uplivra vault <command> [options]

Commands:
  init           Create an empty vault (do this once per collector)
  list           Show saved credentials (names only, never passwords)
  set-snmp       Save an SNMP community (v1/v2c) or SNMPv3 user
  set-ssh        Save an SSH login for Linux servers and network gear
  set-windows    Save a Windows login
  delete         Remove a credential
  import FILE    Move an old plain-text credentials.json into the vault

Every command accepts -config (default collector.json) to find the vault.

Examples:
  uplivra vault init
  uplivra vault set-snmp -name core-v2
  uplivra vault set-snmp -name core-v3 -v3 -user monitor -auth SHA256 -priv AES
  uplivra vault set-ssh -name linux-servers -user monitor
  uplivra vault set-ssh -name firewalls -user admin -key-file C:\keys\fw.pem
  uplivra vault set-windows -name domain -user svc-monitor -domain CORP
  uplivra vault delete -kind snmp -name core-v2

After saving a credential, use its name in a check, e.g.
  {"type":"snmp","config":{"credential_ref":"core-v2"}}

uplivra ldap

Check the Active Directory / LDAP sign-in settings. Run it on the Uplivra server.

Check the Active Directory / LDAP sign-in settings in server.json.

Usage:
  uplivra ldap test -user jdoe [-config server.json]

It connects to the directory with the service account, looks the person up,
shows which Uplivra role they would get, and can test their password.

uplivra backup

Back up the database and keys (to /var/backups/uplivra). Run it on the Uplivra server.

uplivra backup
uplivra backup -settings-only
uplivra backup -show-key
uplivra backup -verify FILE

uplivra restore

Restore a backup. Run it on the Uplivra server.

uplivra restore -from /var/backups/uplivra/FILE.uvbak

uplivra upgrade

Upgrade from an offline update package. Run it on the Uplivra server or a collector.

Upgrade Uplivra on this computer from an offline update package
(download it from the Uplivra portal: Downloads > Offline update package).

  uplivra upgrade -package uplivra-26.10.1-update.tar.gz

The package's signature and every file are checked first. Test updates in
a lab or development environment before upgrading production. If the new
version doesn't start, the previous one is put back.

uplivra service

Status, start, stop, restart and logs of the Uplivra services. Run it on the Uplivra server or a collector.

uplivra service status
uplivra service restart collector
uplivra service logs server -n 100 -f

uplivra system

The system helper: applies settings from the server (you don't normally run it). Run it on the Uplivra server or a collector.

The Uplivra system helper. It runs as root on computers set up by the
Uplivra installer or appliance image, and applies settings the collector
receives from the Uplivra server: time zone and time servers, network
settings, certificates and upgrades. You don't normally run it yourself.

  uplivra system apply      Apply what the collector handed over (run by uplivra-system.path)
  uplivra system upgrade-server   Install an upgrade the server downloaded (run by uplivra-server-update.path)
  uplivra system os-update        Install Ubuntu updates up to the snapshot Uplivra approved (appliances, nightly)
  uplivra system confirm-network -dir D -version V
                                  Keep new network settings if confirmed, else put the old ones back (scheduled after a change)
  uplivra system install-helper   (Re)install the helper's systemd units (the installer runs it on upgrades)
  uplivra system accounts         Bring the computer's accounts up to date (the installer and upgrades run it)
  uplivra system apply-server     Run what the server handed over: certbot for the web interface (run by uplivra-server-system.path)
  uplivra system certbot-web NAME [-email you@example.com]
                                  Get a certbot certificate for the web interface by hand
  uplivra system ports -port 443 [-keep-old=false]
                                  Change the server's port (browsers and collectors)
  uplivra system ports -close-old Stop answering on older ports once collectors have moved
  uplivra system migrate-ports    Move an older installation from 8443/8444 to 443 (the installer runs it)

Options: -config collector.json

uplivra server

The Uplivra server program (its service runs it). Run it on the Uplivra server.

uplivra server -config /etc/uplivra/server.json

uplivra collector

The collector program (its service runs it). Run it on a collector or appliance.

uplivra collector -config /etc/uplivra/collector.json

uplivra aaa-node

Run this computer as an Access Control (TACACS+ and RADIUS) node. Run it on an Access Control node.

uplivra aaa-node enroll -server https://SERVER -code CODE -pin PIN
uplivra aaa-node install
uplivra aaa-node status