apcupsd alert integration

When apcupsd detects a UPS state change it calls apccontrol, which runs the executable in /etc/apcupsd that has the same name as the event and passes the UPS name as the first argument. apcupsd has no native webhook, so an event script pushes the events to Flashduty in the Standard Alert Event format: onbattery triggers an alert and offbattery recovers it.

Configure in apcupsd

Create the push script on the apcupsd host

Where: The host running apcupsd › /etc/apcupsd/flashduty-notify.sh

Item	Value
File	Create `/etc/apcupsd/flashduty-notify.sh` and make it executable (`chmod +x`)
`URL` in the script (required)	`{integration_url}`, the push URL of the integration
Dependency	The host needs `curl`

#!/bin/sh
# apcupsd event hook: forward a UPS event to a Flashduty Standard Alert Event integration.
# Usage: flashduty-notify.sh <event> <ups-name>
URL='{integration_url}'

EVENT="$1"
UPS="${2:-unknown}"

case "$EVENT" in
  onbattery)  KEY=power;   STATUS=Warning;  TEXT="on battery" ;;
  failing|timeout|loadlimit|runlimit)
              KEY=power;   STATUS=Critical; TEXT="battery limit reached ($EVENT)" ;;
  offbattery|mainsback)
              KEY=power;   STATUS=Ok;       TEXT="utility power restored" ;;
  commfailure) KEY=comm;   STATUS=Critical; TEXT="communication lost" ;;
  commok)     KEY=comm;    STATUS=Ok;       TEXT="communication restored" ;;
  changeme|emergency)
              KEY=battery; STATUS=Critical; TEXT="battery failure ($EVENT)" ;;
  battdetach) KEY=battconn; STATUS=Warning; TEXT="battery disconnected" ;;
  battattach) KEY=battconn; STATUS=Ok;      TEXT="battery reconnected" ;;
  *) exit 0 ;;
esac

esc() { printf '%s' "$1" | tr '\n\r\t' '   ' | sed 's/\\/\\\\/g; s/"/\\"/g'; }

JSON=$(printf '{"title_rule":"UPS %s: %s","event_status":"%s","alert_key":"apcupsd:%s:%s","description":"apcupsd event %s on UPS %s","labels":{"resource":"%s","check":"%s","apcupsd_event":"%s"}}' \
  "$(esc "$UPS")" "$TEXT" "$STATUS" "$(esc "$UPS")" "$KEY" "$(esc "$EVENT")" "$(esc "$UPS")" "$(esc "$UPS")" "$KEY" "$(esc "$EVENT")")

curl -fsS -m 10 -X POST -H 'Content-Type: application/json' -d "$JSON" "$URL" >/dev/null
exit 0

Hook the script into the apcupsd events

Where: The host running apcupsd › /etc/apcupsd/ (executable files named after the events)apcupsd’s customization mechanism (see the apccontrol manual): create an executable file named after the event in /etc/apcupsd. apccontrol runs it first when the event occurs; if it exits with status 0, apccontrol continues with the event’s default action, and exit status 99 skips the default action. The script above always exits with 0, so it does not change apcupsd’s default behavior (including the shutdown sequence).The command below creates one event file per event that only calls the push script. Events that already have a file in the directory (the onbattery, offbattery, commfailure, commok and changeme sample scripts installed by apcupsd are such files) are not overwritten; the command tells you to add the call line near the top of the file yourself:

for e in onbattery offbattery mainsback failing timeout loadlimit runlimit commfailure commok changeme emergency battdetach battattach; do
  f="/etc/apcupsd/$e"
  if [ -e "$f" ]; then
    echo "$f already exists: add the line  /etc/apcupsd/flashduty-notify.sh $e \"\$1\"  near its top"
  else
    printf '#!/bin/sh\n/etc/apcupsd/flashduty-notify.sh %s "$1"\nexit 0\n' "$e" > "$f"
    chmod +x "$f"
  fi
done

How events map to alerts:

apcupsd event	Meaning (apcupsd manual)	Severity	Alert Key
`onbattery`	After a power failure, the UPS is still on battery when `ONBATTERYDELAY` expires	Warning	`apcupsd:<UPS name>:power`
`failing`, `timeout`, `loadlimit`, `runlimit`	Battery exhausted or a time, charge or remaining-runtime limit reached; a shutdown follows	Critical	`apcupsd:<UPS name>:power`
`offbattery`, `mainsback`	Utility power is back	Recovery	`apcupsd:<UPS name>:power`
`commfailure`	Communication with the UPS lost	Critical	`apcupsd:<UPS name>:comm`
`commok`	Communication with the UPS re-established	Recovery	`apcupsd:<UPS name>:comm`
`changeme`, `emergency`	Battery failure (utility power on but the battery is not working, or low battery while utility power is on)	Critical	`apcupsd:<UPS name>:battery`
`battdetach`	The UPS battery was disconnected	Warning	`apcupsd:<UPS name>:battconn`
`battattach`	The battery was reconnected	Recovery	`apcupsd:<UPS name>:battconn`

powerout (generated as soon as the UPS switches to battery) is not hooked: onbattery only fires when the outage lasts longer than ONBATTERYDELAY, which avoids alerts for momentary power dips.

Run the event scripts by hand on the apcupsd host and confirm

Where: Terminal on the host running apcupsdRun the event scripts by hand, first a trigger and then a recovery:

/etc/apcupsd/onbattery myups
/etc/apcupsd/offbattery myups

In Flashduty you should first see the alert UPS myups: on battery and then see it recover; the integration shows Latest event time, which means the setup works. Running onbattery by hand also runs whatever else the event file already contains; to test only the push, run /etc/apcupsd/flashduty-notify.sh onbattery myups directly.

Recovery and deduplication

onbattery, the failure events (failing, timeout, loadlimit, runlimit), offbattery and mainsback share the Alert Key apcupsd:<UPS name>:power: onbattery triggers the alert, a following failure event raises it to Critical, and it recovers when utility power returns
commfailure and commok, and battdetach and battattach, are paired
changeme and emergency have no matching recovery event. While a battery fault persists, apcupsd repeats changeme every 9 hours. After replacing the battery, close the alert manually in Flashduty, or enable the auto-resolve timeout on the channel, starting with 24 hours; if the battery has not been replaced, the next changeme triggers the alert again
Alerts of several UPS units do not affect each other: the Alert Key contains the UPS name (the name configured in apcupsd.conf)

Troubleshooting

No alert arrives: confirm the file named after the event exists in /etc/apcupsd and is executable, and that URL in flashduty-notify.sh is correct; run the event file by hand and check the output
The alert does not recover: confirm the recovery events (offbattery, mainsback, commok, battattach) are hooked too
Flashduty returns a parameter error: confirm URL is the full push URL, including integration_key

For more details, see the apcupsd apccontrol manual.

Quick Start

Product Comparison

Channels

Incident Management

Post-Mortem

Status Page

Analytics

Integration Settings

Configuration

Advanced

Integrations

Best Practices

In Flashduty On-call

Use a dedicated integration

Use a shared integration

Configure in apcupsd

Recovery and deduplication

Troubleshooting