How to Shut Down XCP-ng on a UPS with NUT

Install NUT in dom0 (on XCP-ng 8.3 it is in the XCP-ng updates repo, so plain yum install nut nut-client works), enable nut.target and nut-monitor, and set SHUTDOWNCMD to a script that shuts the VMs down with xe before the host. Do not install epel-release, as the popular forum guide does: XCP-ng's own docs warn that it switches EPEL on for good and can break updates.

On this page
  1. What you are setting up
  2. Pick a layout
  3. Install NUT in dom0 without breaking updates
  4. Layout 1: the host owns the UPS
  5. Layout 2: the host is a client of a NAS or a Pi
  6. The shutdown script, step by step
  7. Worked example: one host, one stubborn VM
  8. Start early: add an on-battery timer
  9. Where this stops applying
  10. 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.

XCP-ng UPS layouts
UPS data cable goes toXCP-ng host runsnut.conf MODEHost role
The XCP-ng host (USB)Driver, upsd and upsmonnetserver (or standalone if nothing else shares the UPS)Primary
A NAS, Raspberry Pi or firewallupsmon onlynetclientSecondary
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.

Where NUT comes from on each XCP-ng release
ReleaseInstall commandNotes
XCP-ng 8.3yum install nut nut-clientNUT 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.2yum install nut nut-client --enablerepo=epelNot 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:

  1. Checks it is the pool master. It reads /etc/xensource/pool.conf and exits on any other host. Install it on every host anyway, in case the master role moves.
  2. Asks every running VM to shut down with xe vm-shutdown, one second apart, and checks every 10 seconds.
  3. Waits up to 600 seconds (vm_shutdown_timeout) for all of them to stop.
  4. Forces any still running with xe vm-shutdown force=true, then waits 80 seconds.
  5. 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.
  6. Shuts down the other pool hosts, waiting up to 240 seconds for them to stop answering ping.
  7. Disables and shuts down the master. The xe reference says a host must be disabled first, or host-shutdown fails with HOST_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.

Worst case before the host starts shutting down (from the script's own timeouts)
StageSecondsRunning total
upssched timer after the UPS goes on battery (added below)120120
Wait for clean VM shutdown, then give up600720
Force stop, then wait80800
Power-state reset, then wait60860
Worst case = 120 + 600 + 80 + 60 = 860 s, about 14.3 minutes, plus the host's own shutdown

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-ups driver 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

  1. 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)
  2. serrc-techops/NUT-Configuration: xen-shutdown.sh (version 1.0, the script the forum guide uses)
  3. XCP-ng documentation: Additional packages (EPEL disabled on purpose, the --enablerepo switch) and the XCP-ng 8.3 supported extra packages list
  4. XCP-ng 8.3 updates repository (nut-2.8.0-2.1.xcpng8.3 and nut-client, dated 28 April 2026)
  5. XCP-ng CLI reference (xe): vm-shutdown, vm-reset-powerstate, host-disable, host-shutdown
  6. NUT upsmon.conf(5), upsmon(8), upsd.users(5) and upssched.conf(5) manual pages
  7. NUT release notes (NEWS): 2.8.0 deprecates master/slave in favor of primary/secondary
  8. samuel-olavo/xcp-ng-nutclient: NUT client setup tested by its author on XCP-ng 8.3 (October 2025)
  9. XCP-ng forum: apcupsd install (May 2025; SSH-from-a-NUT-box method and the advice not to enable EPEL)
  10. Lawrence Systems forum: Shutdown XCP-NG server with upsmon slave (UPS owned by TrueNAS, XCP-ng as client)