How Do I Set Up a UPS on pfSense or OPNsense with NUT?

Install the NUT package (pfSense: System > Package Manager, then Services > UPS; OPNsense: System > Firmware > Plugins > os-nut, then Services > Nut), choose how the firewall reaches the UPS, and it powers itself off when the UPS reports low battery. Shutting down at your own percentage, or letting a NAS use the same UPS, takes a few extra lines that neither vendor's documentation spells out.

On this page
  1. What each package actually writes
  2. USB, remote NUT or SNMP: which connection
  3. pfSense: local USB setup
  4. OPNsense: local USB setup
  5. When the firewall shuts down: low battery or a set percentage
  6. Serving the UPS to a NAS and other devices
  7. USB problems and the 2.8.1 package change
  8. Test it, and plug in the right things
  9. Frequently asked questions

Both firewalls run the same NUT, but each package wraps it differently, and that decides where every extra setting goes. The table below comes from the two packages' source code, because neither vendor documents it: Netgate's package page is a troubleshooting checklist, and OPNsense's how-to covers only netclient mode.

What each package actually writes

pfSense NUT package vs OPNsense os-nut plugin
ItempfSense (pfSense-pkg-nut)OPNsense (os-nut)
InstallSystem > Package Manager, package nutSystem > Firmware > Plugins, os-nut
ConfigureServices > UPS > UPS Settings (status on UPS Status tab)Services > Nut > Configuration (status under Diagnostics)
Connection choicesLocal USB, Local serial, Local serial (genericups), Remote NUT server, Remote apcupsd, Remote netxml, Remote snmp, Dummy UPSMode standalone or netclient; driver tabs USBHID, APCSMART, APCUPSD, BCMXCPUSB, BlazerUSB, BlazerSerial, Netclient, QX, Riello, SNMP
Where upsd listens127.0.0.1 and ::1 onlyListen Address field, default 127.0.0.1,::1
Accounts it createsadmin and local-monitor, both with random passwordsadmin and monuser, passwords you type
Room for extra usersYes: Additional configuration lines for upsd.usersNo field; only monuser exists
Per-UPS driver optionsExtra Arguments to driver, one per lineExtra Arguments on the driver tab, comma separated
Global ups.conf linesAdditional configuration lines for ups.conf (placed above the UPS section)Not available
Shutdown command/sbin/shutdown -p +0 (power off)/usr/local/etc/rc.halt
Kill UPS power at the endYes: POWERDOWNFLAG /etc/killpower plus a hook that runs upsdrvctl shutdownPOWERDOWNFLAG /etc/killpower is written
Role as a network clientslaveslave

Two rows matter most. On pfSense, the global ups.conf box lands above the UPS section and Extra Arguments lands inside it, so a driver option in the wrong box applies to the wrong scope. On OPNsense, a NAS client must log in as monuser, which the plugin creates with upsmon master rights. For the NUT basics (drivers, upsd, upsmon, FSD), see the NUT setup guide.

USB, remote NUT or SNMP: which connection

Choosing how the firewall reads the UPS
Your situationpfSense typeOPNsense setting
UPS USB cable plugs into the firewallLocal USB, driver usbhid-ups for most APC, CyberPower, Eaton and Tripp Lite unitsstandalone, USBHID tab enabled
Cable goes to a NAS or server already running NUTRemote NUT server: address, port (optional), username, passwordnetclient, Netclient tab enabled
UPS has a network management cardRemote snmp (runs snmp-ups on the firewall)standalone, SNMP tab, add port= card address to arguments

Rule of thumb: let the firewall own the UPS

Everything else needs the firewall in order to talk. If it is a client of the NAS, the NAS's shutdown decision takes the network down with it. As the owner, the firewall is the NUT primary, which by design waits for clients to disconnect (up to HOSTSYNC) before shutting itself down. With a management card, SNMP from the firewall keeps that arrangement; see network management cards and SNMP.

pfSense: local USB setup

  1. Install. System > Package Manager > Available Packages, install nut, and connect the UPS's USB data cable to the firewall.
  2. General Settings. Services > UPS > UPS Settings. Set UPS Type to Local USB and a UPS Name: use ups if a Synology will ever connect, because it cannot ask for any other name. Enable notifications sends mail through System > Advanced > Notifications.
  3. Driver. usbhid-ups, unless the NUT hardware list names another for your model.
  4. Save and check. The UPS Status tab should show ups.status as OL and list battery.charge. If the service will not start, read Status > System Logs for nut: entries, or run /usr/local/etc/rc.d/nut.sh start from the shell (console option 8) to see the error. Netgate notes the form cannot validate combinations, so a mismatched driver and cable type saves fine and then fails, and that a reboot after connecting the UPS sometimes helps.

