Home Network UPS Tools (NUT) Ultimate Guide
Post
Cancel

Network UPS Tools (NUT) Ultimate Guide

Posted Sep 25, 2021 Updated Feb 22, 2023
Preview Image
By Techno Tim
7 min read

Meet NUT Server, or Network UPS Tools. It’s an open UPS networking monitoring tool that runs on many different operating systems and processors. This means you can run the server on Linux, MacOS, or BSD and run the client on Windows, MacOS, Linux, and more. It’ perfect for your Pi, server, or desktop. It works with hundreds of UPS devices, PDUs, and many other power management systems.

This is the ultimate guide to configuring Network UPS Tools (NUT). We cover everything from installing and configuring the server on as Raspberry Pi, configuring the client on Windows and Linux, configure a charting and graphing website to visualize NUT data, spin up an additional web site use Docker, and finally set up monitoring and alerting to automate shutdowns of your machine.

https://networkupstools.org

Also, note to self, don’t eat a salad before you record a video….

📺 Watch Video

NUT UPS Server

plug in ups

1

lsusb

should see something like

1
2
3
4

Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 019: ID 09ae:2012 Tripp Lite
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

1
2

sudo apt update
sudo apt install nut nut-client nut-server

1

sudo nut-scanner -U

should see something like

tripp lite

1
2
3
4
5
6
7
8

[nutdev1]
        driver = "usbhid-ups"
        port = "auto"
        vendorid = "09AE"
        productid = "2012"
        product = "Tripp Lite UPS"
        vendor = "Tripp Lite"
        bus = "001"

apc 1500

1
2
3
4
5
6
7
8
9

[nutdev1]
        driver = "usbhid-ups"
        port = "auto"
        vendorid = "051D"
        productid = "0002"
        product = "Back-UPS XS 1500M FW:947.d10 .D USB FW:d10"
        serial = "3xxxxxxxxxxx"
        vendor = "Tripp Lite"
        bus = "001"

apc 850

1
2
3
4
5
6
7
8
9

[nutdev3]
        driver = "usbhid-ups"
        port = "auto"
        vendorid = "051D"
        productid = "0002"
        product = "Back-UPS ES 850G2 FW:931.a10.D USB FW:a"
        serial = "3xxxxxxxxxxx"
        vendor = "American Power Conversion"
        bus = "001"

1

sudo nano /etc/nut/ups.conf

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

pollinterval = 1
maxretry = 3

[tripplite]
    driver = usbhid-ups
    port = auto
    desc = "Tripp Lite 1500VA SmartUPS"
    vendorid = 09ae
    productid = 2012

[apc-network]
    driver = usbhid-ups
    port = auto
    desc = "APC Back-UPS XS 1500"
    vendorid = 051d
    productid = 0002
    serial = 3xxxxxxxxx

[apc-modem]
    driver = usbhid-ups
    port = auto
    desc = "APC 850 VA"
    vendorid = 051d
    productid = 0002
    serial = 3xxxxxxxxx

1

sudo nano /etc/nut/upsmon.conf

1
2
3

MONITOR [email protected] 1 admin secret master
MONITOR [email protected] 1 admin secret master
MONITOR [email protected] 1 admin secret master

1

sudo nano /etc/nut/upsd.conf

Change 127.0.0.1

1

LISTEN 127.0.0.1 3493

to all interface

1

LISTEN 0.0.0.0 3493 

1

sudo nano /etc/nut/nut.conf

1

MODE=netserver

1

sudo nano /etc/nut/upsd.users

1
2
3

[monuser]
  password = secret
  admin master

1

sudo nano /etc/udev/rules.d/99-nut-ups.rules

1
2
3
4
5
6
7

SUBSYSTEM!="usb", GOTO="nut-usbups_rules_end"

# TrippLite
#  e.g. TrippLite SMART1500LCD - usbhid-ups
ACTION=="add|change", SUBSYSTEM=="usb|usb_device", SUBSYSTEMS=="usb|usb_device", ATTR{idVendor}=="09ae", ATTR{idProduct}=="2012", MODE="664", GROUP="nut", RUN+="/sbin/upsdrvctl stop; /sbin/upsdrvctl start"

LABEL="nut-usbups_rules_end"

reboot (because it’s easy)

or

1
2
3
4
5

sudo service nut-server restart
sudo service nut-client restart
sudo systemctl restart nut-monitor
sudo upsdrvctl stop
sudo upsdrvctl start

APC UPS 950 va

list all usb devices

1

lsusb

