nupst/readme.md

# @serve.zone/nupst

NUPST is a Network UPS Shutdown Tool for servers that need predictable behavior when power gets ugly. It monitors UPS devices through SNMP or NUT/UPSD, evaluates per-device and grouped power conditions, and runs ordered actions such as Proxmox guest shutdown, webhooks, scripts, and host shutdown.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Why It Exists

Power-failure automation must be boring, explicit, and local-first. NUPST is built as a single compiled Deno binary that can sit on a Proxmox host or another Linux server, poll one or more UPS devices, and execute a controlled shutdown sequence before batteries are exhausted.

It is useful when you need:

- SNMP monitoring for network UPS units.
- NUT/UPSD monitoring for USB UPS units exposed by Network UPS Tools.
- Multiple UPS devices on one daemon.
- Redundant or non-redundant UPS groups.
- Proxmox VM/LXC shutdown before host shutdown.
- Webhook or script notifications.
- A small authenticated HTTP JSON status endpoint.
- Pause/resume for maintenance windows.
- Configuration migration from older NUPST formats.

## Installation

Install the released binary:

```bash
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
```

Install through the npm package wrapper with pnpm:

```bash
pnpm add --global @serve.zone/nupst
```

The installer places the binary under `/opt/nupst/nupst`, creates a symlink in `/usr/local/bin` or `/usr/bin`, and preserves existing `/etc/nupst/config.json` when upgrading.

## Quick Start

Create the first UPS config interactively:

```bash
sudo nupst ups add
```

Test connectivity:

```bash
nupst ups test --debug
```

Install and start the systemd service:

```bash
sudo nupst service enable
sudo nupst service start
```

Inspect status and logs:

```bash
nupst service status
nupst service logs
```

## CLI Reference

```bash
nupst <command> [subcommand] [options]
```

Global options:

| Option | Purpose |
| --- | --- |
| `--version`, `-v` | Show version. |
| `--help`, `-h` | Show help. |
| `--debug`, `-d` | Enable detailed SNMP/UPSD logging. |

Service commands:

| Command | Purpose |
| --- | --- |
| `service enable` | Install and enable the systemd service. Requires root. |
| `service disable` | Stop, disable, and remove the service. Requires root. |
| `service start` | Start `nupst.service`. |
| `service stop` | Stop `nupst.service`. |
| `service restart` | Restart the service. |
| `service status` | Show service and UPS state. |
| `service logs` | Follow live service logs. |
| `service start-daemon` | Run the daemon process directly. Used by systemd/testing. |

Configuration commands:

| Command | Purpose |
| --- | --- |
| `ups add` | Add a UPS device interactively. |
| `ups edit [id]` | Edit a UPS device. |
| `ups remove <id>` | Remove a UPS device. Alias: `rm`. |
| `ups list` | List UPS devices. Alias: `ls`. |
| `ups test` | Test configured UPS connections. |
| `group add` | Create a UPS group. |
| `group edit <id>` | Edit a group. |
| `group remove <id>` | Remove a group. Alias: `rm`. |
| `group list` | List groups. Alias: `ls`. |
| `action add <target-id>` | Add an action to a UPS or group. |
| `action edit <target-id> <index>` | Edit an action by array index. |
| `action remove <target-id> <index>` | Remove an action. Alias: `rm`. |
| `action list [target-id]` | List actions globally or for one target. Alias: `ls`. |
| `feature httpServer` | Configure the optional JSON status endpoint. Aliases: `http-server`, `http`. |
| `config show` | Display the active configuration. |
| `pause [--duration <time>]` | Suppress actions while polling continues. |
| `resume` | Resume action execution. |
| `upgrade` | Upgrade NUPST from the latest release. Requires root. |
| `uninstall` | Remove NUPST. Requires root. |

Pause durations support values such as `30m`, `2h`, and `1d`. The maximum pause duration is 24 hours.

## Configuration Model

NUPST stores configuration at:

```text
/etc/nupst/config.json
```

The daemon loads and migrates this file at startup. It also watches for configuration changes and can reload normal config edits without a service restart.

Current normalized config version is `4.4`.

Minimal shape:

```json
{
  "version": "4.4",
  "checkInterval": 30000,
  "defaultShutdownDelay": 5,
  "upsDevices": [
    {
      "id": "ups-main",
      "name": "Main UPS",
      "protocol": "snmp",
      "snmp": {
        "host": "192.168.1.100",
        "port": 161,
        "version": 2,
        "community": "public",
        "timeout": 5000,
        "upsModel": "apc",
        "runtimeUnit": "ticks"
      },
      "groups": ["rack-a"],
      "actions": [
        {
          "type": "proxmox",
          "triggerMode": "onlyThresholds",
          "thresholds": { "battery": 30, "runtime": 15 },
          "proxmoxMode": "auto",
          "proxmoxHaPolicy": "haStop"
        },
        {
          "type": "shutdown",
          "triggerMode": "onlyThresholds",
          "thresholds": { "battery": 20, "runtime": 10 },
          "shutdownDelay": 5
        }
      ]
    }
  ],
  "groups": [
    {
      "id": "rack-a",
      "name": "Rack A",
      "mode": "nonRedundant",
      "actions": []
    }
  ]
}
```

## Protocols

SNMP supports these UPS model profiles:

| Config value | Typical use |
| --- | --- |
| `cyberpower` | CyberPower devices. |
| `apc` | APC/PowerNet devices. |
| `eaton` | Eaton/Powerware devices. |
| `tripplite` | Tripp Lite devices. |
| `liebert` | Liebert/Vertiv devices. |
| `custom` | Custom OID mapping. |

