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:

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

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:

• 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

1. Install NUPST (see Installation section above)

2. Add your first UPS device:

   sudo nupst ups add
   

   Follow the interactive prompts to configure your UPS.

3. Test the configuration:

   nupst ups test
   

4. Enable the service:

   sudo nupst service enable
   sudo nupst service start
   

5. Check status:

   nupst service status
   

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

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

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

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.