query device by USB bus (replace with # from previous command)

1

lsusb -D /dev/bus/usb/001/057

You should see something like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass            0
  bDeviceSubClass         0
  bDeviceProtocol         0
  bMaxPacketSize0        64
  idVendor           0x051d American Power Conversion
  idProduct          0x0002 Uninterruptible Power Supply
  bcdDevice            0.90
  iManufacturer           1
  iProduct                2
  iSerial                 3
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength       0x0022
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0
    bmAttributes         0xe0
      Self Powered
      Remote Wakeup
    MaxPower                2mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           1
      bInterfaceClass         3 Human Interface Device
      bInterfaceSubClass      0
      bInterfaceProtocol      0
      iInterface              0
        HID Device Descriptor:
          bLength                 9
          bDescriptorType        33
          bcdHID               1.00
          bCountryCode           33 US
          bNumDescriptors         1
          bDescriptorType        34 Report
          wDescriptorLength    1049
         Report Descriptors:
           ** UNAVAILABLE **
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0008  1x 8 bytes
        bInterval             100

NUT CGI Server

1

sudo apt install apache2 nut-cgi

1

sudo nano /etc/nut/hosts.conf

1
2
3

MONITOR [email protected] "Tripp Lite 1500VA SmartUPS - Rack"
MONITOR [email protected] "APC 850 VA - Wall"
MONITOR [email protected] "APC Back-UPS XS 1500 - Rack"

1

sudo a2enmod cgi

1

sudo systemctl restart apache2

1

sudo nano /etc/nut/upsset.conf

1

I_HAVE_SECURED_MY_CGI_DIRECTORY

visit

http://your.ip.adddress/cgi-bin/nut/upsstats.cgi

Webnut Docker Container

1
2
3

mkdir webnut
cd webnut
nano docker-compose.yml

paste contents and save

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

version: "3.1"
services:
  nut:
    image: teknologist/webnut
    container_name: webnut
    environment:
      - UPS_HOST=ip.address.of.nut.server
      - UPS_PORT=3493
      - UPS_USER=admin
      - UPS_PASSWORD=secret
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - proxy
    ports:
      - 6543:6543
networks:
  proxy:
    external: true

1

docker-compose up -d --force-recreate

Linux NUT Client (remote)

1

sudo apt install nut-client

then run

1

upsc

to verify

verify you can connect

1

upsc [email protected]

1

sudo nano /etc/nut/upsmon.conf

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

RUN_AS_USER root

MONITOR apc-modem@ip.address.of.nut.server 1 admin secret slave

MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h"
NOTIFYCMD /usr/sbin/upssched
POLLFREQ 2
POLLFREQALERT 1
HOSTSYNC 15
DEADTIME 15
POWERDOWNFLAG /etc/killpower

NOTIFYMSG ONLINE    "UPS %s on line power"
NOTIFYMSG ONBATT    "UPS %s on battery"
NOTIFYMSG LOWBATT   "UPS %s battery is low"
NOTIFYMSG FSD       "UPS %s: forced shutdown in progress"
NOTIFYMSG COMMOK    "Communications with UPS %s established"
NOTIFYMSG COMMBAD   "Communications with UPS %s lost"
NOTIFYMSG SHUTDOWN  "Auto logout and shutdown proceeding"
NOTIFYMSG REPLBATT  "UPS %s battery needs to be replaced"
NOTIFYMSG NOCOMM    "UPS %s is unavailable"
NOTIFYMSG NOPARENT  "upsmon parent process died - shutdown impossible"

NOTIFYFLAG ONLINE   SYSLOG+WALL+EXEC
NOTIFYFLAG ONBATT   SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT  SYSLOG+WALL
NOTIFYFLAG FSD      SYSLOG+WALL+EXEC
NOTIFYFLAG COMMOK   SYSLOG+WALL+EXEC
NOTIFYFLAG COMMBAD  SYSLOG+WALL+EXEC
NOTIFYFLAG SHUTDOWN SYSLOG+WALL+EXEC
NOTIFYFLAG REPLBATT SYSLOG+WALL
NOTIFYFLAG NOCOMM   SYSLOG+WALL+EXEC
NOTIFYFLAG NOPARENT SYSLOG+WALL

RBWARNTIME 43200

NOCOMMWARNTIME 600

FINALDELAY 5

set net client

1

sudo nano /etc/nut/nut.conf

1

MODE=netclient

restart service

1

sudo systemctl restart nut-client

check status

1

sudo systemctl status nut-client

Windows NUT Client

https://github.com/gawindx/WinNUT-Client/releases

scheduling on the remote system

1

sudo nano /etc/nut/upssched.conf

1
2
3
4
5
6
7
8
9
10
11
12
13

CMDSCRIPT /etc/nut/upssched-cmd
PIPEFN /etc/nut/upssched.pipe
LOCKFN /etc/nut/upssched.lock

AT ONBATT * START-TIMER onbatt 30
AT ONLINE * CANCEL-TIMER onbatt online
AT ONBATT * START-TIMER earlyshutdown 30
AT LOWBATT * EXECUTE onbatt
AT COMMBAD * START-TIMER commbad 30
AT COMMOK * CANCEL-TIMER commbad commok
AT NOCOMM * EXECUTE commbad
AT SHUTDOWN * EXECUTE powerdown
AT SHUTDOWN * EXECUTE powerdown

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

sudo nano /etc/nut/upssched-cmd
``

```bash
#!/bin/sh
 case $1 in
       onbatt)
          logger -t upssched-cmd "UPS running on battery"
          ;;
       earlyshutdown)
          logger -t upssched-cmd "UPS on battery too long, early shutdown"
          /usr/sbin/upsmon -c fsd
          ;;
       shutdowncritical)
          logger -t upssched-cmd "UPS on battery critical, forced shutdown"
          /usr/sbin/upsmon -c fsd
          ;;
       upsgone)
          logger -t upssched-cmd "UPS has been gone too long, can't reach"
          ;;
       *)
          logger -t upssched-cmd "Unrecognized command: $1"
          ;;
 esac

make it executable (should already be)

1

chmod +x /etc/nut/upssched-cmd

Be sure PIPEFN and LOCKFN point to a folder that esists, I’ve seen it point to /etc/nut/upssched/ instead of /etc/nut If it does, create the folder or update these variables.

1

mkdir /etc/nut/upssched/

test

1

systemctl restart nut-client

then pull the plug on the ups connected to the master, check syslogs

1

tail /var/log/syslog

should see the logs

machine should shutdown

⚙️ See all the hardware I recommend at https://l.technotim.live/gear

🚀 Don’t forget to check out the 🚀Launchpad repo with all of the quick start source files

homelab
homelab nut self-hosted docker ups pdu open-source
This post is licensed under CC BY 4.0 by the author.
Recently Updated
Contents

Meet File Browser, a Small but Mighty Web File Browser

Meet Uptime Kuma, a Fancy Open Source Uptime Monitor for all your HomeLab Monitoring Needs