OPNsense: local USB setup

  1. Install. System > Firmware > Plugins, install os-nut. Its pages appear under Services > Nut.
  2. General settings. Tick Enable Nut, set Service Mode to standalone, set a Name (again, ups if a Synology may connect). Leave Listen Address at 127.0.0.1,::1 unless you will share the UPS.
  3. Passwords. Set Admin Password and Monitor Password. The plugin's default for both is literally Password; change them.
  4. Driver tab. Open USBHID, tick Enable, keep port=auto in Extra Arguments. Enable only one driver tab: each writes a section with the same name. Then check Services > Nut > Diagnostics for model and status.

As a client of another server, choose netclient, enable the Netclient tab and fill IP Address, Port, Username and Password. Name must match the server's UPS name, because the plugin builds MONITOR name@address from it.

When the firewall shuts down: low battery or a set percentage

Out of the box, both shut down at the UPS's own low battery signal; OPNsense's help text says the system shuts down "when the UPS emits a low battery warning." In NUT terms the trigger is ups.status showing OB LB.

That default is only as good as the threshold the UPS uses to raise LB, and you did not choose it. The pfSense maintainer, for example, has pointed out that a Tripp Lite Smart1500LCD ships with battery.charge.low at 10 percent, not the 50 percent its owner assumed.

Option 1: move the UPS's own threshold

The maintainer notes the Tripp Lite value is settable with upsrw, which writes it into the UPS. Run upsrw yourups to see what your unit accepts; on some units only ups.delay.shutdown is listed and other writes return ERR VAR-NOT-SUPPORTED. If it works, you keep the UPS's own LB signal, just earlier.

Option 2: ignorelb plus an override

When the UPS will not take a new threshold, tell the NUT driver to ignore the UPS's LB flag and compute low battery itself. Per the ups.conf manual, with ignorelb set the driver declares low battery when battery.charge < battery.charge.low or battery.runtime < battery.runtime.low, and you set those levels with overrides:

# pfSense: Services > UPS > Extra Arguments to driver (one per line)
ignorelb
override.battery.charge.low = 40
override.battery.runtime.low = 300

# OPNsense: USBHID tab > Extra Arguments (comma separated)
port=auto,ignorelb,override.battery.charge.low=40,override.battery.runtime.low=300

On pfSense these go in Extra Arguments to driver, not the global ups.conf box. The manual's caution: this works only if the UPS reports charge or runtime reliably, so confirm both appear on the status page, and drop the runtime line if the estimate is erratic.

The cost: the trigger now follows NUT's polling

The UPS's own LB flag reaches usbhid-ups through interrupt reports in its short pollinterval loop (normally 2 seconds). With ignorelb, the decision rests on charge and runtime values, which the driver guarantees to re-read only on its full update every pollfreq: 30 seconds by default, 12 for CyberPower. Many units push changed values sooner; plan for the slow case.

Worst-case extra drain = pollfreq (s) / runtime at your load (s) x 100 percent

Worked example: a UPS that runs the firewall, modem and switch for 40 minutes (2,400 s) loses about 30 / 2,400 x 100 = 1.25 percent in one 30 s gap. A 40 percent setting can therefore fire as late as roughly 39 percent. Harmless at 40, but a single-digit setting leaves no room for that lag or for an aged battery. How much runtime you need covers budgeting the rest.

The override moves everyone's shutdown, not just the firewall's

The driver writes LB into ups.status, which every NUT client reads, so a 40 percent setting on the firewall sends a NAS client down at 40 percent too. Clients that must leave earlier need their own timer: upssched on Linux (see Proxmox UPS shutdown) or a Synology's Safe Mode timer.

Serving the UPS to a NAS and other devices

pfSense as the NUT server

pfSense's upsd listens only on loopback, so other hosts cannot reach it until you open a path. The package maintainer gives two ways, and is blunt about mixing them: "DO NOT DO BOTH AT THE SAME TIME."

Opening pfSense's NUT server to the LAN: pick one
MethodWhereSettingsRestricting access
Port forward (simpler)Firewall > NAT > Port ForwardInterface LAN, protocol TCP, destination LAN address, port 3493, redirect target 127.0.0.1 port 3493Add a Source address to the NAT rule
Listen directiveServices > UPS > Display Advanced, upsd.conf boxLISTEN 192.168.1.1 (the LAN interface address; IPv6 also works)Separate firewall rules on the interface

Either way, add a user in the upsd.users box under Display Advanced. The maintainer's example uses the pre-2.8 role word, which current NUT still accepts:

[remoteuser]
password = mypassword
upsmon slave

A Linux or TrueNAS client then monitors ups@192.168.1.1 with those credentials; the TrueNAS UPS guide shows where they go in its form.

The Synology case

Synology's NUT implementation uses hardcoded values: UPS name ups, username monuser, password secret. DSM's client option asks only for an IP address. So to serve a Synology from pfSense, name the UPS ups and add this to upsd.users:

[monuser]
password = secret
upsmon slave

On OPNsense, use the built-in account: Name ups, Monitor Password secret, and the LAN address added to Listen Address (for example 127.0.0.1,::1,192.168.1.1). That account has master rights, so allow 3493 only from the NAS's address.

With the Synology as owner, use Remote NUT server (OPNsense: netclient) with the same three values, and add the firewall's IP to DSM's permitted devices list or it gets permission denied. Synology UPS setup covers the DSM side.

