How Do I Make a UPS Shut Down VMware ESXi, Including the Free Version?

On a paid vSphere license, run the UPS vendor's VMware appliance and let it shut the host down. On the free ESXi 8.0 Update 3e license, those appliances cannot finish the job, because Broadcom limits API access on free hosts to read-only. Use a separate always-on box running NUT (or apcupsd) that logs into the host over SSH and runs /sbin/shutdown.sh && /sbin/poweroff. Either way, the ESXi autostart setting is what decides whether your VMs shut down or get switched off.

On this page
  1. Why the free license breaks vendor shutdown tools
  2. Decision table: which path fits your host
  3. Step one on every path: make ESXi shut its VMs down
  4. The free-license path: NUT on a separate box, SSH to the host
  5. The paid-license path: a vendor appliance
  6. A timing example against real runtime
  7. Where this stops applying
  8. Frequently asked questions

Why the free license breaks vendor shutdown tools

Broadcom brought back a free ESXi with 8.0 Update 3e. Broadcom's knowledge base article on it describes the same build as the paid release; only the license differs. The free license allows unlimited VMs within hardware limits, up to 2 physical CPUs per host and 8 vCPUs per VM, and management through the vSphere Host Client. Its listed limitations are no vCenter, no vMotion, DRS, HA or VADP backups, no official support, and one line that matters for power protection:

Broadcom KB 399823, free license limitations

"Usage of APIs to manage hosts is not supported, and may only provide read-only information."

UPS vendor appliances for VMware are VMs that receive a signal from the UPS and then log into the host (or vCenter) to shut guests and the host down. That login goes through the management API. On a free host the appliance can usually connect and read status, so the setup screen looks fine, but the shutdown call is exactly the kind of write the license does not support. This is not new: TinkerTry's long-running CyberPower walkthrough notes that older vCLI-based shutdown scripts "doesn't work with free Hypervisor, because it relies on vCLI", and later that the PowerPanel appliance "is now said to not work for the free hypervisor ESXi 6.7."

SSH is a different door. It is a shell on the host, not the managed API, and the free license does not remove it. That is why the reliable free-license recipe is an outside machine that monitors the UPS and, when the time comes, opens an SSH session and runs ESXi's own shutdown commands.

Why the two answers both circulate

