NUT on Unraid

NUT on Unraid

Network UPS Tools (NUT) can monitor a UPS and arrange a clean shutdown of your Unraid server when backup power runs low. The community Network UPS Tools (NUT) plugin by desertwitch integrates NUT with Unraid's settings, notifications and shutdown process.

This guide uses that plugin's graphical interface. It covers a UPS connected to Unraid, sharing that UPS with other computers, and an Unraid server monitoring a UPS through another NUT server. The plugin runs on the Unraid host; a Docker container is not needed.

The settings and paths below were checked against plugin 2026.06.18, with a running installation on Unraid 7.3.2 using NUT 2.8.5. Plugin and NUT backend versions are separate; check the installed versions when following this guide.

Before you begin

• Check your UPS in the NUT Hardware Compatibility List and read its recommended driver's manual. A USB connection does not necessarily mean that usbhid-ups is the right driver.
• Connect the server to a battery-backed UPS outlet. For a directly connected USB UPS, also connect its USB data cable to the Unraid host and leave that device available to the host rather than passing it through to a VM.
• If another computer supplies UPS status over the network, the network equipment between the computers must also remain powered during an outage.
• For an existing UPS installation, save its configuration and arrange a suitable maintenance window before changing which service manages it.

Unraid's built-in UPS Settings page uses apcupsd, which is a separate UPS service. Before enabling NUT, go to Settings > UPS Settings, set Start APC UPS daemon to No, and apply the change. The NUT plugin warns when apcupsd is also enabled. Avoid running both services against the same UPS.

Install the plugin

In Unraid's Apps tab (Community Applications), search for Network UPS Tools (NUT) and choose the plugin maintained by desertwitch. The plugin support thread directs users to this version; older plugin links in that thread are deprecated.

Open Settings > NUT Settings. Keep Start Network UPS Tools Service set to No while preparing the configuration. Leave Enable Manual Configuration at No for the normal setup, and use the default backend unless your UPS requires a specific newer driver or fix.

The Network UPS Tools Backend field shows the installed backend. The Backend Switch field selects a backend for installation; selecting it alone is not evidence that the running version has changed. Follow the plugin's instructions when switching versions.

Choose the mode

The plugin uses the following labels:

NUT Mode	Use it when	Components on Unraid
Standalone	Unraid communicates with the UPS and only this server needs monitoring.	UPS driver, upsd data server and upsmon shutdown monitor.
Netserver	Unraid communicates with the UPS and other computers also need its status.	UPS driver, upsd and upsmon.
Slave	Another NUT server communicates with the UPS; Unraid is a monitoring client.	upsmon, connecting to that server.

The plugin's Slave label corresponds to a NUT secondary monitor. Current NUT documentation uses primary/secondary where older configurations use master/slave.

UPS connected to Unraid

Choose Standalone, or Netserver if other computers will connect, then configure:

Setting	Value
NUT Master IP Address[:Port]	127.0.0.1 in both modes. This is the address the local monitor uses.
UPS Name	A short name such as ups. Clients must use this exact name.
UPS Driver	The driver recommended for your UPS. The Scan for Devices control can help identify it.
UPS Driver Port	The selected driver's required port. For usbhid-ups, use auto.
NUT Monitor Username / Password	The local monitoring account and a unique password. Use a long random password containing letters and digits, as recommended by the plugin.

For Netserver, also set NUT Slave Username / Password for remote shutdown monitors. Use a different username from the local monitor. On each remote computer, configure its NUT monitor with this account, the UPS name, the Unraid server's address and the secondary role. Each computer needs its own shutdown monitor; merely displaying UPS readings does not configure automatic shutdown.

Unraid as a network client

Choose Slave, then set:

• NUT Master IP Address[:Port] to the remote NUT server's address. NUT normally uses TCP port 3493.
• UPS Name to the name configured on that server.
• NUT Monitor Username / Password to an account authorised for secondary monitoring on that server. If the server is another Unraid NUT installation, these are its NUT Slave Username / Password values.

The remote server must allow the connection and supply UPS data. No local UPS driver is needed in this mode. Review the shutdown policy on both machines so the Unraid client has time to stop before UPS output is removed.

Check network access and accounts

The plugin's supplied upsd.conf listens on all IPv4 interfaces. Its mode selection does not rewrite that file in the version covered here, so do not rely on the Standalone label to restrict access.

For a local-only setup, open the plugin's NUT Configuration Editor, select /etc/nut/upsd.conf, and replace the active LISTEN line with:

LISTEN 127.0.0.1 3493

For a network server, retain loopback and add a LISTEN line for the server's intended LAN address. Limit access to the required trusted computers using your network's access controls; do not forward NUT's port from the Internet. See the upsd.conf manual for listening and TLS options.

Also review /etc/nut/upsd.users in the configuration editor before allowing network access. The plugin supplies an administrator account with control permissions as well as the monitoring accounts. Replace its default password too; changing the monitoring passwords in the settings page does not change that account. Preserve the file's GUI-reserved line positions when editing. Remote shutdown monitors only need the secondary monitoring account, not administrator credentials.

Set the shutdown policy

Choose a Shutdown Mode and a threshold that leaves enough time for Unraid to stop its VMs, containers and array under the expected workload:

Mode	Behaviour
Battery Level	Initiates shutdown when the reported charge falls to the configured percentage while on battery.
Runtime Left	Uses the selected runtime attribute's raw value. For the standard NUT battery.runtime variable, enter seconds: 300 means five minutes. Check NUT Details and the field's help if your device reports different units.
Time on Battery	Initiates shutdown after the selected time on battery. Choose a duration shorter than the UPS can sustain the protected load, allowing time for shutdown.
None (the UPS decides)	Disables the plugin's additional threshold or timer. NUT still responds when the UPS reports the critical on-battery/low-battery condition.

Battery runtime and charge are device-reported estimates. If the values are missing or unreliable, use a time-based policy with a suitable margin instead of building a shutdown decision around them. None does not mean that automatic shutdown is disabled.

Disable UPS Power after Shutdown is a separate choice: it requests that the UPS remove output power after the NUT-initiated shutdown. Leave it at No until you have planned and tested this behaviour for the UPS and every connected load. Support and restart behaviour depend on the UPS; restarting the server after power returns also depends on its firmware's power-restoration setting.

Save the configuration, then set Start Network UPS Tools Service to Yes and apply it. This enables the shutdown monitor, so resolve any existing critical UPS condition before starting it. Use the plugin's service controls for later changes rather than starting a second driver manually.

Verify monitoring

Open NUT Details and check the UPS identity, status and plausible readings. From the Unraid terminal or SSH, the following read-only checks show the installed client version and query the local data server:

upsc -V
upsc -l 127.0.0.1
upsc ups@127.0.0.1 ups.status
upsc ups@127.0.0.1 driver.name

Replace ups with your UPS Name. For Slave mode, use the remote server's address instead of 127.0.0.1. OL means utility power is online; OB means the UPS is on battery. Status may contain several tokens, such as OL CHRG.

For Standalone or Netserver, check the actual listening address:

ss -ltn '( sport = :3493 )'

Check the Unraid system log for upsmon, upsd and driver messages, especially repeated authentication failures, connection errors or stale data. If the plugin redirects service logs, use NUT Service Logs; its separate file is /var/log/nut.log. Filtered messages may be in NUT Spam Logs instead.

Successful upsc output proves that UPS data can be read. Status queries do not use the monitoring password, so they do not prove that upsmon authenticated. For network clients, the server's NUT Connected Slaves display is useful for checking monitor logins; dashboards that only read metrics will not appear there.

After the next planned reboot, repeat the status and log checks to confirm startup. Before relying on the setup, arrange a controlled test of the complete shutdown and recovery sequence using NUT's shutdown testing guidance. Include the Unraid workloads, remote clients, network equipment and any intended UPS output shutdown. Forced-shutdown and UPS control commands can stop every protected system; they are not connectivity tests.

Configuration and persistence

Use the plugin settings and NUT Configuration Editor for normal changes:

Location	Purpose
/boot/config/plugins/nut-dw/nut-dw.cfg	Persistent plugin settings on the Unraid boot device.
/boot/config/plugins/nut-dw/ups/	Persistent copies of the NUT configuration files.
/etc/nut/	Active configuration used by the running system.

The plugin restores the saved NUT files to /etc/nut during installation at startup. The configuration editor saves both the active file and its persistent copy; its changes take effect on the next NUT restart. A terminal edit under /etc/nut alone is not a dependable persistence method.

With Enable Manual Configuration: No, the plugin updates reserved lines from its settings. For extra driver options, choose for UPS Driver and edit ups.conf; the plugin continues managing the other settings. Yes enables full manual configuration, but the selected NUT mode still determines which services start. Keep the GUI's UPS name and server address consistent so it displays the intended UPS.

Preserve the reserved lines and their positions in files still managed by the GUI. Back up the persistent configuration before substantial changes and protect that backup: it includes NUT credentials. Use Reset Config only when intentionally replacing the saved configuration.

Troubleshooting

Symptom	Check first
UPS not detected or USB device cannot be claimed	Correct driver, USB data cable, device availability to the host, and whether apcupsd or another process owns the device.
Connection refused	Correct server address and port, running upsd, listening addresses and network access controls. A Slave installation has no local upsd.
Unknown UPS	The name before @ must match the server's configured UPS name.
Driver not connected or data stale	Driver and USB/network-device logs. A running upsd alone does not establish communication with the UPS.
Readings work but the monitor reports an authentication error	Matching username, password and monitoring role at both ends; status queries do not validate them.
Changes disappear after restart or reboot	Save through the plugin editor and check whether the changed lines are GUI-managed.
Readings or available drivers differ from a guide	Check the installed NUT backend, plugin version and driver manual. Different backend selections can provide different NUT versions.

For plugin installation, GUI or Unraid integration questions, use the plugin support thread. For driver problems, include the NUT version, driver, UPS model and relevant sanitised log messages. Remove passwords, serial numbers and private network details before posting configuration or logs.

References

• Network UPS Tools plugin for Unraid: source and release information
• Plugin settings and field help for the version covered here
• NUT configuration guide
• NUT driver manuals
• upsd.users manual
• upsmon.conf manual