USB problems and the 2.8.1 package change

By late 2023, the maintainer wrote, many users had issues with the 2.8.0 package and were running custom builds; on USB units a common workaround was the interruptonly driver flag. On 2023-11-09 the maintainer released package 2.8.1, built on the newer nut-devel-2023.10.07_1, and the final release appeared as package 2.8.2 with the same NUT inside. Testers reported it fixed USB CyberPower units, including dropping interruptonly with no more disconnects. The current port requires NUT 2.8.2 or later.

  • Version floor. The new package needs pfSense Plus 23.09 or CE 2.7.1. On older releases upsmon fails to start because libraries such as OpenSSL 3 are missing (the log shows libssl.so.30 not found).
  • Leftover workarounds. One tester's firewall (Eaton Ellipse Eco 650) shut itself down, ending with "NUT killing power", the moment the service restarted after the upgrade. interruptonly was still set; removing it, power-cycling and reconnecting the USB cable fixed it. Restart NUT after changes only when an unexpected shutdown would not hurt.

The user=root test

If a local USB driver still fails to start, the maintainer's usual diagnosis is a missing FreeBSD USB quirk: the kernel attaches its default driver to the UPS, and only root can replace it. Add this to Additional configuration lines for ups.conf:

user=root

If NUT now starts, the quirk is missing. The proper fix is a quirk built from the idVendor and idProduct in usbconfig -v, made permanent in /boot/loader.conf.local (not loader.conf, which pfSense may rewrite):

hw.usb.quirk.0="0x04b4 0x5500 0x0000 0xffff UQ_HID_IGNORE"

That line is a forum user's working quirk for a Riello VST1100; substitute your own IDs. If usbconfig does not list the UPS at all, the problem is the cable or port, so start with UPS not detected by computer.

Test it, and plug in the right things

Netgate's graceful-shutdown guide puts a UPS first among its five tips, rated to keep the firewall powered long enough for a graceful shutdown. Prove yours at a quiet time: pull the UPS plug from the wall, watch ups.status turn OB, and watch the charge reach your threshold. upsmon -c fsd simulates the whole sequence, including cutting UPS output.

Put the modem or ONT and the switch on battery outlets too; UPS for a modem and router has typical draws, and UPS for a network rack covers PoE switches and outlet groups. A periodic runtime calibration keeps the charge and runtime figures your threshold depends on honest.

Where this guide stops applying

Field names come from the current pfSense-pkg-nut (2.8.2 series) and os-nut 1.9 sources; older versions differ. A firewall with two power supplies on two UPS units needs MINSUPPLIES tuning that neither form exposes (pfSense's upsmon.conf box can take it).

Frequently asked questions

Should the firewall or the NAS own the UPS USB cable?

Give it to the box that should stay up longest. The firewall is a good owner because it is usually the last thing you want off, and NUT's primary already waits for its clients to disconnect before it powers down. If the NAS owns the cable instead, the firewall becomes a client and goes down when the NAS says so, which leaves no network for anything else.

Why does OPNsense only offer standalone and netclient modes?

The os-nut plugin's mode field lists only those two. Standalone still runs upsd, and it binds to whatever you put in Listen Address, so adding the LAN address there turns a standalone OPNsense into a server other machines can reach. There is no separate netserver choice to pick.

Can I change the Synology monuser password to something stronger?

Not from DSM. The pfSense package maintainer describes the ups, monuser and secret values as hardcoded in Synology's NUT implementation, so any server a Synology connects to must accept exactly those. Protect it with a source address restriction on the port forward or a firewall rule instead.

My UPS reported 60 minutes, then dropped to 30 minutes the moment power failed. Is it broken?

Not necessarily. The pfSense NUT package maintainer has noted that a sudden runtime drop on battery is not completely abnormal for a standby UPS, and that a deep runtime test under load is the fix for a bad estimate. Until you have run one, prefer a charge threshold over a runtime threshold.

Does the pfSense UPS also get switched off after the firewall halts?

Yes, when the UPS supports it. The package writes POWERDOWNFLAG /etc/killpower and installs a shutdown hook that runs upsdrvctl shutdown if the flag is set, which tells the UPS to cut its output after its shutdown delay (20 seconds by default for usbhid-ups, 60 for CyberPower). That power cycle is what lets equipment restart unattended.

Sources and further reading

  1. Netgate: pfSense NUT package documentation
  2. Netgate Forum: NUT Package (2.8.1 and above), maintainer dennypage, from 2023-11-09
  3. pfSense-pkg-nut source (nut_settings.php, nut.inc, Makefile)
  4. OPNsense: Network UPS Tools how-to and os-nut plugin source
  5. NUT ups.conf(5) and usbhid-ups(8) manual pages
  6. Netgate Forum: NUT package thread, dennypage on Tripp Lite battery.charge.low and runtime drops (2022-02-21)
  7. NUT User Manual: configuration notes and shutdown design
  8. Netgate Why To Series: Graceful Shutdowns (2018)