APCCONTROL(8)

👑 APCCONTROL(8) — the manual page, but make it make sense 💅

okay bestie, welcome to APCCONTROL(8) from the System Manager's Manual 🎀 this is part one of two so don't go anywhere, we're just getting started ✨

---

🌸 NAME 🌸

apccontrol — the event handler script for apcupsd(8). she's the one who takes action when your UPS starts acting up, no cap 🫶

---

⭐ SYNOPSIS ⭐

apccontrol { <event> <ups-name> <connected> <powered> }

---

💖 DESCRIPTION 💖

so here's the vibe. when apcupsd(8) clocks something sus coming off the UPS it's monitoring, it fires off an event, and that event usually means one or more calls to the apccontrol shell script. every event makes apccontrol do a specific thing. and the default behaviour? honestly iconic, it's sane for basically every event apcupsd is likely to run into. but — and this is the good part — you can change the behaviour of every single action. every one. periodt 💅

when apcupsd spots an event, it calls the apccontrol script with these four arguments, in this order:

• event — the event that just happened. go peep the list of possible events below 👇
• ups-name — the name of the UPS as specified in the /etc/apcupsd/apcupsd.conf configuration file. and like, not the name in the EEPROM of a smart UPS, okay? different thing, don't get it twisted 🙈
• connected — this is 1 if apcupsd is connected to the UPS via a serial or USB port. on a slave machine where apcupsd isn't directly connected to the UPS? then this value is 0.
• powered — this is 1 if the computer running apcupsd is powered by the UPS, and 0 if not. heads up though: this is not currently implemented and always defaults to 0. yeah. she's aspirational 😭

events get sent to the system log and, optionally, to the temporary events file (/etc/apcupsd/apcupsd.events). they also trigger a call to apccontrol, which in turn will call any scripts you've dropped into the /etc/apcupsd directory. the whole pipeline is giving main character energy fr fr 🔥

---

✨ LIST OF EVENTS AND DEFAULT ACTIONS ✨

• annoyme — apcupsd fires this one when a shutdown is scheduled and the time specified by the ANNOYME configuration directive in the /etc/apcupsd/apcupsd.conf file has expired.

Default action — sends "Power problems please logoff." to wall(1) and then exits. she's annoying you on purpose, that's the whole point 🗣️

• battattach — apcupsd fires this when it detects the UPS battery has been reconnected after a battdetach event.

Default action: does nothing. chill. unbothered. 🌸

• battdetach — apcupsd fires this when it detects the UPS battery has been disconnected.

Default action: does nothing. also just vibing 🦋

• changeme — apcupsd fires this when it detects the utility power is on, but the battery is not functioning correctly. this one repeats every 9 hours. every. nine. hours. she will not let it go 😤

Default action — sends "Emergency! UPS batteries have failed Change them NOW" to wall and then exits. she is yelling. respectfully. 💀

• commfailure — apcupsd fires this each time it loses communication with the monitored UPS. note: this event is not detected on simple signalling UPSes like the Back-UPS 650.

Default action — sends "Communications with UPS lost." to wall and then exits. ghosted by your own UPS 😭

• commok — apcupsd fires this after a commfailure event, when communication with the UPS is re-established.

Default action — sends "Communications with UPS restored." to wall and then exits. we love a comeback story 🫶

• doreboot — this event is deprecated and should not be used. like, do not. ⚠️

Default action — sends "Beginning Reboot Sequence" to wall and then calls shutdown(8) with the "-r now" command line arguments to reboot the computer.

• doshutdown — apcupsd fires this to shut the computer down when the UPS is running on battery power and one of the limits (time, run, load) has been reached.

Default action — sends "Beginning Shutdown Sequence" to wall and then calls shutdown(8) with the command line arguments "-h now" to shut the computer down.

• emergency — apcupsd fires this when the UPS is on battery power, the battery is low, and the utility power is on. that combination? a sure sign of battery failure 🚨

Default action — sends "Emergency Shutdown. Possible UPS battery failure." to wall. immediately after this, apcupsd generates a doshutdown event to shut the system down.

• failing — apcupsd fires this when the UPS is running on batteries and the UPS sets the low battery signal, indicating battery power is nearly exhausted. after this event, apcupsd will immediately generate a doshutdown event.

Default action — sends "UPS battery power exhausted. Doing shutdown." to wall and then exits.

• killpower — apcupsd does not normally generate this event. instead, it's invoked directly from the system halt script as 'apccontrol killpower', because the killpower event needs to happen as late in system shutdown as possible. she's the final boss of shutdown 🧚

Default action — sends "UPS now committed to shut down" to wall, waits for 10 seconds, and then issues the command "apcupsd --killpower" to put the UPS into hibernate mode and shut off power to the connected equipment. in the case of a smart UPS, the UPS will then wait for the expiry of any configured shutdown time delay specified by the SLEEP configuration directive. in hibernate mode, the UPS will restore utility power to the connected equipment subject to the values specified for the RETURNCHARGE and WAKEUP configuration directives. yes that's a lot of directives, write them down 📝

• loadlimit — apcupsd fires this when the battery discharge limit specified by the BATTERYLEVEL configuration directive has been reached.

Default action — sends "UPS battery discharge limit reached. Doing shutdown" to wall and then exits. after this event, apcupsd will immediately generate a doshutdown event.

