TrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

UPS

6 minute read.

Last Modified 2024-03-15 13:07 EDT

UPS Namespace

The ups namespace has three commands and is based on UPS service functions found in the SCALE API and web UI. It provides access to UPS management methods through the ups commands.

UPS Commands

The following ups commands allow you to view and edit UPS properties.

You can enter commands from the main CLI prompt or from the UPS namespace prompt.

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

Interactive Argument Editor (TUI)

Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Click for more information
The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.
Optional properties, indicated by the # symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.
To configure required properties, enter a space after the colon then add the value.
To enable optional properties, delete # from the corresponding line.
Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.
Press F2 or click Save to save the modified file.
Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.

Config Command

The config command returns a table with current UPS settings.

Using the Config Command

Description

The config command has no required properties. Enter the command then press Enter. The command returns a table of current UPS settings when successful.

Usage

From the CLI prompt, enter:

service ups config

Command Example

service ups config
+---------------------+--------------------+
|                  id | 1                  |
|                mode | MASTER             |
|          identifier | ups                |
|          remotehost |                    |
|          remoteport | 3493               |
|              driver |                    |
|                port |                    |
|             options |                    |
|         optionsupsd |                    |
|         description |                    |
|            shutdown | BATT               |
|       shutdowntimer | 30                 |
|             monuser | upsmon             |
|              monpwd |                    |
|          extrausers |                    |
|            rmonitor | false              |
|           powerdown | false              |
|      nocommwarntime | <null>             |
|            hostsync | 15                 |
|         shutdowncmd | <null>             |
| complete_identifier | ups@localhost:3493 |
+---------------------+--------------------+

Driver_Choices Command

The driver_choices command returns choices of UPS drivers supported by the system.

Using the Driver_Choices Command

Description

The driver_choices command has no required properties. Enter the command then press Enter. The command returns a table of UPS drivers your system supports when successful.

Usage

From the CLI prompt, enter:

service ups driver_choices

Command Example

