nupst/readme.md

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

```bash
# Download and run installer (most reliable)
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
```

```bash
# One-line installation (non-interactive with auto-confirm)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
```

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](https://code.foss.global/serve.zone/nupst/releases):

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

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

```
-y, --yes                Automatically answer yes to all prompts
-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:

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

```bash
# 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:**
   ```bash
   sudo nupst ups add
   ```
   Follow the interactive prompts to configure your UPS.

3. **Test the configuration:**
   ```bash
   nupst ups test
   ```

4. **Enable the service:**
   ```bash
   sudo nupst service enable
   sudo nupst service start
   ```

5. **Check status:**
   ```bash
   nupst service status
   ```

6. **View logs:**
   ```bash
   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:

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

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

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

```bash
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
```

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](https://code.foss.global/serve.zone/nupst/releases)
2. Replace the existing binary:
   ```bash
   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:

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

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

```bash
# Run the installer (handles stop/update/restart automatically)
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y

# 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 ~340MB 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:**
```bash
# Re-enable service to update systemd file
sudo nupst service disable
sudo nupst service enable
sudo nupst service start
```

**Binary won't execute:**
```bash
sudo chmod +x /opt/nupst/nupst
```

**Command not found:**
```bash
# Recreate symlink
sudo ln -sf /opt/nupst/nupst /usr/local/bin/nupst
```

## Troubleshooting

### Binary Won't Execute

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

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

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

```bash
# 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](https://deno.land/) v1.x or later

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

```bash
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](https://code.foss.global/serve.zone/nupst/issues)
- **Documentation**: [Full documentation](https://code.foss.global/serve.zone/nupst)
- **Source Code**: [View source](https://code.foss.global/serve.zone/nupst)

## 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](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.