SNMP versions `1`, `2`, and `3` are supported. SNMPv3 supports `noAuthNoPriv`, `authNoPriv`, and `authPriv` with MD5/SHA authentication and DES/AES privacy.

UPSD/NIS supports UPS devices exposed by NUT:

```json
{
  "protocol": "upsd",
  "upsd": {
    "host": "127.0.0.1",
    "port": 3493,
    "upsName": "ups",
    "timeout": 5000,
    "username": "optional",
    "password": "optional"
  }
}
```

## Action System

Actions are evaluated in array order. Put Proxmox shutdown actions before host shutdown actions so guests get time to stop cleanly.

Action types:

| Type | Purpose |
| --- | --- |
| `shutdown` | Schedule host shutdown with an optional delay. |
| `webhook` | Send an HTTP GET or POST request. |
| `script` | Execute a script from `/etc/nupst/`. |
| `proxmox` | Shut down Proxmox VMs and LXC containers. |

Trigger modes:

| Mode | Behavior |
| --- | --- |
| `onlyPowerChanges` | Run only when status changes between online and battery states. |
| `onlyThresholds` | Run only when battery/runtime thresholds are newly violated. |
| `powerChangesAndThresholds` | Run on power changes or threshold violations. This is the default. |
| `anyChange` | Run on every poll/check. |

Threshold-based actions are edge-triggered. They fire when the condition is entered, not on every poll while the condition remains true. If the condition clears and later re-enters, the action can fire again.

## Groups

Groups coordinate conditions across multiple UPS devices:

| Mode | Behavior |
| --- | --- |
| `redundant` | Threshold actions trigger only when all group members are on battery and below the action thresholds. |
| `nonRedundant` | Threshold actions trigger when any group member is on battery and below the action thresholds. |

For destructive threshold-based group actions such as `shutdown` and `proxmox`, NUPST suppresses execution while any required group member is `unreachable`. This avoids acting on incomplete data during network failures.

## Proxmox Integration

The Proxmox action supports three modes:

| Mode | Behavior |
| --- | --- |
| `auto` | Prefer local `qm`/`pct` CLI tools when available as root, otherwise use the API. |
| `cli` | Force local CLI mode. Requires root on a Proxmox host. |
| `api` | Force Proxmox REST API mode with token auth. |

Useful options:

| Option | Purpose |
| --- | --- |
| `proxmoxHost` | API host. Defaults to `localhost`. |
| `proxmoxPort` | API port. Defaults to `8006`. |
| `proxmoxNode` | Node name. Defaults to system hostname. |
| `proxmoxTokenId` | API token ID, for API mode. |
| `proxmoxTokenSecret` | API token secret, for API mode. |
| `proxmoxExcludeIds` | VM/CT IDs to skip. |
| `proxmoxStopTimeout` | Graceful stop timeout in seconds. Defaults to `120`. |
| `proxmoxForceStop` | Force-stop guests that do not shut down. Defaults to `true`. |
| `proxmoxInsecure` | Skip TLS verification in API mode. Defaults to `true`. |
| `proxmoxHaPolicy` | `none` or `haStop` for HA-managed resources. |

## HTTP Status API

Enable interactively:

```bash
sudo nupst feature httpServer
```

When enabled, the endpoint returns cached daemon status and requires a bearer token or `token` query parameter.

```bash
curl -H "Authorization: Bearer <token>" http://localhost:8080/ups-status
curl "http://localhost:8080/ups-status?token=<token>"
```

Response shape:

```json
{
  "upsDevices": [
    {
      "id": "ups-main",
      "name": "Main UPS",
      "powerStatus": "online",
      "batteryCapacity": 100,
      "batteryRuntime": 45,
      "outputLoad": 23,
      "outputPower": 115,
      "outputVoltage": 230,
      "outputCurrent": 0.5
    }
  ],
  "paused": false
}
```

## Runtime Behavior

- Default polling interval is 30 seconds.
- UPS devices become `unreachable` after 3 consecutive polling failures.
- Failure counters are capped at 100.
- Shutdown delay defaults to 5 minutes unless overridden per action.
- Pause state is stored at `/etc/nupst/pause`.
- Normal monitoring talks to configured UPS, NUT, and Proxmox targets. Upgrade and release checks contact `code.foss.global`.

Installed system paths:

| Path | Purpose |
| --- | --- |
| `/opt/nupst/nupst` | Installed binary. |
| `/usr/local/bin/nupst` or `/usr/bin/nupst` | Symlink to the binary. |
| `/etc/nupst/config.json` | Main configuration. |
| `/etc/nupst/pause` | Pause state. |
| `/etc/systemd/system/nupst.service` | systemd unit. |

## Development

```bash
deno task dev
deno task check
deno task lint
deno task fmt
deno task test
deno task compile
```

Package scripts are also available:

```bash
pnpm build
pnpm test
pnpm run lint
pnpm run format
```

Source map:

| Path | Purpose |
| --- | --- |
| `mod.ts` | CLI entry point. |
| `ts/cli.ts` | Command parser and help output. |
| `ts/nupst.ts` | Main facade wiring protocol clients, daemon, systemd, and handlers. |
| `ts/daemon.ts` | Config loading, migration, polling loop, and action orchestration. |
| `ts/snmp/` | SNMP protocol implementation and OID sets. |
| `ts/upsd/` | NUT/UPSD client. |
| `ts/actions/` | Shutdown, webhook, script, and Proxmox actions. |
| `ts/cli/` | Interactive command handlers. |
| `ts/migrations/` | Config format migrations. |
| `ts/http-server.ts` | Optional authenticated JSON status endpoint. |

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH\
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.