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. Distributed as self-contained binaries with zero runtime dependencies for maximum reliability.

**Version 4.3+** is powered by Deno and distributed as single pre-compiled binaries—no installation, no setup, just run.

## ✨ 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
- **📦 Self-Contained Binary**: Single executable with zero runtime dependencies—just download and run
- **🖥️ Cross-Platform**: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon), and Windows

## 🚀 Quick Start

### One-Line Installation

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

### Initial Setup

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

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

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

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

```bash
# Check version
nupst --version

# View help
nupst help
```

## 📖 Usage

### Command Structure

NUPST uses an intuitive subcommand structure:

```
nupst <command> <subcommand> [options]
```

### Service Management

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

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

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

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

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

```bash
nupst config show         # Display current configuration
```

### Global Options

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

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

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

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

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

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

```bash
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 zero runtime dependencies
- **No Installation Required**: Pre-compiled binaries run immediately without package managers
- **Minimal Attack Surface**: Compiled Deno binary with only essential SNMP functionality
- **Reduced 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:**

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

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

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

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

```bash
nupst --version
```

Visit the [releases page](https://code.foss.global/serve.zone/nupst/releases) for the latest version.

## 🗑️ Uninstallation

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

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

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

### Service Won't Start

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

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

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

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

```bash
# 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 |
| **Distribution** | Git repo + npm install | Pre-compiled binaries |
| **Runtime Dependencies** | node_modules required | Zero (self-contained) |
| **Size** | ~150MB (with node_modules) | ~80MB (single binary) |
| **Startup** | Seconds | Milliseconds |
| **Commands** | Flat (`nupst add`) | Subcommands (`nupst ups add`) |
| **Configuration** | UPS-level thresholds | Action-based thresholds |

### Configuration Compatibility

Your v3.x configuration is **fully compatible**. The migration system automatically converts:

**v4.0 format** (UPS-level thresholds):
```json
{
  "version": "4.0",
  "upsDevices": [{
    "id": "ups-1",
    "thresholds": { "battery": 60, "runtime": 20 }
  }]
}
```

**v4.1 format** (action-based thresholds):
```json
{
  "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](https://deno.land/) v1.x or later

```bash
# 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](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 that is 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.