nupst/example-action.sh

#!/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