Search results for this question split between "install the vendor appliance, it takes 15 minutes" and "it does not work, use a script". Both are right, for different licenses. Most appliance guides were written against trial or paid hosts (TinkerTry's demonstration used the 60-day trial period), not the free license. A setup tested during a trial proves nothing about the free key, so test again after the free license is in place.

Decision table: which path fits your host

ESXi UPS shutdown by license and UPS connection
LicenseUPS connectionUse thisWhy
Paid vSphere (Essentials or higher), with or without vCenterNetwork card (APC NMC, CyberPower RMCARD)Vendor VMware appliance: PowerChute Network Shutdown or PowerPanel Business for Virtual MachineFull API access; the appliance can also handle clusters, vMotion and vSAN through vCenter
Paid, single hostUSB onlyNUT or apcupsd on a separate box with SSH, or vendor software on a separate PC calling an SSH scriptAvoids passing the UPS USB device through to a VM on the host being shut down
Free 8.0U3eNetwork cardNUT on a separate box using the snmp-ups driver to read the card, then SSHCard gives status over the network; SSH does the shutdown the API will not
Free 8.0U3eUSB onlyNUT (any brand) or apcupsd (APC) on a Raspberry Pi, NAS or firewall with the USB cable, then SSHThe only path that does not depend on API writes

The Broadcom community thread on APC shutdowns adds a useful limit for the USB case: the poster's PowerChute-plus-SSH design is "for single-host, single UPS setups", and clustered hosts using vMotion or vSAN need PowerChute Network Shutdown with a management card instead. For what each card offers beyond shutdown, see network management cards and SNMP; for the vendor editions, PowerChute and PowerPanel.

Step one on every path: make ESXi shut its VMs down

Every method above ends with the same thing: the host is told to shut down. What happens to the running VMs at that moment is decided by the host's autostart configuration, not by the UPS software. On a free host there is no vCenter to step in, so this setting is the whole guest shutdown plan.

  1. Install VMware Tools (or open-vm-tools) in every guest. A guest shutdown request needs Tools running inside the VM.
  2. Enable autostart. In the Host Client: Manage, System, Autostart, Edit settings, set Enabled to Yes.
  3. Set Stop action to Shut down and leave Stop delay at 120 seconds to start with. Power off is the equivalent of pulling the VM's power cord, and Suspend writes memory to disk, which costs battery time on large VMs.
  4. Add each VM to autostart. In the Virtual Machines list, right-click a VM, Autostart, Enable. Per Broadcom's API reference, a VM whose stop action is none "does not participate in auto-stop".
  5. Order them. VMs start in ascending order and stop in reverse, so put dependencies such as DNS, a domain controller or a database early in the start order. They will be the last to stop. VMs left at "any order" are typically handled after all the numbered ones.

Broadcom's API reference defines the stop delay as the "delay in seconds before continuing with the next virtual machine in the order sequence", with a system default of 120 seconds. Shutdown is sequential, so a VM that ignores the request holds up every VM behind it for its full delay.

The free-license path: NUT on a separate box, SSH to the host

The Broadcom community recipe runs ssh root@[IP] "/sbin/shutdown.sh && /sbin/poweroff" from a Windows VM running PowerChute. The same command works from any NUT client or server. Here the NUT machine is a Raspberry Pi with the UPS USB cable; it is set up as a normal NUT primary, and upssched adds a host-specific timer.

1. Give the NUT box a key on the host

Enable the SSH service in the Host Client (Manage, Services, TSM-SSH) with the policy "Start and stop with host". Then on the NUT box:

ssh-keygen -t rsa -b 4096 -N "" -f /etc/nut/esxi_key
chown nut:nut /etc/nut/esxi_key     # upssched runs as the NUT user
chmod 600 /etc/nut/esxi_key

Append the contents of esxi_key.pub to /etc/ssh/keys-root/authorized_keys on the host, which Broadcom KB 313767 names as the root key file (it can hold more than one key, and PermitRootLogin must be yes in /etc/ssh/sshd_config). Accept the host key once, as the NUT user, so the unattended run does not stop at a prompt:

sudo -u nut ssh -i /etc/nut/esxi_key \
  -o UserKnownHostsFile=/etc/nut/esxi_known_hosts \
  root@192.168.1.30 "vmware -v"

2. Fire the shutdown from upssched

NUT's own trigger is low battery: upsmon acts when the UPS reports OB LB. For a hypervisor that is usually too late, so the host gets a timer that starts when the UPS goes on battery and is cancelled if power returns, plus a low battery backstop.

# /etc/nut/upsmon.conf (additions)
NOTIFYCMD /sbin/upssched          # check the path with: command -v upssched
NOTIFYFLAG ONBATT  SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE  SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC

# /etc/nut/upssched.conf
CMDSCRIPT /etc/nut/upssched-cmd
PIPEFN /run/nut/upssched/upssched.pipe
LOCKFN /run/nut/upssched/upssched.lock
AT ONBATT  * START-TIMER esxi-down 120
AT ONLINE  * CANCEL-TIMER esxi-down
AT LOWBATT * EXECUTE esxi-down

# /etc/nut/upssched-cmd  (chmod 755)
#!/bin/sh
case "$1" in
    esxi-down)
        logger -t upssched "Shutting down ESXi host 192.168.1.30"
        ssh -i /etc/nut/esxi_key -o BatchMode=yes -o ConnectTimeout=10 \
            -o UserKnownHostsFile=/etc/nut/esxi_known_hosts \
            root@192.168.1.30 "/sbin/shutdown.sh && /sbin/poweroff"
        ;;
esac

The Pi's own SHUTDOWNCMD stays as it is, so the Pi goes down last, on low battery. If the UPS has a network card instead of USB, swap the driver for snmp-ups and point it at the card; nothing else changes. On an APC USB unit, apcupsd can do the same job by calling the SSH line from its event script.

Lock the key down

That key is root on your hypervisor. Keep it only on the UPS box, and in the Host Client (Networking, Firewall rules, SSH Server) restrict allowed IP addresses to the NUT box and your admin workstation.

The paid-license path: a vendor appliance

With API access, the vendor appliance is the tidier choice, because it shuts down guests and host from one console and, with vCenter, handles clusters. CyberPower's PowerPanel Business for Virtual Machine lists ESXi 8.0 U2 among supported systems, and the product page splits the role into LOCAL (USB or serial), REMOTE (through an RMCARD) and MANAGEMENT. Its free MANAGEMENT tier covers 30 physical nodes; CyberPower requires a paid license for "configuring multiple VM shutdown scenarios". APC's equivalent is PowerChute Network Shutdown, paired with a Network Management Card.

The appliance runs as a VM on the host it protects. That works because it only has to send the shutdown order; the host's autostart settings then stop the other VMs, so the steps in the autostart section above still apply. In TinkerTry's walkthrough, the "Shutdown Initiated" delay after utility power failure was set to 30 seconds, which is aggressive. Pick it with the timing budget below rather than copying it.

A timing example against real runtime

