How to Configure and Test systemd-bsod Emergency Error Displays in Ubuntu

Beginning with systemd version 255 (introduced in Ubuntu 24.04 LTS Noble Numbat), the Linux init system includes a diagnostic daemon named systemd-bsod. Designed to bridge the gap between headless system crashes and accessible troubleshooting, systemd-bsod captures log messages logged with emergency priority (LOG_EMERG) during failed boot transactions and displays them full-screen on a blue background, accompanied by an automatically generated QR code. For systems administrators and fleet operators, this diagnostic facility provides an immediate visual summary of kernel or service startup panics on physical consoles and remote KVMs without requiring manual journal recovery from live media.

Architecture and Function of systemd-bsod

The systemd-bsod service (provided by package systemd) interfaces directly with the Linux Direct Rendering Manager (DRM) or standard framebuffer subsystem to render emergency text directly to the display terminal. Its operational lifecycle follows these core mechanics:

• Log Level Filtering: The daemon scans the systemd journal for messages tagged with syslog level 0 (LOG_EMERG / Emergency).
• Framebuffer Rendering: If an emergency event occurs during boot, systemd-bsod.service acquires the physical console, sets a high-contrast blue background, and prints the error text.
• QR Code Generation: Utilizing an embedded QR encoder, the service generates a scannable QR code containing the full panic message or a unique journal token. Technicians can scan the code with a smartphone to capture the exact error string without transcribing hex registers or call traces manually.

Verifying systemd-bsod Availability in Ubuntu

Ensure your Ubuntu installation runs systemd 255 or newer. Check the installed version and service status in the terminal:

systemd --version
systemctl status systemd-bsod.service

The service is typically in an inactive (dead) state during normal operations, waiting to be triggered dynamically or invoked manually during emergency runlevels.

Enabling the systemd-bsod Service

While systemd-bsod is packaged with systemd, ensuring that the service and its associated socket/generator triggers are enabled guarantees that boot-time panics capture the screen:

sudo systemctl enable systemd-bsod.service

You can inspect the systemd unit configuration to review its execution parameters:

systemctl cat systemd-bsod.service

The service definition confirms execution under root with restricted capabilities, invoking /usr/lib/systemd/systemd-bsod with appropriate arguments.

Testing the Emergency Blue Screen Display Safely

To evaluate how the blue screen appears on your physical hardware, virtual machine console, or IPMI display without crashing the running kernel, systemd-bsod provides a dedicated test flag: --continuous.

Warning: Executing the test directly in a graphical desktop session (such as GNOME on Wayland or X11) may conflict with your active display manager. For best results, switch to a virtual console (Ctrl + Alt + F3) or test over an out-of-band KVM console.

1. Simulating an Emergency Message

First, write a test message with syslog emergency priority using logger:

logger -p emerg "TEST ERROR: Critical filesystem corruption detected on root volume during initramfs stage"

2. Invoking systemd-bsod in Test Mode

Run the binary with continuous rendering enabled:

sudo /usr/lib/systemd/systemd-bsod --continuous

The active screen will switch to a blue background showing:

1. The high-priority emergency log message at the top of the display.
2. A QR code rendered on the right side containing the text payload.
3. Prompt instructions to exit or dismiss the screen.

Press any key (or Ctrl + C) to exit test mode and restore the shell prompt.

Troubleshooting Missing Framebuffer or Display Issues

If systemd-bsod fails to draw the console or exits with an error indicating display device unavailability, review the following hardware configurations:

• DRM Kernel Modesetting (KMS): Verify that the appropriate kernel graphics driver is loaded (e.g., i915, amdgpu, nouveau, or virtio-gpu). Headless servers lacking simple framebuffer or DRM device nodes (/dev/dri/card0 or /dev/fb0) cannot render graphical consoles.
• Kernel Boot Parameters: Check /etc/default/grub to ensure that nomodeset is not disabling graphics acceleration unless strictly required for legacy hardware compatibility.

By configuring and validating systemd-bsod, Ubuntu administrators gain a modern, rapid-response visual triage mechanism, simplifying offline error documentation and accelerating recovery during boot-stage system failures.