Network UPS Tools (NUT): A Complete Setup Guide

How NUT is put together

NUT is a set of small programs rather than one daemon. Knowing which piece does what makes every error message easier to read.

The examples below use the Debian and Ubuntu layout (/etc/nut/). Some distributions use /etc/ups/; the file contents are the same. Install the packages first (on Debian and Ubuntu, the nut package pulls in server and client parts).

Step 1: nut.conf sets the role

# /etc/nut/nut.conf
# none        = NUT disabled
# standalone  = one machine, UPS on this host, no network clients
# netserver   = UPS on this host, other machines connect to it
# netclient   = this host only runs upsmon against a remote server
MODE=netserver

Use standalone if this is the only machine on the UPS. In practice netserver costs nothing extra and makes adding a second host later a one-file change.

Step 2: ups.conf defines the UPS

Run nut-scanner -U first. It lists USB UPS devices and prints a ready-made section with the right driver, vendor ID and product ID.

# /etc/nut/ups.conf
maxretry = 3

[myups]
    driver = usbhid-ups
    port = auto
    desc = "Rack UPS, office closet"
    # Optional: raise low-battery earlier than the UPS's own signal
    # ignorelb
    # override.battery.charge.low = 30
    # override.battery.runtime.low = 300

The name in brackets (myups) is how every other tool refers to the UPS. port = auto is correct for USB drivers; serial drivers need a device such as /dev/ttyS0. If you have two USB UPS units on one host, add vendorid, productid or serial lines so each section matches the right one.

Start the driver and check for errors:

sudo upsdrvctl start
# or, on distributions with NUT 2.8 systemd units:
sudo systemctl restart nut-driver@myups.service

Unit names vary. Recent NUT releases generate one nut-driver@NAME unit per section, grouped by nut-driver.target; older packages use a single nut-driver.service. Run systemctl list-units 'nut*' to see what your system has.

Step 3: upsd.conf and upsd.users control access

# /etc/nut/upsd.conf
LISTEN 127.0.0.1 3493
LISTEN 192.168.1.10 3493     # this server's LAN address

You will see many guides use LISTEN 0.0.0.0 3493. That works, but it listens on every interface, including VPN, guest or public-facing ones. Listing specific addresses is safer. Either way, allow 3493 only from your LAN in the host firewall.

# /etc/nut/upsd.users
[upsmon_local]
    password = ChangeThisLocal
    upsmon primary

[monuser]
    password = ChangeThisRemote
    upsmon secondary

[admin]
    password = ChangeThisAdmin
    actions = SET
    instcmds = ALL

upsmon primary grants the right to declare a forced shutdown. Give it only to the upsmon on the server itself. Clients get upsmon secondary. The admin user is for upscmd and upsrw; leave it out if you will never send commands. On NUT older than 2.8, write upsmon master and upsmon slave instead. The files hold passwords, so make sure they are readable only by root and the NUT group (packages usually set this).

Step 4: upsmon.conf decides when to shut down

# /etc/nut/upsmon.conf (on the server)
MONITOR myups@localhost 1 upsmon_local ChangeThisLocal primary
MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
POWERDOWNFLAG /etc/killpower

POLLFREQ 5
POLLFREQALERT 5
HOSTSYNC 15
DEADTIME 15
FINALDELAY 5

NOTIFYCMD /usr/local/bin/ups-notify.sh
NOTIFYFLAG ONBATT   SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE   SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT  SYSLOG+WALL+EXEC
NOTIFYFLAG FSD      SYSLOG+WALL+EXEC
NOTIFYFLAG COMMBAD  SYSLOG+WALL+EXEC
NOTIFYFLAG REPLBATT SYSLOG+WALL+EXEC

• MONITOR: UPS name at host, the number of power supplies this host draws from that UPS (1 for a normal server), user, password, role.
• MINSUPPLIES: how many supplies must stay healthy for the host to keep running. Servers with two power supplies on two UPS units can use this so losing one UPS does not shut them down.
• SHUTDOWNCMD: what upsmon runs. Use the full path. On hypervisors this is often a script that stops guests first.
• POWERDOWNFLAG: a file the primary creates just before shutdown, telling the late shutdown stage to send killpower. Some packages set a different default path; keep whatever your distribution's shutdown hook expects.
• NOTIFYCMD and NOTIFYFLAG: EXEC runs your script with the message as an argument and NOTIFYTYPE and UPSNAME in the environment. That script is where email, push alerts or webhooks go.
• HOSTSYNC: how long the primary waits for secondaries to disconnect during FSD. DEADTIME: how long a UPS can go without fresh data before upsmon treats it as dead.

Now start everything and check:

sudo systemctl restart nut-server nut-monitor
upsc -l                # lists UPS names upsd is serving
upsc myups@localhost   # dumps all variables

Typical output includes lines such as battery.charge: 100, battery.runtime: ... (seconds), input.voltage: ..., ups.load: ... (percent) and, most important, ups.status: OL CHRG. Which variables appear depends on what the UPS reports.

Reading ups.status

Step 5: add network clients

On each additional machine, install the client package and set two files:

# /etc/nut/nut.conf
MODE=netclient

# /etc/nut/upsmon.conf
MONITOR myups@192.168.1.10 1 monuser ChangeThisRemote secondary
MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"

Restart nut-monitor on the client and run upsc myups@192.168.1.10 to confirm it can reach the server. Clients that cannot reach the server log COMMBAD and, after DEADTIME, will shut down if the UPS was last seen on battery.

The shutdown sequence, step by step

Understanding FSD avoids most "why did it shut down early" and "why didn't it come back" questions.

1. Power fails. The UPS reports OB. Every upsmon logs ONBATT and runs its notifications. Nothing shuts down yet.
2. Battery reaches critical. The status becomes OB LB. The primary upsmon sets the FSD flag on upsd.
3. Secondaries shut down. They see FSD, run their SHUTDOWNCMD, and disconnect from upsd as they go down.
4. The primary waits. It waits until all secondaries have disconnected or HOSTSYNC expires, whichever comes first.
5. The primary shuts down. It creates the POWERDOWNFLAG file, waits FINALDELAY, and runs its own SHUTDOWNCMD.
6. Killpower. Near the end of the OS shutdown, a hook checks for the flag (with upsmon -K) and runs the driver's shutdown routine (upsdrvctl shutdown or the packaged equivalent). The UPS is told to turn its output off after a delay, often around 20 seconds by default for usbhid-ups (ups.delay.shutdown).
7. Power returns. The UPS restores output, and machines with "restore on AC power loss" set in BIOS boot automatically.

Commands and settings: upscmd and upsrw

upscmd -l myups                                   # list supported instant commands
upscmd -u admin myups test.battery.start.quick    # start a quick self-test
upscmd -u admin myups beeper.mute                 # silence the current alarm
upsrw myups                                       # list writable variables
upsrw -s ups.delay.shutdown=60 -u admin myups     # change the killpower delay

Both tools prompt for the password if you omit -p, which keeps it out of shell history. Commands and writable variables vary widely by UPS model. See self-test and runtime calibration for when to run tests.

Troubleshooting

If the operating system does not see the UPS at all (nothing in lsusb), the problem is below NUT. Work through UPS not detected by computer.

Where to go next

For platform-specific setups, see Proxmox UPS shutdown, Synology, TrueNAS and Home Assistant monitoring. For an APC-only alternative with a simpler single file, see apcupsd. For picking a shutdown threshold, see how much runtime you need, and for a NAS-centered setup, UPS for a NAS.