Powermon, a Simple Power‑Loss Monitor for UPS‑Backed Servers

powermon is a lightweight Bash script that monitors one or more network hosts (typically Wi‑Fi access points or switches). If all monitored hosts become unreachable for a configurable amount of time, the script assumes a site‑wide power outage and triggers a clean shutdown procedure.

This tool is intended for servers running on a UPS without a usable API. Instead of querying the UPS directly, it infers power loss by detecting when the surrounding network infrastructure goes dark.

---

Features

• Monitors multiple hosts using ICMP ping
• Configurable retry count and wait time (grace period)
• Broadcasts a shutdown warning over UDP
• Executes a custom shutdown script
• Includes test modes:
  • --test-ping
  • --test-broadcast
  • --test-notification
  • --simulate (dry‑run shutdown)
• Designed to run continuously under systemd
• Uses a simple /etc/powermon/powermon.env config file

---

Installation

1. Download the program to your Proxmox machine

Clone the repository, and run install.sh

git clone https://git.mcodev.net/mcodev/proxmox-simple-powermonitor.git
cd proxmox-simple-powermonitor
chmod +x install.sh uninstall.sh
./install.sh

If in the future, you wish to uninstall the tool, use the uninstall.sh script. This will do the reverse of install.sh.

The install.sh will do the following:

• Install ipcalc using apt install ipcalc. This program is used in the broadcast for finding out the network-broadcasting IP.
• Create the folder /etc/powermon
• Copy the files powerdown.sh, powermon.sh and powermon.env into the /etc/powermon folder
• Set the mode of powerdown.sh and powermon.sh to executable
• Set the permission of powermon.env to 660
• Copy the powermon.service file to /etc/systemd/system
• Create the the systemd service for powermon
• It will enable the service, but will not yet start it.

After installation you should first change the powermon.env file in /etc/powermon and test it first before starting it.

/etc/powermon/powermon.sh --test-ping
/etc/powermon/powermon.sh --simulate
tail /var/log/powermon.log

⚠️ Warning: Starting the service without properly setting up the powermon.env file may result in your server going down.

2. Change the environment file to your needs.

Edit /etc/powermon/powermon.env using nano or vi. Pay close attention to the variable PWMON_AP_HOSTS. Put at least 2 remote IP addresses in this list. These ip addresses are best local devices, such as a Wi-Fi access points or a network switches, and important: devices that are not UPS protected or have batteries.

nano /etc/powermon/powermon.env
vi /etc/powermon/powermon.env

PWMON_AP_HOSTS=("192.168.1.1" "192.168.1.2" "192.168.1.3")

Please note that it will only require one of these devices to respond to a ping, for the system to determine that everything is still okay.

3. Start the systemd service:

systemctl start powermon.service

Usage

Normal operation

/etc/powermon/powermon.sh

Runs indefinitely, monitoring the configured hosts.

Simulation mode

/etc/powermon/powermon.sh --simulate

Triggers the shutdown logic using the configured shutdown script, but without actually powering off the machine. If you use your own shutdown script, the powermon.sh will call your script with the parameter --dry-run, so make sure that you handle this parameter, otherwise you may trigger an actual shut down if this is not implemented properly.

Test ping behavior

/etc/powermon/powermon.sh --test-ping

Pings all configured hosts with retries and prints results. If at least one hosts replies, the test will succeed.

Test broadcast behavior

/etc/powermon/powermon.sh --test-broadcast

Sends a test UDP broadcast message on all active interfaces. You can monitor this with a packet sniffer. Watch for packets on port 9999/UDP.

Test notification behavior

/etc/powermon/powermon.sh --test-notification

This will send a notification using the proxmox-mail-forward program. You will need to set it up in Proxmox for this to work. When it works, you should receive an email test notification.

What to do after powermon shuts down the server

When powermon triggers a shutdown (for example, during a power failure), it creates a file /root/.powereddown.
This file contains the timestamp of the shutdown event and serves as a disarm flag.

As long as this file exists, powermon will remain disarmed.
This prevents the system from immediately shutting down again after powering on, a safeguard designed for situations where the shutdown was caused by a network outage, not an actual power failure.

To re‑arm powermon, simply remove the file:

rm /root/.powereddown*

Once the file is removed, powermon will resume normal monitoring and shutdown behavior.

Logs

The script logs to /var/log/powermon.log, and when run under systemd: journalctl -u powermon.service -f

Shutdown script

powermon calls the script defined in PWMON_POWERDOWN_SCRIPT when a power loss is detected. This script should handle:

• notifying users (optional)
• stopping services
• syncing disks
• shutting down the system

Example path: /etc/powermon/powerdown.sh

Make sure it is executable:

chmod +x /etc/powermon/powerdown.sh

When you used the install.sh script, everything should already be in the correct mode and permissions.

Configuration Summary

All environe variables for /etc/powermon/powermon.env

Variable	Description	Default Value
PWMON_LOGFILE	Path to the log file used by powermon.	/var/log/powermon.log
PWMON_AP_HOSTS	Array of hosts (APs, switches, routers, etc.) that powermon will ping to detect network/power failure.	(no default — must be set)
PWMON_POWERDOWN_SCRIPT	Script executed when all monitored hosts become unreachable (interpreted as a power‑failure event).	/etc/powermon/powerdown.sh
PWMON_CHECK_INTERVAL	Time in seconds between monitoring cycles.	5
PWMON_PING_TIMEOUT	Timeout in seconds for each individual ping attempt.	1
PWMON_MAX_RETRIES	Number of ping rounds to attempt before declaring all hosts unreachable.	2
PWMON_PING_WAIT	Time in seconds to wait between ping retry rounds.	10
PWMON_NOTIF_COUNT	Number of powermon runs between disarmed‑state notifications.	720 (≈1 hour)
PWMON_POWEROFF_DELAY	Delay in seconds between shutting down guests and issuing the final poweroff command to the host.	20

License

MIT License

Copyright (c) 2026 mCoDev Systems

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.