969 lines
27 KiB
Markdown
969 lines
27 KiB
Markdown
# ⚡ 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.
|
||
|
||
**Version 5.0+** is powered by Deno and distributed as single pre-compiled binaries—no installation,
|
||
no setup, just run.
|
||
|
||
## ✨ Features
|
||
|
||
- **🔌 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
|
||
- **🌐 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
|
||
- **🌐 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
|
||
|
||
### One-Line Installation
|
||
|
||
```bash
|
||
# Download and install NUPST automatically
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
||
```
|
||
|
||
### Initial Setup
|
||
|
||
```bash
|
||
# 1. Add your first UPS device
|
||
sudo nupst ups add
|
||
|
||
# 2. Test the connection
|
||
nupst ups test
|
||
|
||
# 3. Enable and start monitoring
|
||
sudo nupst service enable
|
||
sudo nupst service start
|
||
|
||
# 4. Check status
|
||
nupst service status
|
||
```
|
||
|
||
**That's it!** Your system is now protected. 🛡️
|
||
|
||
## 📥 Installation
|
||
|
||
### Via npm (NEW! - Recommended)
|
||
|
||
Install NUPST globally using npm:
|
||
|
||
```bash
|
||
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.
|
||
|
||
### Automated Installer Script
|
||
|
||
The installer script handles everything automatically:
|
||
|
||
```bash
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
||
```
|
||
|
||
**What it does:**
|
||
|
||
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
|
||
|
||
```bash
|
||
# Install specific version
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | \
|
||
sudo bash -s -- --version v5.0.0
|
||
|
||
# Custom installation directory
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | \
|
||
sudo bash -s -- --install-dir /usr/local/nupst
|
||
|
||
# Show help
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | bash -s -- --help
|
||
```
|
||
|
||
### Manual Installation
|
||
|
||
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` |
|
||
|
||
```bash
|
||
# Download binary (replace with your platform)
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v5.0.0/nupst-linux-x64 -o nupst
|
||
|
||
# Make executable
|
||
chmod +x nupst
|
||
|
||
# Move to system path
|
||
sudo mv nupst /usr/local/bin/nupst
|
||
```
|
||
|
||
### Verify Installation
|
||
|
||
```bash
|
||
# Check version
|
||
nupst --version
|
||
|
||
# View help
|
||
nupst help
|
||
```
|
||
|
||
## 📖 Usage
|
||
|
||
### Command Structure
|
||
|
||
NUPST uses an intuitive subcommand structure:
|
||
|
||
```
|
||
nupst <command> <subcommand> [options]
|
||
```
|
||
|
||
### Service Management
|
||
|
||
```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
|
||
```
|
||
|
||
### UPS Device Management
|
||
|
||
```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
|
||
```
|
||
|
||
### Group Management
|
||
|
||
```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
|
||
```
|
||
|
||
### Action Management 🆕
|
||
|
||
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
|
||
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
|
||
|
||
# List actions for specific UPS/group
|
||
nupst action list <ups-id|group-id>
|
||
```
|
||
|
||
**Example: Adding an action**
|
||
|
||
```bash
|
||
$ sudo nupst action add ups-main
|
||
|
||
Add Action to UPS Main Server UPS
|
||
|
||
Action type: shutdown
|
||
Battery threshold (%): 20
|
||
Runtime threshold (minutes): 10
|
||
|
||
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
|
||
|
||
Shutdown delay (seconds) [5]: 10
|
||
|
||
✓ Action added 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
|
||
nupst config show # Display current configuration
|
||
```
|
||
|
||
### Global Options
|
||
|
||
```bash
|
||
--version, -v # Show version information
|
||
--help, -h # Show help message
|
||
--debug, -d # Enable debug mode (detailed SNMP logging)
|
||
```
|
||
|
||
## ⚙️ 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.
|
||
|
||
### Example Configuration (v4.1+)
|
||
|
||
```json
|
||
{
|
||
"version": "4.2",
|
||
"checkInterval": 30000,
|
||
"httpServer": {
|
||
"enabled": true,
|
||
"port": 8080,
|
||
"path": "/ups-status",
|
||
"authToken": "abc123xyz789def456"
|
||
},
|
||
"upsDevices": [
|
||
{
|
||
"id": "ups-main",
|
||
"name": "Main Server UPS",
|
||
"snmp": {
|
||
"host": "192.168.1.100",
|
||
"port": 161,
|
||
"community": "public",
|
||
"version": 1,
|
||
"timeout": 5000,
|
||
"upsModel": "cyberpower"
|
||
},
|
||
"actions": [
|
||
{
|
||
"type": "shutdown",
|
||
"thresholds": {
|
||
"battery": 20,
|
||
"runtime": 10
|
||
},
|
||
"triggerMode": "onlyThresholds",
|
||
"shutdownDelay": 10
|
||
}
|
||
],
|
||
"groups": ["datacenter"]
|
||
},
|
||
{
|
||
"id": "ups-backup",
|
||
"name": "Backup UPS",
|
||
"snmp": {
|
||
"host": "192.168.1.101",
|
||
"port": 161,
|
||
"community": "public",
|
||
"version": 1,
|
||
"timeout": 5000,
|
||
"upsModel": "apc"
|
||
},
|
||
"actions": [
|
||
{
|
||
"type": "shutdown",
|
||
"thresholds": {
|
||
"battery": 15,
|
||
"runtime": 5
|
||
},
|
||
"triggerMode": "onlyThresholds",
|
||
"shutdownDelay": 5
|
||
}
|
||
],
|
||
"groups": ["datacenter"]
|
||
}
|
||
],
|
||
"groups": [
|
||
{
|
||
"id": "datacenter",
|
||
"name": "Data Center",
|
||
"mode": "redundant",
|
||
"description": "Redundant UPS setup - only shutdown when both are critical",
|
||
"actions": [
|
||
{
|
||
"type": "shutdown",
|
||
"thresholds": {
|
||
"battery": 10,
|
||
"runtime": 5
|
||
},
|
||
"triggerMode": "onlyThresholds",
|
||
"shutdownDelay": 15
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Configuration Fields
|
||
|
||
#### Global Settings
|
||
|
||
- **`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
|
||
|
||
- **`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)
|
||
|
||
**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" |
|
||
|
||
**SNMPv3 Security:**
|
||
|
||
| 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 |
|
||
|
||
#### Action Configuration
|
||
|
||
Actions define automated responses to UPS conditions:
|
||
|
||
```json
|
||
{
|
||
"type": "shutdown",
|
||
"thresholds": {
|
||
"battery": 20,
|
||
"runtime": 10
|
||
},
|
||
"triggerMode": "onlyThresholds",
|
||
"shutdownDelay": 10
|
||
}
|
||
```
|
||
|
||
**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 |
|
||
|
||
**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 |
|
||
|
||
#### Group Settings
|
||
|
||
Groups allow coordinated management of multiple UPS devices:
|
||
|
||
```json
|
||
{
|
||
"id": "datacenter",
|
||
"name": "Data Center",
|
||
"mode": "redundant",
|
||
"description": "Production servers with backup power",
|
||
"actions": [...]
|
||
}
|
||
```
|
||
|
||
**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.
|
||
|
||
#### 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
|
||
|
||
NUPST includes built-in OID mappings for:
|
||
|
||
- **CyberPower** (`cyberpower`)
|
||
- **APC** (`apc`)
|
||
- **Eaton** (`eaton`)
|
||
- **TrippLite** (`tripplite`)
|
||
- **Liebert/Vertiv** (`liebert`)
|
||
- **Custom OIDs** (`custom`)
|
||
|
||
For custom UPS models, specify `customOIDs`:
|
||
|
||
```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"
|
||
}
|
||
```
|
||
|
||
## 🖥️ Monitoring
|
||
|
||
### Status Display
|
||
|
||
The status command shows comprehensive information about your UPS devices, groups, and configured
|
||
actions:
|
||
|
||
```bash
|
||
$ 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)
|
||
```
|
||
|
||
### Live Logs
|
||
|
||
Monitor NUPST in real-time:
|
||
|
||
```bash
|
||
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)
|
||
[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)
|
||
```
|
||
|
||
## 🔒 Security
|
||
|
||
NUPST is designed with security as a priority:
|
||
|
||
### Architecture Security
|
||
|
||
- **Single Binary**: Self-contained executable with zero runtime dependencies
|
||
- **No Installation Required**: Pre-compiled binaries run immediately without package managers
|
||
- **Minimal Attack Surface**: Compiled Deno binary with only essential SNMP functionality
|
||
- **Reduced Supply Chain Risk**: Pre-compiled binaries with SHA256 checksums
|
||
- **Isolated Execution**: Runs with minimal required privileges
|
||
|
||
### SNMP Security
|
||
|
||
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) |
|
||
|
||
**Example SNMPv3 Configuration:**
|
||
|
||
```json
|
||
{
|
||
"version": 3,
|
||
"securityLevel": "authPriv",
|
||
"username": "nupst_monitor",
|
||
"authProtocol": "SHA",
|
||
"authKey": "your-auth-password",
|
||
"privProtocol": "AES",
|
||
"privKey": "your-encryption-password"
|
||
}
|
||
```
|
||
|
||
### Network Security
|
||
|
||
- **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
|
||
|
||
All releases include SHA256 checksums:
|
||
|
||
```bash
|
||
# Download binary and checksums
|
||
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
|
||
|
||
# Verify checksum
|
||
sha256sum -c SHA256SUMS.txt --ignore-missing
|
||
```
|
||
|
||
## 🔄 Updating NUPST
|
||
|
||
### Automatic Update
|
||
|
||
Re-run the installer to update to the latest version:
|
||
|
||
```bash
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash
|
||
```
|
||
|
||
The installer will:
|
||
|
||
- Download the latest binary
|
||
- Replace the existing installation
|
||
- Preserve your configuration
|
||
- Restart the service if it was running
|
||
|
||
### Manual Update
|
||
|
||
```bash
|
||
# Stop service
|
||
sudo nupst service stop
|
||
|
||
# Download and install new binary
|
||
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v5.0.0/nupst-linux-x64 -o nupst
|
||
sudo mv nupst /opt/nupst/nupst
|
||
sudo chmod +x /opt/nupst/nupst
|
||
|
||
# Start service
|
||
sudo nupst service start
|
||
```
|
||
|
||
### Check for Updates
|
||
|
||
```bash
|
||
nupst --version
|
||
```
|
||
|
||
Visit the [releases page](https://code.foss.global/serve.zone/nupst/releases) for the latest
|
||
version.
|
||
|
||
## 🗑️ Uninstallation
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
## 🔧 Troubleshooting
|
||
|
||
### Binary Won't Execute
|
||
|
||
```bash
|
||
# Make executable
|
||
chmod +x /opt/nupst/nupst
|
||
|
||
# Check architecture
|
||
uname -m # Should match binary (x86_64 = x64, aarch64 = arm64)
|
||
```
|
||
|
||
### Service Won't Start
|
||
|
||
```bash
|
||
# Check service status
|
||
sudo systemctl status nupst
|
||
|
||
# View detailed logs
|
||
sudo journalctl -u nupst -n 50
|
||
|
||
# Verify configuration
|
||
nupst config show
|
||
|
||
# Test SNMP connectivity
|
||
nupst ups test --debug
|
||
```
|
||
|
||
### Can't Connect to UPS
|
||
|
||
```bash
|
||
# Test with debug output
|
||
nupst ups test --debug
|
||
|
||
# Check network connectivity
|
||
ping <ups-ip-address>
|
||
|
||
# Verify SNMP port
|
||
nc -zv <ups-ip-address> 161
|
||
|
||
# Check SNMP settings on UPS
|
||
# - Ensure SNMP is enabled
|
||
# - Verify community string matches
|
||
# - Check IP access restrictions
|
||
```
|
||
|
||
### Permission Denied Errors
|
||
|
||
Most system operations require root:
|
||
|
||
```bash
|
||
# Service management
|
||
sudo nupst service enable
|
||
sudo nupst service start
|
||
|
||
# Configuration changes
|
||
sudo nupst ups add
|
||
sudo nupst action add ups-main
|
||
```
|
||
|
||
### Action Not Triggering
|
||
|
||
```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
|
||
|
||
| 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
|
||
|
||
- Creates `nupst.service` systemd unit (when enabled)
|
||
- Runs with root permissions (required for system shutdown)
|
||
|
||
### Network
|
||
|
||
- Outbound SNMP to UPS devices (default port 161)
|
||
- Optional inbound HTTP server (disabled by default, configurable port)
|
||
- 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:**
|
||
|
||
- 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
|
||
|
||
| 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",
|
||
"upsDevices": [{
|
||
"id": "ups-1",
|
||
"thresholds": { "battery": 60, "runtime": 20 }
|
||
}]
|
||
}
|
||
```
|
||
|
||
**v4.1 format** (action-based thresholds):
|
||
|
||
```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
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone https://code.foss.global/serve.zone/nupst.git
|
||
cd nupst
|
||
|
||
# Run directly
|
||
deno run --allow-all mod.ts help
|
||
|
||
# Run tests
|
||
deno test --allow-all test/
|
||
|
||
# Type check
|
||
deno check ts/cli.ts
|
||
|
||
# Compile for current platform
|
||
deno compile --allow-all --output nupst mod.ts
|
||
|
||
# Compile for all platforms
|
||
deno task compile
|
||
```
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
## 📞 Support
|
||
|
||
- **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)
|
||
|
||
## 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.
|
||
|
||
**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.
|
||
|
||
### Company Information
|
||
|
||
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.
|
||
|
||
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.
|