From ce2daa5b7ab8029f6a1fed843aedce85484e3efd Mon Sep 17 00:00:00 2001 From: BeeJoe Date: Sat, 13 Jun 2026 21:53:58 -0400 Subject: [PATCH] Add Network UPS Tools docs --- start-os/src/README.md | 1 + start-os/src/SUMMARY.md | 1 + start-os/src/network-ups-tools.md | 59 +++++++++++++++++++++++++++++++ start-os/src/surge-and-ups.md | 4 +-- 4 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 start-os/src/network-ups-tools.md diff --git a/start-os/src/README.md b/start-os/src/README.md index 45e29b2..8a9975a 100644 --- a/start-os/src/README.md +++ b/start-os/src/README.md @@ -56,6 +56,7 @@ StartOS is a sovereign computing platform that makes it easy to run a personal s - [SSH](ssh.md) - [SMTP](smtp.md) - [WiFi](wifi.md) +- [Network UPS Tools (NUT)](network-ups-tools.md) - [Internationalization](internationalization.md) - [Kiosk Mode](kiosk-mode.md) - [Updating StartOS](updating-startos.md) diff --git a/start-os/src/SUMMARY.md b/start-os/src/SUMMARY.md index 1d020b3..02ed632 100644 --- a/start-os/src/SUMMARY.md +++ b/start-os/src/SUMMARY.md @@ -71,6 +71,7 @@ - [SSH](ssh.md) - [SMTP](smtp.md) - [WiFi](wifi.md) +- [Network UPS Tools (NUT)](network-ups-tools.md) - [Internationalization](internationalization.md) - [Kiosk Mode](kiosk-mode.md) - [Updating StartOS](updating-startos.md) diff --git a/start-os/src/network-ups-tools.md b/start-os/src/network-ups-tools.md new file mode 100644 index 0000000..daeb114 --- /dev/null +++ b/start-os/src/network-ups-tools.md @@ -0,0 +1,59 @@ +# Network UPS Tools (NUT) + +Network UPS Tools (NUT) lets StartOS monitor an uninterruptible power supply (UPS) and shut down safely when the UPS reports a low battery. StartOS can talk directly to a connected UPS or monitor a UPS through another NUT server on the network. + +## Opening Network UPS Tools + +Open **Settings > Network UPS Tools** from the sidebar under **WiFi**. + +## Modes + +StartOS supports three NUT modes: + +- **Disabled** - Turns off NUT monitoring. +- **Direct UPS** - Monitors a UPS connected directly to the StartOS machine. +- **Network UPS Client** - Monitors a UPS through another NUT server on the network. + +Each mode is described below. + +### Disabled + +Disabled turns off NUT monitoring. + +### Direct UPS + +Use Direct UPS when the UPS is connected directly to the StartOS machine, usually by USB. + +Common settings: + +- **UPS Name** - Internal NUT name, for example `ups`. +- **Driver** - For many USB UPS units, use `usbhid-ups`. +- **Device or address** - For most USB UPS units, use `auto`. +- **Monitor username/password** - Local credentials StartOS uses to monitor the UPS. +- **Allow network clients** - Enable only if other machines should monitor this UPS through StartOS. +- **Network client username/password** - Credentials remote NUT clients will use. +- **Shutdown delay** - Seconds StartOS waits after the final shutdown signal before powering down. + +### Network UPS Client + +Use Network UPS Client when another machine is already connected to the UPS and running NUT as the server. + +Common settings: + +- **UPS Name** - Must match the UPS name on the remote NUT server. +- **NUT server host** - IP address or hostname of the NUT server. +- **NUT server port** - Usually `3493`. +- **Monitor username/password** - Credentials from the remote NUT server. +- **Shutdown delay** - Seconds StartOS waits after the final shutdown signal. + +## Status + +After saving a Direct UPS or Network UPS Client configuration, StartOS shows **UPS Status**. This displays all data returned by the UPS, such as `ups.status`, `battery.charge`, `battery.runtime`, `input.voltage`, and driver details. + +Click **Refresh** to reload the status. If StartOS cannot read valid UPS data, it shows a system notification and an error message. Check the UPS name, host, port, credentials, driver, and cable or network connection. + +## Operational Notes + +For a network UPS setup, the router or switch between StartOS and the NUT server should also be on UPS power. Otherwise, StartOS may lose network access before it can receive the low-battery signal. + +To test safely, confirm the status page reports normal data first. Then unplug the UPS from wall power, not the StartOS power cable, and verify `ups.status` changes from online to on-battery. Avoid draining the battery unless you are prepared for a real shutdown. diff --git a/start-os/src/surge-and-ups.md b/start-os/src/surge-and-ups.md index 001ae66..0811eca 100644 --- a/start-os/src/surge-and-ups.md +++ b/start-os/src/surge-and-ups.md @@ -44,6 +44,6 @@ There are three common topologies. For a home server, **line-interactive** is th ## Automatic shutdown on low battery -StartOS does not currently include built-in support for UPS monitoring (USB or network), so it cannot automatically shut down when the battery is low during an extended outage. The server will run until battery exhaustion and then power off uncleanly. This still carries some risk of data corruption, but it is dramatically less risky than facing the original surge, brownout, or sudden outage with no UPS at all. +StartOS supports automatic shutdown on low battery through [Network UPS Tools (NUT)](network-ups-tools.md). Configure NUT to monitor either a directly connected UPS, usually by USB, or a UPS served by another NUT server on the network. -If your area has frequent or long outages, size your UPS to give yourself time to shut down manually from the StartOS UI before the battery runs out. +If your area has frequent or long outages, size your UPS to keep your server and any required networking equipment powered long enough for StartOS to receive the low-battery signal and shut down cleanly.