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:
162
readme.md
162
readme.md
@@ -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
|
||||
|
||||
|
Reference in New Issue
Block a user