Add Network UPS Tools docs

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)

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)

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.

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.