posts/NUT-server-guide/

[giscus[bot]]

posts/NUT-server-guide/

Documentation for Techno Tim YouTube videos for all your copy pasta needs!

https://technotim.live/posts/NUT-server-guide/

[elminster13]

Awesome tutorial - thank you for sharing. Helped me a lot as NUT is not the most intuitive system to config.

[xenolithis]

great guide, thank you!
had to add CANCEL-TIMER earlyshutdown to /etc/nut/upssched.conf for my linux clients to stop them from continuing to shutdown if line power is restored

[samip5]

Could you share how you did that?

[xenolithis]

Certainly

Add AT ONLINE * CANCEL-TIMER earlyshutdown to /etc/nut/upssched.conf

reload the nut-client service afterwards to apply

[SSPW]

In upssched-cmd, i see cases for onbat and earlyshutdown, that map to the events in upssched.conf,

but i dont see how shutdowncritical and upsgone every get passed to the script.

shouldnt they be powerdown and commbad to match upssched.conf???

totally noob here, what am i missing!

[SDeGonge]

Great tutorial. I do, however, want to disable broadcast messages but haven't been able to figure out how to do it (kind of a noob to Linux). Can you help? thanks.

oh...one more question. Occasionally the service stops working and I have to issue "sudo service nut-server restart" to get it going again. Don't know why this is happening and I know that the server did not restart. Any insight on this?

[Curtingham]

I'm not sure if this will stop absolutely all of the broadcast messages, but many of them are requested by the "+WALL" flag in upsmon.conf. For any NOTIFY event you don't want broadcasted, remove the "+WALL" from the NOTIFYFLAG line. So, if you have:

NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC

... and you don't want the broadcast messages for "UPS Online" to go out, change that line to:

NOTIFYFLAG ONLINE SYSLOG+EXEC

[smithj33]

Thanks for the guide! Looks like a typo on the Linux client install process.
systemctl status user-client

[Fernando-Checa]

great guide!! Thanks a lot for the time you invest.

Another typo at the end of linux client:
sduo systemctl status nut-client

[Unchain3140]

hi, on the /etc/nut/upssched.conf

i had use this config on:

==========================================
/etc/nut/upsmon.conf

RUN_AS_USER root

MONITOR your-ups-name@ip-of-your-NUT-server username yourpassword slave
NOTIFYCMD /usr/sbin/upssched
NOTIFYFLAG ONLINE WALL+EXEC
NOTIFYFLAG ONBATT WALL+EXEC

==========================================

CMDSCRIPT /etc/nut/upssched-cmd

PIPEFN /var/run/nut/upssched.pipe
LOCKFN /var/run/nut/upssched.lock

Timer to shutdown machine after 300 seconds

AT ONBATT * START-TIMER onbattwarn 300
AT ONLINE * CANCEL-TIMER onbattwarn

========================================

/etc/nut/upssched-cmd

#!/bin/sh
case $1 in
onbattwarn)
logger -t upssched-cmd "Timer On Battery Warning has been triggered - Shutting Down!"
wall "UPS timer expired: shutting down..."
shutdown -h now
;;
*)
logger -t upssched-cmd "Unrecognized command: $1"
;;
esac

=============================

base on my testing it will shutdown the server or pc base on how long you want but it will cancel the shutdown timer if the AC power return

[Unchain3140]

Hi, i updated the some config setting on the nut client.

#=========================================================

nano /etc/nut/upsmon.conf

#=========================================================

UPDATED 2023 SEP 16

RUN_AS_USER root
MONITOR [email protected] 1 monuser secret slave
#MONITOR [email protected] 1 monuser secret slave
NOTIFYCMD /usr/sbin/upssched
POLLFREQ 2
POLLFREQALERT 1
HOSTSYNC 15
DEADTIME 15
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
NOTIFYFLAG COMMOK SYSLOG+WALL+EXEC
NOTIFYFLAG COMMBAD SYSLOG+WALL+EXEC
RBWARNTIME 43200
NOCOMMWARNTIME 300
FINALDELAY 5

#=========================================================

nano /etc/nut/upssched.conf

#=========================================================

CMDSCRIPT /etc/nut/upssched-cmd

