From eb5a8185aea0bd1c50d8abea20b90c646dac72a5 Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Mon, 20 Oct 2025 12:52:26 +0000 Subject: [PATCH] docs: create comprehensive readme with v4.3 features - Add action management documentation (new feature) - Update configuration examples to v4.1+ action-based format - Document trigger modes and action system - Update status command output examples with groups and actions - Remove outdated contributing section - Add modern emojis and engaging tone - Update all version references to v4.3.3 - Maintain Task Venture Capital GmbH legal section --- readme.md | 1032 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 587 insertions(+), 445 deletions(-) diff --git a/readme.md b/readme.md index dc9e1dc..b408958 100644 --- a/readme.md +++ b/readme.md @@ -1,61 +1,102 @@ -# NUPST - Network UPS Shutdown Tool +# ⚑ NUPST - Network UPS Shutdown Tool -NUPST is a lightweight, self-contained command-line tool that monitors SNMP-enabled UPS devices and -initiates system shutdown when power outages are detected and battery levels are low. +**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. Zero runtime dependencies, maximum reliability. -**Version 4.0+** is powered by Deno and distributed as pre-compiled binaries requiring zero -dependencies. +**Version 4.3+** is powered by Deno and distributed as single pre-compiled binariesβ€”no Node.js, no npm, no headaches. -## Features +## ✨ Features -- **Multi-UPS Support**: Monitor and manage multiple UPS devices from a single installation -- **Group Management**: Organize UPS devices into groups with different operating modes - - **Redundant Mode**: Only shutdown when ALL UPS devices in a group are in critical condition - - **Non-Redundant Mode**: Shutdown when ANY UPS device in a group is in critical condition -- **SNMP Protocol 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 and log viewing -- **Zero Dependencies**: Single self-contained binary with no runtime requirements -- **Cross-Platform**: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon), and - Windows +- **πŸ”Œ 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 +- **πŸ“¦ Zero Dependencies**: Single self-contained binary with no runtime requirements +- **πŸ–₯️ Cross-Platform**: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon), and Windows -## Installation +## πŸš€ Quick Start -### Quick Install (Recommended) - -The easiest way to install NUPST is using the automated installer: +### One-Line Installation ```bash -# One-line installation +# Download and install NUPST automatically curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash ``` -The installer will: +### Initial Setup -1. Auto-detect your platform (OS and architecture) -2. Download the latest pre-compiled binary from releases -3. Install to `/opt/nupst/nupst` -4. Create a symlink in `/usr/local/bin/nupst` for global access +```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 + +### Automated Installer (Recommended) + +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 v4.3.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 the -[releases page](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): -- **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` - -Then install manually: +| 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/v4.0.0/nupst-linux-x64 -o nupst +curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.3.3/nupst-linux-x64 -o nupst # Make executable chmod +x nupst @@ -64,175 +105,127 @@ chmod +x nupst sudo mv nupst /usr/local/bin/nupst ``` -### Installation Options - -The installer script (`install.sh`) supports the following options: - -``` --h, --help Show help message ---version VERSION Install specific version (e.g., --version v4.0.0) ---install-dir DIR Custom installation directory (default: /opt/nupst) -``` - -Examples: +### Verify Installation ```bash -# Install specific version -curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- --version v4.0.0 +# Check version +nupst --version -# 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 +# View help +nupst help ``` -## System Changes +## πŸ“– Usage -When installed, NUPST makes the following changes to your system: +### Command Structure -### File System Changes +NUPST uses an intuitive subcommand structure: -| Path | Description | -| ----------------------------------- | -------------------------------------- | -| `/opt/nupst/nupst` | Pre-compiled binary (default location) | -| `/etc/nupst/config.json` | Configuration file | -| `/usr/local/bin/nupst` | Symlink to the NUPST binary | -| `/etc/systemd/system/nupst.service` | Systemd service file (when enabled) | +``` +nupst [options] +``` -### Service Changes - -- Creates and enables a systemd service called `nupst.service` (when enabled with - `nupst service enable`) -- The service runs with root permissions to allow system shutdown capabilities - -### Network Access - -- NUPST only communicates with your UPS device via SNMP (default port 161) -- No external network connections required after installation - -## Uninstallation +### Service Management ```bash -# Disable and remove service first -sudo nupst service disable - -# Remove binary and config -sudo rm /usr/local/bin/nupst -sudo rm /opt/nupst/nupst -sudo rm -rf /etc/nupst/ - -# Or use the uninstall script if installed from git -sudo ./uninstall.sh +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 ``` -## Usage - -### Command Structure (v4.0+) - -NUPST v4.0 uses a subcommand structure for better organization: - -``` -NUPST - Network UPS Shutdown Tool -Version: 4.0.0 - -Usage: nupst [subcommand] [options] - -Service Management: - nupst service enable - Install and enable the systemd service - nupst service disable - Stop and disable the systemd service - nupst service start - Start the systemd service - nupst service stop - Stop the systemd service - nupst service restart - Restart the systemd service - nupst service status - Show service and UPS status - nupst service logs - Show service logs in real-time - nupst service start-daemon - Start daemon directly (for testing) - -UPS Management: - nupst ups add - Add a new UPS device - nupst ups edit [id] - Edit a UPS device (prompts if no ID) - nupst ups remove - Remove a UPS device by ID - nupst ups list - List all configured UPS devices - nupst ups test - Test UPS connections - -Group Management: - nupst group add - Add a new UPS group - nupst group edit - Edit a UPS group - nupst group remove - Remove a UPS group - nupst group list - List all UPS groups - -Configuration: - nupst config show - Display current configuration - -Global Options: - --version, -v - Show version information - --help, -h - Show help message - --debug, -d - Enable debug mode for detailed logging - -Aliases (for backward compatibility): - nupst ls - Alias for 'nupst ups list' - nupst rm - Alias for 'nupst ups remove' -``` - -### Quick Start Guide - -1. **Install NUPST** (see Installation section above) - -2. **Add your first UPS device:** - ```bash - sudo nupst ups add - ``` - Follow the interactive prompts to configure your UPS. - -3. **Test the configuration:** - ```bash - nupst ups test - ``` - -4. **Enable the service:** - ```bash - sudo nupst service enable - sudo nupst service start - ``` - -5. **Check status:** - ```bash - nupst service status - ``` - -6. **View logs:** - ```bash - nupst service logs - ``` - -## Configuration - -NUPST supports monitoring multiple UPS devices organized into groups. The configuration file is -located at `/etc/nupst/config.json`. - -### Interactive Configuration - -The easiest way to configure NUPST is through the interactive commands: +### UPS Device Management ```bash -# Add a new UPS device -sudo nupst ups add - -# Create a group -sudo nupst group add - -# Assign UPS devices to groups -sudo nupst group edit +nupst ups add # Add a new UPS device (interactive) +nupst ups edit [id] # Edit a UPS device +nupst ups remove # Remove a UPS device +nupst ups list # List all UPS devices +nupst ups test # Test UPS connections ``` -### Configuration File Structure +### Group Management -Here's an example configuration with multiple UPS devices in a redundant group: +```bash +nupst group add # Create a new UPS group +nupst group edit # Edit a group +nupst group remove # 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 + +# Remove an action by index +nupst action remove + +# List all actions +nupst action list + +# List actions for specific UPS/group +nupst action list +``` + +**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 +``` + +### 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.1", "checkInterval": 30000, "upsDevices": [ { - "id": "ups-1", - "name": "Server Room UPS", + "id": "ups-main", + "name": "Main Server UPS", "snmp": { "host": "192.168.1.100", "port": 161, @@ -241,15 +234,22 @@ Here's an example configuration with multiple UPS devices in a redundant group: "timeout": 5000, "upsModel": "cyberpower" }, - "thresholds": { - "battery": 60, - "runtime": 20 - }, + "actions": [ + { + "type": "shutdown", + "thresholds": { + "battery": 20, + "runtime": 10 + }, + "triggerMode": "onlyThresholds", + "shutdownDelay": 10 + } + ], "groups": ["datacenter"] }, { - "id": "ups-2", - "name": "Network Rack UPS", + "id": "ups-backup", + "name": "Backup UPS", "snmp": { "host": "192.168.1.101", "port": 161, @@ -258,10 +258,17 @@ Here's an example configuration with multiple UPS devices in a redundant group: "timeout": 5000, "upsModel": "apc" }, - "thresholds": { - "battery": 50, - "runtime": 15 - }, + "actions": [ + { + "type": "shutdown", + "thresholds": { + "battery": 15, + "runtime": 5 + }, + "triggerMode": "onlyThresholds", + "shutdownDelay": 5 + } + ], "groups": ["datacenter"] } ], @@ -270,7 +277,18 @@ Here's an example configuration with multiple UPS devices in a redundant group: "id": "datacenter", "name": "Data Center", "mode": "redundant", - "description": "Main data center UPS group with redundant power" + "description": "Redundant UPS setup - only shutdown when both are critical", + "actions": [ + { + "type": "shutdown", + "thresholds": { + "battery": 10, + "runtime": 5 + }, + "triggerMode": "onlyThresholds", + "shutdownDelay": 15 + } + ] } ] } @@ -280,85 +298,212 @@ Here's an example configuration with multiple UPS devices in a redundant group: #### Global Settings -- `checkInterval`: How often to check UPS status in milliseconds (default: 30000) +- **`version`**: Config format version (current: "4.1") +- **`checkInterval`**: Polling interval in milliseconds (default: 30000) #### UPS Device Settings -- `id`: Unique identifier for the UPS -- `name`: Friendly name for the UPS -- `groups`: Array of group IDs this UPS belongs to +- **`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:** -- `host`: IP address or hostname of your UPS -- `port`: SNMP port (default: 161) -- `version`: SNMP version (1, 2, or 3) -- `timeout`: Timeout in milliseconds (default: 5000) -- `upsModel`: UPS brand ('cyberpower', 'apc', 'eaton', 'tripplite', 'liebert', or 'custom') +| 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" | -**For SNMPv1/v2c:** +**SNMPv3 Security:** -- `community`: SNMP community string (default: "public") +| 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 | -**For SNMPv3:** +#### Action Configuration -- `securityLevel`: 'noAuthNoPriv', 'authNoPriv', or 'authPriv' -- `username`: SNMPv3 username -- `authProtocol`: 'MD5' or 'SHA' -- `authKey`: Authentication password -- `privProtocol`: 'DES' or 'AES' (for authPriv level) -- `privKey`: Privacy/encryption password +Actions define automated responses to UPS conditions: -**For Custom UPS Models:** +```json +{ + "type": "shutdown", + "thresholds": { + "battery": 20, + "runtime": 10 + }, + "triggerMode": "onlyThresholds", + "shutdownDelay": 10 +} +``` -- `customOIDs`: Custom OID mappings - - `POWER_STATUS`: OID for AC power status - - `BATTERY_CAPACITY`: OID for battery percentage - - `BATTERY_RUNTIME`: OID for runtime remaining (minutes) +**Action Fields:** -**Shutdown Thresholds:** +| 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 | -- `battery`: Battery percentage threshold (default: 60%) -- `runtime`: Runtime minutes threshold (default: 20 minutes) +**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 -- `id`: Unique identifier for the group -- `name`: Friendly name for the group -- `mode`: Operating mode ('redundant' or 'nonRedundant') -- `description`: Optional description +Groups allow coordinated management of multiple UPS devices: -### Group Modes - -- **Redundant Mode**: System shuts down only when ALL UPS devices in the group are critical. Ideal - for setups with backup UPS units where one can maintain power. - -- **Non-Redundant Mode**: System shuts down when ANY UPS device in the group is critical. Used when - all UPS devices must be operational for system stability. - -## Setup as a Service - -Enable NUPST as a systemd service for automatic monitoring: - -```bash -# Enable and start service -sudo nupst service enable -sudo nupst service start - -# Check status -nupst service status - -# View real-time logs -nupst service logs - -# Stop service -sudo nupst service stop - -# Disable service -sudo nupst service disable +```json +{ + "id": "datacenter", + "name": "Data Center", + "mode": "redundant", + "description": "Production servers with backup power", + "actions": [...] +} ``` -## Updating NUPST +**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. + +### 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 no external dependencies +- **No Runtime Dependencies**: Zero npm packages, zero Node.js modules +- **Minimal Attack Surface**: Compiled Deno binary with only essential SNMP functionality +- **No 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 + +### Verifying Downloads + +All releases include SHA256 checksums: + +```bash +# Download binary and checksums +curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.3.3/nupst-linux-x64 -o nupst +curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.3.3/SHA256SUMS.txt -o SHA256SUMS.txt + +# Verify checksum +sha256sum -c SHA256SUMS.txt --ignore-missing +``` + +## πŸ”„ Updating NUPST ### Automatic Update @@ -369,179 +514,59 @@ curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | ``` The installer will: - -1. Download the latest binary -2. Replace the existing installation -3. Preserve your configuration at `/etc/nupst/config.json` -4. Restart the service if it was running +- Download the latest binary +- Replace the existing installation +- Preserve your configuration +- Restart the service if it was running ### Manual Update -1. Download the latest binary from [releases](https://code.foss.global/serve.zone/nupst/releases) -2. Replace the existing binary: - ```bash - sudo nupst service stop - sudo mv nupst-linux-x64 /opt/nupst/nupst # adjust for your platform - sudo chmod +x /opt/nupst/nupst - sudo nupst service start - ``` +```bash +# Stop service +sudo nupst service stop -### Version Checking +# Download and install new binary +curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.3.3/nupst-linux-x64 -o nupst +sudo mv nupst /opt/nupst/nupst +sudo chmod +x /opt/nupst/nupst -Check your current version: +# Start service +sudo nupst service start +``` + +### Check for Updates ```bash nupst --version ``` -## Security +Visit the [releases page](https://code.foss.global/serve.zone/nupst/releases) for the latest version. -NUPST is designed with security as a priority: - -### Architecture Security - -- **Single Binary**: Self-contained executable with no external dependencies -- **No Runtime Dependencies**: Unlike v3.x (Node.js), v4.0+ requires no runtime environment -- **Minimal Attack Surface**: Compiled Deno binary with only essential SNMP functionality -- **No Supply Chain Risk**: Pre-compiled binaries verified with SHA256 checksums -- **Isolated Execution**: Runs with minimal required privileges - -### SNMP Security - -- **SNMPv3 Support**: Full authentication and encryption support - - `noAuthNoPriv`: Basic access (no security) - - `authNoPriv`: Authentication without encryption - - `authPriv`: Full authentication and encryption (recommended) -- **Authentication**: MD5 or SHA protocols -- **Encryption**: DES or AES privacy protocols -- **Secure Defaults**: Automatic timeout adjustment based on security level - -### Installation Security - -- **Checksum Verification**: SHA256SUMS.txt provided for all releases -- **Transparent Installation**: Standard locations with clear documentation -- **Minimal Permissions**: Only systemd operations require root access -- **Source Available**: Full source code available for audit - -### Network Security - -- **Local-Only Communication**: Only connects to UPS devices on local network -- **No Telemetry**: No data sent to external servers -- **No Update Checks**: Manual update process only - -### Verifying Downloads - -All releases include SHA256 checksums: +## πŸ—‘οΈ Uninstallation ```bash -# Download binary and checksums -curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/nupst-linux-x64 -o nupst -curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/SHA256SUMS.txt -o SHA256SUMS.txt - -# Verify checksum -sha256sum -c SHA256SUMS.txt --ignore-missing -``` - -## Migration from v3.x - -If you're upgrading from NUPST v3.x (Node.js-based) to v4.0 (Deno-based), the migration is -straightforward using the install.sh script. - -### Quick Migration - -The installer script automatically handles the entire migration while preserving your configuration: - -```bash -# Run the installer (handles stop/update/restart automatically) -curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash - -# Verify -nupst service status -``` - -**That's it!** The installer automatically: - -- Detects your v3.x installation -- Stops the running service -- Replaces the binary with v4.0 -- Restarts the service -- Preserves your `/etc/nupst/config.json` (fully compatible, no changes needed) - -### Key Changes in v4.0 - -- **Runtime**: Node.js β†’ Deno -- **Distribution**: Git repository + npm packages β†’ Pre-compiled binaries -- **Installation**: Clone + setup.sh β†’ Download binary via install.sh -- **Dependencies**: Node.js + npm packages β†’ Zero dependencies (self-contained binary) -- **CLI Structure**: Flat commands β†’ Subcommand structure (backward compatible) -- **Updates**: `nupst update` β†’ Re-run install.sh -- **Footprint**: Single ~80MB self-contained binary (vs repo + node_modules in v3.x) -- **Startup**: Seconds β†’ Milliseconds - -### Command Mapping - -v4.0 uses a new subcommand structure, but **old commands still work** with deprecation warnings: - -| v3.x Command | v4.0 Command | Notes | -| ------------------- | ----------------------- | ---------------------- | -| `nupst enable` | `nupst service enable` | Old works with warning | -| `nupst disable` | `nupst service disable` | Old works with warning | -| `nupst start` | `nupst service start` | Old works with warning | -| `nupst stop` | `nupst service stop` | Old works with warning | -| `nupst status` | `nupst service status` | Old works with warning | -| `nupst logs` | `nupst service logs` | Old works with warning | -| `nupst add` | `nupst ups add` | Old works with warning | -| `nupst edit [id]` | `nupst ups edit [id]` | Old works with warning | -| `nupst delete ` | `nupst ups remove ` | Old works with warning | -| `nupst list` | `nupst ups list` | Old works with warning | -| `nupst test` | `nupst ups test` | Old works with warning | -| `nupst config` | `nupst config show` | Old works with warning | - -**New aliases:** `nupst ls` (list UPS devices), `nupst rm ` (remove UPS device) - -### Configuration Compatibility - -βœ… **Fully Compatible:** - -- Configuration file format: `/etc/nupst/config.json` -- All SNMP settings (host, port, community, version, security) -- UPS device configurations (IDs, names, thresholds, groups) -- Group configurations (redundant/non-redundant modes) -- Supported UPS models (CyberPower, APC, Eaton, TrippLite, Liebert, custom OIDs) - -### Troubleshooting Migration - -**Service won't start after migration:** - -```bash -# Re-enable service to update systemd file +# Stop and disable service sudo nupst service disable -sudo nupst service enable -sudo nupst service start + +# 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 ``` -**Binary won't execute:** - -```bash -sudo chmod +x /opt/nupst/nupst -``` - -**Command not found:** - -```bash -# Recreate symlink -sudo ln -sf /opt/nupst/nupst /usr/local/bin/nupst -``` - -## Troubleshooting +## πŸ”§ Troubleshooting ### Binary Won't Execute ```bash -# Make sure it's executable +# Make executable chmod +x /opt/nupst/nupst -# Check architecture matches your system +# Check architecture uname -m # Should match binary (x86_64 = x64, aarch64 = arm64) ``` @@ -551,29 +576,37 @@ uname -m # Should match binary (x86_64 = x64, aarch64 = arm64) # Check service status sudo systemctl status nupst -# Check logs for errors +# 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 SNMP connectivity +# Test with debug output nupst ups test --debug # Check network connectivity ping -# Verify SNMP port is accessible +# Verify SNMP port nc -zv 161 + +# Check SNMP settings on UPS +# - Ensure SNMP is enabled +# - Verify community string matches +# - Check IP access restrictions ``` ### Permission Denied Errors -Most operations that modify the system require root: +Most system operations require root: ```bash # Service management @@ -582,48 +615,166 @@ sudo nupst service start # Configuration changes sudo nupst ups add -sudo nupst group add +sudo nupst action add ups-main ``` -## Development +### 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) +- No inbound connections required +- 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 (self-contained) | +| **Distribution** | Git repo + packages | Pre-compiled binaries | +| **Dependencies** | node_modules | Zero | +| **Size** | ~150MB (with deps) | ~80MB (single binary) | +| **Startup** | Seconds | Milliseconds | +| **Commands** | Flat (`nupst add`) | Subcommands (`nupst ups add`) | +| **Configuration** | UPS-level thresholds | Action-based thresholds | + +### Command Migration + +Old v3.x commands still work with deprecation warnings: + +| v3.x | v4.x | Still Works? | +|------|------|--------------| +| `nupst add` | `nupst ups add` | βœ“ (with warning) | +| `nupst list` | `nupst ups list` | βœ“ (with warning) | +| `nupst enable` | `nupst service enable` | βœ“ (with warning) | +| `nupst status` | `nupst service status` | βœ“ (with warning) | + +### 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 +**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 with Deno +# 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 -bash scripts/compile-all.sh +deno task compile ``` -### Running Tests +### Project Structure -```bash -deno test --allow-all tests/ +``` +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 ``` -### Contributing - -Contributions are welcome! Please: - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Submit a pull request - -## Support +## πŸ“ž 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) @@ -631,28 +782,19 @@ Contributions are welcome! Please: ## License and Legal Information -This repository contains open-source code 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.