Diagnose systemd-bsod Without Triggering a Blue Screen

The boot hangs on a blank screen with no error in sight, and systemd-bsod is the tool built to surface whatever killed it. This guide covers what it reads, whether this host can even run its service, and how to inspect the relevant emergency messages without changing boot configuration. The installed package here is systemd 255.4-1ubuntu8.17, reporting systemd version 255. Allow about fifteen minutes, plus time to investigate whatever emergency message you find.

1. Confirm the installed program

The executable is installed under /usr/lib/systemd on this machine, rather than necessarily being available as systemd-bsod on your shell's PATH. Ask it for its version:

$ /usr/lib/systemd/systemd-bsod --version
systemd 255 (255.4-1ubuntu8.17)
+PAM +AUDIT +SELINUX +APPARMOR +IMA +SMACK +SECCOMP +GCRYPT -GNUTLS +OPENSSL +ACL +BLKID +CURL +ELFUTILS +FIDO2 +IDN2 -IDN +IPTC +KMOD +LIBCRYPTSETUP +LIBFDISK +PCRE2 -PWQUALITY +P11KIT +QRENCODE +TPM2 +BZIP2 +LZ4 +XZ +ZLIB +ZSTD -BPF_FRAMEWORK -XKBCOMMON +UTMP +SYSVINIT default-hierarchy=unified

Your feature list can differ even when the systemd version matches. The useful checkpoint is the first line and a zero exit status:

$ printf '%s\n' "$?"
0

2. Read the program's boundary

$ /usr/lib/systemd/systemd-bsod --help
systemd-bsod

Filter the journal to fetch the first message from the
current boot with an emergency log level and displays it
as a string and a QR code.

   -h --help            Show this help
      --version         Show package version
   -c --continuous      Make systemd-bsod wait continuously
                        for changes in the journal

Only three options exist in this installed build. --help and --version exit after printing information. --continuous changes the wait behaviour: when no emergency message turns up on the first attempt, the program keeps waiting for journal changes. The manpage records it as added in systemd 255.

There is no option here for selecting a unit, changing a log level, or enabling the service. That is a common distraction trap: systemd-bsod is a display consumer for emergency journal data, not a general journal viewer or a boot-policy editor.

3. Find the emergency message first

Inspect recent emergency-priority entries for the current boot with journalctl:

$ journalctl --boot 0 --priority emerg --no-pager --lines 20
-- Journal begins at ... --
... host systemd[1]: An emergency-priority message from this boot

The output is host-specific. An empty result is still useful evidence: there was no matching entry in the journal view available to your account. It does not prove an earlier boot succeeded, and it does not create an emergency message for testing. --boot 0 means the current boot, while --priority emerg selects the emergency level named in the program help.

If access is denied, repeat the same read-only query with elevated privileges:

$ sudo journalctl --boot 0 --priority emerg --no-pager --lines 20

sudo is for journal access only here. Do not use it to run the display program as root unless you have a specific operational reason and have reviewed the consequences. Capture the original output before changing filters, so you can return to the same checkpoint.

4. Inspect the service without starting it

$ systemctl cat systemd-bsod.service
[Service]
RemainAfterExit=yes
ExecStart=/usr/lib/systemd/systemd-bsod --continuous

$ systemctl show systemd-bsod.service \\
    -p LoadState -p UnitFileState -p ActiveState -p ConditionResult \\
    -p ExecStart -p FragmentPath
ExecStart={ path=/usr/lib/systemd/systemd-bsod ; argv[]=/usr/lib/systemd/systemd-bsod --continuous ; ... }
LoadState=loaded
ActiveState=inactive
FragmentPath=/usr/lib/systemd/system/systemd-bsod.service
UnitFileState=static
ConditionResult=no

Some properties vary by host, but the important details hold: the packaged service invokes --continuous, has RemainAfterExit=yes, and is static. A static unit is not enabled with systemctl enable; it is normally reached by another unit or started explicitly when the administrator has a reason. The unit also carries ConditionVirtualization=no, so systemd skips it on a detected virtual machine. A skipped condition is different from a failed executable.

5. Test only when the display impact is acceptable

Starting the service is the one state-changing and display-disrupting action in this guide. It can show a full-screen blue screen and its QR code on the active console. Run it only on a disposable test machine, or during a maintenance window with an operator at the console:

$ sudo systemctl start systemd-bsod.service
$ systemctl status systemd-bsod.service --no-pager

The command may do nothing if the unit condition is false, may report no emergency message, or may stay active after displaying one because the unit specifies RemainAfterExit=yes.

To return the unit to its inactive state after a deliberate test, stop it:

$ sudo systemctl stop systemd-bsod.service
$ systemctl is-active systemd-bsod.service
inactive

Stopping the unit does not remove journal entries and does not alter boot configuration. If an unrelated dependency started it, check that dependency before stopping services on a production host.

Common traps

• No screen and no error. Inspect ConditionResult. A virtual machine can be skipped by the unit's condition.
• No message to display. Check the current boot with journalctl --boot 0 --priority emerg. The program waits continuously only when you use --continuous and the initial search finds nothing.
• Command not found. Use the unit's absolute ExecStart path; the service file is the authority for how systemd invokes the installed program.
• Journal permission failure. Use sudo for the journal query, then keep the diagnostic output separate from normal shell output.
• Unexpected non-zero status. Check systemctl status and the service's journal with journalctl -u systemd-bsod.service --no-pager. The manpage defines zero as successful display and non-zero as failure.