NUPST is a command-line tool that monitors SNMP-enabled UPS devices and initiates system shutdown when power outages are detected and battery levels are low.

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
Monitors UPS devices using SNMP (v1, v2c, and v3 supported)
Automatic shutdown when battery level falls below threshold
Automatic shutdown when runtime remaining falls below threshold
Supports multiple UPS brands (CyberPower, APC, Eaton, TrippLite, Liebert/Vertiv)
Simple systemd service integration
Regular status logging for monitoring
Real-time log viewing with journalctl
Version checking and automatic updates
Self-contained - includes its own Node.js runtime

Installation

Quick Install (One-line command)

# Method 1: Download and run (most reliable across all environments)
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

# Method 2: Pipe with automatic yes for dependencies (non-interactive)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y

# Method 3: Process substitution (only on systems that support /dev/fd/)
# Note: This may fail on some systems with "No such file or directory" errors
sudo bash <(curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh)

Direct from Git

# Clone the repository
git clone https://code.foss.global/serve.zone/nupst.git
cd nupst

# Option 1: Quick install (requires root privileges)
sudo ./install.sh

# Option 1a: Quick install with auto-yes for dependencies
sudo ./install.sh -y

# Option 2: Manual setup
./setup.sh
sudo ln -s $(pwd)/bin/nupst /usr/local/bin/nupst

Installation Options

The installer script (install.sh) supports the following options:

-y, --yes     Automatically answer yes to all prompts (like installing git)
-h, --help    Show the help message

From NPM

npm install -g @serve.zone/nupst

System Changes

When installed, NUPST makes the following changes to your system:

File System Changes

