feat(actions): implement action system for UPS state management with shutdown, webhook, and script actions

example-action.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+# NUPST Action Script Example
+# Copy this to /etc/nupst/ and customize for your needs
+#
+# This script is called by NUPST when power events or threshold violations occur.
+# It receives UPS state information via environment variables and command-line arguments.
+
+# ==============================================================================
+# ARGUMENTS (positional parameters)
+# ==============================================================================
+# $1 = Power Status (online|onBattery|unknown)
+# $2 = Battery Capacity (percentage, 0-100)
+# $3 = Battery Runtime (estimated minutes remaining)
+
+POWER_STATUS=$1
+BATTERY_CAPACITY=$2
+BATTERY_RUNTIME=$3
+
+# ==============================================================================
+# ENVIRONMENT VARIABLES
+# ==============================================================================
+# NUPST_UPS_ID               - Unique UPS identifier
+# NUPST_UPS_NAME             - Human-readable UPS name
+# NUPST_POWER_STATUS         - Current power status
+# NUPST_BATTERY_CAPACITY     - Battery percentage (0-100)
+# NUPST_BATTERY_RUNTIME      - Estimated runtime in minutes
+# NUPST_THRESHOLDS_EXCEEDED  - "true" if below configured thresholds
+# NUPST_TRIGGER_REASON       - "powerStatusChange" or "thresholdViolation"
+# NUPST_BATTERY_THRESHOLD    - Configured battery threshold percentage
+# NUPST_RUNTIME_THRESHOLD    - Configured runtime threshold in minutes
+# NUPST_TIMESTAMP            - Unix timestamp (milliseconds since epoch)
+
+# ==============================================================================
+# EXAMPLE: Log the event
+# ==============================================================================
+LOG_FILE="/var/log/nupst-actions.log"
+
+echo "========================================" >> "$LOG_FILE"
+echo "NUPST Action Triggered: $(date)" >> "$LOG_FILE"
+echo "----------------------------------------" >> "$LOG_FILE"
+echo "UPS: $NUPST_UPS_NAME ($NUPST_UPS_ID)" >> "$LOG_FILE"
+echo "Power Status: $POWER_STATUS" >> "$LOG_FILE"
+echo "Battery: $BATTERY_CAPACITY%" >> "$LOG_FILE"
+echo "Runtime: $BATTERY_RUNTIME minutes" >> "$LOG_FILE"
+echo "Trigger Reason: $NUPST_TRIGGER_REASON" >> "$LOG_FILE"
+echo "Thresholds Exceeded: $NUPST_THRESHOLDS_EXCEEDED" >> "$LOG_FILE"
+echo "========================================" >> "$LOG_FILE"
+
+# ==============================================================================
+# EXAMPLE: Send email notification
+# ==============================================================================
+# if [ "$NUPST_TRIGGER_REASON" = "thresholdViolation" ]; then
+#   echo "ALERT: UPS $NUPST_UPS_NAME battery critical!" | \
+#     mail -s "UPS Battery Critical" admin@example.com
+# fi
+
+# ==============================================================================
+# EXAMPLE: Gracefully shutdown virtual machines
+# ==============================================================================
+# if [ "$NUPST_POWER_STATUS" = "onBattery" ] && [ "$NUPST_THRESHOLDS_EXCEEDED" = "true" ]; then
+#   echo "Shutting down VMs..." >> "$LOG_FILE"
+#   # virsh shutdown vm1
+#   # virsh shutdown vm2
+#   # Wait for VMs to shutdown
+#   # sleep 120
+# fi
+
+# ==============================================================================
+# EXAMPLE: Call external API/service
+# ==============================================================================
+# curl -X POST https://monitoring.example.com/ups-alert \
+#   -H "Content-Type: application/json" \
+#   -d "{
+#     \"upsId\": \"$NUPST_UPS_ID\",
+#     \"upsName\": \"$NUPST_UPS_NAME\",
+#     \"powerStatus\": \"$POWER_STATUS\",
+#     \"batteryCapacity\": $BATTERY_CAPACITY,
+#     \"batteryRuntime\": $BATTERY_RUNTIME,
+#     \"triggerReason\": \"$NUPST_TRIGGER_REASON\"
+#   }"
+
+# ==============================================================================
+# EXAMPLE: Remote shutdown via SSH with password
+# ==============================================================================
+# You can implement custom shutdown logic for remote systems
+# that require password authentication or webhooks
+#
+# if [ "$NUPST_THRESHOLDS_EXCEEDED" = "true" ]; then
+#   # Call a webhook with a secret password/token
+#   curl -X POST "https://remote-server.local/shutdown?token=YOUR_SECRET_TOKEN"
+#
+#   # Or use SSH with password (requires sshpass)
+#   # sshpass -p 'your-password' ssh user@remote-server 'sudo shutdown -h +5'
+# fi
+
+# ==============================================================================
+# EXAMPLE: Conditional logic based on battery level
+# ==============================================================================
+# if [ "$BATTERY_CAPACITY" -lt 20 ]; then
+#   echo "Battery critically low! Immediate action needed." >> "$LOG_FILE"
+# elif [ "$BATTERY_CAPACITY" -lt 50 ]; then
+#   echo "Battery low. Preparing for shutdown." >> "$LOG_FILE"
+# else
+#   echo "Battery acceptable. Monitoring." >> "$LOG_FILE"
+# fi
+
+# ==============================================================================
+# EXAMPLE: Different actions for different trigger reasons
+# ==============================================================================
+# case "$NUPST_TRIGGER_REASON" in
+#   powerStatusChange)
+#     echo "Power status changed to: $POWER_STATUS" >> "$LOG_FILE"
+#     # Send notification but don't take drastic action yet
+#     ;;
+#   thresholdViolation)
+#     echo "Thresholds violated! Taking emergency action." >> "$LOG_FILE"
+#     # Initiate graceful shutdowns, save data, etc.
+#     ;;
+# esac
+
+# Exit with success
+exit 0