Run and Troubleshoot plymouthd Safely in an Initrd

You will identify the installed plymouthd interface, choose the correct boot or shutdown mode, and prepare a diagnostic launch without accidentally taking over the active console. This guide uses plymouth 24.004.60-1ubuntu7.2, installed here on Ubuntu. Allow about fifteen minutes for inspection, or longer if you are debugging an initrd.

plymouthd is normally started from the initrd. It does the work behind the Plymouth splash screen, records the session and accepts control requests from the plymouth client. Starting a second copy on a running desktop or boot session can interfere with that work, so the examples begin with read-only checks.

1. Confirm the binary and version

Run these commands as an ordinary user. They inspect the installed executable and package; they do not start the daemon:

$ command -v plymouthd
/usr/sbin/plymouthd
$ dpkg-query -W -f='${Package} ${Version}\n' plymouth
plymouth 24.004.60-1ubuntu7.2
$ plymouthd --help

The path can differ on another distribution. The important checkpoint is that the command resolves to the package you intend to troubleshoot and that its help output is available.

2. Read the daemon boundary correctly

The daemon is not the usual interactive command for changing a splash screen. The separate plymouth command sends requests to it. Use plymouthd when the boot or shutdown environment needs the server itself, or when you need server-side diagnostics.

The documented options in this installed manpage are:

• --no-daemon keeps the process in the foreground instead of daemonising it.
• --debug enables debugging output, while --debug-file=PATH selects its destination.
• --mode=boot or --mode=shutdown selects the session mode.
• --pid-file=PATH writes the daemon process ID to the named file.
• --tty=PATH selects a TTY instead of the default.
• --attach-to-session redirects console messages from the screen to the log.

Do not infer a default TTY, log path or PID-file path from the option names. The manpage does not promise those values, and they can be supplied by the initrd integration on your distribution.

3. Select boot or shutdown mode

Use boot mode for the normal startup splash and shutdown mode for the end-of-session splash. The mode is a property of the daemon invocation, not a cosmetic label you can change safely after the session has begun.

$ plymouthd --help | grep -- '--mode'
  --mode=<string>                   Mode is one of: boot, shutdown

That output is from the installed binary. If a boot script or initrd generator supplies a mode, inspect the generated configuration and the script that launches it rather than starting a competing daemon by hand. A mode mismatch is a plausible explanation for a splash that behaves correctly during boot but not during shutdown.

4. Prepare a foreground diagnostic run

When you have an unused test TTY and a writable temporary directory, keep the process in the foreground and write diagnostics to a disposable file:

# plymouthd --no-daemon --debug \
    --debug-file=/tmp/plymouthd-debug.log \
    --pid-file=/tmp/plymouthd.pid \
    --mode=boot \
    --tty=/dev/tty1

The command is intentionally shown with a root prompt because the test environment may need access to the TTY and Plymouth runtime resources. The exact permissions depend on the initrd and distribution. Stop with Ctrl-C when the foreground test is complete. That stops this test process; it does not repair a service that another supervisor has already started.

In a second shell, check the files you explicitly requested:

# test -s /tmp/plymouthd-debug.log && echo 'debug log has data'
debug log has data
# cat /tmp/plymouthd.pid
1234

The PID is an example and will differ. If the log is empty, first check that the path is writable and that the daemon reached the point where it emits diagnostics. Do not treat the presence of a PID file alone as proof that the splash is working.

5. Use the installed help to spot version differences

The local manpage documents the core options above, but this package's binary also reports --no-boot-log, --ignore-serial-consoles and --graphical-boot in --help. These are version-specific observations for plymouth 24.004.60-1ubuntu7.2, not options to assume on another host. Check the target machine's help before copying an initrd argument.

$ plymouthd --help | tail -3
  --no-boot-log                     Do not write boot log file
  --ignore-serial-consoles          Ignore serial consoles
  --graphical-boot                  Use graphical splashes even if the kernel console is not a VT

In particular, do not add an option merely because a different distribution's Plymouth guide mentions it. An initrd generator may reject an unknown argument before the daemon can show a splash.

6. Diagnose without destroying the evidence

Preserve the original boot log and initrd before editing anything. First collect read-only facts and the diagnostic file:

$ command -v plymouthd
$ plymouthd --help > /tmp/plymouthd-help.txt
$ ls -l /tmp/plymouthd-debug.log /tmp/plymouthd.pid
$ sed -n '1,120p' /tmp/plymouthd-debug.log

If the TTY is wrong, verify the device exists with ls -l /dev/tty1 and choose a TTY that belongs to the test environment. If the daemon exits immediately, inspect its exit status and the first diagnostic lines before changing permissions or deleting runtime files. An inability to write a debug or PID file is often a path or permission problem, not evidence that the splash plugin is broken.

Once the test is finished, remove only the temporary files you created, if they contain no evidence you still need:

# rm -f /tmp/plymouthd-debug.log /tmp/plymouthd.pid /tmp/plymouthd-help.txt

This cleanup is optional and irreversible. Do not remove files under the initrd, /run or the system's Plymouth configuration as a first troubleshooting step. To undo the foreground test itself, stop the process with Ctrl-C; if a service manager launched it, stop or restart that service through its normal recovery procedure instead of killing an unrelated PID.