This repository provides a tested step-by-step guide to configure a
NUT (Network UPS Tools) client on an XCP-ng host for safe, automatic shutdown of all VMs and the host itself when power fails.

Log into your XCP-ng dom0 via SSH or console.

yum update -y

The nut-client package depends on EPEL or extra repos.

yum --enablerepo=* install epel-release -y

yum install -y nut nut-client --enablerepo=epel

Installing both ensures the presence of the nut.target systemd unit,
required for nut-monitor to start automatically.

Configuration files are typically stored under /etc/ups/.

Create or edit the following:

MODE=netclient

This host acts as a network client.

Example configuration:

RUN_AS_USER root
MONITOR a@b 1 u p slave
#a - Name of UPS
#b - IP UPS
#u - user
#p - password

#EXAMPLE:
# MONITOR ups-number01@10.2.0.0 1 myuser randompassword slave


#Script for shutdown host
SHUTDOWNCMD "/etc/ups/xen-shutdown.sh"


MINSUPPLIES 1
POLLFREQ 5
POLLFREQALERT 5
HOSTSYNC 15
DEADTIME 25
POWERDOWNFLAG /etc/killpower
NOTIFYFLAG ONLINE SYSLOG+WALL
NOTIFYFLAG ONBATT SYSLOG+WALL
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
RBWARNTIME 43200
NOCOMMWARNTIME 300
FINALDELAY 5

Explanation:

• MONITOR defines which UPS (from the remote NUT server) this host monitors.
  Replace IP/user/password as needed.
• slave marks this as a NUT client, not a master.
• SHUTDOWNCMD points to a shutdown script that gracefully stops VMs and powers off the host.

#!/bin/bash
# /etc/ups/xen-shutdown.sh
# --------------------------------------------
# Author:  Samuel Olavo
# --------------------------------------------

LOG="/var/log/nut.log"

echo "$(date '+%Y-%m-%d %H:%M:%S') - NUT: Power event received, initiating VM shutdown sequence..." >> "$LOG"

# Get all VMs except control domain (dom0) and templates
VM_LIST=$(xe vm-list is-control-domain=false is-a-template=false params=uuid --minimal | tr ',' ' ')

for vm in $VM_LIST; do
    vm_name=$(xe vm-param-get uuid=$vm param-name=name-label)
    vm_state=$(xe vm-param-get uuid=$vm param-name=power-state)

    # Only shut down running VMs
    if [ "$vm_state" = "running" ]; then
        echo "$(date '+%Y-%m-%d %H:%M:%S') - Shutting down VM: $vm_name" >> "$LOG"
        xe vm-shutdown uuid=$vm >/dev/null 2>&1
        sleep 5  # Give it a few seconds between shutdowns
    else
        echo "$(date '+%Y-%m-%d %H:%M:%S') - Skipping VM (already halted): $vm_name" >> "$LOG"
    fi
done

# Wait a bit before shutting down the host
sleep 10
echo "$(date '+%Y-%m-%d %H:%M:%S') - All VMs processed. Powering off host..." >> "$LOG"
poweroff

# End of script

Ensure the client services are active at boot:

systemctl enable nut.target
systemctl enable nut-monitor
systemctl start nut-monitor
systemctl status nut-monitor

If startup fails, review logs:

journalctl -u nut-monitor -xe

Without installing the full nut package, nut.target may be missing, preventing nut-monitor from launching.

Run this on the XCP-ng host (client):

upsc ups-number01@myuser

If you see UPS status details, communication works fine.

If not:

• Ensure port 3493/TCP is open between client and server.
• Check /etc/nut/upsd.conf and /etc/nut/upsd.users on the server:

  [myuser]
    password = randompassword
    upsmon slave

Open the firewall port if needed:

iptables -I INPUT -p tcp --dport 3493 -j ACCEPT
service iptables save

You can simulate a power failure safely.

upsmon -c fsd

You should see:

Broadcast message from nut@xcp-virtual-desktops:
Executing automatic power-fail shutdown

The script /etc/ups/xen-shutdown.sh will then trigger:

1. Graceful VM shutdown
2. Host poweroff

To confirm, check /var/log/nut.log.

MIT License

• Network UPS Tools (NUT)
• XCP-ng Forum discussion
• Adapted and tested by Samuel Olavo