sudo upscmd -u <admin_user> <ups> test.battery.start.quick doesn't fire shutdown handler script

[LoZZoL]

To be clear early doors, I'm sure this is a user setup issue rather than an actual bug. The problem may be that I've ended up grabbing bits of configuration from various sources on the internet, some of which may be out of date.

High level: I am expecting, when nut server detects an ONBATT signal from the USB attached UPS, that a script is executed. When the script is executed manually it works fine, but I understand that the best way to simulate the ONBATT status is to run sudo upscmd -u <admin_user> <ups> test.battery.start.quick. This gives me an OK message but never seems to run the script.

I should say that the UPS is detected and sudo upsc <ups> gives me back the status.

I've been searching around the internet on and off for a number of days/weeks but haven't yet found a way to get this resolved. I'll paste as much information as I understand to be useful below, and would be grateful for any pointers!

/etc/os-release:

PRETTY_NAME="Ubuntu 24.04.4 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.4 LTS (Noble Numbat)"
VERSION_CODENAME=noble
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=noble
LOGO=ubuntu-logo

uname -a:
Linux rpiupsdns 6.8.0-1052-raspi #56-Ubuntu SMP PREEMPT_DYNAMIC Fri Mar 27 03:58:47 UTC 2026 aarch64 aarch64 aarch64 GNU/Linux

/etc/nut/ups.conf:

[<ups>]
driver = usbhid-ups
desc = "<desc>"
port = auto
vendorid = 051d
productid = 0002
override.battery.charge.low=75

/etc/nut/nut.conf:
MODE=standalone

/etc/nut/upsd.conf:

LISTEN 127.0.0.1 [3493]
MAXCONN 15

/etc/nut/upsd.users:

[admin]
    password = <secret>
    actions = set
    actions = fsd
    instcmds = ALL
    upsmon primary
[monuser]
    password = <secret>
    upsmon slave

/etc/nut/upsmon.conf:

MINSUPPLIES 1
SHUTDOWNCMD "/usr/sbin/shutdown -h +0"
NOTIFYCMD /bin/upssched-cmd
POLLFREQ 5
POLLFREQALERT 5
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"
NOTIFYMSG CAL           "UPS %s: calibration in progress"
NOTIFYMSG OFF           "UPS %s: administratively OFF or asleep"
NOTIFYMSG NOTOFF        "UPS %s: no longer administratively OFF or asleep"
NOTIFYMSG BYPASS        "UPS %s: on bypass (powered, not protecting)"
NOTIFYMSG NOTBYPASS     "UPS %s: no longer on bypass"
NOTIFYFLAG ONLINE     EXEC+SYSLOG+WALL
NOTIFYFLAG ONBATT     EXEC+SYSLOG+WALL
NOTIFYFLAG LOWBATT    EXEC+SYSLOG+WALL
NOTIFYFLAG REPLBATT   EXEC+SYSLOG+WALL
OFFDURATION 30
RBWARNTIME 43200
NOCOMMWARNTIME 300
FINALDELAY 5
MONITOR qnapups@localhost 1 <user> <password> primary

/etc/nut/upssched.conf:

CMDSCRIPT /bin/upssched-cmd
PIPEFN /run/nut/upssched.pipe
LOCKFN /run/nut/upssched.lock
AT ONBATT * EXECUTE shutdown_onbatt
AT ONBATT * EXECUTE info_onbatt
AT ONLINE * CANCEL-TIMER shutdown_onbatt
AT ONLINE * EXECUTE ups-back-on-power
AT LOWBATT * EXECUTE shutdown_lowbatt
AT REPLBATT * EXECUTE replace_batt

/bin/upssched-cmd:

case $1 in
    shutdown_onbatt)
        touch /home/lozlocal/ran
        logger -t upsmon[upssched] "shutdown_onbatt): Triggering shutdown after 2 minutes on battery"
        <other code>
        ;;

    shutdown_lowbatt)
        logger -t upsmon[upssched] "shutdown_lowbatt): Triggering shutdown when battery.charge.low is under 75%"
        <other code>
        ;;

    info_onbatt)
        logger -t upsmon[upssched] "info_onbatt): Now on battery"
        <other>
        ;;

    ups-back-on-power)
        logger -t upsmon[upssched] "ups-back-on-power): UPS back on power"
        <code>
        ;;

    replace_batt)
        message="Quick self-test indicates battery requires replacement"
        logger -t upsmon[upssched] "replace_batt): $message"
        <code>
        ;;

    *)
        logger -t upsmon[upssched] "*) = Unrecognized command: $1"
        ;;
