2025-10-20 12:52:26 +00:00
|
|
|
|
# ⚡ NUPST - Network UPS Shutdown Tool
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
**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.
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
**Version 5.0+** is powered by Deno and distributed as single pre-compiled binaries—no installation,
|
|
|
|
|
|
no setup, just run.
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## ✨ Features
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- **🔌 Multi-UPS Support**: Monitor multiple UPS devices from a single installation
|
|
|
|
|
|
- **👥 Group Management**: Organize UPS devices into groups with flexible operating modes
|
|
|
|
|
|
- **Redundant Mode**: Only shutdown when ALL UPS devices in a group are critical
|
|
|
|
|
|
- **Non-Redundant Mode**: Shutdown when ANY UPS device in a group is critical
|
|
|
|
|
|
- **⚙️ Action System**: Define custom actions with flexible trigger conditions
|
|
|
|
|
|
- Battery threshold triggers
|
|
|
|
|
|
- Runtime threshold triggers
|
|
|
|
|
|
- Power status change triggers
|
|
|
|
|
|
- Configurable shutdown delays
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- **🌐 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
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- **🚀 Systemd Integration**: Simple service installation and management
|
|
|
|
|
|
- **📊 Real-time Monitoring**: Live status updates with detailed action and group information
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- **🌐 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
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 🚀 Quick Start
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### One-Line Installation
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Download and install NUPST automatically
|
2025-10-19 21:37:41 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Initial Setup
|
2025-03-25 13:15:48 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
# 1. Add your first UPS device
|
|
|
|
|
|
sudo nupst ups add
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# 2. Test the connection
|
|
|
|
|
|
nupst ups test
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# 3. Enable and start monitoring
|
|
|
|
|
|
sudo nupst service enable
|
|
|
|
|
|
sudo nupst service start
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# 4. Check status
|
|
|
|
|
|
nupst service status
|
|
|
|
|
|
```
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**That's it!** Your system is now protected. 🛡️
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 📥 Installation
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-22 14:18:09 +00:00
|
|
|
|
### Via npm (NEW! - Recommended)
|
|
|
|
|
|
|
|
|
|
|
|
Install NUPST globally using npm:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
npm install -g @serve.zone/nupst
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**Benefits:**
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-22 14:18:09 +00:00
|
|
|
|
- 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
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
**Note:** The installation will download the appropriate binary from GitHub releases during the
|
|
|
|
|
|
postinstall step.
|
2025-10-22 14:18:09 +00:00
|
|
|
|
|
|
|
|
|
|
### Automated Installer Script
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
The installer script handles everything automatically:
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
2025-03-25 11:31:24 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**What it does:**
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
1. Detects your platform (OS and architecture)
|
|
|
|
|
|
2. Downloads the latest pre-compiled binary
|
|
|
|
|
|
3. Installs to `/opt/nupst/nupst`
|
|
|
|
|
|
4. Creates symlink at `/usr/local/bin/nupst`
|
|
|
|
|
|
5. Preserves existing configuration
|
|
|
|
|
|
|
|
|
|
|
|
### Installer Options
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-18 13:33:46 +00:00
|
|
|
|
# Install specific version
|
2025-10-20 12:52:26 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | \
|
2025-10-20 13:00:42 +00:00
|
|
|
|
sudo bash -s -- --version v5.0.0
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
# Custom installation directory
|
2025-10-20 12:52:26 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | \
|
|
|
|
|
|
sudo bash -s -- --install-dir /usr/local/nupst
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Show help
|
|
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | bash -s -- --help
|
|
|
|
|
|
```
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Manual Installation
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
Download the appropriate binary for your platform from
|
|
|
|
|
|
[releases](https://code.foss.global/serve.zone/nupst/releases):
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| 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` |
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
# Download binary (replace with your platform)
|
2025-10-20 13:00:42 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v5.0.0/nupst-linux-x64 -o nupst
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Make executable
|
|
|
|
|
|
chmod +x nupst
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Move to system path
|
|
|
|
|
|
sudo mv nupst /usr/local/bin/nupst
|
|
|
|
|
|
```
|
2025-03-25 11:31:24 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Verify Installation
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Check version
|
|
|
|
|
|
nupst --version
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# View help
|
|
|
|
|
|
nupst help
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 📖 Usage
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Command Structure
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
NUPST uses an intuitive subcommand structure:
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
2025-10-20 12:52:26 +00:00
|
|
|
|
nupst <command> <subcommand> [options]
|
|
|
|
|
|
```
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Service Management
|
2025-03-28 16:19:43 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
nupst service enable # Install and enable systemd service
|
|
|
|
|
|
nupst service disable # Stop and disable systemd service
|
|
|
|
|
|
nupst service start # Start the service
|
|
|
|
|
|
nupst service stop # Stop the service
|
|
|
|
|
|
nupst service restart # Restart the service
|
|
|
|
|
|
nupst service status # Show service and UPS status
|
|
|
|
|
|
nupst service logs # Show live service logs
|
|
|
|
|
|
```
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### UPS Device Management
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
nupst ups add # Add a new UPS device (interactive)
|
|
|
|
|
|
nupst ups edit [id] # Edit a UPS device
|
|
|
|
|
|
nupst ups remove <id> # Remove a UPS device
|
|
|
|
|
|
nupst ups list # List all UPS devices
|
|
|
|
|
|
nupst ups test # Test UPS connections
|
|
|
|
|
|
```
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Group Management
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
nupst group add # Create a new UPS group
|
|
|
|
|
|
nupst group edit <id> # Edit a group
|
|
|
|
|
|
nupst group remove <id> # Remove a group
|
|
|
|
|
|
nupst group list # List all groups
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Action Management 🆕
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
Actions define what happens when UPS conditions are met. Actions can be attached to individual UPS
|
|
|
|
|
|
devices or to groups.
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
# Add an action to a UPS device or group
|
|
|
|
|
|
nupst action add <ups-id|group-id>
|
|
|
|
|
|
|
|
|
|
|
|
# Remove an action by index
|
|
|
|
|
|
nupst action remove <ups-id|group-id> <index>
|
|
|
|
|
|
|
|
|
|
|
|
# List all actions
|
|
|
|
|
|
nupst action list
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# List actions for specific UPS/group
|
|
|
|
|
|
nupst action list <ups-id|group-id>
|
|
|
|
|
|
```
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**Example: Adding an action**
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
$ sudo nupst action add ups-main
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Add Action to UPS Main Server UPS
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Action type: shutdown
|
|
|
|
|
|
Battery threshold (%): 20
|
|
|
|
|
|
Runtime threshold (minutes): 10
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Trigger mode:
|
|
|
|
|
|
1) onlyPowerChanges - Trigger only when power status changes
|
|
|
|
|
|
2) onlyThresholds - Trigger only when thresholds are violated
|
|
|
|
|
|
3) powerChangesAndThresholds - Trigger on power change AND thresholds
|
|
|
|
|
|
4) anyChange - Trigger on any status change
|
|
|
|
|
|
Choice [2]: 2
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Shutdown delay (seconds) [5]: 10
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
✓ Action added to UPS Main Server UPS
|
|
|
|
|
|
Changes saved and will be applied automatically
|
|
|
|
|
|
```
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
### 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
|
|
|
|
|
|
}
|
|
|
|
|
|
]
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Configuration
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
nupst config show # Display current configuration
|
|
|
|
|
|
```
|
2025-03-28 16:19:43 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Global Options
|
2025-03-28 16:19:43 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
--version, -v # Show version information
|
|
|
|
|
|
--help, -h # Show help message
|
|
|
|
|
|
--debug, -d # Enable debug mode (detailed SNMP logging)
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## ⚙️ Configuration
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
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.
|
2025-10-20 12:52:26 +00:00
|
|
|
|
|
|
|
|
|
|
### Example Configuration (v4.1+)
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
2025-10-23 12:57:58 +00:00
|
|
|
|
"version": "4.2",
|
2025-03-28 16:19:43 +00:00
|
|
|
|
"checkInterval": 30000,
|
2025-10-23 12:57:58 +00:00
|
|
|
|
"httpServer": {
|
|
|
|
|
|
"enabled": true,
|
|
|
|
|
|
"port": 8080,
|
|
|
|
|
|
"path": "/ups-status",
|
|
|
|
|
|
"authToken": "abc123xyz789def456"
|
|
|
|
|
|
},
|
2025-03-28 16:19:43 +00:00
|
|
|
|
"upsDevices": [
|
|
|
|
|
|
{
|
2025-10-20 12:52:26 +00:00
|
|
|
|
"id": "ups-main",
|
|
|
|
|
|
"name": "Main Server UPS",
|
2025-03-28 16:19:43 +00:00
|
|
|
|
"snmp": {
|
|
|
|
|
|
"host": "192.168.1.100",
|
|
|
|
|
|
"port": 161,
|
|
|
|
|
|
"community": "public",
|
|
|
|
|
|
"version": 1,
|
|
|
|
|
|
"timeout": 5000,
|
|
|
|
|
|
"upsModel": "cyberpower"
|
|
|
|
|
|
},
|
2025-10-20 12:52:26 +00:00
|
|
|
|
"actions": [
|
|
|
|
|
|
{
|
|
|
|
|
|
"type": "shutdown",
|
|
|
|
|
|
"thresholds": {
|
|
|
|
|
|
"battery": 20,
|
|
|
|
|
|
"runtime": 10
|
|
|
|
|
|
},
|
|
|
|
|
|
"triggerMode": "onlyThresholds",
|
|
|
|
|
|
"shutdownDelay": 10
|
|
|
|
|
|
}
|
|
|
|
|
|
],
|
2025-03-28 16:19:43 +00:00
|
|
|
|
"groups": ["datacenter"]
|
|
|
|
|
|
},
|
|
|
|
|
|
{
|
2025-10-20 12:52:26 +00:00
|
|
|
|
"id": "ups-backup",
|
|
|
|
|
|
"name": "Backup UPS",
|
2025-03-28 16:19:43 +00:00
|
|
|
|
"snmp": {
|
|
|
|
|
|
"host": "192.168.1.101",
|
|
|
|
|
|
"port": 161,
|
|
|
|
|
|
"community": "public",
|
|
|
|
|
|
"version": 1,
|
|
|
|
|
|
"timeout": 5000,
|
|
|
|
|
|
"upsModel": "apc"
|
|
|
|
|
|
},
|
2025-10-20 12:52:26 +00:00
|
|
|
|
"actions": [
|
|
|
|
|
|
{
|
|
|
|
|
|
"type": "shutdown",
|
|
|
|
|
|
"thresholds": {
|
|
|
|
|
|
"battery": 15,
|
|
|
|
|
|
"runtime": 5
|
|
|
|
|
|
},
|
|
|
|
|
|
"triggerMode": "onlyThresholds",
|
|
|
|
|
|
"shutdownDelay": 5
|
|
|
|
|
|
}
|
|
|
|
|
|
],
|
2025-03-28 16:19:43 +00:00
|
|
|
|
"groups": ["datacenter"]
|
|
|
|
|
|
}
|
|
|
|
|
|
],
|
|
|
|
|
|
"groups": [
|
|
|
|
|
|
{
|
|
|
|
|
|
"id": "datacenter",
|
|
|
|
|
|
"name": "Data Center",
|
|
|
|
|
|
"mode": "redundant",
|
2025-10-20 12:52:26 +00:00
|
|
|
|
"description": "Redundant UPS setup - only shutdown when both are critical",
|
|
|
|
|
|
"actions": [
|
|
|
|
|
|
{
|
|
|
|
|
|
"type": "shutdown",
|
|
|
|
|
|
"thresholds": {
|
|
|
|
|
|
"battery": 10,
|
|
|
|
|
|
"runtime": 5
|
|
|
|
|
|
},
|
|
|
|
|
|
"triggerMode": "onlyThresholds",
|
|
|
|
|
|
"shutdownDelay": 15
|
|
|
|
|
|
}
|
|
|
|
|
|
]
|
2025-03-28 16:19:43 +00:00
|
|
|
|
}
|
|
|
|
|
|
]
|
2025-03-25 09:06:23 +00:00
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2025-03-28 16:19:43 +00:00
|
|
|
|
### Configuration Fields
|
|
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
#### Global Settings
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- **`version`**: Config format version (current: "4.2")
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- **`checkInterval`**: Polling interval in milliseconds (default: 30000)
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- **`httpServer`**: Optional HTTP server configuration (see HTTP Server Configuration below)
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
#### UPS Device Settings
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- **`id`**: Unique identifier for the UPS
|
|
|
|
|
|
- **`name`**: Friendly name
|
|
|
|
|
|
- **`groups`**: Array of group IDs this UPS belongs to
|
|
|
|
|
|
- **`actions`**: Array of action configurations (see Actions section)
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
**SNMP Configuration:**
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| 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" |
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**SNMPv3 Security:**
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| Field | Description |
|
|
|
|
|
|
| --------------- | ------------------------------------------- |
|
2025-10-20 12:52:26 +00:00
|
|
|
|
| `securityLevel` | 'noAuthNoPriv', 'authNoPriv', or 'authPriv' |
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| `username` | SNMPv3 username |
|
|
|
|
|
|
| `authProtocol` | 'MD5' or 'SHA' |
|
|
|
|
|
|
| `authKey` | Authentication password |
|
|
|
|
|
|
| `privProtocol` | 'DES' or 'AES' (for authPriv) |
|
|
|
|
|
|
| `privKey` | Privacy/encryption password |
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
#### Action Configuration
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Actions define automated responses to UPS conditions:
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"type": "shutdown",
|
|
|
|
|
|
"thresholds": {
|
|
|
|
|
|
"battery": 20,
|
|
|
|
|
|
"runtime": 10
|
|
|
|
|
|
},
|
|
|
|
|
|
"triggerMode": "onlyThresholds",
|
|
|
|
|
|
"shutdownDelay": 10
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**Action Fields:**
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| 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 |
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**Trigger Modes:**
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| 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 |
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
#### Group Settings
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Groups allow coordinated management of multiple UPS devices:
|
2025-03-28 16:19:43 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"id": "datacenter",
|
|
|
|
|
|
"name": "Data Center",
|
|
|
|
|
|
"mode": "redundant",
|
|
|
|
|
|
"description": "Production servers with backup power",
|
|
|
|
|
|
"actions": [...]
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
2025-03-28 16:19:43 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**Group Modes:**
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- **`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
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Supported UPS Models
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
NUPST includes built-in OID mappings for:
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- **CyberPower** (`cyberpower`)
|
|
|
|
|
|
- **APC** (`apc`)
|
|
|
|
|
|
- **Eaton** (`eaton`)
|
|
|
|
|
|
- **TrippLite** (`tripplite`)
|
|
|
|
|
|
- **Liebert/Vertiv** (`liebert`)
|
|
|
|
|
|
- **Custom OIDs** (`custom`)
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
For custom UPS models, specify `customOIDs`:
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```json
|
|
|
|
|
|
"customOIDs": {
|
|
|
|
|
|
"POWER_STATUS": "1.3.6.1.4.1.1234.1.1.0",
|
|
|
|
|
|
"BATTERY_CAPACITY": "1.3.6.1.4.1.1234.1.2.0",
|
|
|
|
|
|
"BATTERY_RUNTIME": "1.3.6.1.4.1.1234.1.3.0"
|
|
|
|
|
|
}
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 🖥️ Monitoring
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Status Display
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
The status command shows comprehensive information about your UPS devices, groups, and configured
|
|
|
|
|
|
actions:
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
$ nupst service status
|
|
|
|
|
|
|
|
|
|
|
|
UPS Devices (2):
|
|
|
|
|
|
✓ Main Server UPS (online - 100%, 3840min)
|
|
|
|
|
|
Host: 192.168.1.100:161
|
|
|
|
|
|
Groups: Data Center
|
|
|
|
|
|
Action: shutdown (onlyThresholds: battery<20%, runtime<10min, delay=10s)
|
|
|
|
|
|
|
|
|
|
|
|
✓ Backup UPS (online - 95%, 2400min)
|
|
|
|
|
|
Host: 192.168.1.101:161
|
|
|
|
|
|
Groups: Data Center
|
|
|
|
|
|
Action: shutdown (onlyThresholds: battery<15%, runtime<5min, delay=5s)
|
|
|
|
|
|
|
|
|
|
|
|
Groups (1):
|
|
|
|
|
|
ℹ Data Center (redundant)
|
|
|
|
|
|
Redundant UPS setup - only shutdown when both are critical
|
|
|
|
|
|
UPS Devices (2): Main Server UPS, Backup UPS
|
|
|
|
|
|
Action: shutdown (onlyThresholds: battery<10%, runtime<5min, delay=15s)
|
2025-03-25 09:06:23 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Live Logs
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Monitor NUPST in real-time:
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
nupst service logs
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Example output:
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```
|
|
|
|
|
|
[2025-01-15 10:30:15] ℹ NUPST daemon started
|
|
|
|
|
|
[2025-01-15 10:30:15] ✓ Connected to Main Server UPS (192.168.1.100)
|
|
|
|
|
|
[2025-01-15 10:30:15] ✓ Connected to Backup UPS (192.168.1.101)
|
|
|
|
|
|
[2025-01-15 10:30:45] ℹ Status check: All systems normal
|
|
|
|
|
|
[2025-01-15 10:31:15] ⚠ Main Server UPS on battery (85%, 45min remaining)
|
2025-03-25 09:49:30 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 🔒 Security
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
NUPST is designed with security as a priority:
|
|
|
|
|
|
|
|
|
|
|
|
### Architecture Security
|
|
|
|
|
|
|
2025-10-20 12:59:14 +00:00
|
|
|
|
- **Single Binary**: Self-contained executable with zero runtime dependencies
|
|
|
|
|
|
- **No Installation Required**: Pre-compiled binaries run immediately without package managers
|
2025-10-18 13:33:46 +00:00
|
|
|
|
- **Minimal Attack Surface**: Compiled Deno binary with only essential SNMP functionality
|
2025-10-20 12:59:14 +00:00
|
|
|
|
- **Reduced Supply Chain Risk**: Pre-compiled binaries with SHA256 checksums
|
2025-10-18 13:33:46 +00:00
|
|
|
|
- **Isolated Execution**: Runs with minimal required privileges
|
|
|
|
|
|
|
|
|
|
|
|
### SNMP Security
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Full SNMPv3 support with authentication and encryption:
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| Security Level | Description |
|
|
|
|
|
|
| -------------- | ------------------------------------------------------ |
|
|
|
|
|
|
| `noAuthNoPriv` | No authentication, no encryption (not recommended) |
|
|
|
|
|
|
| `authNoPriv` | MD5/SHA authentication without encryption |
|
|
|
|
|
|
| `authPriv` | Full authentication + DES/AES encryption (recommended) |
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
**Example SNMPv3 Configuration:**
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"version": 3,
|
|
|
|
|
|
"securityLevel": "authPriv",
|
|
|
|
|
|
"username": "nupst_monitor",
|
|
|
|
|
|
"authProtocol": "SHA",
|
|
|
|
|
|
"authKey": "your-auth-password",
|
|
|
|
|
|
"privProtocol": "AES",
|
|
|
|
|
|
"privKey": "your-encryption-password"
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
### Network Security
|
|
|
|
|
|
|
|
|
|
|
|
- **Local-Only Communication**: Only connects to UPS devices on local network
|
|
|
|
|
|
- **No Telemetry**: No data sent to external servers
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- **No Auto-Updates**: Manual update process only
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- **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
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
### Verifying Downloads
|
|
|
|
|
|
|
|
|
|
|
|
All releases include SHA256 checksums:
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-18 13:33:46 +00:00
|
|
|
|
# Download binary and checksums
|
2025-10-20 13:00:42 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v5.0.0/nupst-linux-x64 -o nupst
|
|
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v5.0.0/SHA256SUMS.txt -o SHA256SUMS.txt
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
# Verify checksum
|
|
|
|
|
|
sha256sum -c SHA256SUMS.txt --ignore-missing
|
2025-03-25 09:49:30 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 🔄 Updating NUPST
|
2025-10-19 13:05:51 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Automatic Update
|
2025-10-19 13:05:51 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Re-run the installer to update to the latest version:
|
2025-10-19 13:05:51 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-19 21:37:41 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
2025-10-19 13:05:51 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
The installer will:
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- Download the latest binary
|
|
|
|
|
|
- Replace the existing installation
|
|
|
|
|
|
- Preserve your configuration
|
|
|
|
|
|
- Restart the service if it was running
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Manual Update
|
2025-10-19 13:05:51 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
# Stop service
|
|
|
|
|
|
sudo nupst service stop
|
2025-10-19 13:05:51 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Download and install new binary
|
2025-10-20 13:00:42 +00:00
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v5.0.0/nupst-linux-x64 -o nupst
|
2025-10-20 12:52:26 +00:00
|
|
|
|
sudo mv nupst /opt/nupst/nupst
|
|
|
|
|
|
sudo chmod +x /opt/nupst/nupst
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Start service
|
2025-10-19 13:05:51 +00:00
|
|
|
|
sudo nupst service start
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Check for Updates
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-19 13:05:51 +00:00
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
nupst --version
|
2025-10-19 13:05:51 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
Visit the [releases page](https://code.foss.global/serve.zone/nupst/releases) for the latest
|
|
|
|
|
|
version.
|
2025-10-20 12:52:26 +00:00
|
|
|
|
|
|
|
|
|
|
## 🗑️ Uninstallation
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-19 13:05:51 +00:00
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Stop and disable service
|
|
|
|
|
|
sudo nupst service disable
|
|
|
|
|
|
|
|
|
|
|
|
# Remove binary and configuration
|
|
|
|
|
|
sudo rm /usr/local/bin/nupst
|
|
|
|
|
|
sudo rm -rf /opt/nupst
|
|
|
|
|
|
sudo rm -rf /etc/nupst
|
|
|
|
|
|
|
|
|
|
|
|
# Remove systemd service file (if it exists)
|
|
|
|
|
|
sudo rm /etc/systemd/system/nupst.service
|
|
|
|
|
|
sudo systemctl daemon-reload
|
2025-10-19 13:05:51 +00:00
|
|
|
|
```
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 🔧 Troubleshooting
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
### Binary Won't Execute
|
2025-03-26 13:49:47 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Make executable
|
2025-10-18 13:33:46 +00:00
|
|
|
|
chmod +x /opt/nupst/nupst
|
2025-03-26 13:54:49 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Check architecture
|
2025-10-18 13:33:46 +00:00
|
|
|
|
uname -m # Should match binary (x86_64 = x64, aarch64 = arm64)
|
2025-03-26 13:49:47 +00:00
|
|
|
|
```
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
### Service Won't Start
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
# Check service status
|
|
|
|
|
|
sudo systemctl status nupst
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# View detailed logs
|
2025-10-18 13:33:46 +00:00
|
|
|
|
sudo journalctl -u nupst -n 50
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
# Verify configuration
|
|
|
|
|
|
nupst config show
|
2025-10-20 12:52:26 +00:00
|
|
|
|
|
|
|
|
|
|
# Test SNMP connectivity
|
|
|
|
|
|
nupst ups test --debug
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
### Can't Connect to UPS
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```bash
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Test with debug output
|
2025-10-18 13:33:46 +00:00
|
|
|
|
nupst ups test --debug
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
# Check network connectivity
|
|
|
|
|
|
ping <ups-ip-address>
|
2025-03-26 13:27:47 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Verify SNMP port
|
2025-10-18 13:33:46 +00:00
|
|
|
|
nc -zv <ups-ip-address> 161
|
2025-10-20 12:52:26 +00:00
|
|
|
|
|
|
|
|
|
|
# Check SNMP settings on UPS
|
|
|
|
|
|
# - Ensure SNMP is enabled
|
|
|
|
|
|
# - Verify community string matches
|
|
|
|
|
|
# - Check IP access restrictions
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```
|
2025-03-26 13:27:47 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
### Permission Denied Errors
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
Most system operations require root:
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# Service management
|
|
|
|
|
|
sudo nupst service enable
|
|
|
|
|
|
sudo nupst service start
|
|
|
|
|
|
|
|
|
|
|
|
# Configuration changes
|
|
|
|
|
|
sudo nupst ups add
|
2025-10-20 12:52:26 +00:00
|
|
|
|
sudo nupst action add ups-main
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Action Not Triggering
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
# Check action configuration
|
|
|
|
|
|
nupst action list
|
|
|
|
|
|
|
|
|
|
|
|
# View live logs to see trigger evaluation
|
|
|
|
|
|
nupst service logs
|
|
|
|
|
|
|
|
|
|
|
|
# Test with debug mode
|
|
|
|
|
|
sudo nupst service stop
|
|
|
|
|
|
sudo nupst service start-daemon --debug
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 📊 System Changes
|
|
|
|
|
|
|
|
|
|
|
|
When installed, NUPST makes the following changes:
|
|
|
|
|
|
|
|
|
|
|
|
### File System
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| Path | Description |
|
|
|
|
|
|
| ----------------------------------- | -------------------- |
|
|
|
|
|
|
| `/opt/nupst/nupst` | Pre-compiled binary |
|
|
|
|
|
|
| `/usr/local/bin/nupst` | Symlink to binary |
|
|
|
|
|
|
| `/etc/nupst/config.json` | Configuration file |
|
2025-10-20 12:52:26 +00:00
|
|
|
|
| `/etc/systemd/system/nupst.service` | Systemd service unit |
|
|
|
|
|
|
|
|
|
|
|
|
### Services
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- Creates `nupst.service` systemd unit (when enabled)
|
|
|
|
|
|
- Runs with root permissions (required for system shutdown)
|
2025-10-19 13:14:18 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Network
|
|
|
|
|
|
|
|
|
|
|
|
- Outbound SNMP to UPS devices (default port 161)
|
2025-10-23 12:57:58 +00:00
|
|
|
|
- Optional inbound HTTP server (disabled by default, configurable port)
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- No external internet connections
|
|
|
|
|
|
|
|
|
|
|
|
## 🚀 Migration from v3.x
|
|
|
|
|
|
|
|
|
|
|
|
Upgrading from NUPST v3.x (Node.js) to v4.x (Deno) is seamless:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# One command to migrate everything
|
|
|
|
|
|
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**The installer automatically:**
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
- Detects v3.x installation
|
|
|
|
|
|
- Stops the service
|
|
|
|
|
|
- Replaces Node.js version with Deno binary
|
|
|
|
|
|
- Migrates configuration (v4.0 → v4.1 format if needed)
|
|
|
|
|
|
- Restarts the service
|
|
|
|
|
|
|
|
|
|
|
|
### Key Changes in v4.x
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
| 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 |
|
2025-10-20 12:52:26 +00:00
|
|
|
|
|
|
|
|
|
|
### Configuration Compatibility
|
|
|
|
|
|
|
|
|
|
|
|
Your v3.x configuration is **fully compatible**. The migration system automatically converts:
|
|
|
|
|
|
|
|
|
|
|
|
**v4.0 format** (UPS-level thresholds):
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"version": "4.0",
|
|
|
|
|
|
"upsDevices": [{
|
|
|
|
|
|
"id": "ups-1",
|
|
|
|
|
|
"thresholds": { "battery": 60, "runtime": 20 }
|
|
|
|
|
|
}]
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**v4.1 format** (action-based thresholds):
|
2025-10-23 12:57:58 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"version": "4.1",
|
|
|
|
|
|
"upsDevices": [{
|
|
|
|
|
|
"id": "ups-1",
|
|
|
|
|
|
"actions": [{
|
|
|
|
|
|
"type": "shutdown",
|
|
|
|
|
|
"thresholds": { "battery": 60, "runtime": 20 },
|
|
|
|
|
|
"triggerMode": "onlyThresholds",
|
|
|
|
|
|
"shutdownDelay": 5
|
|
|
|
|
|
}]
|
|
|
|
|
|
}]
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Migration happens automatically on first run—no manual changes needed.
|
|
|
|
|
|
|
|
|
|
|
|
## 💻 Development
|
|
|
|
|
|
|
|
|
|
|
|
### Building from Source
|
|
|
|
|
|
|
|
|
|
|
|
**Requirements:** [Deno](https://deno.land/) v1.x or later
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# Clone repository
|
|
|
|
|
|
git clone https://code.foss.global/serve.zone/nupst.git
|
|
|
|
|
|
cd nupst
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Run directly
|
2025-10-18 13:33:46 +00:00
|
|
|
|
deno run --allow-all mod.ts help
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
# Run tests
|
|
|
|
|
|
deno test --allow-all test/
|
|
|
|
|
|
|
|
|
|
|
|
# Type check
|
|
|
|
|
|
deno check ts/cli.ts
|
|
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
# Compile for current platform
|
|
|
|
|
|
deno compile --allow-all --output nupst mod.ts
|
|
|
|
|
|
|
|
|
|
|
|
# Compile for all platforms
|
2025-10-20 12:52:26 +00:00
|
|
|
|
deno task compile
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
### Project Structure
|
2025-10-18 13:33:46 +00:00
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
```
|
|
|
|
|
|
nupst/
|
|
|
|
|
|
├── mod.ts # Entry point
|
|
|
|
|
|
├── ts/
|
|
|
|
|
|
│ ├── cli.ts # CLI command routing
|
|
|
|
|
|
│ ├── nupst.ts # Main coordinator class
|
|
|
|
|
|
│ ├── daemon.ts # Background monitoring daemon
|
|
|
|
|
|
│ ├── systemd.ts # Systemd service management
|
|
|
|
|
|
│ ├── snmp/ # SNMP implementation
|
|
|
|
|
|
│ ├── actions/ # Action system
|
|
|
|
|
|
│ ├── migrations/ # Config migration system
|
|
|
|
|
|
│ └── cli/ # CLI handlers
|
|
|
|
|
|
├── test/ # Test files
|
|
|
|
|
|
├── scripts/ # Build scripts
|
|
|
|
|
|
└── deno.json # Deno configuration
|
2025-10-18 13:33:46 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2025-10-20 12:52:26 +00:00
|
|
|
|
## 📞 Support
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-10-18 13:33:46 +00:00
|
|
|
|
- **Issues**: [Report bugs or request features](https://code.foss.global/serve.zone/nupst/issues)
|
|
|
|
|
|
- **Documentation**: [Full documentation](https://code.foss.global/serve.zone/nupst)
|
|
|
|
|
|
- **Source Code**: [View source](https://code.foss.global/serve.zone/nupst)
|
2025-03-25 09:49:30 +00:00
|
|
|
|
|
2025-03-25 11:36:11 +00:00
|
|
|
|
## License and Legal Information
|
2025-03-25 09:06:23 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
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.
|
2025-03-25 11:36:11 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
**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.
|
2025-03-25 11:36:11 +00:00
|
|
|
|
|
|
|
|
|
|
### Trademarks
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
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.
|
2025-03-25 11:36:11 +00:00
|
|
|
|
|
|
|
|
|
|
### Company Information
|
|
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany
|
2025-03-25 11:36:11 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
For any legal inquiries or if you require further information, please contact us via email at
|
|
|
|
|
|
hello@task.vc.
|
2025-03-25 11:36:11 +00:00
|
|
|
|
|
2025-10-23 12:57:58 +00:00
|
|
|
|
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.
|