initial
This commit is contained in:
146
readme.md
Normal file
146
readme.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# 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
|
||||
- Automatic shutdown when battery level falls below threshold
|
||||
- Automatic shutdown when runtime remaining falls below threshold
|
||||
- Simple systemd service integration
|
||||
- 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
|
||||
```
|
||||
|
||||
### 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 2: Manual setup
|
||||
./setup.sh
|
||||
sudo ln -s $(pwd)/bin/nupst /usr/local/bin/nupst
|
||||
```
|
||||
|
||||
### From NPM
|
||||
|
||||
```bash
|
||||
npm install -g @serve.zone/nupst
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
|
||||
```bash
|
||||
# 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
|
||||
- Remove the symlink from /usr/local/bin
|
||||
- Optionally remove configuration files from /etc/nupst
|
||||
|
||||
## 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
|
||||
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 help - Show this help message
|
||||
```
|
||||
|
||||
## 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": "127.0.0.1",
|
||||
"port": 161,
|
||||
"community": "public",
|
||||
"version": 1,
|
||||
"timeout": 5000
|
||||
},
|
||||
"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)
|
||||
- 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
|
||||
- `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
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
Reference in New Issue
Block a user