diff --git a/changelog.md b/changelog.md index 446f38f..3496cff 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,13 @@ # Changelog +## 2025-03-25 - 1.10.1 - fix(systemd/readme) +Improve README documentation and fix UPS status retrieval in systemd service + +- Updated README features and installation instructions to clarify SNMP version support, UPS models, and configuration +- Modified default SNMP host to '192.168.1.100' and added 'upsModel' property in configuration examples +- Enhanced instructions for real-time log viewing and update process in README +- Fixed systemd.ts to use a test configuration with an appropriate timeout when fetching UPS status + ## 2025-03-25 - 1.10.0 - feat(core) Add update checking and version logging across startup components diff --git a/readme.md b/readme.md index f443653..cebb84d 100644 --- a/readme.md +++ b/readme.md @@ -4,10 +4,14 @@ NUPST is a command-line tool that monitors SNMP-enabled UPS devices and initiate ## Features -- Monitors UPS devices using SNMP +- 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 +- Supports multiple UPS brands (CyberPower, APC, Eaton, TrippLite, Liebert/Vertiv) - Simple systemd service integration +- Regular status logging for monitoring +- Real-time log viewing with journalctl +- Version checking and automatic updates - Self-contained - includes its own Node.js runtime ## Installation @@ -66,12 +70,18 @@ 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 logs - Show logs of the systemd service in real-time 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 + nupst update - Update NUPST from repository and refresh systemd service (requires root) nupst help - Show this help message + +Options: + --debug, -d - Enable debug mode for detailed SNMP logging + (Example: nupst test --debug) ``` ## Configuration @@ -93,11 +103,12 @@ Alternatively, you can manually edit the configuration file at `/etc/nupst/confi ```json { "snmp": { - "host": "127.0.0.1", + "host": "192.168.1.100", "port": 161, "community": "public", "version": 1, - "timeout": 5000 + "timeout": 5000, + "upsModel": "cyberpower" }, "thresholds": { "battery": 60, @@ -112,6 +123,7 @@ Alternatively, you can manually edit the configuration file at `/etc/nupst/confi - `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: @@ -121,6 +133,11 @@ Alternatively, you can manually edit the configuration file at `/etc/nupst/confi - `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) @@ -141,6 +158,56 @@ To check the status: nupst status ``` +To view logs in real-time: + +```bash +nupst logs +``` + +## Updating NUPST + +NUPST checks for updates automatically and will notify you when an update is available. To update to the latest version: + +```bash +sudo nupst update +``` + +This will: +1. Pull the latest changes from the git repository +2. Run the installation scripts +3. Refresh the systemd service configuration +4. Restart the service if it was running + +## Security + +NUPST was designed with security in mind: + +### Minimal Dependencies + +- **Zero Runtime NPM Dependencies**: NUPST is built without any external NPM packages to minimize the attack surface and avoid supply chain risks. +- **Self-contained Node.js**: NUPST ships with its own Node.js binary, isolated from the system's Node.js installation. This ensures: + - No dependency on system Node.js versions + - Zero external libraries that could become compromised + - Consistent, tested environment for execution + - Reduced risk of dependency-based attacks + +### Implementation Security + +- **Privilege Separation**: Only specific commands that require elevated permissions (`enable`, `disable`, `update`) check for root access; all other functionality runs with minimal privileges. +- **Limited Network Access**: NUPST only communicates with the UPS device over SNMP and contacts npmjs.org only to check for updates. +- **Secure SNMPv3 Support**: Supports encrypted authentication and privacy for secure communication with the UPS device. +- **Isolated Execution**: The application runs in its working directory (`/opt/nupst`) or specified installation location, minimizing the impact on the rest of the system. + +### Installation Security + +- The installation script can be reviewed before execution (`curl -sSL [url] | less`) +- All setup scripts download only verified versions and check integrity +- Installation is transparent and places files in standard locations (`/opt/nupst`, `/usr/local/bin`, `/etc/systemd/system`) + +### Audit and Review + +The codebase is small, focused, and designed to be easily auditable. All code is open source and available for review. + ## License MIT \ No newline at end of file diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 901138b..f5b6b3a 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@serve.zone/nupst', - version: '1.10.0', + version: '1.10.1', description: 'Node.js UPS Shutdown Tool for SNMP-enabled UPS devices' } diff --git a/ts/systemd.ts b/ts/systemd.ts index 5da0e34..bd802fa 100644 --- a/ts/systemd.ts +++ b/ts/systemd.ts @@ -170,9 +170,16 @@ WantedBy=multi-user.target */ private async displayUpsStatus(): Promise { try { - const upsStatus = await this.daemon.getConfig().snmp; + const config = this.daemon.getConfig(); const snmp = this.daemon.getNupstSnmp(); - const status = await snmp.getUpsStatus(upsStatus); + + // Create a test config with appropriate timeout, similar to the test command + const snmpConfig = { + ...config.snmp, + timeout: Math.min(config.snmp.timeout, 10000) // Use at most 10 seconds for status check + }; + + const status = await snmp.getUpsStatus(snmpConfig); console.log('┌─ UPS Status ───────────────────────────────┐'); console.log(`│ Power Status: ${status.powerStatus}`);