How to Detect AC Mains Power and Battery State in Ubuntu Using systemd-ac-power

In modern systems administration, background automation scripts, unattended system upgrades, and scheduled maintenance tasks must be aware of host electrical sources. Initiating resource-intensive operations—such as full filesystem backups, OS package upgrades via APT, ZFS scrubbing, or heavy container compilations—while a laptop or remote battery-backed edge server is operating on battery reserve can rapidly deplete stored energy, risking ungraceful power failure and filesystem corruption. In Ubuntu and systemd-based Linux systems, administrators and automation engineers can query power supply state natively using the systemd-ac-power utility. By integrating this tool into shell scripts and systemd unit condition directives, tasks can automatically defer execution until stable AC mains power is restored.

Understanding Linux Power Supply Abstraction and systemd-ac-power

The Linux kernel exposes physical power telemetry through the /sys/class/power_supply/ sysfs directory. Kernel drivers communicate with Advanced Configuration and Power Interface (ACPI) tables, Power Management ICs (PMICs), or battery fuel gauges, populating device nodes categorized by type (e.g., Mains, Battery, USB).

Rather than requiring administrators to write complex shell parsers to crawl sysfs nodes, systemd-ac-power provides a standardised, binary status check:

• Exit Code 0 (Success): Indicates that the system is currently connected to AC mains power (or that no battery is present, as in standard desktop and rackmount server hardware).
• Exit Code 1 (Failure): Indicates that the system is running on battery power (discharging).
• Exit Code > 1: Indicates a system error or inability to query the power subsystem.

Basic Usage and Command Syntax

The simplest way to use systemd-ac-power is to run it directly from a terminal prompt:

systemd-ac-power

By default, systemd-ac-power operates silently, communicating state strictly through its process exit code. You can inspect the returned code immediately using the shell $? variable:

systemd-ac-power
echo "Exit code: $?"

If the command outputs 0, the machine is drawing AC power. If it returns 1, the machine is discharging on battery.

Enabling Verbose Terminal Output

For interactive troubleshooting or human-readable reporting, append the -v (or --verbose) flag:

systemd-ac-power -v

The utility outputs a direct string description:

yes

If the device is unplugged and discharging, it outputs:

no

Integrating Power Detection into Shell Automation Scripts

Because systemd-ac-power follows standard POSIX exit status conventions, it integrates cleanly into if conditionals within Bash and POSIX shell scripts. The following script demonstrates guarding an intensive disk backup workflow:

#!/bin/bash
set -euo pipefail

echo "[*] Checking power status before initiating system backup..."

if ! systemd-ac-power; then
    echo "[!] WARNING: System is running on battery power."
    echo "[!] Aborting backup to conserve battery reserve."
    exit 0
fi

echo "[+] AC mains power confirmed. Commencing filesystem synchronization..."
rsync -aAXv --delete /home/ /mnt/backup/home/
echo "[+] Backup completed successfully."

Conditioning Systemd Services with ConditionACPower

In addition to standalone CLI invocation, systemd natively integrates AC power checks into its service manager via unit conditions. Rather than launching a service only to have it abort itself, you can configure systemd to skip unit execution entirely when on battery.

Configuring a Service Unit with ConditionACPower

Open or create a systemd service unit file (e.g., /etc/systemd/system/nightly-backup.service):

[Unit]
Description=Nightly Disk Backup Job
ConditionACPower=true

[Service]
Type=oneshot
ExecStart=/usr/local/bin/run-heavy-backup.sh

[Install]
WantedBy=multi-user.target

When the systemd timer triggers this service:

• If the machine is plugged into AC power, ConditionACPower=true evaluates to true, and the service starts normally.
• If the machine is running on battery, systemd marks the condition as failed and skips the service cleanly without logging an error or alerting monitoring alarms.

Auditing Underlying Power Supply Sysfs Nodes

To verify the physical kernel device nodes that systemd-ac-power inspects behind the scenes, query the sysfs power supply directory:

# List all power supply hardware detected by kernel
ls -la /sys/class/power_supply/

# Inspect AC adapter online status (1 = connected, 0 = disconnected)
cat /sys/class/power_supply/AC/online 2>/dev/null || cat /sys/class/power_supply/ADP1/online 2>/dev/null

Debugging Condition Failures via journalctl

To verify why a scheduled service was skipped or executed, query the systemd journal for unit condition logs:

journalctl -u nightly-backup.service --grep="Condition"

If skipped, systemd logs:

systemd[1]: Starting Nightly Disk Backup Job...
systemd[1]: nightly-backup.service: Skipped due to 'ConditionACPower=true'.

By leveraging systemd-ac-power and the declarative ConditionACPower directive, Ubuntu administrators ensure that high-impact maintenance operations execute safely without threatening battery life or causing data corruption during power interruptions.