Control systemd-backlight Brightness Restore Safely

A laptop lid closes, reopens, and the screen comes back far too bright or dim: that restore is [email protected] doing its job. This guide checks how it saves brightness at shutdown and restores it at boot, then walks through diagnosing or suppressing that restore safely. Examples match systemd 255.4-1ubuntu8.17 on this machine. Allow about 15 minutes.

• You need: a shell. Inspection is normally unprivileged; reading service logs or changing the kernel command line may need administrator access.

1. Check the installed service and helper

The service is a template. Its instance name identifies a backlight device or an LED device, and the unit passes that instance to the helper as backlight:DEVICE or leds:DEVICE. It runs early in boot, conflicts with shutdown, and stays loaded after the start action finishes.

$ systemctl cat [email protected]
# /usr/lib/systemd/system/[email protected]
[Unit]
Description=Load/Save Screen Backlight Brightness of %i
...
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/lib/systemd/systemd-backlight load %i
ExecStop=/usr/lib/systemd/systemd-backlight save %i

The displayed unit may include more lines, such as its boot condition and a 90-second timeout. The part that matters: ExecStart loads a saved value, ExecStop saves the current one.

$ test -x /usr/lib/systemd/systemd-backlight && echo installed
installed
$ /usr/lib/systemd/systemd-backlight --help
systemd-backlight save [backlight|leds]:DEVICE
systemd-backlight load [backlight|leds]:DEVICE

2. Find the device instance before reading status

List the device names udev knows about. A common laptop backlight is named something like intel_backlight, but do not copy that name unless this machine actually reports it.

$ udevadm info --export-db | grep '^E: ID_BACKLIGHT='

For a more focused inventory, look straight at the backlight and LED directories:

$ printf '%s\n' /sys/class/backlight/* /sys/class/leds/* 2>/dev/null

• Use the final directory name as DEVICE.
• Glob printed literally? That class has no matching entries, so the corresponding service instance has nothing to control.
• Remember the service does not create a device. A graphics driver, firmware setting or desktop session can expose a different interface entirely.

3. Inspect the matching unit without changing it

Replace DEVICE below with a name you found, keeping the prefix. This only asks systemd for recorded status and recent logs:

$ systemctl status 'systemd-backlight@backlight:DEVICE.service'
$ journalctl -b -u 'systemd-backlight@backlight:DEVICE.service' --no-pager

A successful load does not normally print a confirmation line from the helper. Look for the unit's result and any error explaining why the device or stored state could not be read.

• Unit absent? Check the instance spelling first.
• Unit skipped? The installed unit's ConditionPathExists=!/etc/initrd-release stops it running inside an initrd.

The saved brightness lives below /var/lib/systemd/backlight/. Inspect that directory rather than guessing a filename:

$ sudo find /var/lib/systemd/backlight -maxdepth 1 -type f -printf '%f\n'

4. Understand the brightness floor

While loading, systemd-backlight normally clamps the restored value to at least 1 or 5 percent of the device maximum, whichever is higher, so a saved value cannot leave a supported display effectively dark. A udev property named ID_BACKLIGHT_CLAMP controls that behaviour.

• Property unset: the normal floor applies.
• Property is exactly false: loading skips the clamp.
• Property holds a percentage, such as 30%: that percentage becomes the floor.

This is a device rule, not a systemd service option. Find the property on the relevant device before touching any udev rule:

$ udevadm info --query=property --path=/sys/class/backlight/DEVICE | grep '^ID_BACKLIGHT_CLAMP='
$ udevadm info --query=property --path=/sys/class/backlight/DEVICE | grep '^ID_BACKLIGHT_CLAMP=' || echo 'using the default clamp'

Changing a udev rule is a system configuration change that affects future boots. Make one change at a time, reload rules only through your distribution's normal procedure, and keep the old rule so you can restore it if the brightness turns unsafe or unusable.

5. Stop boot restoration while keeping shutdown saves

Need systemd to keep saving the current brightness but stop restoring an old value at boot? Use the kernel parameter systemd.restore_state=0. The default is effectively 1. Shutdown saves still happen with 0 set.

Check the current command line first:

$ tr ' ' '\n' < /proc/cmdline | grep '^systemd\.restore_state=' || echo 'restore_state is using its default'
restore_state is using its default

$ tr ' ' '\n' < /proc/cmdline | grep '^systemd\.restore_state='
systemd.restore_state=0
$ journalctl -b -u 'systemd-backlight@backlight:DEVICE.service' --no-pager

Undo the change by removing systemd.restore_state=0 from the boot entry and rebooting. Do not mask the template as a first response: masking blocks both its load and its save actions, which is a different result from what you probably want.

6. Recover from a bad brightness or failed load

If the display is usable but the restored level is wrong, set a comfortable brightness through the desktop controls or driver interface, then let a normal shutdown happen so the service can save it. Avoid repeatedly power-cycling while testing; that gives the service no clean shutdown to save from.

If the helper reports a permission error when run by hand, that is expected for a state directory owned by root; the service itself runs with system privileges. A manual test, when genuinely needed, must use the exact instance and elevated privileges:

$ sudo /usr/lib/systemd/systemd-backlight load backlight:DEVICE