migration/deno-v4 #1
377
MIGRATION.md
Normal file
377
MIGRATION.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# Migration Guide: NUPST v3.x to v4.0
|
||||
|
||||
This guide will help you migrate from NUPST v3.x (Node.js-based) to v4.0 (Deno-based with pre-compiled binaries).
|
||||
|
||||
## Overview
|
||||
|
||||
NUPST v4.0 is a complete architectural rewrite:
|
||||
|
||||
- **Runtime**: Node.js → Deno
|
||||
- **Distribution**: Git repository + npm packages → Pre-compiled binaries
|
||||
- **Installation**: Clone + setup.sh → Download binary
|
||||
- **Dependencies**: Node.js + npm packages → Zero dependencies (self-contained binary)
|
||||
- **CLI Structure**: Flat commands → Subcommand structure (with backward compatibility)
|
||||
|
||||
**Good news**: Your configuration files are **100% compatible** - no changes needed!
|
||||
|
||||
## Pre-Migration Checklist
|
||||
|
||||
Before migrating, gather this information:
|
||||
|
||||
1. **Current version**: Run `nupst --version` or check `/opt/nupst/`
|
||||
2. **Service status**: Run `nupst status` to verify service is running
|
||||
3. **Configuration backup**: Copy `/etc/nupst/config.json` to a safe location
|
||||
4. **Current installation**: Note where NUPST is installed (usually `/opt/nupst/`)
|
||||
|
||||
```bash
|
||||
# Backup your configuration
|
||||
sudo cp /etc/nupst/config.json ~/nupst-config-backup.json
|
||||
|
||||
# Check current status
|
||||
nupst status
|
||||
|
||||
# Note your version
|
||||
nupst --version # or cat /opt/nupst/package.json | grep version
|
||||
```
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Step 1: Stop and Disable v3.x Service
|
||||
|
||||
```bash
|
||||
# Stop the running service
|
||||
sudo nupst stop
|
||||
|
||||
# Disable the service (removes from systemd)
|
||||
sudo nupst disable
|
||||
|
||||
# Verify service is stopped
|
||||
sudo systemctl status nupst # Should show "inactive" or "not found"
|
||||
```
|
||||
|
||||
### Step 2: Remove v3.x Installation
|
||||
|
||||
The v4.0 installer will replace files, but it's cleaner to remove the old installation first:
|
||||
|
||||
```bash
|
||||
# Remove the symlink
|
||||
sudo rm /usr/local/bin/nupst
|
||||
|
||||
# Remove the installation directory
|
||||
sudo rm -rf /opt/nupst
|
||||
|
||||
# Configuration at /etc/nupst/ is preserved
|
||||
# DO NOT remove /etc/nupst/config.json
|
||||
```
|
||||
|
||||
### Step 3: Install NUPST v4.0
|
||||
|
||||
Use the new binary-based installer:
|
||||
|
||||
```bash
|
||||
# Method 1: Download and run (recommended)
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh -o nupst-install.sh
|
||||
sudo bash nupst-install.sh
|
||||
rm nupst-install.sh
|
||||
```
|
||||
|
||||
```bash
|
||||
# Method 2: One-line installation
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
|
||||
```
|
||||
|
||||
The installer will:
|
||||
- Auto-detect your platform (Linux x64/ARM64, macOS Intel/ARM, Windows)
|
||||
- Download the appropriate pre-compiled binary
|
||||
- Install to `/opt/nupst/nupst`
|
||||
- Create symlink at `/usr/local/bin/nupst`
|
||||
|
||||
### Step 4: Verify Installation
|
||||
|
||||
```bash
|
||||
# Check version (should show 4.0.0 or higher)
|
||||
nupst --version
|
||||
|
||||
# Verify configuration is intact
|
||||
nupst config show
|
||||
|
||||
# Test UPS connectivity
|
||||
nupst ups test
|
||||
```
|
||||
|
||||
### Step 5: Update CLI Commands (Optional)
|
||||
|
||||
v4.0 uses a new subcommand structure, but **old commands still work** with deprecation warnings.
|
||||
|
||||
You can update your scripts gradually:
|
||||
|
||||
**Old (v3.x) → New (v4.0) Command Mapping:**
|
||||
|
||||
| v3.x Command | v4.0 Command | Status |
|
||||
|-------------|--------------|--------|
|
||||
| `nupst enable` | `nupst service enable` | Old works with warning |
|
||||
| `nupst disable` | `nupst service disable` | Old works with warning |
|
||||
| `nupst start` | `nupst service start` | Old works with warning |
|
||||
| `nupst stop` | `nupst service stop` | Old works with warning |
|
||||
| `nupst status` | `nupst service status` | Old works with warning |
|
||||
| `nupst logs` | `nupst service logs` | Old works with warning |
|
||||
| `nupst add` | `nupst ups add` | Old works with warning |
|
||||
| `nupst edit [id]` | `nupst ups edit [id]` | Old works with warning |
|
||||
| `nupst delete <id>` | `nupst ups remove <id>` | Old works with warning |
|
||||
| `nupst list` | `nupst ups list` | Old works with warning |
|
||||
| `nupst test` | `nupst ups test` | Old works with warning |
|
||||
| `nupst group add` | `nupst group add` | Unchanged |
|
||||
| `nupst group edit <id>` | `nupst group edit <id>` | Unchanged |
|
||||
| `nupst group delete <id>` | `nupst group remove <id>` | Changed |
|
||||
| `nupst group list` | `nupst group list` | Unchanged |
|
||||
| `nupst config` | `nupst config show` | Old works with warning |
|
||||
| `nupst update` | Re-run installer | **Removed** |
|
||||
| `nupst uninstall` | Manual removal | **Removed** |
|
||||
|
||||
**New aliases in v4.0:**
|
||||
- `nupst ls` → `nupst ups list`
|
||||
- `nupst rm <id>` → `nupst ups remove <id>`
|
||||
|
||||
### Step 6: Enable and Start Service
|
||||
|
||||
```bash
|
||||
# Enable systemd service
|
||||
sudo nupst service enable
|
||||
|
||||
# Start the service
|
||||
sudo nupst service start
|
||||
|
||||
# Check status
|
||||
nupst service status
|
||||
|
||||
# View logs
|
||||
nupst service logs
|
||||
```
|
||||
|
||||
### Step 7: Verify Operation
|
||||
|
||||
```bash
|
||||
# Check UPS status
|
||||
nupst service status
|
||||
|
||||
# View recent logs
|
||||
nupst service logs
|
||||
|
||||
# Verify daemon is monitoring
|
||||
sudo journalctl -u nupst -n 20
|
||||
```
|
||||
|
||||
## Configuration Compatibility
|
||||
|
||||
### What Stays the Same
|
||||
|
||||
✅ **Configuration file format**: `/etc/nupst/config.json` remains identical
|
||||
|
||||
✅ **All SNMP settings**: host, port, community, version, security levels, etc.
|
||||
|
||||
✅ **UPS device configurations**: All device IDs, names, thresholds, groups
|
||||
|
||||
✅ **Group configurations**: Redundant/non-redundant modes, descriptions
|
||||
|
||||
✅ **Supported UPS models**: CyberPower, APC, Eaton, TrippLite, Liebert, custom OIDs
|
||||
|
||||
### What Changes
|
||||
|
||||
❌ **Installation method**: No more git clone, use binary installer
|
||||
|
||||
❌ **Update process**: Re-run installer instead of `nupst update`
|
||||
|
||||
❌ **Uninstall process**: Manual removal instead of `nupst uninstall`
|
||||
|
||||
❌ **Systemd service path**: ExecStart now points to binary instead of wrapper script
|
||||
|
||||
## Troubleshooting Migration Issues
|
||||
|
||||
### Issue: `nupst: command not found`
|
||||
|
||||
**Solution**: Symlink wasn't created or isn't in PATH
|
||||
|
||||
```bash
|
||||
# Verify symlink exists
|
||||
ls -la /usr/local/bin/nupst
|
||||
|
||||
# If missing, create manually
|
||||
sudo ln -sf /opt/nupst/nupst /usr/local/bin/nupst
|
||||
|
||||
# Or add binary location to PATH
|
||||
export PATH="/opt/nupst:$PATH"
|
||||
```
|
||||
|
||||
### Issue: `Permission denied` when running nupst
|
||||
|
||||
**Solution**: Binary isn't executable
|
||||
|
||||
```bash
|
||||
sudo chmod +x /opt/nupst/nupst
|
||||
```
|
||||
|
||||
### Issue: Service won't start after migration
|
||||
|
||||
**Solution**: Systemd service file may reference old paths
|
||||
|
||||
```bash
|
||||
# Check service file
|
||||
sudo systemctl cat nupst
|
||||
|
||||
# If it references old paths, re-enable service
|
||||
sudo nupst service disable
|
||||
sudo nupst service enable
|
||||
sudo nupst service start
|
||||
```
|
||||
|
||||
### Issue: Configuration not found
|
||||
|
||||
**Solution**: Configuration may have been accidentally deleted
|
||||
|
||||
```bash
|
||||
# Restore from backup
|
||||
sudo cp ~/nupst-config-backup.json /etc/nupst/config.json
|
||||
|
||||
# Or re-create configuration
|
||||
sudo nupst ups add
|
||||
```
|
||||
|
||||
### Issue: Old commands show deprecation warnings
|
||||
|
||||
**This is expected behavior**. Old commands still work but will show:
|
||||
|
||||
```
|
||||
Note: 'nupst enable' is deprecated. Use 'nupst service enable' instead.
|
||||
```
|
||||
|
||||
To remove warnings, update to the new command syntax (see Step 5 above).
|
||||
|
||||
### Issue: Binary won't execute (macOS)
|
||||
|
||||
**Solution**: macOS Gatekeeper may block unsigned binaries
|
||||
|
||||
```bash
|
||||
# Remove quarantine attribute
|
||||
xattr -d com.apple.quarantine /opt/nupst/nupst
|
||||
|
||||
# Or right-click and "Open" in Finder
|
||||
```
|
||||
|
||||
### Issue: Wrong architecture binary downloaded
|
||||
|
||||
**Solution**: Installer detected wrong platform
|
||||
|
||||
```bash
|
||||
# Check your architecture
|
||||
uname -m # Should show: x86_64 (x64) or aarch64/arm64 (ARM)
|
||||
|
||||
# Download correct binary manually
|
||||
# For Linux x64:
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/nupst-linux-x64 -o nupst
|
||||
sudo mv nupst /opt/nupst/nupst
|
||||
sudo chmod +x /opt/nupst/nupst
|
||||
```
|
||||
|
||||
## Rollback to v3.x
|
||||
|
||||
If you need to rollback to v3.x:
|
||||
|
||||
```bash
|
||||
# Stop v4.0 service
|
||||
sudo nupst service stop
|
||||
sudo nupst service disable
|
||||
|
||||
# Remove v4.0 installation
|
||||
sudo rm /usr/local/bin/nupst
|
||||
sudo rm -rf /opt/nupst
|
||||
|
||||
# Reinstall v3.x using old method
|
||||
cd /tmp
|
||||
git clone https://code.foss.global/serve.zone/nupst.git -b main /opt/nupst
|
||||
cd /opt/nupst
|
||||
git checkout v3.1.2 # Or your previous version
|
||||
sudo ./install.sh -y
|
||||
|
||||
# Your configuration at /etc/nupst/config.json will still work
|
||||
```
|
||||
|
||||
## Post-Migration Best Practices
|
||||
|
||||
### Update Automation Scripts
|
||||
|
||||
If you have scripts or automation that call NUPST:
|
||||
|
||||
```bash
|
||||
# Update cron jobs, monitoring scripts, etc.
|
||||
# Old: nupst status
|
||||
# New: nupst service status
|
||||
|
||||
# Example crontab update:
|
||||
# OLD: 0 * * * * /usr/local/bin/nupst status >> /var/log/nupst-check.log
|
||||
# NEW: 0 * * * * /usr/local/bin/nupst service status >> /var/log/nupst-check.log
|
||||
```
|
||||
|
||||
### Monitor for Issues
|
||||
|
||||
Keep an eye on logs for the first few days:
|
||||
|
||||
```bash
|
||||
# Real-time monitoring
|
||||
nupst service logs
|
||||
|
||||
# Check for errors
|
||||
sudo journalctl -u nupst --since "1 hour ago" | grep -i error
|
||||
```
|
||||
|
||||
### Update Documentation
|
||||
|
||||
Update any internal documentation to reflect:
|
||||
- New installation method (binary-based)
|
||||
- New CLI command structure
|
||||
- New update process (re-run installer)
|
||||
|
||||
## Benefits of v4.0
|
||||
|
||||
After migration, you'll enjoy:
|
||||
|
||||
✅ **Faster Startup**: Binary starts in milliseconds vs seconds
|
||||
|
||||
✅ **Zero Dependencies**: No Node.js or npm on the system
|
||||
|
||||
✅ **Easier Updates**: `curl | bash` vs `git pull && npm install`
|
||||
|
||||
✅ **Better Security**: No npm supply chain risks, checksums provided
|
||||
|
||||
✅ **Smaller Footprint**: ~340MB binary vs ~500MB+ (repo + Node.js + node_modules)
|
||||
|
||||
✅ **Official Support**: Pre-compiled binaries for all major platforms
|
||||
|
||||
✅ **Automated Releases**: New versions built and tested automatically
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **Issues**: https://code.foss.global/serve.zone/nupst/issues
|
||||
- **Documentation**: https://code.foss.global/serve.zone/nupst
|
||||
- **Changelog**: See [changelog.md](./changelog.md) for detailed v4.0 changes
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
Use this checklist to track your migration:
|
||||
|
||||
- [ ] Backup configuration file
|
||||
- [ ] Note current version and status
|
||||
- [ ] Stop v3.x service (`nupst stop`)
|
||||
- [ ] Disable v3.x service (`nupst disable`)
|
||||
- [ ] Remove old installation
|
||||
- [ ] Run v4.0 installer
|
||||
- [ ] Verify version (`nupst --version`)
|
||||
- [ ] Test configuration (`nupst config show`)
|
||||
- [ ] Test UPS connectivity (`nupst ups test`)
|
||||
- [ ] Enable v4.0 service (`nupst service enable`)
|
||||
- [ ] Start v4.0 service (`nupst service start`)
|
||||
- [ ] Verify service status (`nupst service status`)
|
||||
- [ ] Monitor logs for issues (`nupst service logs`)
|
||||
- [ ] Update automation scripts (optional)
|
||||
- [ ] Update documentation (optional)
|
||||
|
||||
Welcome to NUPST v4.0! 🎉
|
||||
147
changelog.md
147
changelog.md
@@ -1,5 +1,152 @@
|
||||
# Changelog
|
||||
|
||||
## 2025-10-18 - 4.0.0 - BREAKING CHANGE(core): Complete migration to Deno runtime
|
||||
|
||||
**MAJOR RELEASE: NUPST v4.0 is a complete rewrite powered by Deno**
|
||||
|
||||
This release fundamentally changes NUPST's architecture from Node.js-based to Deno-based, distributed as pre-compiled binaries. This is a **breaking change** in terms of installation and distribution, but configuration files from v3.x are **fully compatible**.
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
**Installation & Distribution:**
|
||||
- **Removed**: Node.js runtime dependency - NUPST no longer requires Node.js
|
||||
- **Removed**: npm package distribution (no longer published to npmjs.org)
|
||||
- **Removed**: `bin/nupst` wrapper script
|
||||
- **Removed**: `setup.sh` dependency installation
|
||||
- **Removed**: All Node.js-related files (package.json, tsconfig.json, pnpm-lock.yaml, npmextra.json)
|
||||
- **Changed**: Installation now downloads pre-compiled binaries instead of cloning repository
|
||||
- **Changed**: Binary-based distribution (~340MB self-contained executables)
|
||||
|
||||
**CLI Structure (Backward Compatible):**
|
||||
- **Changed**: Commands now use subcommand structure (e.g., `nupst service enable` instead of `nupst enable`)
|
||||
- **Maintained**: Old command format still works with deprecation warnings for smooth migration
|
||||
- **Added**: Aliases for common commands (`nupst ls`, `nupst rm`)
|
||||
|
||||
### New Features
|
||||
|
||||
**Distribution & Installation:**
|
||||
- Pre-compiled binaries for 5 platforms:
|
||||
- Linux x86_64
|
||||
- Linux ARM64
|
||||
- macOS x86_64 (Intel)
|
||||
- macOS ARM64 (Apple Silicon)
|
||||
- Windows x86_64
|
||||
- Automated binary releases via Gitea Actions
|
||||
- SHA256 checksum verification for all releases
|
||||
- Installation from Gitea releases via updated `install.sh`
|
||||
- Zero dependencies - completely self-contained binaries
|
||||
- Cross-platform compilation from single codebase
|
||||
|
||||
**CI/CD Automation:**
|
||||
- Gitea Actions workflows for continuous integration
|
||||
- Automated release workflow triggered by git tags
|
||||
- Automatic binary compilation for all platforms on release
|
||||
- Type checking and linting in CI pipeline
|
||||
- Build verification on every push
|
||||
|
||||
**CLI Improvements:**
|
||||
- New hierarchical command structure with subcommands
|
||||
- `nupst service` - Service management (enable, disable, start, stop, restart, status, logs)
|
||||
- `nupst ups` - UPS device management (add, edit, remove, list, test)
|
||||
- `nupst group` - Group management (add, edit, remove, list)
|
||||
- `nupst config show` - Display configuration
|
||||
- `nupst --version` - Show version information
|
||||
- Better help messages organized by category
|
||||
- Backward compatibility maintained with deprecation warnings
|
||||
|
||||
**Technical Improvements:**
|
||||
- Deno runtime for modern TypeScript/JavaScript execution
|
||||
- Native TypeScript support without compilation step
|
||||
- Faster startup and execution compared to Node.js
|
||||
- Smaller memory footprint
|
||||
- Built-in permissions system
|
||||
- No build step required for development
|
||||
|
||||
### Migration Guide
|
||||
|
||||
**For Users:**
|
||||
1. Stop existing v3.x service: `sudo nupst disable`
|
||||
2. Install v4.0 using new installer: `curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y`
|
||||
3. Your configuration at `/etc/nupst/config.json` is preserved and fully compatible
|
||||
4. Enable service with new CLI: `sudo nupst service enable && sudo nupst service start`
|
||||
5. Update systemd commands to use new syntax (old syntax still works with warnings)
|
||||
|
||||
**Configuration Compatibility:**
|
||||
- All configuration files from v3.x work without modification
|
||||
- No changes to `/etc/nupst/config.json` format
|
||||
- All SNMP settings, thresholds, and group configurations preserved
|
||||
|
||||
**Command Mapping:**
|
||||
```bash
|
||||
# Old (v3.x) → New (v4.0)
|
||||
nupst enable → nupst service enable
|
||||
nupst disable → nupst service disable
|
||||
nupst start → nupst service start
|
||||
nupst stop → nupst service stop
|
||||
nupst status → nupst service status
|
||||
nupst logs → nupst service logs
|
||||
nupst add → nupst ups add
|
||||
nupst edit [id] → nupst ups edit [id]
|
||||
nupst delete <id> → nupst ups remove <id>
|
||||
nupst list → nupst ups list
|
||||
nupst test → nupst ups test
|
||||
nupst group add → nupst group add (unchanged)
|
||||
nupst group edit <id> → nupst group edit <id> (unchanged)
|
||||
nupst group delete <id> → nupst group remove <id>
|
||||
nupst group list → nupst group list (unchanged)
|
||||
nupst config → nupst config show
|
||||
```
|
||||
|
||||
### Technical Details
|
||||
|
||||
**Commit History:**
|
||||
- `df6a44d`: Complete migration with Gitea Actions workflows and install.sh updates
|
||||
- `9efcc4b`: CLI reorganization with subcommand structure
|
||||
- `5903ae7`: Cross-platform compilation scripts
|
||||
- `a649c59`: Deno migration with npm: and node: specifiers
|
||||
- `5f4f3ec`: Initial migration to Deno
|
||||
|
||||
**Files Changed:**
|
||||
- Removed: 11 files (package.json, tsconfig.json, pnpm-lock.yaml, npmextra.json, bin/nupst, setup.sh)
|
||||
- Added: 3 Gitea Actions workflows (ci.yml, release.yml, README.md)
|
||||
- Modified: 14 TypeScript files for Deno compatibility
|
||||
- Updated: install.sh, .gitignore, readme.md
|
||||
- Net reduction: -10,242 lines (93% reduction in repository size)
|
||||
|
||||
**Dependencies:**
|
||||
- Runtime: Deno v1.x (bundled in binary, no installation required)
|
||||
- SNMP: npm:net-snmp@3.20.0 (bundled in binary via npm: specifier)
|
||||
- Node.js built-ins: Accessed via node: specifier (node:fs, node:child_process, etc.)
|
||||
|
||||
### Benefits
|
||||
|
||||
**For Users:**
|
||||
- **Faster Installation**: Download single binary instead of cloning repo + installing Node.js + npm dependencies
|
||||
- **Zero Dependencies**: No Node.js or npm required on target system
|
||||
- **Smaller Footprint**: Single binary vs repo + Node.js + node_modules
|
||||
- **Easier Updates**: Download new binary instead of git pull + npm install
|
||||
- **Better Security**: No npm supply chain risks, binary checksums provided
|
||||
- **Platform Support**: Official binaries for all major platforms
|
||||
|
||||
**For Developers:**
|
||||
- **Modern Tooling**: Native TypeScript support without build configuration
|
||||
- **Faster Development**: No compilation step during development
|
||||
- **CI/CD Automation**: Automated releases and testing
|
||||
- **Cleaner Codebase**: 93% reduction in configuration files
|
||||
- **Cross-Platform**: Compile for all platforms from any platform
|
||||
|
||||
### Known Issues
|
||||
|
||||
- Windows ARM64 not supported (Deno limitation)
|
||||
- Binary sizes are larger (~340MB) due to bundled runtime (trade-off for zero dependencies)
|
||||
- First-time execution may be slower on some systems (binary extraction)
|
||||
|
||||
### Acknowledgments
|
||||
|
||||
This release represents a complete modernization of NUPST's infrastructure while maintaining full backward compatibility for user configurations. Special thanks to the Deno team for creating an excellent runtime that made this migration possible.
|
||||
|
||||
---
|
||||
|
||||
## 2025-03-28 - 3.1.2 - fix(cli/ups-handler)
|
||||
Improve UPS device listing table formatting for better column alignment
|
||||
|
||||
|
||||
563
readme.md
563
readme.md
@@ -1,6 +1,8 @@
|
||||
# NUPST - Node.js UPS Shutdown Tool
|
||||
# NUPST - Network 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.
|
||||
NUPST is a lightweight, self-contained command-line tool that monitors SNMP-enabled UPS devices and initiates system shutdown when power outages are detected and battery levels are low.
|
||||
|
||||
**Version 4.0+** is powered by Deno and distributed as pre-compiled binaries requiring zero dependencies.
|
||||
|
||||
## Features
|
||||
|
||||
@@ -8,52 +10,58 @@ NUPST is a command-line tool that monitors SNMP-enabled UPS devices and initiate
|
||||
- **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
|
||||
- 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
|
||||
- **SNMP Protocol Support**: Full support for SNMP v1, v2c, and v3 with authentication and encryption
|
||||
- **Multiple UPS Brands**: Works with CyberPower, APC, Eaton, TrippLite, Liebert/Vertiv, and custom OID configurations
|
||||
- **Systemd Integration**: Simple service installation and management
|
||||
- **Real-time Monitoring**: Live status updates and log viewing
|
||||
- **Zero Dependencies**: Single self-contained binary with no runtime requirements
|
||||
- **Cross-Platform**: Binaries available for Linux (x64, ARM64), macOS (Intel, Apple Silicon), and Windows
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Install (One-line command)
|
||||
### Quick Install (Recommended)
|
||||
|
||||
The easiest way to install NUPST is using the automated installer:
|
||||
|
||||
```bash
|
||||
# Method 1: Download and run (most reliable across all environments)
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh -o nupst-install.sh && sudo bash nupst-install.sh && rm nupst-install.sh
|
||||
# Download and run installer (most reliable)
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh -o nupst-install.sh
|
||||
sudo bash nupst-install.sh
|
||||
rm nupst-install.sh
|
||||
```
|
||||
|
||||
```bash
|
||||
# Method 2: Pipe with automatic yes for dependencies (non-interactive)
|
||||
# One-line installation (non-interactive with auto-confirm)
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
|
||||
```
|
||||
|
||||
```bash
|
||||
# Method 3: Process substitution (only on systems that support /dev/fd/)
|
||||
# Note: This may fail on some systems with "No such file or directory" errors
|
||||
sudo bash <(curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh)
|
||||
```
|
||||
The installer will:
|
||||
1. Auto-detect your platform (OS and architecture)
|
||||
2. Download the latest pre-compiled binary from releases
|
||||
3. Install to `/opt/nupst/nupst`
|
||||
4. Create a symlink in `/usr/local/bin/nupst` for global access
|
||||
|
||||
### Direct from Git
|
||||
### Manual Installation
|
||||
|
||||
Download the appropriate binary for your platform from the [releases page](https://code.foss.global/serve.zone/nupst/releases):
|
||||
|
||||
- **Linux x64**: `nupst-linux-x64`
|
||||
- **Linux ARM64**: `nupst-linux-arm64`
|
||||
- **macOS Intel**: `nupst-macos-x64`
|
||||
- **macOS Apple Silicon**: `nupst-macos-arm64`
|
||||
- **Windows x64**: `nupst-windows-x64.exe`
|
||||
|
||||
Then install manually:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://code.foss.global/serve.zone/nupst.git
|
||||
cd nupst
|
||||
# Download binary (replace with your platform)
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/nupst-linux-x64 -o nupst
|
||||
|
||||
# Option 1: Quick install (requires root privileges)
|
||||
sudo ./install.sh
|
||||
# Make executable
|
||||
chmod +x nupst
|
||||
|
||||
# Option 1a: Quick install with auto-yes for dependencies
|
||||
sudo ./install.sh -y
|
||||
|
||||
# Option 2: Manual setup
|
||||
./setup.sh
|
||||
sudo ln -s $(pwd)/bin/nupst /usr/local/bin/nupst
|
||||
# Move to system path
|
||||
sudo mv nupst /usr/local/bin/nupst
|
||||
```
|
||||
|
||||
### Installation Options
|
||||
@@ -61,14 +69,20 @@ sudo ln -s $(pwd)/bin/nupst /usr/local/bin/nupst
|
||||
The installer script (`install.sh`) supports the following options:
|
||||
|
||||
```
|
||||
-y, --yes Automatically answer yes to all prompts (like installing git)
|
||||
-h, --help Show the help message
|
||||
-y, --yes Automatically answer yes to all prompts
|
||||
-h, --help Show help message
|
||||
--version VERSION Install specific version (e.g., --version v4.0.0)
|
||||
--install-dir DIR Custom installation directory (default: /opt/nupst)
|
||||
```
|
||||
|
||||
### From NPM
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
npm install -g @serve.zone/nupst
|
||||
# Install specific version
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- --version v4.0.0
|
||||
|
||||
# Custom installation directory
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- --install-dir /usr/local/nupst
|
||||
```
|
||||
|
||||
## System Changes
|
||||
@@ -79,99 +93,137 @@ When installed, NUPST makes the following changes to your system:
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `/opt/nupst/` | Main installation directory containing the NUPST files |
|
||||
| `/opt/nupst/nupst` | Pre-compiled binary (default location) |
|
||||
| `/etc/nupst/config.json` | Configuration file |
|
||||
| `/usr/local/bin/nupst` | Symlink to the NUPST executable |
|
||||
| `/usr/local/bin/nupst` | Symlink to the NUPST binary |
|
||||
| `/etc/systemd/system/nupst.service` | Systemd service file (when enabled) |
|
||||
|
||||
### Service Changes
|
||||
|
||||
- Creates and enables a systemd service called `nupst.service` (when enabled with `nupst enable`)
|
||||
- Creates and enables a systemd service called `nupst.service` (when enabled with `nupst service enable`)
|
||||
- The service runs with root permissions to allow system shutdown capabilities
|
||||
|
||||
### Network Access
|
||||
|
||||
- NUPST only communicates with your UPS device via SNMP (default port 161)
|
||||
- Brief connections to npmjs.org to check for updates
|
||||
- No external network connections required after installation
|
||||
|
||||
## Uninstallation
|
||||
|
||||
```bash
|
||||
# Using the CLI tool:
|
||||
sudo nupst uninstall
|
||||
# Disable and remove service first
|
||||
sudo nupst service disable
|
||||
|
||||
# If installed from git repository:
|
||||
cd /path/to/nupst
|
||||
# Remove binary and config
|
||||
sudo rm /usr/local/bin/nupst
|
||||
sudo rm /opt/nupst/nupst
|
||||
sudo rm -rf /etc/nupst/
|
||||
|
||||
# Or use the uninstall script if installed from git
|
||||
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 from `/etc/systemd/system/nupst.service`
|
||||
- Remove the symlink from `/usr/local/bin/nupst`
|
||||
- Optionally remove configuration files from `/etc/nupst/`
|
||||
- Remove the repository directory from `/opt/nupst/` (when using `nupst uninstall`)
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
NUPST - Node.js UPS Shutdown Tool
|
||||
### Command Structure (v4.0+)
|
||||
|
||||
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 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 v4.0 uses a subcommand structure for better organization:
|
||||
|
||||
```
|
||||
NUPST - Network UPS Shutdown Tool
|
||||
Version: 4.0.0
|
||||
|
||||
Usage: nupst <command> [subcommand] [options]
|
||||
|
||||
Service Management:
|
||||
nupst service enable - Install and enable the systemd service
|
||||
nupst service disable - Stop and disable the systemd service
|
||||
nupst service start - Start the systemd service
|
||||
nupst service stop - Stop the systemd service
|
||||
nupst service restart - Restart the systemd service
|
||||
nupst service status - Show service and UPS status
|
||||
nupst service logs - Show service logs in real-time
|
||||
nupst service start-daemon - Start daemon directly (for testing)
|
||||
|
||||
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)
|
||||
nupst help - Show this help message
|
||||
nupst ups add - Add a new UPS device
|
||||
nupst ups edit [id] - Edit a UPS device (prompts if no ID)
|
||||
nupst ups remove <id> - Remove a UPS device by ID
|
||||
nupst ups list - List all configured UPS devices
|
||||
nupst ups test - Test UPS connections
|
||||
|
||||
Options:
|
||||
--debug, -d - Enable debug mode for detailed SNMP logging
|
||||
(Example: nupst test --debug)
|
||||
Group Management:
|
||||
nupst group add - Add a new UPS group
|
||||
nupst group edit <id> - Edit a UPS group
|
||||
nupst group remove <id> - Remove a UPS group
|
||||
nupst group list - List all UPS groups
|
||||
|
||||
Configuration:
|
||||
nupst config show - Display current configuration
|
||||
|
||||
Global Options:
|
||||
--version, -v - Show version information
|
||||
--help, -h - Show help message
|
||||
--debug, -d - Enable debug mode for detailed logging
|
||||
|
||||
Aliases (for backward compatibility):
|
||||
nupst ls - Alias for 'nupst ups list'
|
||||
nupst rm <id> - Alias for 'nupst ups remove'
|
||||
```
|
||||
|
||||
### Quick Start Guide
|
||||
|
||||
1. **Install NUPST** (see Installation section above)
|
||||
|
||||
2. **Add your first UPS device:**
|
||||
```bash
|
||||
sudo nupst ups add
|
||||
```
|
||||
Follow the interactive prompts to configure your UPS.
|
||||
|
||||
3. **Test the configuration:**
|
||||
```bash
|
||||
nupst ups test
|
||||
```
|
||||
|
||||
4. **Enable the service:**
|
||||
```bash
|
||||
sudo nupst service enable
|
||||
sudo nupst service start
|
||||
```
|
||||
|
||||
5. **Check status:**
|
||||
```bash
|
||||
nupst service status
|
||||
```
|
||||
|
||||
6. **View logs:**
|
||||
```bash
|
||||
nupst service logs
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
NUPST supports monitoring multiple UPS devices organized into groups. You can set up your UPS devices using the interactive commands:
|
||||
NUPST supports monitoring multiple UPS devices organized into groups. The configuration file is located at `/etc/nupst/config.json`.
|
||||
|
||||
### Interactive Configuration
|
||||
|
||||
The easiest way to configure NUPST is through the interactive commands:
|
||||
|
||||
```bash
|
||||
# Add a new UPS device
|
||||
nupst add
|
||||
sudo nupst ups add
|
||||
|
||||
# Create a new group
|
||||
nupst group add
|
||||
# Create a group
|
||||
sudo nupst group add
|
||||
|
||||
# Assign UPS devices to groups
|
||||
nupst group edit <group-id>
|
||||
sudo nupst group edit <group-id>
|
||||
```
|
||||
|
||||
### Configuration File Structure
|
||||
|
||||
The configuration file is located at `/etc/nupst/config.json`. Here's an example of a multi-UPS configuration:
|
||||
Here's an example configuration with multiple UPS devices in a redundant group:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -217,7 +269,7 @@ The configuration file is located at `/etc/nupst/config.json`. Here's an example
|
||||
"id": "datacenter",
|
||||
"name": "Data Center",
|
||||
"mode": "redundant",
|
||||
"description": "Main data center UPS group"
|
||||
"description": "Main data center UPS group with redundant power"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -225,141 +277,274 @@ The configuration file is located at `/etc/nupst/config.json`. Here's an example
|
||||
|
||||
### Configuration Fields
|
||||
|
||||
#### Global Settings
|
||||
|
||||
- `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
|
||||
|
||||
#### UPS Device Settings
|
||||
|
||||
- `id`: Unique identifier for the UPS
|
||||
- `name`: Friendly name for the UPS
|
||||
- `groups`: Array of group IDs this UPS belongs to
|
||||
|
||||
**SNMP Configuration:**
|
||||
- `host`: IP address or hostname of your UPS
|
||||
- `port`: SNMP port (default: 161)
|
||||
- `version`: SNMP version (1, 2, or 3)
|
||||
- `timeout`: Timeout in milliseconds (default: 5000)
|
||||
- `upsModel`: UPS brand ('cyberpower', 'apc', 'eaton', 'tripplite', 'liebert', or 'custom')
|
||||
|
||||
**For SNMPv1/v2c:**
|
||||
- `community`: SNMP community string (default: "public")
|
||||
|
||||
**For SNMPv3:**
|
||||
- `securityLevel`: 'noAuthNoPriv', 'authNoPriv', or 'authPriv'
|
||||
- `username`: SNMPv3 username
|
||||
- `authProtocol`: 'MD5' or 'SHA'
|
||||
- `authKey`: Authentication password
|
||||
- `privProtocol`: 'DES' or 'AES' (for authPriv level)
|
||||
- `privKey`: Privacy/encryption password
|
||||
|
||||
**For Custom UPS Models:**
|
||||
- `customOIDs`: Custom OID mappings
|
||||
- `POWER_STATUS`: OID for AC power status
|
||||
- `BATTERY_CAPACITY`: OID for battery percentage
|
||||
- `BATTERY_RUNTIME`: OID for runtime remaining (minutes)
|
||||
|
||||
**Shutdown Thresholds:**
|
||||
- `battery`: Battery percentage threshold (default: 60%)
|
||||
- `runtime`: Runtime minutes threshold (default: 20 minutes)
|
||||
|
||||
#### Group Settings
|
||||
|
||||
- `id`: Unique identifier for the group
|
||||
- `name`: Friendly name for the group
|
||||
- `mode`: Operating mode ('redundant' or 'nonRedundant')
|
||||
- `description`: Optional description
|
||||
|
||||
### 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.
|
||||
- **Redundant Mode**: System shuts down only when ALL UPS devices in the group are critical. Ideal for setups with backup UPS units where one can maintain power.
|
||||
|
||||
- **Non-Redundant Mode**: System shuts down when ANY UPS device in the group is critical. Used when all UPS devices must be operational for system stability.
|
||||
|
||||
## Setup as a Service
|
||||
|
||||
To set up NUPST as a systemd service:
|
||||
Enable NUPST as a systemd service for automatic monitoring:
|
||||
|
||||
```bash
|
||||
sudo nupst enable
|
||||
sudo nupst start
|
||||
```
|
||||
# Enable and start service
|
||||
sudo nupst service enable
|
||||
sudo nupst service start
|
||||
|
||||
To check the status:
|
||||
# Check status
|
||||
nupst service status
|
||||
|
||||
```bash
|
||||
nupst status
|
||||
```
|
||||
# View real-time logs
|
||||
nupst service logs
|
||||
|
||||
To view logs in real-time:
|
||||
# Stop service
|
||||
sudo nupst service stop
|
||||
|
||||
```bash
|
||||
nupst logs
|
||||
# Disable service
|
||||
sudo nupst service disable
|
||||
```
|
||||
|
||||
## Updating NUPST
|
||||
|
||||
NUPST checks for updates automatically and will notify you when an update is available. To update to the latest version:
|
||||
### Automatic Update
|
||||
|
||||
Re-run the installer to update to the latest version:
|
||||
|
||||
```bash
|
||||
sudo nupst update
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/raw/branch/main/install.sh | sudo bash -s -- -y
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Pull the latest changes from the git repository
|
||||
2. Run the installation scripts
|
||||
3. Force-update Node.js and all dependencies, even if they already exist
|
||||
4. Refresh the systemd service configuration
|
||||
5. Restart the service if it was running
|
||||
The installer will:
|
||||
1. Download the latest binary
|
||||
2. Replace the existing installation
|
||||
3. Preserve your configuration at `/etc/nupst/config.json`
|
||||
4. Restart the service if it was running
|
||||
|
||||
You can also manually run the setup script with the force flag to update Node.js and dependencies without updating the application code:
|
||||
### Manual Update
|
||||
|
||||
1. Download the latest binary from [releases](https://code.foss.global/serve.zone/nupst/releases)
|
||||
2. Replace the existing binary:
|
||||
```bash
|
||||
sudo nupst service stop
|
||||
sudo mv nupst-linux-x64 /opt/nupst/nupst # adjust for your platform
|
||||
sudo chmod +x /opt/nupst/nupst
|
||||
sudo nupst service start
|
||||
```
|
||||
|
||||
### Version Checking
|
||||
|
||||
Check your current version:
|
||||
|
||||
```bash
|
||||
# If you're in the nupst directory:
|
||||
bash ./setup.sh --force
|
||||
|
||||
# If you're in another directory, specify the full path:
|
||||
bash /opt/nupst/setup.sh --force
|
||||
nupst --version
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
NUPST was designed with security in mind:
|
||||
NUPST is designed with security as a priority:
|
||||
|
||||
### Minimal Dependencies
|
||||
### Architecture Security
|
||||
|
||||
- **Minimal Runtime Dependencies**: NUPST uses only one carefully selected NPM package (net-snmp) to minimize the attack surface and avoid supply chain risks while providing robust SNMP functionality.
|
||||
- **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
|
||||
- Minimal external libraries that could become compromised
|
||||
- Consistent, tested environment for execution
|
||||
- Reduced risk of dependency-based attacks
|
||||
- **Single Binary**: Self-contained executable with no external dependencies
|
||||
- **No Runtime Dependencies**: Unlike v3.x (Node.js), v4.0+ requires no runtime environment
|
||||
- **Minimal Attack Surface**: Compiled Deno binary with only essential SNMP functionality
|
||||
- **No Supply Chain Risk**: Pre-compiled binaries verified with SHA256 checksums
|
||||
- **Isolated Execution**: Runs with minimal required privileges
|
||||
|
||||
### Implementation Security
|
||||
### SNMP 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.
|
||||
- **Isolated Execution**: The application runs in its working directory (`/opt/nupst`) or specified installation location, minimizing the impact on the rest of the system.
|
||||
|
||||
### SNMP Security Features
|
||||
|
||||
- **SNMPv3 Support with Secure Authentication and Privacy**:
|
||||
- Three security levels available:
|
||||
- `noAuthNoPriv`: No authentication or encryption (basic access)
|
||||
- `authNoPriv`: Authentication without encryption (verifies identity)
|
||||
- `authPriv`: Full authentication and encryption (most secure)
|
||||
- Authentication protocols: MD5 or SHA
|
||||
- Privacy/encryption protocols: DES or AES
|
||||
- Automatic fallback mechanisms for compatibility
|
||||
- Context support for segmented SNMP deployments
|
||||
- Configurable timeouts based on security level
|
||||
- **Graceful degradation**: If authentication or privacy details are missing or invalid, NUPST will automatically fall back to a lower security level while logging appropriate warnings.
|
||||
- **Interactive setup**: Guided setup process to properly configure SNMPv3 security settings with clear explanations of each security option.
|
||||
- **SNMPv3 Support**: Full authentication and encryption support
|
||||
- `noAuthNoPriv`: Basic access (no security)
|
||||
- `authNoPriv`: Authentication without encryption
|
||||
- `authPriv`: Full authentication and encryption (recommended)
|
||||
- **Authentication**: MD5 or SHA protocols
|
||||
- **Encryption**: DES or AES privacy protocols
|
||||
- **Secure Defaults**: Automatic timeout adjustment based on security level
|
||||
|
||||
### 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`)
|
||||
- Automatically detects platform architecture and OS for proper binary selection
|
||||
- Installs production dependencies locally without requiring global npm packages
|
||||
- **Checksum Verification**: SHA256SUMS.txt provided for all releases
|
||||
- **Transparent Installation**: Standard locations with clear documentation
|
||||
- **Minimal Permissions**: Only systemd operations require root access
|
||||
- **Source Available**: Full source code available for audit
|
||||
|
||||
### Audit and Review
|
||||
### Network Security
|
||||
|
||||
The codebase is small, focused, and designed to be easily auditable. All code is open source and available for review.
|
||||
- **Local-Only Communication**: Only connects to UPS devices on local network
|
||||
- **No Telemetry**: No data sent to external servers
|
||||
- **No Update Checks**: Manual update process only
|
||||
|
||||
### Verifying Downloads
|
||||
|
||||
All releases include SHA256 checksums:
|
||||
|
||||
```bash
|
||||
# Download binary and checksums
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/nupst-linux-x64 -o nupst
|
||||
curl -sSL https://code.foss.global/serve.zone/nupst/releases/download/v4.0.0/SHA256SUMS.txt -o SHA256SUMS.txt
|
||||
|
||||
# Verify checksum
|
||||
sha256sum -c SHA256SUMS.txt --ignore-missing
|
||||
```
|
||||
|
||||
## Migration from v3.x
|
||||
|
||||
If you're upgrading from NUPST v3.x (Node.js-based), see [MIGRATION.md](./MIGRATION.md) for detailed migration instructions.
|
||||
|
||||
**Key Changes in v4.0:**
|
||||
- Powered by Deno instead of Node.js
|
||||
- Distributed as pre-compiled binaries
|
||||
- New subcommand structure (backward compatible)
|
||||
- Zero dependencies required
|
||||
- Smaller installation footprint
|
||||
- Faster startup and execution
|
||||
|
||||
**Configuration Compatibility:**
|
||||
Your existing `/etc/nupst/config.json` from v3.x is fully compatible with v4.0. No changes required.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Binary Won't Execute
|
||||
|
||||
```bash
|
||||
# Make sure it's executable
|
||||
chmod +x /opt/nupst/nupst
|
||||
|
||||
# Check architecture matches your system
|
||||
uname -m # Should match binary (x86_64 = x64, aarch64 = arm64)
|
||||
```
|
||||
|
||||
### Service Won't Start
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
sudo systemctl status nupst
|
||||
|
||||
# Check logs for errors
|
||||
sudo journalctl -u nupst -n 50
|
||||
|
||||
# Verify configuration
|
||||
nupst config show
|
||||
```
|
||||
|
||||
### Can't Connect to UPS
|
||||
|
||||
```bash
|
||||
# Test SNMP connectivity
|
||||
nupst ups test --debug
|
||||
|
||||
# Check network connectivity
|
||||
ping <ups-ip-address>
|
||||
|
||||
# Verify SNMP port is accessible
|
||||
nc -zv <ups-ip-address> 161
|
||||
```
|
||||
|
||||
### Permission Denied Errors
|
||||
|
||||
Most operations that modify the system require root:
|
||||
|
||||
```bash
|
||||
# Service management
|
||||
sudo nupst service enable
|
||||
sudo nupst service start
|
||||
|
||||
# Configuration changes
|
||||
sudo nupst ups add
|
||||
sudo nupst group add
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Building from Source
|
||||
|
||||
Requirements:
|
||||
- [Deno](https://deno.land/) v1.x or later
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://code.foss.global/serve.zone/nupst.git
|
||||
cd nupst
|
||||
|
||||
# Run directly with Deno
|
||||
deno run --allow-all mod.ts help
|
||||
|
||||
# Compile for current platform
|
||||
deno compile --allow-all --output nupst mod.ts
|
||||
|
||||
# Compile for all platforms
|
||||
bash scripts/compile-all.sh
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
deno test --allow-all tests/
|
||||
```
|
||||
|
||||
### Contributing
|
||||
|
||||
Contributions are welcome! Please:
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Submit a pull request
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues**: [Report bugs or request features](https://code.foss.global/serve.zone/nupst/issues)
|
||||
- **Documentation**: [Full documentation](https://code.foss.global/serve.zone/nupst)
|
||||
- **Source Code**: [View source](https://code.foss.global/serve.zone/nupst)
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
|
||||
|
||||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||||
|
||||
@@ -369,9 +554,9 @@ This project is owned and maintained by Task Venture Capital GmbH. The names and
|
||||
|
||||
### Company Information
|
||||
|
||||
Task Venture Capital GmbH
|
||||
Task Venture Capital GmbH
|
||||
Registered at District court Bremen HRB 35230 HB, Germany
|
||||
|
||||
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
|
||||
|
||||
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|
||||
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|
||||
|
||||
Reference in New Issue
Block a user