PIPEFN /var/run/nut/upssched.pipe
LOCKFN /var/run/nut/upssched.lock

Timer if the USP Server is offline for 300 seconds or 5 mins

AT COMMBAD * START-TIMER upsoffline 300
AT ONLINE * CANCEL-TIMER upsoffline
AT COMMOK * CANCEL-TIMER upsoffline

Timer to shutdown machine after 180 seconds

AT ONBATT * START-TIMER onbattwarn 180
AT ONLINE * CANCEL-TIMER onbattwarn

Timer if the UPS Battery is low 60 seconds before shutdown

AT LOWBATT * START-TIMER lowbatt 60
AT ONLINE * CANCEL-TIMER lowbatt

#=========================================================

mkdir /etc/nut/upssched/
nano /etc/nut/upssched-cmd

#=========================================================

#!/bin/sh
case $1 in
onbattwarn)
logger -t upssched-cmd "UPS IS ON BATTERY, SHUTING DOWN WITH IN 180 SECONDS !"
wall "180 SECONDS UP, UPS SYSTEM WILL SHUT DOWN...."
shutdown -h now
;;
lowbatt)
logger -t upssched-cmd "UPS BATTERY IS LOW IT WILL SHUT DONW WITH IN 60 SEC"
wall "60 SECONDS UP, UPS BATTERY IS LOW SYSTEM WILL SHUTDOWN...."
shutdown -h now
;;
upsoffline)
logger -t upssched-cmd "UPS SERVER IS OFFLINE"
wall "UPS SERVER IS OFFLINE ALREADY FOR 300 SECONDS OR 5 MINUTES, SYSTEM WILL SHUT DOWN...."
shutdowm -h now
;;
*)
logger -t upssched-cmd "Unrecognized command: $1"
;;
esac

#=========================================================

on that new configuration it will shutdown the server if it cant connect to the ups nut server, and also it will stop the count down timer if the nut server is up, same goes on the batter low and on ups battery mode, once the AC power is up and runinng all timer will be termincated.

[Techssh]

Can I configure it with Nginx web server?

[nickshin]

@Techssh, install fcgiwrap and use something similar to the following:

server {
	listen 8080; # your_port_number
	server_name nut.homelab; # your_server_name

	location /nut {
		alias /usr/share/nut/www/;
		try_files $url $url/ /index.html;
		index index.html;
	}

	location /cgi-bin/ {
		gzip off;
		root /usr/lib;

# because this is CGI-BIN - restrict access with a HEAVY hand
		allow 127.0.0.1;
#		<add more allow here>
		deny all;

		include /etc/nginx/fastcgi.conf;
		fastcgi_pass unix:/var/run/fcgiwrap.socket;
	}

	# and what ever else you want here for (e.g.) `location /`
}

[PikkonMG]

How would you do this to shutdown on battery % or give longer run time. My UPS can run my server for around an hour so I don't need it shutting down in seconds.

[Curtingham]

There are more than one ways to do this, but what I've found preferable is this:

In ups.conf, for the UPS in question, add these lines:

	ignorelb
	override.battery.charge.low = 95
	override.battery.runtime.low = 1800

ignorelb: From what I could see, "Low Battery" status was otherwise determined by the UPS firmware, and it was a bit unclear exactly when it would decide the battery was low. This setting ignores what the UPS reports, and basically lets the next two settings determine when the battery is low

override.battery.charge.low: this is a percentage, and what I set here was very high. Edit it as you see fit. When the battery drops below this percentage, the UPS will go into "Low battery" state

override.battery.runtime.low: Similar to above, but based on the UPSs estimate of remaining battery time left. I set to 30 minutes in this example, but you could adjust as needed.

With the three options set above, the UPS will go into "Low battery" mode when either the battery charge drops below override.battery.charge.low, or when the estimated time remaining on battery drops below override.battery.runtime.low.

If you have upsmon running on a device monitoring this UPS, it won't shut down until "Low Battery" mode is hit. So tuning the variables above should give you what you are looking for.

[Fufs]

So according to https://networkupstools.org/ the upsmon types are primary and secondary, while linux.die.org says it's master and slave. Which is correct? Also according to the documentaion upsd.users should be

[monuser]
  password = secret
  upsmon [master/primary]

