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:

# One-line installation
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash

The installer will:

Auto-detect your platform (OS and architecture)
Download the latest pre-compiled binary from releases
Install to /opt/nupst/nupst
Create a symlink in /usr/local/bin/nupst for global access

Manual Installation

Download the appropriate binary for your platform from the releases page:

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:

# 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:

-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:

# 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

# 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

Install NUPST (see Installation section above)
Add your first UPS device:
```
sudo nupst ups add
```
Follow the interactive prompts to configure your UPS.
Test the configuration:
```
nupst ups test
```

Enable the service:

sudo nupst service enable
sudo nupst service start

Check status:
```
nupst service status
```
View logs:
```
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:

# 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:

{
  "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:

# 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:

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 at /etc/nupst/config.json
Restart the service if it was running

Manual Update

Download the latest binary from releases

Replace the existing binary:

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:

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:

# 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:

# 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 <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:

# Re-enable service to update systemd file
sudo nupst service disable
sudo nupst service enable
sudo nupst service start

Binary won't execute:

sudo chmod +x /opt/nupst/nupst

Command not found:

# Recreate symlink
sudo ln -sf /opt/nupst/nupst /usr/local/bin/nupst

Troubleshooting

Binary Won't Execute

# 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

# 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

# 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:

# 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 v1.x or later

# 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

deno test --allow-all tests/

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Support

Issues: Report bugs or request features
Documentation: Full documentation
Source Code: View source

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 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.

readme.md

NUPST - Network UPS Shutdown Tool