nupst/readme.md

⚡ 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. Zero runtime dependencies, maximum reliability.

Version 4.3+ is powered by Deno and distributed as single pre-compiled binaries—no Node.js, no npm, no headaches.

✨ 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
• 📦 Zero Dependencies: Single self-contained binary with no runtime requirements
• 🖥️ Cross-Platform: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon), and Windows

🚀 Quick Start

One-Line Installation

# Download and install NUPST automatically
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash

Initial Setup

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

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

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

# Download binary (replace with your platform)
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.3.3/nupst-linux-x64 -o nupst

# Make executable
chmod +x nupst

# Move to system path
sudo mv nupst /usr/local/bin/nupst

Verify Installation

# Check version
nupst --version

# View help
nupst help

📖 Usage

Command Structure

NUPST uses an intuitive subcommand structure:

nupst <command> <subcommand> [options]

Service Management

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

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

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.

# 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

$ 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

nupst config show         # Display current configuration

Global Options

--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+)

{
  "version": "4.1",
  "checkInterval": 30000,
  "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.1")
• checkInterval: Polling interval in milliseconds (default: 30000)

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:

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

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

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:

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

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

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:

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

# 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

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
• Restart the service if it was running

Manual Update

# Stop service
sudo nupst service stop

# 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

# Start service
sudo nupst service start

Check for Updates

nupst --version

Visit the releases page for the latest version.

🗑️ Uninstallation

# 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

# Make executable
chmod +x /opt/nupst/nupst

# Check architecture
uname -m  # Should match binary (x86_64 = x64, aarch64 = arm64)

Service Won't Start

# 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

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

# 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

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

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

{
  "version": "4.0",
  "upsDevices": [{
    "id": "ups-1",
    "thresholds": { "battery": 60, "runtime": 20 }
  }]
}

v4.1 format (action-based thresholds):

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

# 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
• Documentation: Full documentation
• Source Code: View source

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