Use systemd-boot-check-no-failures to Gate Boot Completion

You will finish with a safe way to inspect systemd-boot-check-no-failures.service, run its underlying check, and decide whether its very small test is suitable for your boot policy. The examples use systemd 255.4-1ubuntu8.17, installed here on an Ubuntu system.

Allow about fifteen minutes. You need a shell and access to the systemd manager. Reading status is normally unprivileged. Enabling or starting a system service changes boot behaviour and normally needs root privileges, so this guide keeps those commands in a separate step.

1. Check whether the service is in use

Start with read-only status queries. They do not enable, start, stop or reset anything:

$ systemctl is-enabled systemd-boot-check-no-failures.service
disabled
$ systemctl is-active systemd-boot-check-no-failures.service
inactive
$ systemctl cat systemd-boot-check-no-failures.service

The installed unit is a oneshot service. It runs /usr/lib/systemd/systemd-boot-check-no-failures, remains marked active after a successful run, and is installed as a requirement of boot-complete.target. It is disabled by default, so an inactive result is not itself an error.

Checkpoint: confirm that you are inspecting the expected unit and that its ExecStart path exists:

$ test -x /usr/lib/systemd/systemd-boot-check-no-failures && echo executable
executable

2. Run the helper without changing the system

The helper is the smallest reproducible part of the check. Run it directly as an ordinary command:

$ /usr/lib/systemd/systemd-boot-check-no-failures
Health check: 0 units have failed.

A message reporting zero failed units and exit status 0 is the healthy result. The number is not a general boot-quality score. This helper checks only whether systemd currently has failed units.

Capture the status explicitly when using it in a shell or diagnostic script:

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

If the helper prints a non-zero count, it exits non-zero. On this host the command printed Health check: 1 units have failed. and returned status 1 because certbot.service was failed. That is a genuine failed-unit result, not a request to restart the service automatically.

3. Identify what failed before changing anything

Use systemctl to list failed units, then inspect the named unit. These commands are read-only:

$ systemctl --failed --no-legend --no-pager
certbot.service loaded failed failed Certbot
$ systemctl status certbot.service --no-pager
$ journalctl -u certbot.service -b --no-pager

Your output will differ. Treat the unit name and its logs as the starting point for diagnosis. Do not clear a failure with systemctl reset-failed merely to make the boot check pass: that changes the manager's recorded state and hides the symptom without repairing its cause.

Checkpoint: rerun the helper only after you understand the failed unit. A zero result means that no units are currently recorded as failed; it does not prove that a service is correctly configured, reachable or ready for your application.

4. Understand what enabling it changes

The manual describes this service as an example for developing more fine-grained checks. When enabled, it is ordered before boot-complete.target. Its purpose is therefore to prevent that target being reached when the simple failed-unit test reports a problem.

Enabling the service is a persistent, boot-affecting change and requires elevated privileges:

$ sudo systemctl enable systemd-boot-check-no-failures.service
Created symlink .../boot-complete.target.requires/systemd-boot-check-no-failures.service ...

The symlink path and exact message vary by distribution. Check the result without starting a boot transaction:

$ systemctl is-enabled systemd-boot-check-no-failures.service
enabled
$ systemctl cat systemd-boot-check-no-failures.service

There is no need to start the service manually just to test the helper. If you enabled it by mistake, undo that persistent change with:

$ sudo systemctl disable systemd-boot-check-no-failures.service

Disabling it removes the enablement relationship. It does not repair any failed unit and does not undo a service run that has already happened.

5. Do not mistake this for a complete boot health policy

A failed-unit count is deliberately broad and shallow. A unit can be active while its application is unusable, and a unit can be failed for a reason that is harmless on a particular machine. The check also does not test network reachability, storage contents, application readiness, data integrity or a specific security property.

For a real deployment, put a more specific check in a service designed for your environment and order that check before the target it is meant to protect. Test the failure path first in a maintenance window. A check that blocks boot completion can affect recovery and automation, so keep console or out-of-band access available before enabling one.

The local systemd 255 manpage has a small packaging mismatch worth spotting: its synopsis shows /usr/lib/systemd/system-boot-check-no-failures, while this host's installed unit starts /usr/lib/systemd/systemd-boot-check-no-failures. Follow the unit's ExecStart and verify the executable on the host rather than copying the synopsis path blindly.