Take the single-server rack from our homelab UPS example: a 1500 VA unit at about 292 W, worth roughly 25 to 30 minutes new and 15 to 20 minutes after a few years. Put a Raspberry Pi, the switch and the ESXi host on battery outlets, with four VMs at the default 120 second stop delay.

Worst-case shutdown budget, free ESXi host with NUT and SSH (illustrative; measure your own)
StageSecondsRunning total
upssched timer after going on battery120120
NUT detection (POLLFREQALERT default 5 s) and SSH connect15135
Four VMs, each allowed the full 120 s stop delay480615
Host services stop and hardware powers off90705
Worst case = 120 + 15 + (4 x 120) + 90 = 705 s, about 12 minutes

Our runtime guide adds about 50% margin on top of the shutdown budget. That makes 705 s into roughly 17.6 minutes, which an aged battery's 15 minutes cannot cover. Two cheap fixes: time each VM's real shutdown and cut its stop delay to about twice that (a Linux VM that stops in 20 seconds does not need 120), and shorten the timer to 60 seconds. With stop delays of 45 seconds the budget falls to 60 + 15 + 180 + 90 = 345 s, or about 8.6 minutes with margin, inside the aged runtime. The runtime calculator gives the battery side.

Rule of thumb: budget the sum of stop delays

People time one clean shutdown, see 90 seconds, and plan for 90 seconds. ESXi's worst case is every stop delay in sequence, because a hung guest burns its whole delay before the next one starts. Size the timer against that sum, then shrink the delays once you have measured each VM.

Where this stops applying

  • Storage on a NAS. If VM disks live on NFS or iSCSI, the host must be off before the NAS shuts down. The Proxmox ordering section shows the timer pattern; the same logic applies to ESXi.
  • Clusters and vSAN. The SSH recipe is single-host. Multi-host clusters need vCenter and a paid license, which also makes the vendor appliance the right tool.
  • USB passthrough. Passing the UPS cable through to a VM on the same host is fragile; see UPS not detected for why.
  • Licensing changes. This page reflects Broadcom's KB 399823 wording for 8.0 Update 3e. If a later free release changes the API line, the vendor appliance may work again, and a pull-the-plug test will tell you.

Test once in a maintenance window: unplug the UPS from the wall, watch the Pi's syslog for the upssched line, and watch the Host Client until the VMs and then the host go down. Then confirm everything comes back when you plug it in again.

Frequently asked questions

Does PowerChute Network Shutdown work with free ESXi?

Do not plan on it. Vendor VMware appliances shut the host down through its management interface, and Broadcom says API management on the free 8.0U3e license is not supported and may be read-only. Older free releases had a similar limit: vCLI-based shutdown scripts did not work on them. If you are on the free license, use an SSH-based shutdown from NUT, apcupsd, or a PowerChute install on a separate PC calling an SSH script.

Can I install NUT directly on ESXi?

Not as a supported package. ESXi is not a general Linux distribution and has no package manager for tools like NUT. The supported pattern is to run NUT on another machine, such as a Raspberry Pi, a NAS or a firewall, and have that machine tell the host to shut down over SSH.

Is it safe to leave SSH enabled on an ESXi host?

It widens the attack surface, so limit it. Use key authentication with a key that exists only on the UPS box, restrict the SSH Server firewall rule on the host to that box's IP address, and keep the management network off untrusted segments.

Why did my VMs crash even though the host shut down cleanly?

Almost always the autostart configuration. Either autostart was disabled, the VM was not in the autostart list, or the stop action was Power off. With a free host there is no vCenter to orchestrate anything, so the host's own autostart settings are the only thing that sends guest shutdown requests.

Will the ESXi host turn back on when power returns?

Only if the server firmware's AC power recovery setting is set to power on or last state, and only if the UPS actually removes and restores output. A host that powered off while the UPS kept its outlets live will stay off until someone presses the button, even after mains returns.

Sources and further reading

  1. Broadcom KB 399823: VMware ESXi 8.0 Update 3e now available as a Free Hypervisor (free license features and limitations)
  2. Broadcom KB 313767: Allowing SSH access to ESXi hosts with public/private key authentication
  3. Broadcom vSphere API reference: AutoStartPowerInfo and AutoStartDefaults (stop order, stop delay, 120 s defaults)
  4. Broadcom Community: ESXi hosts shutdown with APC UPS, how to (August 2024)
  5. TinkerTry: Configure automated shutdown of your homelab in 15 minutes (CyberPower PowerPanel Business appliance, updated April 2019)
  6. CyberPower: PowerPanel Business for Virtual Machine
  7. NUT User Manual: Configuration notes and Advanced usage and scheduling notes (upssched)
  8. NUT upsmon.conf(5) manual page