fix(systemd/readme): Improve README documentation and fix UPS status retrieval in systemd service

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
 

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

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'
 }

ts/systemd.ts

@@ -170,9 +170,16 @@ WantedBy=multi-user.target
    */
   private async displayUpsStatus(): Promise<void> {
     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}`);