apcupsd (UPS Daemon)

Networking 2026-08-28

apcupsd monitors APC Uninterruptible Power Supplies and triggers a graceful system shutdown when battery runs low. It is pre-installed on Shani OS. Connect your APC UPS via USB — most models are detected automatically with no additional drivers.

Not active by default. Enable it only if a UPS is connected.

Enable

sudo systemctl enable --now apcupsd

systemctl status apcupsd

Configuration

Edit /etc/apcupsd/apcupsd.conf:

# UPS name (label only — for log messages)
UPSNAME myups

# Communication device — USB is most common for desktop APC units
UPSCABLE usb
UPSTYPE usb
DEVICE                    # leave blank for USB; apcupsd auto-detects

# Shutdown thresholds
BATTERYLEVEL 10           # shut down when battery drops to 10%
MINUTES 5                 # or when < 5 minutes runtime remains

# How long to wait on battery before shutdown (0 = immediate)
TIMEOUT 0

# Where to write the status file
STATFILE /var/log/apcupsd.status

# Event scripts directory
SCRIPTDIR /etc/apcupsd

# Network Information Server — allows remote status queries
NISIP 127.0.0.1           # 0.0.0.0 to allow LAN access
NISPORT 3551

After editing:

sudo systemctl restart apcupsd

Status & Monitoring

# Live UPS status (battery level, load, runtime estimate, events)
apcaccess status

# Watch status continuously
watch -n 5 apcaccess status

# View event log (power failures, battery tests, shutdowns)
sudo tail -f /var/log/apcupsd.events

# Run a battery self-test
apctest

Key fields in apcaccess status:

Field	Meaning
`STATUS`	`ONLINE`, `ONBATT`, `LOWBATT`
`BCHARGE`	Battery charge percentage
`TIMELEFT`	Estimated runtime on battery
`LOADPCT`	Load on the UPS as percentage of capacity
`LINEV`	Input mains voltage
`BATTV`	Battery voltage

Event Scripts

apcupsd runs scripts from /etc/apcupsd/ when power events occur. The key events and their script names:

Event	Script	Triggered when
Power failure	`onbattery`	Mains power lost
Power restored	`offbattery`	Mains power returns
Low battery	`doshutdown`	Battery/runtime threshold reached
Battery test done	`endapctest`	Self-test completes

Edit /etc/apcupsd/onbattery to send a notification when power fails:

#!/bin/sh
echo "Power failure at $(date)" | mail -s "UPS: On Battery" root

Make scripts executable:

sudo chmod +x /etc/apcupsd/onbattery

The mail example above requires mailx to be installed and configured. To log events to the journal instead: logger -t apcupsd "on battery"

Network Status Server

apcupsd includes a small status server (NIS) on port 3551. Query a remote apcupsd instance from another machine:

# Query local daemon
apcaccess status localhost

# Query a remote machine (must have NISIP 0.0.0.0 in config)
apcaccess status 192.168.1.10:3551

Open the firewall if you need LAN access to the status server:

sudo firewall-cmd --add-port=3551/tcp --permanent
sudo firewall-cmd --reload

Troubleshooting

Issue	Solution
`apcupsd` won't start	Check `journalctl -u apcupsd`; common cause is wrong `UPSCABLE`/`UPSTYPE` — use `usb` for USB-connected APC units
`apcaccess` returns `NETWORK ERROR`	Daemon isn't running or NIS is disabled — check `systemctl status apcupsd`
UPS not detected	Run `lsusb` to confirm the UPS appears; APC USB devices use the standard HID UPS class — no extra driver needed
Shutdown not triggering on low battery	Check `BATTERYLEVEL` and `MINUTES` thresholds in the config; test with `apctest` → option 7 (simulate power failure)
`STATFLAG` shows `0x060000` (communication lost)	Cable issue or wrong port — unplug/replug USB; check `DEVICE` is blank for USB