service ups driver_choices
+-----------------------------------+------------------------------------------------------------------+
| blazer_usb$625L | Ablerex ups 2 625L USB (blazer_usb)                                                |
| snmp-ups$various RPC | Baytech pdu 3 various RPC (snmp-ups)                                          |
| genericups upstype=7$550SL | Cyber Power Systems ups 1 550SL (genericups)                            |
| mge-shut$Tower 500W LV / HV | Dell ups 5 Tower 500W LV / HV Serial port (mge-shut)                   |
| usbhid-ups$3S | Eaton ups 5 3S (usbhid-ups)                                                          |
| blazer_ser$PowerPal | Fenton Technologies ups 5 PowerPal L-series (blazer_ser)                       |
| gamatronic$µPS3/1 | Gamatronic ups 5 µPS3/1 (gamatronic)                                             |
| apcsmart$PowerTrust 2997A | HP ups 1 PowerTrust 2997A HP 5061-2575 cable (apcsmart)                  |
| usbhid-ups$Various | IBM ups 5 Various USB port (usbhid-ups)                                         |
| genericups upstype=4$Jasuny USPS | Jageson Technology ups 1 Jasuny USPS (genericups)                 |
| nutdrv_atcl_usb$800 VA | Kanji ups 1 800 VA USB (nutdrv_atcl_usb) / Plexus ups 1 800 V...            |
| metasys$WHAD 2500 | Legrand ups 4 WHAD 2500 Serial (metasys)                                         |
| masterguard$(various) | Masterguard ups 1 (various) (masterguard)                                    |
| gamatronic$Expert C Online 6000 | NHS Sistemas de Energia ups 5 Expert C Online 6000 (gamatronic)    |
| oneac$ON400 | Oneac ups 1 ON400 advanced interface (oneac)                                           |
| usbhid-ups$Black Knight PRO | Powercom ups 5 Black Knight PRO USB (2009 models, product id:...       |
| snmp-ups$Metered PDU - Raritan PM | Raritan pdu 3 Metered PDU - Raritan PM no report, but should ... |
| blazer_ser$Castle C*K | Santak ups 2 Castle C*K Serial (blazer_ser)                                  |
| usbhid-ups$AVRX750UD | Tripp Lite ups 3 AVRX750UD USB (protocol 2010) (usbhid-ups)                   |
| blazer_ser$Alpha 1000is | UNITEK ups 2 Alpha 1000is (blazer_ser)                                     |
| nutdrv_qx$Vesta LED 850VA | Voltronic Power ups 2 Vesta LED 850VA USB (nutdrv_qx)                    |
| blazer_ser$CPM-800 | WinPower ups 2 CPM-800 (blazer_ser)                                             |
+-----------------------------------+------------------------------------------------------------------+

Port_Choices Command

The port_choices command returns choices of UPS ports available on the system.

Using the Port_Choices Command

Description

The port_choices command has no required properties. Enter the command then press Enter. The command returns a list of UPS port choices when successful.

Usage

From the CLI prompt, enter:

service ups port_choices

Command Example

service ups port_choices
/dev/ttyS1
/dev/ttyS0
/dev/uhid
auto

Update Command

The update command allows you to update UPS service settings.

Using the Update Command

Description

The update command requires entering a port and a driver. It also has 17 additional properties you can configure. See the Update Command Properties table below for details. After specifying the port and a driver, you can include any other properties you want to update. Enter the command string, then press Enter. The command returns nothing when successful.

Update Command Properties

Property	Required	Description	Syntax Example
`powerdown`	No	When enabled, the UPS powers off after the system shuts down.	`powerdown="true/false"`
`rmonitor`	No	Sets the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass.	`rmonitor="true/false"`
`nocommwarntime`	No	Number in seconds to wait before alerting that the service cannot reach any UPS. Warnings continue until the situation is fixed.	`nocommwarntime=number`
`remoteport`	No	Only enabled when the UPS Mode is set to `SLAVE`. Enter the open network port number of the UPS Master system. The default port is `3493`.	`remoteport=number`
`shutdowntimer`	No	Value in seconds the service waits for the UPS before initiating a shutdown. This only applies when `shutdown` is set to `BATT`.	`shutdowntimer=number`
`hostsync`	No	Value in seconds Upsmon waits in master mode for the slaves to disconnect during a shutdown situation.	`hostsync=number`
`description`	No	User-defined description for the service.	`description=“description”`
`driver`	Yes	Network UPS Tools compatible driver.	`driver="driver"`
`extrausers`	No	User ID you want to have administrative access.	`extrausers=UID`
`identifier`	No	User-defined identifier. It can contain alphanumeric, period, comma, hyphen, and underscore characters.	`identifier=identifier`
`mode`	No	Choose `MASTER` if the UPS is plugged into the serial port. The UPS shuts down last. Choose `SLAVE` to have this system shut down before master.	`mode=MODE`
`monpwd`	No	Changes the default password to improve system security. The new password cannot contain a space or #.	`monpwd=password`
`monuser`	No	Enter a user ID to associate with this service. We recommend the default.	`monuser=UID`
`options`	No	Extra options from UPS.CONF(5).	`options=ups.conf`
`optionssupsd`	No	Extra options from UPSD.CONF(5).	`optionssupsd=upsd.conf`
`port`	Yes	Serial or USB port connected to the UPS. To automatically detect and manage the USB port settings, enter `auto`.	`port=port`
`remotehost`	No	IP address of the remote system with UPS Mode set as `MASTER`.	`remotehost=0.0.0.0`
`shutdown`	No	Choose when the UPS initiates shutdown. Options are `BATT` and `LOWBATT`.	`shutdown=MODE`
`shutdowncmd`	No	The custom command to overrule the default shutdown command when battery power is low or the shutdown timer ends.	`shutdowncmd=command`

Usage

From the CLI prompt, enter:

service ups update port=port driver="driver"

Where:

port is the serial or USB port connected to the UPS.
driver is the network UPS tools compatible UPS driver.

Command Example

service ups update port=auto driver="blazer_usb$625L"