• mainsback — apcupsd fires this when the utility power returns after a powerout event. whether the doshutdown event got generated depends on the parameters you've defined and how long the outage was. and listen: attempting cancellation of a doshutdown event should never be tried, because it's very unlikely to succeed and will almost certainly leave your computer in an indeterminate state. do not do it. that's the rule 🙅

Default action — if the file /var/run/powerfail exists, sends "Continuing with shutdown." to wall and then exits. otherwise, does nothing.

• onbattery — apcupsd fires this if a power failure has been detected and the UPS is still on battery power at the expiry of the delay specified by the ONBATTERYDELAY configuration directive.

Default action — sends "Power failure. Running on UPS batteries." to wall and then exits.

• offbattery — apcupsd fires this when the utility power returns, if and only if the onbattery event has been generated.

Default — sends ""Power has returned..." to wall and then exits. (yes, those quotes are exactly like that in the original, we don't fix, we report 💅)

• powerout — apcupsd fires this as soon as it detects the UPS has switched to battery power, and it's not a self-test.

Default action — does nothing. just a lil heads up ✨

• remotedown — apcupsd fires this on a slave machine when it detects either (1) that the master has shut down, or (2) that an onbattery event has occurred and communication with the master has been lost.

Default action: sends "Remote Shutdown. Beginning Shutdown Sequence." to wall and exits. immediately after this, apcupsd generates a doshutdown event to shut the system down.

• runlimit — apcupsd fires this when the remaining runtime limit specified by the MINUTES configuration directive expires while the UPS is on battery power as the result of a utility power outage. the remaining runtime is internally calculated by the UPS and monitored by apcuspd. (that's how it's spelled in the original, iykyk 😌)

Default action — sends "UPS battery runtime percent reached. Doing shutdown." to wall and then exits. after this event, apcupsd will immediately generate a doshutdown event.

• timeout — apcupsd fires this when the time specified by the TIMEOUT configuration directive expires while the UPS is on battery power as the result of a utility power outage. this configuration directive is not normally used with smart UPSes, which would instead rely on the more reliable remaining runtime (MINUTES) or the battery level (BATTERYLEVEL) configuration directives. smart UPSes said "we have better options" 💅

Default action — send "UPS battery runtime limit exceeded. Doing shutdown." to wall and then exits. after this event, apcupsd will immediately generate a doshutdown event.

• startselftest — apcupsd fires this when it detects the start of a UPS self test.

Default action: does nothing. she's just watching 🧚

• endselftest — apcupsd fires this when it detects the end of a UPS self test.

Default action: does nothing. all done, no notes 🌈

---

💅 CUSTOMISING EVENT ACTIONS 💅

Do not modify apccontrol directly, bestie, because it will be overwritten the next time you upgrade to a new release of apcupsd. we are NOT losing your hard work to an upgrade. never 😭

the recommended way to customise an event action is simply to create an executable program or script file with the same name as the event, and put that file in the /etc/apcupsd directory. now, when the selected event occurs, apccontrol will execute your program or script. so easy. so clean. obsessed 🫶

if you want apccontrol to also execute its default action for the selected event, your program or script should exit with an exit status of 0 (zero). both things happen, everyone eats 🍓

if you do not want apccontrol to also execute its default action for the selected event, your program or script must exit with an exit status of 99. but be aware — if you completely override the default action, you must ensure the proper shutdown of your computer if this is necessary. that's on you now, queen 👑

some sample scripts (changeme, commfailure, commok, offbattery and onbattery) that email messages to root instead of broadcasting messages to all logged-in users may be found in /etc/apcupsd after an installation, and also in the platforms/etc directory of the apcupsd source code. free templates, go off 💖

---

🎀 FILES 🎀

• /etc/apcupsd/apccontrol

---

okay that's the first half, stay tuned for part two, we're not done yet ✨

👀 SEE ALSO — go read these too bestie

Like, don't just stop here, the lore goes deep:

• wall(1) — for shouting at everybody's terminal at once 💬
• apcupsd.conf(5) — the config file that runs the whole show 🎀
• apcupsd(8) — the daemon herself, the main character 👑
• shutdown(8) — what actually happens when the power dips 💀

---

Also?? There's a whole HTML apcupsd manual that's installed on your system, and if you don't have it locally you can grab it online at http://www.apcupsd.org/ ✨ It's giving documentation, it's giving resources, it's giving everything you need fr fr.

---

💖 AUTHORS — the icons who made this happen

🎀 This page

• Trevor Roydhouse — wrote the page you're literally reading rn 🫶

🦋 Software

• Adam Kropelin — current Project Manager and Code Maintainer 🧚 (yes, present tense, he's that girl)
• Kern Sibbald — former Project Manager and Code Maintainer 🌸
• Riccardo Facchetti — former Project Manager and Code Maintainer 🌈
• Andre M. Hedrick — Project Founder and former Code Maintainer ⭐ like, the actual origin story

💜 Contributors

• An enormous number of users who have devoted their time and energy to this project — thanks 🙏😭 no cap, genuinely, every single one of them ate 💅

---

okay bestie that's the whole page, you made it to the end, iconic behavior, 10/10 no notes 🎀✨

apccontrol v3.14.6 — January 10, 2009 💖 (yes it's been iconic since 2009 and it still slays, we love a timeless queen 👑)