Promethist Watchdog

Shutting down when the power fails

A kiosk on a UPS has a few minutes of battery when the building loses power — enough to close everything properly, but only if something tells it to. Left alone it runs until the battery dies and stops mid-write, which is how configurations and databases get corrupted.

Told to shut down, Watchdog emails the alert, stops every app in your configured order using each one’s grace period, then powers the PC off. If the power-off command fails it restarts the apps and emails an error, so the machine is never left running with everything closed.

The feature is on by default, but it opens no port and answers nobody until you turn on the network trigger below.

From the command line

Point your UPS software at this — PowerChute, Eaton IPM, NUT and the rest all exist to run a command when the battery gets low.

wdog shutdown --in 60 --reason "UPS on battery" --yes    power off in 60 seconds
wdog shutdown --now --yes                                 straight away
wdog shutdown --cancel                                    call it off; the power came back
wdog shutdown --status                                    is one pending, and when
wdog shutdown --dry-run                                   a test: sends the alert, changes nothing

--reason and --source go into the log and the alert email, so months later the log says why a kiosk went off and who asked. Use them.

Start with --dry-run when commissioning — it is the only way to prove the alert reaches the right mailbox before the day it matters.

Choosing the delay. It exists so a brief flicker can be called off before anything closes. Allow for the shutdown itself: 3 seconds for the email, plus each app’s grace period one after another (20 s each by default), plus 10 s for Windows. With a 5-minute UPS and three apps, --in 120 leaves two minutes of margin.

A pending shutdown can be brought forward but never pushed back, and sending the same instruction twice is harmless — a system that retries will not double anything up.

Cancelling

wdog shutdown --cancel, or the Cancel shutdown button on the red banner in Watchdog’s window. There is deliberately no button that starts one. What happens depends on how far it got, and --status always says:

Still counting down Cancelled. Nothing was touched.

Still counting down	Cancelled. Nothing was touched.
Stopping the apps	Too late — refused, because starting an app halfway through being stopped leaves it in an unknown state. Let it finish and start the PC again.
Windows is counting down	Watchdog runs `shutdown /a`. If that works it restarts the apps it stopped. If Windows refuses, the cancel fails and the apps are left stopped on purpose — starting them into the final seconds before the power is cut is the damage this feature exists to prevent.

Stopping the apps

Too late — refused, because starting an app halfway through being stopped leaves it in an unknown state. Let it finish and start the PC again.

Windows is counting down

Watchdog runs shutdown /a. If that works it restarts the apps it stopped. If Windows refuses, the cancel fails and the apps are left stopped on purpose — starting them into the final seconds before the power is cut is the damage this feature exists to prevent.

Letting a building system ask over the network

Only when nothing can run a program on the kiosk. Off by default.

Store a password for callers — never written to the settings file:
```
echo my-long-random-password | wdog config trigger-token --stdin
```
Or Settings → Emergency shutdown → Advanced → Password for callers. Either way it is stored for the account Watchdog runs as. Do not add it to the Credential Manager by hand from another account — Windows keeps each account’s vault separate.

Turn the listener on, in the same Settings page or:

wdog config set emergency_shutdown.listen.enabled true
wdog config set emergency_shutdown.listen.bind 10.1.2.50      this PC on the building network
wdog config set emergency_shutdown.listen.allow_from 10.1.2.7  only the building system may ask

Restart Watchdog. The address, port and on/off switch are read once at startup. (allow_from and the password take effect immediately.)

Allow it through the firewall. Watchdog creates no rule on purpose. Once, as administrator:

netsh advfirewall firewall add rule name="Promethist Watchdog emergency shutdown" ^
  dir=in action=allow protocol=TCP localport=8099 remoteip=10.1.2.7 profile=domain,private

Test it with "dry_run": true before you rely on it.

What the building system sends

curl -X POST http://10.1.2.50:8099/emergency-shutdown \
  -H "Authorization: Bearer my-long-random-password" \
  -H "Content-Type: application/json" \
  -d '{"delay_s":120,"reason":"mains lost","source":"bms-b12"}'

Every field in the body is optional.

Method Path What it does

Method	Path	What it does
`POST`	`/emergency-shutdown`	Arm it
`POST`	`/emergency-shutdown/cancel`	Call it off
`GET`	`/emergency-shutdown`	Is one pending, and when

POST

/emergency-shutdown

Arm it

POST

/emergency-shutdown/cancel

Call it off

GET

/emergency-shutdown

Is one pending, and when

The reply is JSON either way. 200 accepted, 401 wrong or missing password, 403 address not on the allow-list, 409 too late to cancel, 429 too many wrong passwords, 503 the feature is switched off.

This is HTTP, not HTTPS — the password crosses your network unencrypted. What a listener gains is narrow: it can only turn that one kiosk off, not read the configuration, list or start apps, read a log, or stop Watchdog. Keep it small by preferring the command line, leaving bind at 127.0.0.1 unless the building system genuinely needs the network, always setting allow_from, and matching the firewall rule to it.

A password in the URL (?token=…) is refused, because URLs land in every proxy log they pass through.

Everything lands in wdog logs, including refused attempts and the address they came from. The alert email is the emergency_shutdown event, included by default — see Email alerts.