not

[monuser]
  password = secret
  admin [master/primary]

[Fufs]

Quick follow-up, primary and secondary seem to throw an error in nut-server service on Ubuntu server 22.04LTS. Not sure why the official documentation is different.

[Curtingham]

I also ran into this confusion recently. 'upsmon [master/slave]' is used up to NUT version 2.7.4, anything later uses 'admin [primary/secondary]'. If you're getting an error when trying to use 'admin [primary/secondary]' in your configuration files, I would bet that it's due to being on NUT version 2.7.4 or earlier, which still expects 'upsmon [master/slave]'.

While the documentation has been updated to cover the latest version of NUT, apt (and possibly other package managers) are still installing 2.7.4.

[Madchristian]

upssched.conf

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

# Starts a timer when the UPS switches to battery power
AT ONBATT * START-TIMER shutdown_timer 600

# Cancels the shutdown timer when power is restored
AT ONLINE * CANCEL-TIMER shutdown_timer

# Executes immediate shutdown when battery is low
AT LOWBATT * EXECUTE immediate_shutdown

# Starts a timer on communication failure
AT COMMBAD * START-TIMER commbad_timer 300

# Cancels the communication failure timer when communication is restored
AT COMMOK * CANCEL-TIMER commbad_timer

# Executes shutdown on persistent communication failure
AT NOCOMM * EXECUTE commbad_shutdown

# Executes powerdown on system shutdown
AT SHUTDOWN * EXECUTE powerdown

upssched-cmd Skript

#!/bin/sh

case $1 in
    shutdown_timer)
        # Log the event and initiate a controlled shutdown
        logger -t upssched-cmd "UPS running on battery for too long, initiating shutdown"
        /usr/sbin/upsmon -c fsd
        ;;

    immediate_shutdown)
        # Log the critical battery status and initiate immediate shutdown
        logger -t upssched-cmd "UPS on battery critical, forced shutdown"
        /usr/sbin/upsmon -c fsd
        ;;

    commbad_timer)
        # Log persistent communication failures and initiate shutdown
        logger -t upssched-cmd "UPS communication failure persists, initiating shutdown"
        /usr/sbin/upsmon -c fsd
        ;;

    commbad_shutdown)
        # Log communication failure and initiate shutdown
        logger -t upssched-cmd "UPS communication failed, initiating shutdown"
        /usr/sbin/upsmon -c fsd
        ;;

    powerdown)
        # Log the execution of the shutdown
        logger -t upssched-cmd "Executing powerdown command"
        ;;

    *)
        # Log unknown commands
        logger -t upssched-cmd "Unrecognized command: $1"
        ;;
esac

In these configurations:

• The upssched.conf file sets up various timers and actions based on UPS events.
• The upssched-cmd script handles each event with appropriate logging and actions, such as initiating a forced shutdown when the UPS is on battery for too long or when it's critically low.

Remember to make the upssched-cmd script executable with sudo chmod +x /etc/nut/upssched-cmd and test these configurations in a controlled environment to ensure they work as expected.

[HankB]

Thanks for a treat tutorial - just about perfect for my level of expertise. I started testing on my server and the battery died before it could shut down. New battery ordered. (It lasted ~2 minutes so it carries me through the situations where the lights flicker.)

I did have an issue with NUT unable to communicate with the UPS (via USB) on Debian Buster. Likely some sort of permissions problem. I had been meaning to upgrade to Bookworm so I did that (rather than track down the permissions) and that solved the issue.

Thanks!

[JordyWingelaar]

Hi,

I'm trying to install a NUT-client on my MacMini.
My rasberryPI4 functions as NUT-server, with a windows machine and a Macmini attached to it. I've gotten so far that the server is up and running, and the windows machine is able to communicate with the nut-server by using the Win-NUT client.

Trying to set my macmini up to listen to the nut-server. So far, I have installed the NUT-software using MacPorts. However, that is where I'm stuck:(

Can you help me in the right direction?

Thanks, kind regards Jordy

[mspencerl87]

I've found this alternative upssched-cmd script that I thought you might find useful.
I don't have the skill to verify it without breaking everything. But adds a few extra functions to email on these events.

