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)

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

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

```bash
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

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

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

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

```bash
sudo nupst enable
sudo nupst start
```

To check the status:

```bash
nupst status
```

To view logs in real-time:

```bash
nupst logs
```

## Updating NUPST

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

```bash
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