serve.zone/nupst
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

fix(tooling): better oids and more power metrics. Also new json httpServer feature support.

Browse Source
This commit is contained in:
Jürgen Kunz
2025-10-23 12:57:58 +00:00
parent b7a0bbcf6d
commit 777d48d82e
8 changed files with 697 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
readme.md
View File

@@ -1,8 +1,12 @@
# ⚡ NUPST - Network UPS Shutdown Tool
**Keep your systems safe when the power goes out.** NUPST is a lightweight, battle-tested command-line tool that monitors SNMP-enabled UPS devices and orchestrates graceful system shutdowns during power emergencies. Distributed as self-contained binaries with zero runtime dependencies for maximum reliability.
**Keep your systems safe when the power goes out.** NUPST is a lightweight, battle-tested
command-line tool that monitors SNMP-enabled UPS devices and orchestrates graceful system shutdowns
during power emergencies. Distributed as self-contained binaries with zero runtime dependencies for
maximum reliability.
**Version 5.0+** is powered by Deno and distributed as single pre-compiled binaries—no installation, no setup, just run.
**Version 5.0+** is powered by Deno and distributed as single pre-compiled binaries—no installation,
no setup, just run.
## ✨ Features
@@ -15,12 +19,18 @@
- Runtime threshold triggers
- Power status change triggers
- Configurable shutdown delays
- **🌐 Universal SNMP Support**: Full support for SNMP v1, v2c, and v3 with authentication and encryption
- **🏭 Multiple UPS Brands**: Works with CyberPower, APC, Eaton, TrippLite, Liebert/Vertiv, and custom OID configurations
- **🌐 Universal SNMP Support**: Full support for SNMP v1, v2c, and v3 with authentication and
encryption
- **🏭 Multiple UPS Brands**: Works with CyberPower, APC, Eaton, TrippLite, Liebert/Vertiv, and
custom OID configurations
- **🚀 Systemd Integration**: Simple service installation and management
- **📊 Real-time Monitoring**: Live status updates with detailed action and group information
- **📦 Self-Contained Binary**: Single executable with zero runtime dependencies—just download and run
- **🖥️ Cross-Platform**: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon), and Windows
- **🌐 HTTP API**: Optional HTTP server for JSON status export with authentication
- **⚡ Power Metrics**: Monitor output load, power (watts), voltage, and current for all UPS devices
- **📦 Self-Contained Binary**: Single executable with zero runtime dependencies—just download and
run
- **🖥️ Cross-Platform**: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon),
and Windows
## 🚀 Quick Start
@@ -61,13 +71,15 @@ npm install -g @serve.zone/nupst
```
**Benefits:**
- Automatic platform detection and binary download
- Downloads only the binary for your platform (~400-500MB)
- Easy updates via `npm update -g @serve.zone/nupst`
- Version management with npm
- Works with Node.js >=14
**Note:** The installation will download the appropriate binary from GitHub releases during the postinstall step.
**Note:** The installation will download the appropriate binary from GitHub releases during the
postinstall step.
### Automated Installer Script
@@ -78,6 +90,7 @@ curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh |
```
**What it does:**
1. Detects your platform (OS and architecture)
2. Downloads the latest pre-compiled binary
3. Installs to `/opt/nupst/nupst`
@@ -101,15 +114,16 @@ curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh |
### Manual Installation
Download the appropriate binary for your platform from [releases](https://code.foss.global/serve.zone/nupst/releases):
Download the appropriate binary for your platform from
[releases](https://code.foss.global/serve.zone/nupst/releases):
| Platform | Binary |
|----------|--------|
| Linux x64 | `nupst-linux-x64` |
| Linux ARM64 | `nupst-linux-arm64` |
| macOS Intel | `nupst-macos-x64` |
| macOS Apple Silicon | `nupst-macos-arm64` |
| Windows x64 | `nupst-windows-x64.exe` |
| Platform | Binary |
| ------------------- | ----------------------- |
| Linux x64 | `nupst-linux-x64` |
| Linux ARM64 | `nupst-linux-arm64` |
| macOS Intel | `nupst-macos-x64` |
| macOS Apple Silicon | `nupst-macos-arm64` |
| Windows x64 | `nupst-windows-x64.exe` |
```bash
# Download binary (replace with your platform)
@@ -175,7 +189,8 @@ nupst group list # List all groups
### Action Management 🆕
Actions define what happens when UPS conditions are met. Actions can be attached to individual UPS devices or to groups.
Actions define what happens when UPS conditions are met. Actions can be attached to individual UPS
devices or to groups.
```bash
# Add an action to a UPS device or group
@@ -215,6 +230,78 @@ Add Action to UPS Main Server UPS
Changes saved and will be applied automatically
```
### Feature Management 🆕
Optional features like the HTTP server for JSON status export:
```bash
# Configure HTTP server feature (interactive)
nupst feature httpServer
```
**Example: Enabling HTTP Server**
```bash
$ sudo nupst feature httpServer
HTTP Server Feature Configuration
Configure the HTTP server to expose UPS status as JSON
HTTP Server is currently: DISABLED
Enable or disable HTTP server? (enable/disable/cancel): enable
HTTP Server Port [8080]: 8080
URL Path [/ups-status]: /ups-status
Generated new authentication token
✓ HTTP Server Configuration
Status: ENABLED
Port: 8080
Path: /ups-status
Auth Token: abc123xyz789def456
Usage examples:
curl -H "Authorization: Bearer abc123xyz789def456" http://localhost:8080/ups-status
curl "http://localhost:8080/ups-status?token=abc123xyz789def456"
⚠ IMPORTANT: Save the authentication token securely!
Service is running. Restart to apply changes? (Y/n): Y
```
**Query UPS Status via HTTP:**
```bash
# Using Bearer token in header
curl -H "Authorization: Bearer abc123xyz789def456" \
http://localhost:8080/ups-status
# Using token as query parameter
curl "http://localhost:8080/ups-status?token=abc123xyz789def456"
```
**JSON Response:**
```json
[
{
"id": "ups-main",
"name": "Main Server UPS",
"powerStatus": "online",
"batteryCapacity": 100,
"batteryRuntime": 45,
"outputLoad": 23,
"outputPower": 115,
"outputVoltage": 230.5,
"outputCurrent": 0.5,
"lastStatusChange": 1729685123456,
"lastCheckTime": 1729685153456
}
]
```
### Configuration
```bash
@@ -231,14 +318,21 @@ nupst config show # Display current configuration
## ⚙️ Configuration
NUPST stores configuration at `/etc/nupst/config.json`. The easiest way to configure is through interactive commands, but you can also edit the JSON directly.
NUPST stores configuration at `/etc/nupst/config.json`. The easiest way to configure is through
interactive commands, but you can also edit the JSON directly.
### Example Configuration (v4.1+)
```json
{
"version": "4.1",
"version": "4.2",
"checkInterval": 30000,
"httpServer": {
"enabled": true,
"port": 8080,
"path": "/ups-status",
"authToken": "abc123xyz789def456"
},
"upsDevices": [
{
"id": "ups-main",
@@ -315,8 +409,9 @@ NUPST stores configuration at `/etc/nupst/config.json`. The easiest way to confi
#### Global Settings
- **`version`**: Config format version (current: "4.1")
- **`version`**: Config format version (current: "4.2")
- **`checkInterval`**: Polling interval in milliseconds (default: 30000)
- **`httpServer`**: Optional HTTP server configuration (see HTTP Server Configuration below)
#### UPS Device Settings
@@ -327,25 +422,25 @@ NUPST stores configuration at `/etc/nupst/config.json`. The easiest way to confi
**SNMP Configuration:**
| Field | Description | Values |
|-------|-------------|--------|
| `host` | IP address or hostname | e.g., "192.168.1.100" |
| `port` | SNMP port | Default: 161 |
| `version` | SNMP version | 1, 2, or 3 |
| `timeout` | Timeout in milliseconds | Default: 5000 |
| `upsModel` | UPS brand/model | 'cyberpower', 'apc', 'eaton', 'tripplite', 'liebert', 'custom' |
| `community` | SNMP community (v1/v2c) | Default: "public" |
| Field | Description | Values |
| ----------- | ----------------------- | -------------------------------------------------------------- |
| `host` | IP address or hostname | e.g., "192.168.1.100" |
| `port` | SNMP port | Default: 161 |
| `version` | SNMP version | 1, 2, or 3 |
| `timeout` | Timeout in milliseconds | Default: 5000 |
| `upsModel` | UPS brand/model | 'cyberpower', 'apc', 'eaton', 'tripplite', 'liebert', 'custom' |
| `community` | SNMP community (v1/v2c) | Default: "public" |
**SNMPv3 Security:**
| Field | Description |
|-------|-------------|
| Field | Description |
| --------------- | ------------------------------------------- |
| `securityLevel` | 'noAuthNoPriv', 'authNoPriv', or 'authPriv' |
| `username` | SNMPv3 username |
| `authProtocol` | 'MD5' or 'SHA' |
| `authKey` | Authentication password |
| `privProtocol` | 'DES' or 'AES' (for authPriv) |
| `privKey` | Privacy/encryption password |
| `username` | SNMPv3 username |
| `authProtocol` | 'MD5' or 'SHA' |
| `authKey` | Authentication password |
| `privProtocol` | 'DES' or 'AES' (for authPriv) |
| `privKey` | Privacy/encryption password |
#### Action Configuration
@@ -365,21 +460,21 @@ Actions define automated responses to UPS conditions:
**Action Fields:**
| Field | Description | Values |
|-------|-------------|--------|
| `type` | Action type | Currently only 'shutdown' |
| `thresholds` | Battery and runtime limits | `{ battery: 0-100, runtime: minutes }` |
| `triggerMode` | When to trigger action | See Trigger Modes below |
| `shutdownDelay` | Delay before executing (seconds) | Default: 5 |
| Field | Description | Values |
| --------------- | -------------------------------- | -------------------------------------- |
| `type` | Action type | Currently only 'shutdown' |
| `thresholds` | Battery and runtime limits | `{ battery: 0-100, runtime: minutes }` |
| `triggerMode` | When to trigger action | See Trigger Modes below |
| `shutdownDelay` | Delay before executing (seconds) | Default: 5 |
**Trigger Modes:**
| Mode | Description |
|------|-------------|
| `onlyPowerChanges` | Trigger only when power status changes (on battery → online or vice versa) |
| `onlyThresholds` | Trigger only when battery or runtime thresholds are violated |
| `powerChangesAndThresholds` | Trigger only when power changes AND thresholds are violated |
| `anyChange` | Trigger on any status change |
| Mode | Description |
| --------------------------- | -------------------------------------------------------------------------- |
| `onlyPowerChanges` | Trigger only when power status changes (on battery → online or vice versa) |
| `onlyThresholds` | Trigger only when battery or runtime thresholds are violated |
| `powerChangesAndThresholds` | Trigger only when power changes AND thresholds are violated |
| `anyChange` | Trigger on any status change |
#### Group Settings
@@ -397,8 +492,53 @@ Groups allow coordinated management of multiple UPS devices:
**Group Modes:**
- **`redundant`**: System shuts down only when ALL UPS devices in the group are critical. Perfect for setups with backup UPS units.
- **`nonRedundant`**: System shuts down when ANY UPS device in the group is critical. Used when all UPS devices must be operational.
- **`redundant`**: System shuts down only when ALL UPS devices in the group are critical. Perfect
for setups with backup UPS units.
- **`nonRedundant`**: System shuts down when ANY UPS device in the group is critical. Used when all
UPS devices must be operational.
#### HTTP Server Configuration 🆕
Enable optional HTTP server for JSON status export with authentication:
```json
{
"enabled": true,
"port": 8080,
"path": "/ups-status",
"authToken": "abc123xyz789def456"
}
```
**HTTP Server Fields:**
| Field | Description | Default |
| ----------- | ------------------------------------------------ | -------------- |
| `enabled` | Whether HTTP server is enabled | `false` |
| `port` | TCP port for HTTP server | `8080` |
| `path` | URL path for status endpoint | `/ups-status` |
| `authToken` | Authentication token (required for all requests) | Auto-generated |
**Authentication Methods:**
The HTTP server supports two authentication methods:
1. **Bearer Token** (Header): `Authorization: Bearer <token>`
2. **Query Parameter**: `?token=<token>`
**Security Features:**
- Token-based authentication required for all requests
- Returns 401 Unauthorized for invalid/missing tokens
- Serves cached data from monitoring loop (no extra SNMP queries)
- No CORS headers (local network only)
**Use Cases:**
- Integration with monitoring systems (Prometheus, Grafana, etc.)
- Custom dashboards and visualizations
- Mobile apps and web interfaces
- Home automation systems
### Supported UPS Models
@@ -425,7 +565,8 @@ For custom UPS models, specify `customOIDs`:
### Status Display
The status command shows comprehensive information about your UPS devices, groups, and configured actions:
The status command shows comprehensive information about your UPS devices, groups, and configured
actions:
```bash
$ nupst service status
@@ -457,6 +598,7 @@ nupst service logs
```
Example output:
```
[2025-01-15 10:30:15] ℹ NUPST daemon started
[2025-01-15 10:30:15] ✓ Connected to Main Server UPS (192.168.1.100)
@@ -481,11 +623,11 @@ NUPST is designed with security as a priority:
Full SNMPv3 support with authentication and encryption:
| Security Level | Description |
|----------------|-------------|
| `noAuthNoPriv` | No authentication, no encryption (not recommended) |
| `authNoPriv` | MD5/SHA authentication without encryption |
| `authPriv` | Full authentication + DES/AES encryption (recommended) |
| Security Level | Description |
| -------------- | ------------------------------------------------------ |
| `noAuthNoPriv` | No authentication, no encryption (not recommended) |
| `authNoPriv` | MD5/SHA authentication without encryption |
| `authPriv` | Full authentication + DES/AES encryption (recommended) |
**Example SNMPv3 Configuration:**
@@ -506,6 +648,12 @@ Full SNMPv3 support with authentication and encryption:
- **Local-Only Communication**: Only connects to UPS devices on local network
- **No Telemetry**: No data sent to external servers
- **No Auto-Updates**: Manual update process only
- **HTTP Server** (optional):
- Disabled by default
- Token-based authentication required
- Local network access only (no CORS)
- Serves cached data (no additional SNMP queries)
- Configurable port and path
### Verifying Downloads
@@ -531,6 +679,7 @@ curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh |
```
The installer will:
- Download the latest binary
- Replace the existing installation
- Preserve your configuration
@@ -557,7 +706,8 @@ sudo nupst service start
nupst --version
```
Visit the [releases page](https://code.foss.global/serve.zone/nupst/releases) for the latest version.
Visit the [releases page](https://code.foss.global/serve.zone/nupst/releases) for the latest
version.
## 🗑️ Uninstallation
@@ -655,11 +805,11 @@ When installed, NUPST makes the following changes:
### File System
| Path | Description |
|------|-------------|
| `/opt/nupst/nupst` | Pre-compiled binary |
| `/usr/local/bin/nupst` | Symlink to binary |
| `/etc/nupst/config.json` | Configuration file |
| Path | Description |
| ----------------------------------- | -------------------- |
| `/opt/nupst/nupst` | Pre-compiled binary |
| `/usr/local/bin/nupst` | Symlink to binary |
| `/etc/nupst/config.json` | Configuration file |
| `/etc/systemd/system/nupst.service` | Systemd service unit |
### Services
@@ -670,7 +820,7 @@ When installed, NUPST makes the following changes:
### Network
- Outbound SNMP to UPS devices (default port 161)
- No inbound connections required
- Optional inbound HTTP server (disabled by default, configurable port)
- No external internet connections
## 🚀 Migration from v3.x
@@ -683,6 +833,7 @@ curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh |
```
**The installer automatically:**
- Detects v3.x installation
- Stops the service
- Replaces Node.js version with Deno binary
@@ -691,21 +842,22 @@ curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh |
### Key Changes in v4.x
| Aspect | v3.x | v4.x |
|--------|------|------|
| **Runtime** | Node.js + npm | Deno |
| **Distribution** | Git repo + npm install | Pre-compiled binaries |
| **Runtime Dependencies** | node_modules required | Zero (self-contained) |
| **Size** | ~150MB (with node_modules) | ~80MB (single binary) |
| **Startup** | Seconds | Milliseconds |
| **Commands** | Flat (`nupst add`) | Subcommands (`nupst ups add`) |
| **Configuration** | UPS-level thresholds | Action-based thresholds |
| Aspect | v3.x | v4.x |
| ------------------------ | -------------------------- | ----------------------------- |
| **Runtime** | Node.js + npm | Deno |
| **Distribution** | Git repo + npm install | Pre-compiled binaries |
| **Runtime Dependencies** | node_modules required | Zero (self-contained) |
| **Size** | ~150MB (with node_modules) | ~80MB (single binary) |
| **Startup** | Seconds | Milliseconds |
| **Commands** | Flat (`nupst add`) | Subcommands (`nupst ups add`) |
| **Configuration** | UPS-level thresholds | Action-based thresholds |
### Configuration Compatibility
Your v3.x configuration is **fully compatible**. The migration system automatically converts:
**v4.0 format** (UPS-level thresholds):
```json
{
"version": "4.0",
@@ -717,6 +869,7 @@ Your v3.x configuration is **fully compatible**. The migration system automatica
```
**v4.1 format** (action-based thresholds):
```json
{
"version": "4.1",
@@ -788,19 +941,28 @@ nupst/
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT
License can be found in the [license](license) file within this repository.
**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.
**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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
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 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, and any usage must be
approved in writing by Task Venture Capital GmbH.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
For any legal inquiries or if you require 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.
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.