On this page
What the TrueNAS UPS service is
TrueNAS (both the Debian-based SCALE editions and the FreeBSD-based CORE line) ships with Network UPS Tools and wraps it in a single settings form. When you fill in that form and start the service, TrueNAS writes NUT's ups.conf, upsd.conf, upsd.users and upsmon.conf for you and runs the driver, the server and the monitor. Editing those files directly is not supported, because TrueNAS regenerates them, but knowing what each field maps to makes troubleshooting much easier.
The UI has moved between releases. In recent SCALE versions, look for System Settings > Services and the edit (pencil) icon next to UPS. In CORE it lives under Services, UPS. Newer releases may reorganize this again, so if the path differs, search the settings for "UPS".
Field-by-field configuration
| Field | Typical value | NUT equivalent |
|---|---|---|
| Identifier | ups | Section name in ups.conf, used as ups@host |
| UPS Mode | Master (Primary) if the USB cable is on this machine; Slave (Secondary) otherwise | upsmon role and whether a local driver runs |
| Driver | Generic USB HID entry using usbhid-ups | driver = usbhid-ups |
| Port or Hostname | auto for USB; server IP for remote mode | port = auto or the MONITOR host |
| Monitor User / Password | Your choice; avoid the defaults on shared networks | The upsmon account in upsd.users |
| Extra Users (Auxiliary Parameters) | Additional upsd.users sections | Appended to upsd.users |
| Remote Monitor | Enable to let other machines connect | upsd listens on the network, not just localhost |
| Shutdown Mode | UPS goes on battery, or UPS reaches low battery | Timer-based vs low battery triggered shutdown |
| Shutdown Timer | Seconds after going on battery | Delay before shutdown starts |
| Shutdown Command | Leave default unless you know why | SHUTDOWNCMD |
| Power Off UPS | On, if you want the UPS to cut and restore output | Kill-power request at the end of shutdown |
Other fields such as "No Communication Warning Time", "Host Sync" and email notification options appear in some releases. Their defaults are sensible to start with.
Choosing a shutdown mode
The two shutdown modes behave very differently in a long outage.
- UPS goes on battery: TrueNAS starts the Shutdown Timer the moment the UPS reports on battery. If power returns before it expires, nothing happens. If not, TrueNAS shuts down with most of the battery still available.
- UPS reaches low battery: TrueNAS waits until the UPS raises its low battery flag. That uses the most runtime, but everything rides on the UPS's low battery threshold being reached with enough real time left.
Our recommendation for a NAS: on battery plus a short timer
A NAS shutdown can take longer than people expect: services stop, apps and VMs shut down, and the pool exports. On a system with many apps or a busy pool, that can easily take a few minutes. Using "UPS goes on battery" with a timer of roughly 120 to 300 seconds means the shutdown starts while the battery still holds most of its charge, so even an aged battery finishes the job. Time a real shutdown from the UI first, then set the timer so timer plus shutdown time is well under half your measured runtime.
Verify from the shell
After saving the form, enable the service to start automatically and start it. Then open the TrueNAS shell (System, Shell, or an SSH session) and check that NUT is reading the UPS:
# List UPS names known to the local server
upsc -l
# Show all variables for the UPS (use your Identifier instead of "ups")
upsc ups@localhost
# Spot-check the important values
upsc ups@localhost ups.status
upsc ups@localhost battery.charge
upsc ups@localhost battery.runtimeups.status should read OL (on line) normally, and OB (on battery) when you unplug the UPS from the wall. battery.runtime is in seconds. If upsc returns "Driver not connected" or "Data stale", the driver is not talking to the UPS: re-check the driver selection and cable.
Letting other machines use the TrueNAS UPS
When the TrueNAS box owns the USB cable, hypervisors, desktops and other NAS units on the same UPS can follow its lead.
- Enable Remote Monitor in the UPS service form so upsd listens on the network.
- Add a user for clients in the Extra Users (Auxiliary Parameters) box, using NUT's upsd.users syntax:
On TrueNAS releases bundling NUT older than 2.8, use[upsclient] password = choose-a-long-password upsmon secondaryupsmon slave. - Restart the UPS service and confirm port 3493 is reachable from the client.
- On each client, test with
upsc ups@truenas-ip, then add a MONITOR line such asMONITOR ups@192.168.1.30 1 upsclient choose-a-long-password secondaryto upsmon.conf.
If a Synology NAS must be a client, remember that DSM assumes the UPS name ups and the user monuser with password secret; see Synology UPS setup. A [monuser] section in the extra users box satisfies it.
TrueNAS as a client of another server
Set UPS Mode to Slave (Secondary), enter the remote server's IP in the hostname field, and set the identifier, monitor user and password to match that server's configuration. The driver field is ignored in this mode in most releases.
Testing the whole sequence
Once the service is running and upsc shows good data, prove the configuration with a real outage at a quiet time:
- Confirm a recent backup or snapshot replication, and that no scrub or resilver is in progress.
- Make sure the UPS battery has been on charge for several hours.
- Unplug the UPS input cord from the wall. Leave the UPS switched on.
- Watch the TrueNAS alerts and, from an SSH session,
upsc ups@localhost ups.statuschanging toOB. - Time the moment the shutdown starts and the moment the console shows the system halted.
- Note the runtime the UPS still reports. Restore power and confirm the system (and its apps) come back as expected.
If you enabled Power Off UPS, also confirm that the UPS turned its outlets off after TrueNAS halted and turned them back on when power returned. Combined with a firmware setting to power on after AC loss, that is what lets an unattended server recover from a long outage by itself.
Turn on email alerts
TrueNAS can email you when the UPS goes on battery, when communication is lost and when the battery needs replacement. Configure the system email settings first, then enable UPS notifications. A "replace battery" alert months before an outage is far more useful than discovering a dead battery during one.
Pitfalls worth knowing
| Problem | Cause | Fix |
|---|---|---|
| Service will not start after an upgrade | Driver list entries renamed between releases | Reselect the driver from the current list |
| Clients cannot authenticate | Identifier mismatch (case sensitive) or wrong role keyword | Match name@host exactly; use secondary or slave to match the server's NUT version |
| TrueNAS runs as a VM and sees no UPS | USB device not passed through | Pass the UPS USB device to the VM, or run NUT on the hypervisor and make TrueNAS a client |
| Shutdown starts but outage outlasts the battery | Shutdown slower than expected (apps, VMs, pool export) | Time a manual shutdown; reduce the timer |
| Short flickers cause unnecessary shutdowns | Timer too short | Raise the timer to ignore brief events; most outages are either seconds long or very long |
Plan the order when TrueNAS hosts VM storage
If hypervisors mount iSCSI or NFS datastores from TrueNAS, the hypervisors must finish shutting down before TrueNAS goes. Give the clients an earlier trigger (for example a short on-battery timer in their own upsmon via upssched) and keep TrueNAS on a later one. Proxmox UPS shutdown walks through this ordering.
For sizing the UPS itself and estimating the runtime you are budgeting, see UPS for a NAS and how much runtime you need.
Frequently asked questions
Which driver should I pick for my UPS in TrueNAS?
For most APC, CyberPower, Eaton and Tripp Lite units connected by USB, choose the entry that maps to usbhid-ups, often listed as a generic USB HID or by brand with usbhid-ups in parentheses. Serial-only or older units need a model-specific driver; check the NUT hardware compatibility list for your exact model.
Should TrueNAS be master or slave for the UPS?
Choose Master (Primary in releases using newer NUT terminology) when the UPS USB cable plugs into the TrueNAS machine. Choose Slave (Secondary) when another machine owns the UPS and TrueNAS should follow its signals over the network, in which case you enter that server's address as the remote host.
Why does the TrueNAS UPS service fail to start?
Usually the driver cannot find the UPS: wrong driver selected, port not set to auto, a bad cable, or TrueNAS running as a virtual machine without the USB device passed through. Check the service logs and try running upsc after selecting the generic usbhid-ups entry.
What happens to my ZFS pool if TrueNAS loses power suddenly?
ZFS is designed to stay consistent through sudden power loss thanks to copy-on-write, but in-flight writes can be lost, and drives or controllers without power-loss protection can still misbehave. A clean shutdown avoids those risks and avoids long imports or scrubs afterwards, which is why UPS shutdown is still worth configuring.
Can Proxmox or another server use the TrueNAS UPS?
Yes. Enable remote monitoring, add a NUT user with upsmon secondary rights in the extra users field, and point the other machine's upsmon MONITOR line at the TrueNAS address, the UPS identifier and those credentials. Test from the client with upsc identifier@truenas-ip first.
Sources and further reading
- TrueNAS Documentation Hub: UPS service configuration (SCALE and CORE)
- Network UPS Tools project documentation
- NUT Hardware Compatibility List
- NUT upsd.users and upsmon.conf manual pages