https://forum.proxmox.com/threads/nut-client-configuration-help-needed-for-shutdown-proxmox-host.126278/
Code:
#!/bin/sh

EMAIL=cat /etc/pve/user.cfg | grep root | awk '{split($0,a,":"); print a[7]}'
PROXMOXHOST=$(uname -n)

case $1 in
onbatt)
logger -t upssched-cmd "UPS on battery"
/usr/sbin/upsmon -c fsd
;;
commbad_message)
echo "UPS is not connected" | mailx -s "Proxmox ($PROXMOXHOST): UPS Warning" $EMAIL
;;
online)
logger -t upssched-cmd "UPS Online"
;;
commok_message)
echo "UPS is connected again" | mailx -s "Proxmox ($PROXMOXHOST): UPS Warning" $EMAIL
;;
nocomm_message)
echo "UPS is not reachable" | mailx -s "Proxmox ($PROXMOXHOST): UPS Warning" $EMAIL
;;
shutdowncritical)
logger -t upssched-cmd "UPS on battery critical, forced shutdown"
;;
upsgone)
logger -t upssched-cmd "UPS has been gone too long, can't reach"
;;
shutdown_message)
echo "Proxmox shutdown" | mailx -s "Promox ($PROXMOXHOST): UPS Warning" $EMAIL
;;
*)
logger -t upssched-cmd "Unrecognized command: $1"
;;
esac

Also, I've found that on my NUT server, I can't seem to find any loggings. But found you can tell Nut Server to write logs to /var/log/nut.log via 99-nut.conf by adding this to /etc/rsyslog.d/99-nut.conf

This may also bring even more functionality to this guide how to use the 99-nut.conf found here
https://github.com/sysadmin-info/NUT

[mp-strachan]

nut-cgi also supports auto-refresh via a query string... if you add ?refresh={x}, where {x} in a period in seconds, the page will auto refresh. Super handy for dashboard style monitoring

Eg: 5sec refresh:
http://your.ip.adddress/cgi-bin/nut/upsstats.cgi?refresh=5

[MatejsLab]

Hi i use synology as NUT server, and i tested nut client over ETH on Debian 12 with config from post. The NUT is kind of overcomplicated config so i dont trust my config yet.

My planned behaviour:

• On Battery after 5 min, do client device shutdown.
• Make sure UPS keeps running, so prevent UPS powerdown, as synology does it at last.
• Never shutdown client device on comunication issues, dont want random shutdowns, client can survive clean power cut that UPS does.
• Make sure client device restores power ON after software shutdown? It needs Bios fix to always restore power, now is last state before power loss.

What from sudo nano /etc/nut/upsmon.conf and sudo nano /etc/nut/upssched.conf is bare minimum to run cleanlly.
NOTIFYMSG seems useless, where it shows notify mesaage?

RUN_AS_USER root

MONITOR ups@ 1 slave

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

Ditch all commands i don't like

POWERDOWNFLAG /etc/killpower # I deem this is the dangerous call to UPS !!!

NOTIFYMSG ONLINE "UPS %s on line power"

NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC

RBWARNTIME 43200 # What is this?
NOCOMMWARNTIME 600
FINALDELAY 5

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 # When this runs, at shutdown of what?
AT SHUTDOWN * EXECUTE powerdown

!/bin/sh

MQTT_HOST="192.168.1.222"
MQTT_PORT="1883"
MQTT_TOPIC="DS-ups/status"

publish_mqtt() {
MESSAGE=$1
mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" -t "$MQTT_TOPIC" -m "$MESSAGE"
}

case $1 in
online)
publish_mqtt "On AC Power"
;;
onbatt)
publish_mqtt "On Battery"
;;
earlyshutdown)
publish_mqtt "Battery low, PC shutdown"
/usr/sbin/upsmon -c fsd
;;
shutdowncritical)
publish_mqtt "BAT critical, PC shutdown"
/usr/sbin/upsmon -c fsd
;;
upsgone)
publish_mqtt "UPS not connected"
;;
*)
publish_mqtt "Unrecognized command: $1"
;;
esac

[reboot81]

