Files
nupst/readme.md
Juergen Kunz 071ded9c41
All checks were successful
CI / Build All Platforms (Tag/Main only) (push) Has been skipped
CI / Type Check & Lint (push) Successful in 6s
CI / Build Test (Current Platform) (push) Successful in 6s
style: configure deno fmt to use single quotes
- Add singleQuote: true to deno.json fmt configuration
- Reformat all files with single quotes using deno fmt
2025-10-19 13:14:18 +00:00

667 lines
19 KiB
Markdown

# 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.
**Version 4.0+** is powered by Deno and distributed as pre-compiled binaries requiring zero
dependencies.
## 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
## Installation
### Quick Install (Recommended)
The easiest way to install NUPST is using the automated installer:
```bash
# Download and run installer (most reliable)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh -o nupst-install.sh
sudo bash nupst-install.sh
rm nupst-install.sh
```
```bash
# One-line installation (non-interactive with auto-confirm)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
```
The installer will:
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
### Manual Installation
Download the appropriate binary for your platform from the
[releases page](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:
```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
# Make executable
chmod +x nupst
# Move to system path
sudo mv nupst /usr/local/bin/nupst
```
### Installation Options
The installer script (`install.sh`) supports the following options:
```
-y, --yes Automatically answer yes to all prompts
-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:
```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
# 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
```
## System Changes
When installed, NUPST makes the following changes to your system:
### File System Changes
| 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) |
### 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
```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
```
## 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 <command> [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 <id> - 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 <id> - Edit a UPS group
nupst group remove <id> - 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 <id> - 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:
```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 <group-id>
```
### Configuration File Structure
Here's an example configuration with multiple UPS devices in a redundant group:
```json
{
"checkInterval": 30000,
"upsDevices": [
{
"id": "ups-1",
"name": "Server Room UPS",
"snmp": {
"host": "192.168.1.100",
"port": 161,
"community": "public",
"version": 1,
"timeout": 5000,
"upsModel": "cyberpower"
},
"thresholds": {
"battery": 60,
"runtime": 20
},
"groups": ["datacenter"]
},
{
"id": "ups-2",
"name": "Network Rack UPS",
"snmp": {
"host": "192.168.1.101",
"port": 161,
"community": "public",
"version": 1,
"timeout": 5000,
"upsModel": "apc"
},
"thresholds": {
"battery": 50,
"runtime": 15
},
"groups": ["datacenter"]
}
],
"groups": [
{
"id": "datacenter",
"name": "Data Center",
"mode": "redundant",
"description": "Main data center UPS group with redundant power"
}
]
}
```
### Configuration Fields
#### Global Settings
- `checkInterval`: How often to check UPS status 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
**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')
**For SNMPv1/v2c:**
- `community`: SNMP community string (default: "public")
**For SNMPv3:**
- `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
**For Custom UPS Models:**
- `customOIDs`: Custom OID mappings
- `POWER_STATUS`: OID for AC power status
- `BATTERY_CAPACITY`: OID for battery percentage
- `BATTERY_RUNTIME`: OID for runtime remaining (minutes)
**Shutdown Thresholds:**
- `battery`: Battery percentage threshold (default: 60%)
- `runtime`: Runtime minutes threshold (default: 20 minutes)
#### Group Settings
- `id`: Unique identifier for the group
- `name`: Friendly name for the group
- `mode`: Operating mode ('redundant' or 'nonRedundant')
- `description`: Optional description
### 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
```
## 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 -s -- -y
```
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
### 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
```
### Version Checking
Check your current version:
```bash
nupst --version
```
## Security
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:
```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 -s -- -y
# 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 ~340MB 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 <id>` | `nupst ups remove <id>` | 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 <id>` (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
sudo nupst service disable
sudo nupst service enable
sudo nupst service start
```
**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
### Binary Won't Execute
```bash
# Make sure it's executable
chmod +x /opt/nupst/nupst
# Check architecture matches your system
uname -m # Should match binary (x86_64 = x64, aarch64 = arm64)
```
### Service Won't Start
```bash
# Check service status
sudo systemctl status nupst
# Check logs for errors
sudo journalctl -u nupst -n 50
# Verify configuration
nupst config show
```
### Can't Connect to UPS
```bash
# Test SNMP connectivity
nupst ups test --debug
# Check network connectivity
ping <ups-ip-address>
# Verify SNMP port is accessible
nc -zv <ups-ip-address> 161
```
### Permission Denied Errors
Most operations that modify the system require root:
```bash
# Service management
sudo nupst service enable
sudo nupst service start
# Configuration changes
sudo nupst ups add
sudo nupst group add
```
## 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 with Deno
deno run --allow-all mod.ts help
# Compile for current platform
deno compile --allow-all --output nupst mod.ts
# Compile for all platforms
bash scripts/compile-all.sh
```
### Running Tests
```bash
deno test --allow-all tests/
```
### Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## 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 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.