Check systemd's Battery Gate Before Early Boot Powers Off

A laptop with a dying battery powers itself off before you even reach the desktop, and systemd-battery-check.service is why. This guide covers reading the unit safely, understanding why it forces a power-off, and bypassing it for one boot when the hardware detection is wrong. Examples match systemd 255.4-1ubuntu8.17 on this machine. Allow about fifteen minutes.

• You need: a shell for the read-only steps; administrator access for a persistent boot-loader change.
• Do not test the service casually. Its unit has FailureAction=poweroff-force, which can power the machine off if the check fails.

1. Confirm the installed command and version

Start with the ordinary, read-only checks. They show which package and executable your commands refer to:

$ dpkg-query -W -f='${Package} ${Version}
' systemd
systemd 255.4-1ubuntu8.17
$ /usr/lib/systemd/systemd-battery-check --version
systemd 255 (255.4-1ubuntu8.17)

The binary is normally /usr/lib/systemd/systemd-battery-check. In this installed release it accepts only --help and --version as command-line options; the useful battery decision comes from running it without either.

2. Read the unit without starting it

$ systemctl cat systemd-battery-check.service
# /usr/lib/systemd/system/systemd-battery-check.service
[Unit]
Description=Check battery level during early boot
ConditionVirtualization=no
ConditionDirectoryNotEmpty=/sys/class/power_supply/
ConditionKernelCommandLine=!systemd.battery-check=0
AssertPathExists=/etc/initrd-release
DefaultDependencies=no
...
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/lib/systemd/systemd-battery-check
FailureAction=poweroff-force

Three details explain most surprises:

• It targets the initial RAM disk, so /etc/initrd-release must exist in that environment.
• It skips on virtualisation or when there is no power-supply directory.
• It skips when the kernel command line has systemd.battery-check=0. These are conditions, not settings to edit in the unit file.

The unit is Type=oneshot and remains active after a successful run. It has no ordinary enablement workflow: on a normal installation, systemctl is-enabled reports static. Whether it appears in the boot transaction at all is down to early-boot generator or initrd packaging.

3. Check the service state safely

Ask systemd to report the unit's current state. This does not start, stop or reload anything:

$ systemctl show systemd-battery-check.service \
    -p FragmentPath -p Type -p ExecStart -p FailureAction \
    -p ConditionResult -p AssertResult -p ActiveState -p SubState
Type=oneshot
ExecStart={ path=/usr/lib/systemd/systemd-battery-check ; ... }
FailureAction=poweroff-force
ActiveState=inactive
SubState=dead

On a running host, ConditionResult=no or AssertResult=no means systemd skipped the service because an environmental requirement was not met, which is different from a battery failure. Use systemctl status systemd-battery-check.service for a more readable explanation, and inspect the initrd's unit state when diagnosing an actual boot.

4. Understand the pass and fail decision

Run the executable directly only as a controlled diagnostic, never as a substitute for understanding the unit's power-off action. It returns success when it sees AC power or a battery charge above 5 percent, and a non-zero status otherwise:

$ /usr/lib/systemd/systemd-battery-check
$ status=$?
$ printf 'battery check exit status: %s\n' "$status"
battery check exit status: 0

The command normally prints no status report, so capture $? immediately. Zero here means the check passed for the power-supply data visible to that process, not that the battery is healthy, that the charger will stay connected, or that the service was even part of this boot.

5. Bypass a false detection for one boot

When the check misreads the battery or AC state, add the exact kernel parameter systemd.battery-check=0 to one boot entry. This makes the program return success immediately and lets the service succeed without checking capacity or AC power.

• Edit the boot entry temporarily at a graphical boot menu and append the parameter to the kernel command line. The exact key varies by boot loader.
• Remove it before the next boot unless you deliberately need the bypass again.

After boot, verify what the kernel actually received:

$ tr ' ' '\n' < /proc/cmdline | grep '^systemd\.battery-check='
systemd.battery-check=0

No output means the temporary edit was not applied. Do not treat an absent result as proof that the service ran; it only says this particular override is not in the current command line.

6. Make the override persistent only if you accept the trade-off

A persistent override belongs in the boot-loader configuration, not in a copied unit file. Use your distribution's boot-loader tooling and record the original kernel command line first. On a GRUB-based system, check the current setting before editing:

$ grep '^GRUB_CMDLINE_LINUX' /etc/default/grub

Editing /etc/default/grub and rebuilding its menu needs elevated privileges and affects future boots. The exact command differs by distribution, so do not paste a guessed update command from another system. If you go ahead, keep the parameter inside the existing quoted kernel-argument value, rebuild the boot-loader configuration using your distribution's documented command, reboot once, and check /proc/cmdline as above.

To undo it, remove only systemd.battery-check=0 from the same kernel-argument setting, rebuild the boot-loader configuration again, and confirm the parameter is gone after reboot. Do not delete the whole line: it may hold unrelated boot and security settings.