Path	Description
`/opt/nupst/`	Main installation directory containing the NUPST files
`/etc/nupst/config.json`	Configuration file
`/usr/local/bin/nupst`	Symlink to the NUPST executable
`/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 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)
Brief connections to npmjs.org to check for updates

Uninstallation

# Using the CLI tool:
sudo nupst uninstall

# If installed from git repository:
cd /path/to/nupst
sudo ./uninstall.sh

# If installed from npm:
npm uninstall -g @serve.zone/nupst

The uninstaller will:

Stop and disable the systemd service (if installed)
Remove the systemd service file from /etc/systemd/system/nupst.service
Remove the symlink from /usr/local/bin/nupst
Optionally remove configuration files from /etc/nupst/
Remove the repository directory from /opt/nupst/ (when using nupst uninstall)

Usage

NUPST - Node.js UPS Shutdown Tool

Usage:
  nupst enable         - Install and enable the systemd service (requires root)
  nupst disable        - Stop and uninstall the systemd service (requires root)
  nupst daemon-start   - Start the daemon process directly
  nupst logs           - Show logs of the systemd service in real-time
  nupst stop           - Stop the systemd service
  nupst start          - Start the systemd service
  nupst status         - Show status of the systemd service and UPS status

UPS Management:
  nupst add            - Add a new UPS device
  nupst edit [id]      - Edit an existing UPS (default UPS if no ID provided)
  nupst delete <id>    - Delete a UPS by ID
  nupst list           - List all configured UPS devices
  nupst setup          - Alias for 'nupst edit' (backward compatibility)
  
Group Management:
  nupst group list     - List all UPS groups
  nupst group add      - Add a new UPS group
  nupst group edit <id> - Edit an existing UPS group
  nupst group delete <id> - Delete a UPS group
  
System Commands:
  nupst test           - Test the current configuration by connecting to all UPS devices
  nupst config         - Display the current configuration
  nupst update         - Update NUPST from repository and refresh systemd service (requires root)
  nupst uninstall      - Completely uninstall NUPST from the system (requires root)
  nupst help           - Show this help message

Options:
  --debug, -d         - Enable debug mode for detailed SNMP logging
                        (Example: nupst test --debug)

Configuration

NUPST supports monitoring multiple UPS devices organized into groups. You can set up your UPS devices using the interactive commands:

# Add a new UPS device
nupst add

# Create a new group
nupst group add

# Assign UPS devices to groups
nupst group edit <group-id>

Configuration File Structure

The configuration file is located at /etc/nupst/config.json. Here's an example of a multi-UPS configuration:

{
  "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"
    }
  ]
}

Configuration Fields

checkInterval: How often to check UPS status in milliseconds (default: 30000)
upsDevices: Array of UPS device configurations
- id: Unique identifier for the UPS
- name: Friendly name for the UPS
- snmp: SNMP connection settings
  - host: IP address of your UPS (default: 127.0.0.1)
  - port: SNMP port (default: 161)
  - version: SNMP version (1, 2, or 3)
  - timeout: Timeout in milliseconds (default: 5000)
  - upsModel: The UPS model ('cyberpower', 'apc', 'eaton', 'tripplite', 'liebert', or 'custom')
  - For SNMPv1/v2c:
    - community: SNMP community string (default: public)
  - For SNMPv3:
    - securityLevel: Security level ('noAuthNoPriv', 'authNoPriv', or 'authPriv')
    - username: SNMPv3 username
    - authProtocol: Authentication protocol ('MD5' or 'SHA')
    - authKey: Authentication password/key
    - privProtocol: Privacy/encryption protocol ('DES' or 'AES')
    - privKey: Privacy password/key
  - For custom UPS models:
    - customOIDs: Object containing custom OIDs for your UPS:
      - POWER_STATUS: OID for power status
      - BATTERY_CAPACITY: OID for battery capacity percentage
      - BATTERY_RUNTIME: OID for runtime remaining in minutes
- thresholds: When to trigger shutdown
  - battery: Battery percentage threshold (default: 60%)
  - runtime: Runtime minutes threshold (default: 20 minutes)
- groups: Array of group IDs this UPS belongs to
groups: Array of group configurations
- id: Unique identifier for the group
- name: Friendly name for the group
- mode: Group operating mode ('redundant' or 'nonRedundant')
- description: Optional description of the group

Group Modes

Redundant Mode: The system will only initiate shutdown if ALL UPS devices in the group are in critical condition (below threshold). This is ideal for redundant power setups where one UPS can keep systems running.
Non-Redundant Mode: The system will initiate shutdown if ANY UPS device in the group is in critical condition. This is useful for scenarios where all UPS devices must be operational for the system to function properly.

Setup as a Service

To set up NUPST as a systemd service:

sudo nupst enable
sudo nupst start

To check the status:

nupst status

To view logs in real-time:

nupst logs

Updating NUPST

NUPST checks for updates automatically and will notify you when an update is available. To update to the latest version:

sudo nupst update

This will:

Pull the latest changes from the git repository
Run the installation scripts
Force-update Node.js and all dependencies, even if they already exist
Refresh the systemd service configuration
Restart the service if it was running

You can also manually run the setup script with the force flag to update Node.js and dependencies without updating the application code:

# If you're in the nupst directory:
bash ./setup.sh --force

# If you're in another directory, specify the full path:
bash /opt/nupst/setup.sh --force

Security

NUPST was designed with security in mind:

Minimal Dependencies

Minimal Runtime Dependencies: NUPST uses only one carefully selected NPM package (net-snmp) to minimize the attack surface and avoid supply chain risks while providing robust SNMP functionality.
Self-contained Node.js: NUPST ships with its own Node.js binary, isolated from the system's Node.js installation. This ensures:
- No dependency on system Node.js versions
- Minimal external libraries that could become compromised
- Consistent, tested environment for execution
- Reduced risk of dependency-based attacks

Implementation Security

Privilege Separation: Only specific commands that require elevated permissions (enable, disable, update) check for root access; all other functionality runs with minimal privileges.
Limited Network Access: NUPST only communicates with the UPS device over SNMP and contacts npmjs.org only to check for updates.
Isolated Execution: The application runs in its working directory (/opt/nupst) or specified installation location, minimizing the impact on the rest of the system.

SNMP Security Features

SNMPv3 Support with Secure Authentication and Privacy:
- Three security levels available:
  - noAuthNoPriv: No authentication or encryption (basic access)
  - authNoPriv: Authentication without encryption (verifies identity)
  - authPriv: Full authentication and encryption (most secure)
- Authentication protocols: MD5 or SHA
- Privacy/encryption protocols: DES or AES
- Automatic fallback mechanisms for compatibility
- Context support for segmented SNMP deployments
- Configurable timeouts based on security level
Graceful degradation: If authentication or privacy details are missing or invalid, NUPST will automatically fall back to a lower security level while logging appropriate warnings.
Interactive setup: Guided setup process to properly configure SNMPv3 security settings with clear explanations of each security option.

Installation Security

The installation script can be reviewed before execution (curl -sSL [url] | less)
All setup scripts download only verified versions and check integrity
Installation is transparent and places files in standard locations (/opt/nupst, /usr/local/bin, /etc/systemd/system)
Automatically detects platform architecture and OS for proper binary selection
Installs production dependencies locally without requiring global npm packages

Audit and Review

The codebase is small, focused, and designed to be easily auditable. All code is open source and available for review.

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.

readme.md

NUPST - Node.js UPS Shutdown Tool