esac

[jimklimov]

One first reaction - you should not need sudo for clients like upsc and upscmd.

You might want to start the upsmon client daemon as root (its service or init script typically does that) so it can leave a privileged half running just to initiate OS shutdown (altrernately, maybe a sudo in its SHUTDOWNCMD and corresponding NOPASSWD setup in /etc/sudoers for the nut account may achieve same goal.

Rarely one might benefit from running NUT drivers as root, mostly to debug if it is OS permissions or something else that blocks a driver from seeing a device.

I'll go on reading further paragraphs, as I'm commuting now :)

[jimklimov]

Maybe the premise is a bit wrong: when you ask for a battery test or calibration, that state is known to upsmon and so it "knows" this is just a drill and not a real outage, so there is no need to run the shutdown scripts. Not sure, but maybe it would not even upon reaching LB as some UPSes may drain themselves as far as they can, to learn the range of the battery's chemistry as it is today. Sometimes they do overestimate it (e.g. if the last test was so long ago that its data are irrelevant) and the load gets powered off due to the test. Also loss of wall power during the test is likely "fatal".

[jimklimov]

The upscmd and upsrw clients do report "OK" meaning they could submit the request to the upsd server (connectivity and auth were okay, command is known and args acceptable). Most requests are asynchronous, so you might want to add -w argument to upscmd and wait for completion status as propagated from the driver.

IIRC newer versions should warn about this somewhat humanly unexpected twist more loudly (did so in debug messages).

[jimklimov]

In your notification handler script, keep in mind that it runs as the user of the main part of upsmon daemon - typically nut - so would not normally have permissions to touch a file in home directory of your own account.

Not sure now your shell handles brackets; to err on the safe side, perhaps quote all arguments to logger.

The "other code" for shutdown should involve upsmon -c fsd which sends a signal to the daemon and it would start a chain of events that ends up with SHUTDOWNCMD. Process signals may be sent only by same user account (nut as inherited from upsmon to upssched to your script to upsmon -c fsd) or root (e.g. via sudo from some other permitted user).

[LoZZoL]

Thank you very much for all the detailed replies. Some of them are going over my head slightly, I'll have to confess!

One thing that does stand out is what you are saying about the nut user. So, this would be the user 'running' the /bin/upssched-cmd shutdown_onbatt command? If that's the case I definitely have some permissioning to do. You're right, the touch I've got in the script would not work (although that was just added in as a troubleshooting method) but the other commands might not too. I'll change the logger lines to include quotation marks too.

You've given me some things to work on from my end, let me dig in to those and see how I get on. And thanks once again for taking the time to reply!

[LoZZoL]

I've had some time to change things around at my end. Now, running sudo -u nut /bin/upssched-cmd shutdown_onbatt works as expected, it runs through the script handling the machine (VMs, NAS boxes, hypervisors) shutdowns in the correct order. Great.

Now - how can I simulate a power outage where the UPS switches over to battery and nut automatically triggers this script to run? upscmd -u <admin_user> <ups> test.battery.start.quick doesn't appear to be the correct way.

EDIT: It's worth noting that the shutdown_onbatt section of the /bin/upssched-cmd script handles the graceful shutdown of my entire infrastructure, so it is just this script which needs to be triggered.

[jimklimov]

One thing that does stand out is what you are saying about the nut user. So, this would be the user 'running' the /bin/upssched-cmd shutdown_onbatt command? If that's the case I definitely have some permissioning to do.

Yes, and at least regarding the actual shutdown (which needs privileges) the upsmon -c fsd is the way to go - as it can tell the half of its daemon (one that remained as root before the main half dropped privileges to nut) to proceed with the SHUTDOWNCMD. Also if you have many systems fed by the UPS, they will know they need to shut down, and will be waited for by this primary system.

how can I simulate a power outage where the UPS switches over to battery and nut automatically triggers this script to run?

I may be forgetting something, but I think there is no sure-fire way with hardware drivers other than pulling the plug. Maybe there are tricks valid for specific devices and/or drivers.

You can use a dummy-ups however (as if it feeds your box) and feed whatever statuses you need via its dev/seq input file for the same testing effect.

You can also use a dummy SHUTDOWNCMD that logs as if it is going to power off, if you do not want to interrupt the systems - but running the real operation is useful at least to time it (will there be enough battery to complete the clean shutdown?) and to see if nutshutdown hook got well integrated so the UPS would power down (or cycle if/when wall power returns) in the very end.