Gate Scripts on Mains Power with systemd-ac-power

A backup that starts on battery and loses power halfway through is worse than skipping it, and systemd-ac-power guards against exactly that. You will finish with a read-only check for external power, a shell condition that acts on the result, and a separate check for a critically low, discharging battery. The examples use systemd-ac-power from systemd 255; the installed package here is systemd 255.4-1ubuntu8.17.

Allow about ten minutes. You need a Linux shell and the systemd utilities already installed. Nothing in this guide changes power settings, services or persistent configuration, so the commands normally need no elevated privileges.

1. Confirm the installed command

First check which executable your shell will run and ask it for its version. These are ordinary, read-only commands:

$ command -v systemd-ac-power
/usr/bin/systemd-ac-power
$ systemd-ac-power --version
systemd 255 (255.4-1ubuntu8.17)
...

The feature set matters here. --verbose was added in systemd 253 and --low in systemd 254, so an older installation may accept the basic command but reject one of those options.

Checkpoint: if the command is missing, stop here and install or repair the systemd package through your distribution's normal package management. Do not copy a binary from another host just to make this check pass.

2. Run the silent AC-power test

With no options, the command communicates entirely through its exit status. It returns zero when it detects the system is running on AC power, and non-zero otherwise. A successful check is intentionally silent:

$ systemd-ac-power
$ printf 'exit status: %s\n' "$?"
exit status: 0

The exact status depends on the machine at the moment you run it. If the host is on battery, the first command still prints nothing, but the second line reports a non-zero value. Do not use the presence or absence of text as the result: there is none either way.

This is handy as a one-off guard around expensive or disruptive work. The command itself does not switch power sources, pause jobs or notify a service.

3. Put the result in a shell condition

Use the command directly as the condition. This keeps the status attached to the test and avoids accidentally checking the exit status of a later command instead:

$ if systemd-ac-power; then
>     printf '%s\n' 'External power detected; safe to continue.'
> else
>     printf '%s\n' 'Running on battery or power could not be detected.' >&2
> fi
External power detected; safe to continue.

For a script that should do nothing on battery, put the work in the first branch:

if systemd-ac-power; then
    /usr/local/sbin/example-maintenance
else
    printf '%s\n' 'Skipping maintenance because AC power was not detected.' >&2
    exit 0
fi

Replace /usr/local/sbin/example-maintenance with a command you have already reviewed. The example treats a non-zero result conservatively: it does not distinguish battery operation from an inability to detect the power state at all.

4. Ask for a human-readable result

Use --verbose when testing interactively or recording a diagnostic. It prints the state instead of relying purely on the exit status:

$ systemd-ac-power --verbose
yes

On a battery-powered system the result is expected to differ. The useful contract for automation remains the exit status, because scripts should not need to parse display text. The short form, -v, does the same thing.

Keep the two uses separate in your head: silent mode is a Boolean for shell control flow, verbose mode is a report for people and logs. Running --verbose does not make the check more accurate, and it does not request elevated access.

5. Check for a very low, discharging battery

--low asks a different question entirely. It returns zero only when all batteries are currently discharging and are below five per cent of their maximum charge, and non-zero otherwise:

$ systemd-ac-power --low
$ printf 'low-battery status: %s\n' "$?"
low-battery status: 1

A non-zero result means the low-battery condition was not established. It does not mean the battery is exactly empty, and it does not mean the ordinary AC check would give the same answer. Test the condition explicitly:

if systemd-ac-power --low; then
    printf '%s\n' 'All batteries are discharging below 5%.' >&2
    exit 1
fi
printf '%s\n' 'The low-battery condition was not detected.'

That example exits with status 1 when the low condition is present, a reasonable safety stop for a wrapper script. Choose the policy that fits your job. If your script must distinguish a genuinely low battery from a missing or unsupported power reading, this command alone will not give you that extra diagnosis.

6. Use the check without changing systemd policy

systemd-ac-power is also a small way to investigate a unit condition based on AC power. It can help you understand behaviour tied to ConditionACPower= in a systemd unit, but running it does not edit that unit or reproduce every other condition the service manager evaluates.

If a service is skipped, inspect the unit and its journal separately. Do not add a new condition or reload a service just because this command reported the state you expected: those are configuration and service-management changes, and should go through the unit's normal rollback procedure.

If you do need to inspect a unit file, reading it is unprivileged as long as the file is readable:

$ systemctl cat example.service
$ systemctl show example.service -p ConditionACPower

These commands show the unit configuration. They do not prove a service was started, and they do not alter it. Use the actual unit name in place of example.service.

Common traps

Done means