BREAKING CHANGE(core): Add multi-UPS support and group management; update CLI, configuration and documentation to support multiple UPS devices with group modes

This commit is contained in:
2025-03-28 16:19:43 +00:00
parent bd3042de25
commit 0e55f22dad
10 changed files with 2381 additions and 780 deletions

162
readme.md
View File

@@ -4,6 +4,10 @@ NUPST is a command-line tool that monitors SNMP-enabled UPS devices and initiate
## 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
@@ -124,8 +128,22 @@ Usage:
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
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)
@@ -138,62 +156,114 @@ Options:
## Configuration
NUPST provides an interactive setup to configure your UPS:
NUPST supports monitoring multiple UPS devices organized into groups. You can set up your UPS devices using the interactive commands:
```bash
nupst setup
# Add a new UPS device
nupst add
# Create a new group
nupst group add
# Assign UPS devices to groups
nupst group edit <group-id>
```
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
### Configuration File Structure
Alternatively, you can manually edit the configuration file at `/etc/nupst/config.json`. A default configuration will be created on first run:
The configuration file is located at `/etc/nupst/config.json`. Here's an example of a multi-UPS configuration:
```json
{
"snmp": {
"host": "192.168.1.100",
"port": 161,
"community": "public",
"version": 1,
"timeout": 5000,
"upsModel": "cyberpower"
},
"thresholds": {
"battery": 60,
"runtime": 20
},
"checkInterval": 30000
"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"
}
]
}
```
- `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)
### 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