nupst/readme.md

NUPST - Node.js UPS Shutdown Tool

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

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

# Install directly without cloning the repository (requires root privileges)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash

# Install with auto-yes for dependencies (will install git automatically if needed)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y

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
  nupst setup          - Run the interactive setup to configure SNMP settings
  nupst test           - Test the current configuration by connecting to the UPS
  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 provides an interactive setup to configure your UPS:

nupst setup

This will guide you through setting up:

• UPS IP address and SNMP settings
• Shutdown thresholds for battery percentage and runtime
• Monitoring interval
• Test the connection to your UPS

Alternatively, you can manually edit the configuration file at /etc/nupst/config.json. A default configuration will be created on first run:

{
  "snmp": {
    "host": "192.168.1.100",
    "port": 161,
    "community": "public",
    "version": 1,
    "timeout": 5000,
    "upsModel": "cyberpower"
  },
  "thresholds": {
    "battery": 60,
    "runtime": 20
  },
  "checkInterval": 30000
}

• 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)
• checkInterval: How often to check UPS status in milliseconds (default: 30000)

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:

1. Pull the latest changes from the git repository
2. Run the installation scripts
3. Refresh the systemd service configuration
4. Restart the service if it was running

Security

NUPST was designed with security in mind:

Minimal Dependencies

• Zero Runtime NPM Dependencies: NUPST is built without any external NPM packages to minimize the attack surface and avoid supply chain risks.
• 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
  • Zero 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.
• Secure SNMPv3 Support: Supports encrypted authentication and privacy for secure communication with the UPS device.
• Isolated Execution: The application runs in its working directory (/opt/nupst) or specified installation location, minimizing the impact on the rest of the system.

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)

Audit and Review

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

License

MIT