On this page
- What you are setting up
- Pick a layout
- Install NUT in dom0 without breaking updates
- Layout 1: the host owns the UPS
- Layout 2: the host is a client of a NAS or a Pi
- The shutdown script, step by step
- Worked example: one host, one stubborn VM
- Start early: add an on-battery timer
- Where this stops applying
- Frequently asked questions
What you are setting up
Network UPS Tools (NUT) is the open-source program that reads a UPS and shuts computers down when the battery runs low. It has three parts. A driver talks to the UPS over USB or the network. A server, upsd, shares what the driver reads on TCP port 3493. A monitor, upsmon, watches that data and runs a command when it is time to stop. That command is set by SHUTDOWNCMD in upsmon.conf. Our NUT guide covers each part in depth.
On XCP-ng, all of this runs in dom0. That is the small Linux control domain that manages the host. You type xe commands there. It is not a VM you created, and it is not Xen Orchestra.
The job has two halves. NUT decides when. A shell script decides how: it asks each VM to shut down, waits, forces any stragglers, and only then powers off the host. XCP-ng gives you no UPS screen and no UPS page in its docs. The steps below come from the community how-to on the XCP-ng forum, checked against the XCP-ng docs and the NUT manual pages.
Pick a layout
Where the UPS data cable plugs in decides the NUT role. The primary owns the UPS and shuts down last. A secondary follows the primary over the network and shuts down first.
| UPS data cable goes to | XCP-ng host runs | nut.conf MODE | Host role |
|---|---|---|---|
| The XCP-ng host (USB) | Driver, upsd and upsmon | netserver (or standalone if nothing else shares the UPS) | Primary |
| A NAS, Raspberry Pi or firewall | upsmon only | netclient | Secondary |
| A VM on the same host (USB passthrough) | Do not use. The VM stops before the host it is meant to shut down. | ||
The forum how-to's author explains the last row plainly: the NUT server "must be installed on a system to shut down last", so it cannot live in a VM on the host it protects.
Install NUT in dom0 without breaking updates
The forum guide starts with yum --enablerepo=* install epel-release. Skip that line. XCP-ng's own docs say the update process "assumes that only XCP-ng repositories are enabled". They warn that installing epel-release "will automatically enable" EPEL. Updates could then pull packages from it and overwrite XCP-ng's. The EPEL repos are already in dom0, disabled on purpose, so you never need epel-release.
| Release | Install command | Notes |
|---|---|---|
| XCP-ng 8.3 | yum install nut nut-client | NUT 2.8.0, built by XCP-ng, in the 8.3 updates repo. nut is on the 8.3 supported extra packages list. |
| XCP-ng 8.2 | yum install nut nut-client --enablerepo=epel | Not in the XCP-ng repos. EPEL 7 is end of life, so the docs call this "even more at your own risk". |
XCP-ng 8.3 still uses yum, and its package docs show only yum commands. The --enablerepo switch turns a repo on for one command only. Install both packages even on a client. A December 2024 forum post found that nut-monitor will not autostart without nut.target, which comes with them. Then enable both units:
systemctl enable nut.target
systemctl enable nut-monitor
Without the target, that post says, "nothing will ever trigger" and the journal stays empty. That makes it easy to miss until a real outage.
Why two install commands circulate
The epel-release line dates from XCP-ng 8.2, when NUT was only in EPEL. As the XCP-ng docs note, installing epel-release is the common way to enable EPEL on CentOS, so it looks normal. It works on the day you run it. The cost shows up later, at an update. On 8.3 the question is gone: NUT is in XCP-ng's own repo, dated April 2026, so no third-party repo is needed at all.
Layout 1: the host owns the UPS
Plug the UPS USB cable into the host and run nut-scanner -U to find it. The config files live in /etc/ups/ on XCP-ng, not /etc/nut/ as on Debian. These are trimmed from the forum guide. The passwords are placeholders.
# /etc/ups/nut.conf
MODE=netserver
# /etc/ups/ups.conf
[ups]
driver = usbhid-ups
port = auto
# /etc/ups/upsd.conf
LISTEN 127.0.0.1 3493
LISTEN 192.168.1.40 3493 # host's LAN address, only if other machines connect
# /etc/ups/upsd.users
[upsmon_local]
password = change-me
upsmon primary
[upsclient]
password = change-me-too
upsmon secondary
# /etc/ups/upsmon.conf
RUN_AS_USER root
MONITOR ups@localhost 1 upsmon_local change-me primary
SHUTDOWNCMD "/etc/ups/xen-shutdown.sh"
Two changes from the forum version are deliberate. It uses LISTEN 0.0.0.0 and one admin user with instcmds = ALL for everything. Per the upsd.users manual, upsmon primary already grants the right to request a forced shutdown, so the monitor does not need instant commands. Listening only where you need it keeps the management network quieter. If other machines do connect, open the port as the guide shows (iptables -I INPUT -p tcp --dport 3493 -j ACCEPT, then save to /etc/sysconfig/iptables). Then systemctl restart nut-server nut-monitor and check with upsc ups@localhost ups.status. You want OL, for on line.
Layout 2: the host is a client of a NAS or a Pi
This is the setup asked about on the Lawrence Systems forum: TrueNAS owns the UPS, and the XCP-ng box should follow it and stop its VMs first. Only nut.conf and upsmon.conf change:
# /etc/ups/nut.conf
MODE=netclient
# /etc/ups/upsmon.conf
RUN_AS_USER root
MONITOR ups@192.168.1.20 1 upsclient change-me-too secondary
SHUTDOWNCMD "/etc/ups/xen-shutdown.sh"
Test the login with upsc ups@192.168.1.20 first. The user and password come from the server. On TrueNAS you add them in the UPS service's extra users field. A Synology server always uses ups, monuser and secret, as our Synology guide explains. A firewall works too; see pfSense and OPNsense with NUT.
A secondary acts when the primary says the UPS is critical. Per upsmon(8), it then "immediately invokes the local shutdown command". The primary waits up to HOSTSYNC (15 seconds by default) for secondaries to log off, then shuts itself down. So the NAS, Pi and switch must all sit on battery outlets. If the switch drops first, the host never hears the order.
The shutdown script, step by step
Almost every XCP-ng NUT setup uses xen-shutdown.sh from the serrc-techops repository on GitHub. The forum guide fetches it with wget from a github.com/.../blob/... link. That URL returns an HTML page, not the script. Fetch the raw file instead:
cd /etc/ups
wget https://raw.githubusercontent.com/serrc-techops/NUT-Configuration/master/slave/xen/xen-shutdown.sh
head -1 xen-shutdown.sh # must print #!/bin/bash
chmod +x xen-shutdown.sh
Read it before you trust it. Version 1.0 does this, in order:
- Checks it is the pool master. It reads
/etc/xensource/pool.confand exits on any other host. Install it on every host anyway, in case the master role moves. - Asks every running VM to shut down with
xe vm-shutdown, one second apart, and checks every 10 seconds. - Waits up to 600 seconds (
vm_shutdown_timeout) for all of them to stop. - Forces any still running with
xe vm-shutdown force=true, then waits 80 seconds. - Resets any still running with
xe vm-reset-powerstate force=true, then waits 60 seconds. The xe reference says this sets the VM's state to halted "in the management toolstack database only". It is bookkeeping, not a power cut. - Shuts down the other pool hosts, waiting up to 240 seconds for them to stop answering ping.
- Disables and shuts down the master. The xe reference says a host must be disabled first, or
host-shutdownfails withHOST_IN_USE.
If every VM stops quickly, the script moves on right away. The long waits only apply when a VM does not respond. Note one side effect of step 1 in a pool: on a member host, SHUTDOWNCMD does nothing. Members rely on the master to shut them down, so the master and the network between them must outlast them.
Worked example: one host, one stubborn VM
Take the single-server rack from our homelab UPS example: a 1500 VA unit at about 292 W. That is roughly 25 to 30 minutes of runtime new, and 15 to 20 minutes after a few years. Put one XCP-ng host on it with four VMs, one of them the Xen Orchestra appliance. Now suppose the XO VM ignores the shutdown request.
That is not far-fetched. In the forum thread, one user ran the script and every VM stopped except Xen Orchestra. The host went down "after 5-10 minutes", and they were not sure whether XO was stopped cleanly or forced. Reading the script, the 600-second wait plus the force step fits that delay.
| Stage | Seconds | Running total |
|---|---|---|
| upssched timer after the UPS goes on battery (added below) | 120 | 120 |
| Wait for clean VM shutdown, then give up | 600 | 720 |
| Force stop, then wait | 80 | 800 |
| Power-state reset, then wait | 60 | 860 |
Our runtime guide adds about 50% margin to a shutdown budget. That turns 14.3 minutes into roughly 21.5, which an aged 15 to 20 minute battery cannot cover. Now cut vm_shutdown_timeout to 180 seconds, about twice the slowest clean VM shutdown you have timed. The budget falls to 120 + 180 + 80 + 60 = 440 s, about 7.3 minutes, or 11 with margin. That fits even the aged battery. Measure your own VMs before you pick the number.
Rule of thumb: Xen Orchestra is not in the shutdown path
The script talks to the host's toolstack through xe in dom0. Xen Orchestra plays no part in it. So the XO VM is just one more guest that can stall the queue, and it is the one people least expect. Make sure its guest tools work, and time its shutdown on its own before you trust the timeout.
Start early: add an on-battery timer
By default upsmon acts only when the UPS reports on battery and low battery together (OB LB). How much runtime is left at that point is set by the UPS, not by you. Run upsc ups@localhost and look for battery.runtime.low or battery.charge.low if your driver reports them. If that leaves less than your worst case, the default trigger is too late. On the host that owns the UPS, upssched can start the script a fixed time after the power fails:
# /etc/ups/upsmon.conf (additions)
NOTIFYCMD /usr/sbin/upssched # check the path: command -v upssched
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
# /etc/ups/upssched.conf
CMDSCRIPT /etc/ups/upssched-cmd
PIPEFN /var/run/nut/upssched.pipe # any directory the NUT user can write
LOCKFN /var/run/nut/upssched.lock
AT ONBATT * START-TIMER xen-down 120
AT ONLINE * CANCEL-TIMER xen-down
# /etc/ups/upssched-cmd (chmod 755)
#!/bin/sh
case "$1" in
xen-down) /usr/sbin/upsmon -c fsd ;;
esac
Calling upsmon -c fsd on the primary raises a forced shutdown. Secondaries then stop first, and the primary runs xen-shutdown.sh through the normal path. On a host that is only a client, have the timer call /etc/ups/xen-shutdown.sh directly. Make sure the pipe directory exists and the NUT user can write to it. The Proxmox guide walks through the same timer pattern.
Where this stops applying
This page covers one UPS feeding one host or one small pool, with VM disks on local storage. Several things change the answer:
- Shared storage. If VM disks live on a NAS over NFS or iSCSI, every host must be off before the NAS shuts down. Give the hosts the earlier timer.
- Pools with HA. The script disables hosts before shutting them down. It does not manage HA. When the master goes down, the xe reference says the pool is "out of action" until a member is made master or the master reboots. Plan the restart before the outage, not during it.
- Changes to dom0. Even supported extra packages get only best-effort support from the project. A forum member warned in 2025 that changing dom0 may cause problems at patch time. If you would rather leave dom0 untouched, run NUT on a separate box and have it call the script over SSH. Our ESXi guide shows that pattern in full, and it works the same way here.
- Network management cards. A UPS with a network card can be read with the
snmp-upsdriver instead of USB; see network management cards and SNMP.
None of this proves your setup works. Only a test does. Pick a maintenance window, take backups, and unplug the UPS from the wall. Then watch /var/log/nut.log as each VM stops and the host goes down. Check that everything comes back when power returns. The host only powers on by itself if the UPS cut its outlets and the server firmware is set to power on after AC loss.
Frequently asked questions
Does XCP-ng have built-in UPS support like TrueNAS?
No. There is no UPS service and no UPS section in the official docs. The project lead said on the forum in February 2023 that XCP-ng targets data centers, where dual power feeds and generators mean hosts do not need their own UPS shutdown. NUT is now on the XCP-ng 8.3 supported extra packages list, but you still write the config and shutdown script yourself.
Can Xen Orchestra shut down my XCP-ng host when the power fails?
Not by itself, and it does not need to. The shutdown script runs xe commands in dom0, which talk to the host's own toolstack. The XO VM is just one more VM to stop. In fact it is the VM one forum user reported holding up host shutdown by 5 to 10 minutes.
Should I pass the UPS USB cable through to a VM on XCP-ng?
No. The machine that owns the UPS has to be the last one standing. A VM on the host cannot shut that host down after it has stopped itself. A forum user who tried USB passthrough also reported that the device did not reattach reliably at VM boot. Plug the cable into the host, or into a separate always-on box.
Do I use master or primary in upsmon.conf on XCP-ng?
Either works with NUT 2.8.0, the version in the XCP-ng 8.3 repo. NUT's release notes say 2.8.0 deprecated master and slave in favor of primary and secondary, but still accept the old words. Use primary and secondary in new configs, and make the word in upsmon.conf match the role in upsd.users.
How do I test XCP-ng UPS shutdown without a real outage?
Schedule a maintenance window, back up, and unplug the UPS from the wall. Watch /var/log/nut.log, which the script writes to. On a primary, upsmon -c fsd triggers the same forced shutdown, so it is a real shutdown of every machine on that UPS, not a dry run.
Sources and further reading
- XCP-ng forum: Performing automated shutdown during a power failure using a USB-UPS with NUT, XCP-ng 8.2, how-to by Hannes_5253 (8 November 2022); in the same topic, the Xen Orchestra delay report (June 2021), the nut.target note (December 2024) and the project lead's reply on data center power (February 2023)
- serrc-techops/NUT-Configuration: xen-shutdown.sh (version 1.0, the script the forum guide uses)
- XCP-ng documentation: Additional packages (EPEL disabled on purpose, the --enablerepo switch) and the XCP-ng 8.3 supported extra packages list
- XCP-ng 8.3 updates repository (nut-2.8.0-2.1.xcpng8.3 and nut-client, dated 28 April 2026)
- XCP-ng CLI reference (xe): vm-shutdown, vm-reset-powerstate, host-disable, host-shutdown
- NUT upsmon.conf(5), upsmon(8), upsd.users(5) and upssched.conf(5) manual pages
- NUT release notes (NEWS): 2.8.0 deprecates master/slave in favor of primary/secondary
- samuel-olavo/xcp-ng-nutclient: NUT client setup tested by its author on XCP-ng 8.3 (October 2025)
- XCP-ng forum: apcupsd install (May 2025; SSH-from-a-NUT-box method and the advice not to enable EPEL)
- Lawrence Systems forum: Shutdown XCP-NG server with upsmon slave (UPS owned by TrueNAS, XCP-ng as client)