UPS Configuration

Using an Uninterruptible Power Supply (UPS) with TrueNAS.

  4 minute read

TrueNAS uses NUT (Network UPS Tools) to provide UPS support. When the TrueNAS system is connected to a UPS device, configure the UPS service in Services > UPS > Configure.



UPS Configuration Options

SettingValueDescription
IdentifierstringRequired. Describe the UPS device. Can contain alphanumeric, period, comma, hyphen, and underscore characters.
UPS Modedrop-down menuSelect Master if the UPS is plugged directly into the system serial port. The UPS will remain the last item to shut down. Select Slave to have the system shut down before the Master.
Driver or Remote Hostcombo-boxRequired. For a list of supported devices, see the Network UPS Tools compatibility list. The field suggests drivers based on the text entered. To search for a specific driver, begin typing the name of the driver. The search is case sensitive. The Driver field changes to Remote Host when UPS Mode is set to Slave. Enter the IP address of the system configured as the UPS Master system. See this post for more details about configuring multiple systems with a single UPS.
Port or Hostnamedrop-down menuSerial or USB port connected to the UPS. To automatically detect and manage the USB port settings, open the drop-down menu and select auto. If the specific USB port must be chosen, see this note about identifing the USB port used by the UPS. When an SNMP driver is selected, enter the IP address or hostname of the SNMP UPS device. Port or Hostname becomes Remote Port when the UPS Mode is set to Slave. Enter the open network port number of the UPS Master system. The default port is 3493.
Shutdown Modedrop-down menuChoose when the UPS initiates shutdown: UPS goes on battery or UPS reaches low battery.
Shutdown TimerintegerSelect a value in seconds for the UPS to wait before initiating shutdown. Shutdown will not occur if the power is restored while the timer is counting down. This value only applies when Shutdown Mode is set to UPS goes on battery.
Shutdown CommandstringEnter the command to run to shut down the computer when battery power is low or shutdown timer runs out.
Power Off UPScheckboxSet for the UPS to power off after shutting down TrueNAS.
No Communication Warning TimestringEnter a value in seconds to wait before alerting that the service cannot reach any UPS. Warnings continue until the situation is fixed.
Host SyncintegerEnter a time in seconds for UPSMON(8) to wait in master mode for the slaves to disconnect during a shutdown.
DescriptionstringDescription or any notes about the UPS service.
Auxiliary Parameters (ups.conf)stringEnter any additional options from ]ups.conf(5)](https://www.freebsd.org/cgi/man.cgi?query=ups.conf).
Auxiliary Parameters (upsd.conf)stringEnter any additional options from upsd.conf(5).
Monitor UserstringRequired. Enter a user to associate with this service. The recommended default user is upsmon.
Monitor PasswordstringRequired. Default is the known value fixmepass. Change this to enhance system security. Cannot contain a space or #.
Extra UsersstringEnter accounts that have administrative access. See upsd.users(5) for examples.
Remote MonitorcheckboxSet for the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass.
Send Email Status UpdatescheckboxSet to enable TrueNAS to send email updates to the configured Email field.
Emailemail addressEnter any email addresses to receive status updates. Separate multiple addresses with a semicolon (;).
Email SubjectstringEnter a subject line for email status updates.

For USB devices, the easiest way to determine the correct device name is to enable the Show console messages option in System > Advanced. Plug in the USB device and look for a /dev/ugen or /dev/uhid device name in the console messages.

Some UPS models can be unresponsive with the default polling frequency. This can show in TrueNAS logs as a recurring error like libusb_get_interrupt: Unknown error. If this error occurs, decrease the polling frequency by adding an entry to Auxiliary Parameters (ups.conf): pollinterval = 10. The default polling frequency is two seconds.

upsc(8) can be used to get status variables from the UPS daemon such as the current charge and input voltage. It can be run from the Shell using the syntax upsc ups@localhost. The upsc(8) manual page has other usage examples.

upscmd(8) can be used to send commands directly to the UPS, assuming the hardware supports the command being sent. Only users with administrative rights can use this command. These users are created in the Extra Users field.

Multiple Computers with One UPS

A UPS with adequate capacity can power multiple computers. One computer is connected to the UPS data port with a serial or USB cable. This master makes UPS status available on the network for other computers. These slave computers are powered by the UPS, but receive UPS status data from the master computer. See the NUT User Manual and NUT User Manual Pages.