[DEPRECATION NOTICE] Docker Image Format v1 and Docker Image manifest version 2, schema 1 support is disabled by default and will be removed in an upcoming release. Suggest the author of docker.io/teknologist/webnut:latest to upgrade the image to the OCI Format or Docker Image manifest v2, schema 2. More information at https://docs.docker.com/go/deprecated-image-specs/

Any way around this?

[OwlTrkr]

I've been hitting a weird stumbling block that I have not been able to resolve. I have the nut-server installed and running fine on a RasPi4, no problems there. It can see my TrippLite UPS and I can load the stats via browser and upsc on my main Linux workstation just fine.
The problem is with nut-client. I followed the Linux nut-client process above exactly, except for changing the particular details involved in my MONITOR statement. I get an error "Unable to use old-style MONITOR line without a username".

$ sudo systemctl status nut-client
× nut-monitor.service - Network UPS Tools - power device monitor and shutdown controller
Loaded: loaded (/lib/systemd/system/nut-monitor.service; enabled; preset: enabled)
Active: failed (Result: exit-code) since Sat 2024-07-20 07:45:07 EDT; 1min 0s ago
Duration: 1ms
Process: 9504 ExecStart=/sbin/upsmon -F (code=exited, status=1/FAILURE)
Main PID: 9504 (code=exited, status=1/FAILURE)
CPU: 1ms

Jul 20 07:45:07 Fenrir systemd[1]: Started nut-monitor.service - Network UPS Tools - power device monitor and shutdown controller.
Jul 20 07:45:07 Fenrir nut-monitor[9504]: fopen /run/nut/upsmon.pid: No such file or directory
Jul 20 07:45:07 Fenrir nut-monitor[9504]: Could not find PID file to see if previous upsmon instance is already running!
Jul 20 07:45:07 Fenrir nut-monitor[9504]: Unable to use old-style MONITOR line without a username
Jul 20 07:45:07 Fenrir nut-monitor[9504]: Convert it and add a username to upsd.users - see the documentation
Jul 20 07:45:07 Fenrir nut-monitor[9504]: Fatal error: unusable configuration
Jul 20 07:45:07 Fenrir nut-monitor[9504]: Network UPS Tools upsmon 2.8.0
Jul 20 07:45:07 Fenrir systemd[1]: nut-monitor.service: Main process exited, code=exited, status=1/FAILURE
Jul 20 07:45:07 Fenrir systemd[1]: nut-monitor.service: Failed with result 'exit-code'.

-------upsmon.conf---------

RUN_AS_USER root

MONITOR [email protected] 1 admin complexpassword 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

[chicknlil]

Hi there. Got directed to your YT video (and then found this updated guide). I've been working for the past week or so, trying to get my Tripp Lite AVR900U seen by my Proxmox server. Between other Proxmox specific guides and yours (with a more Tripplite angle) I believe I have it set up properly. Yet still it fails to properly connect...

DMESG seems to imply it's not doing the rapid fire disconnect/reconnect these devices are known for. But I'm not sure how well it's being seen, either.

From within the last 10 minutes, after I've tried tweaking things based on your guide:

Communications with UPS tripplite@localhost lost

UPS tripplite@localhost is unavailable

Network UPS Tools - UPS driver controller 2.8.0
Can't open /run/nut/usbhid-ups-tripplite.pid: No such file or directory
Can't open /run/nut/usbhid-ups-auto.pid either: No such file or directory

Network UPS Tools - UPS driver controller 2.8.0
Network UPS Tools - Generic HID driver 0.47 (2.8.0)
USB communication driver (libusb 1.0) 0.43
Can't claim USB device [09ae:3024]@0/0: Entity not found
Driver failed to start (exit status=1)

I know I had this working with a previous version of Proxmox (VE 7) but I can't seem to recrate (or start fresh) with NUT on VE 8.

[MatejsLab]

I like NUT but it is overcomplicated to set up and to misterious for me.
I still installed nutserver and relay the data.

So i have written bash script that runs as service pools the nut data and sends it to MQTT for devices to read and react on it. It is more custom so i can underatand it.
Then other tiny bash script runs on clients that subscribes to MQTT and reacts to UPS events.

Idk if MQTT is best, but i feel like it cant be reliable the original way as its too complicated.
Any ideas or sugestions on my appeoach appriciated