Running Unum

The Unum agent, or just Unum, is a portable command-line utility and long-running daemon with several modes of operation.

This document covers running the Unum agent. Download Unum for your platform from the Releases page.

Overview

Unum supports a few different modes of operation, depending on options received from the command line. In normal operation, the Unum agent is designed to run as a system service.

In any mode of operation, most output is sent to the Unum log file (/var/opt/unum/unum.log by default). Be sure to check the logs for valuable debugging info!

Normal Operation

When started with --daemonize (or -d) the agent will fork into the background immediately on start. Otherwise, Unum will fork itself early on to start a monitor thread (unless started with --unmonitored) that will restart the agent if the main agent process dies.

It's normal for Unum to show up in ps or top with at least two processes-- one is the monitor thread and the other the main agent thread.

Debug Mode

Developer builds can additionally enable an interactive test mode by passing UNUM_DEBUG=1 during build-time (see Building Unum).

This mode can be used by passing t to the --mode (or -m) option.

unum -mt
# >>>>> Starting Unum v2018.1210.151021.0 mode: t <<<<<
# The test option has to be: 't[1|2|3...] [arg1] [arg2] ...'
# 1 - test dumping cfg to file
# 2 - test restoring cfg from file
# ... more tests...

Specify which test with t<test number> as the option value for --mode. Run the first test:

unum -mt1

Miscellaneous modes

Print the agent version with --version (or -v).

unum --version

Print the framework platform (eg. linux_generic) with --product-id (or -z).

unum --product-id

Option Reference

Option	Shorthand	Description
--cfg-file <PATHNAME>	-f <PATHNAME>	Specify the path to the JSON configuration file, see "JSON Configuration"
--skip-net-check	-n	Skip connectivity check at agent startup
--daemonize	-d	Run the agent as a background daemon
--unmonitored	-u	Do not start agent monitoring thread
--pid-prefix	-i	Specify PID file prefix (default: /var/run/unum-)
--set-url-pfx	-s	Specify API URL prefix (default: https://api.minim.co)
--mode	-m	Specify running-mode (only in Debug builds), see the "Debug Mode" section.
--no-provision	-p	Do not provision or use a client certificate when sending data.
--trusted-ca <PATHNAME>	-c <PATHNAME>	Specify path to certificate authority bundle
--lan-if <IFNAME>[,IFNAME2[,IFNAME3,...]]	-l <IFNAME>	Specify the LAN interface name. Accepts multiple, separated by a comma
--wan-if <IFNAME>	-w <IFNAME>	Specify that WAN interface name.
--rtr-t-period <5-120>		Router telemetry reporting frequency, in seconds (default: 30)
--tpcap-period <15-120>		Device telemetry reporting frequency, in seconds (default: 30)
--wscan-period <0-...>		Wireless network scan frequency, in seconds (default: 300). 0 to disable.
--rad-t-period <15-120>		Radio and client telemetry reporting frequency, in seconds (default: 30)
--ipt-period <0-...>		Frequency, in seconds, to report iptables rules and states (default: 300). 0 to disable.
--sysinfo-period <0-...>		Frequency, in seconds, to report system information (default: 300). 0 to disable.

JSON Configuration

Most options can be specified in a JSON configuration rather than on the command-line. The JSON file should use the long option name as the key. For example:

{
  "lan-if": "eth0",
  "wan-if": "eth1",
  "wscan-period": 0
}

Use the --cfg-file option to specify the path to the configuration file from the command line.

unum --cfg-file /etc/opt/unum/config.json