plymouth.png

Contents

  1. Quick Facts
  2. Options
    1. Daemon
  3. Startup
    1. Splash Theme
  4. Testing
    1. Checking Plymouth Can Run in the Initramfs
    2. Checking Plymouth Can Run Early in Boot
    3. Running Plymouth "post-boot"
  5. Debugging
    1. Toggling to Traditional Text-based Boot
    2. Enabling Debugging
  6. Plymouth Logs
  7. Tips
  8. Additional
    1. "plymouth ask-question"
    2. "plymouth ask-for-password"
    3. Special FSCK messages
  9. See Also

Plymouth is the application which provides the graphical "splash" screen when booting and shutting down an Ubuntu system.

Note that on Ubuntu, Plymouth is considered to be the "owner" of the console device (/dev/console) so no application should attempt to modify terminal attributes for this device at boot or shutdown.

Quick Facts

Plymouth:

Options

Daemon

plymouthd runs in one of four modes which are set by specifing the appropriate command-line option:

This allows Plymouth to display potentially different content based on whether the system is starting or stopping.

Startup

The plymouthd daemon attempts to read the following files at startup (the first file it finds takes precedence over any other):

Splash Theme

Contents of /lib/plymouth/themes/default.plymouth: 

  [Plymouth Theme]
  Name=Ubuntu Logo
  Description=A theme that features a blank background with a logo.
  ModuleName=script

  [script]
  ImageDir=/lib/plymouth/themes/ubuntu-logo
  ScriptFile=/lib/plymouth/themes/ubuntu-logo/ubuntu-logo.script

This tells plymouthd to use the "script" splash plugin. This plugin allows the graphical splash experience to be scripted using Plymouths own scripting language (hence the name).

The "script" splash plugin exists as /lib/plymouth/script.so (source code: src/plugins/splash/script/script.c)

Testing

Checking Plymouth Can Run in the Initramfs

  1. Add "break=init" to the kernel command-line and boot.

  2. Chroot to the real filesystem: 
    •     chroot /root
      Some warning messages will be displayed, but they can be ignored: 
          bash: cannot set terminal process group (-1): Inappropriate ioctl for device
    bash: no job control in this shell
  3. Start the daemon: 
    •     plymouthd --tty=`tty` --mode=boot --kernel-command-line="quiet splash"
  4. Check that the daemon is running: 
    •     plymouth --ping && echo plymouth is running || echo plymouth NOT running
  5. Tell the daemon to display the splash screen: 
    •     plymouth show-splash

If this works, to exit the splash screen you'll have to type the following "blind" (and note that backspace won't work, but CONTROL-c will): 

  plymouth exit

To shutdown your system:

  1. Remount the disk read-only: 
    •     mount -oremount,ro /
  2. Power off the system.

Note that "shutdown -h now or "halt" cannot be used since Upstart is not running in this scenario.

Checking Plymouth Can Run Early in Boot

  1. Add "init=/bin/sh" to the kernel command-line and boot.

  2. A warning message will be displayed, but can be ignored: 
    •     /bin/sh: 0: can't access tty: job control turned off
  3. Start the daemon: 
    •     plymouthd --tty=`tty` --mode=boot --kernel-command-line="quiet splash"
  4. Check the daemon is running 
    •     plymouth --ping && echo plymouth is running || echo plymouth NOT running
  5. Tell the daemon to display the splash screen: 
    •     plymouth show-splash

If this works, to exit the splash screen you'll have to type the following "blind" (and not that backspace won't work, but CONTROL-c will): 

  plymouth exit

To shutdown your system:

  1. Flush any pending data: 
    •     sync;sync;sync
  2. Remount disk read-only: 
    •     mount -oremount,ro /
  3. Power off the system.

Note that "shutdown -h now or "halt" cannot be used since Upstart is not running in this scenario.

Running Plymouth "post-boot"

You can experiment with Plymouth after your system has booted. To start the Plymouth daemon:

  1. Boot system and login as usual

  2. (i) [RECOMMENDED] Install plymouth-x11 package (allows you to see the boot screen in an X11 window)

    • sudo apt-get install plymouth-x11

  3. Start a terminal (such as gnome-terminal)

  4. Start the Plymouth daemon by running the following:

    • sudo plymouthd --debug --tty=`tty` --no-daemon

Plymouth is now running, so we can have some fun:

Note that when you run the "show-splash" command, two windows pop up. This is because Plymouth simulates a dual-monitor setup.

To stop the Plymouth daemon:

Debugging

Warning /!\ This section is for advanced users only.

Toggling to Traditional Text-based Boot

If you want to see the text-based boot messages (which use the Plymouth "details" plugin, press the ESCAPE key at any point when Plymouth is running. Note that the ESCAPE key acts as a toggle, so you can keep switching between graphical and text mode as required.

To have the boot start in "text mode" as early as possible, remove "splash" from the kernel command-line in grub.

To make the change permanent, update /etc/default/grub and run "sudo update-grub".

Updating the grub configuration manually is a potentially dangerous operation and can result in a machine that fails to boot without intervention. Do not attempt it unless you understand exactly what you are doing.

Enabling Debugging

You can set Plymouth to overlay internal debug messages (which will also be logged to a file) by adding the following command-line option to grub:

For example, if you are running Ubuntu Natty (11.04) or Oneiric (11.10):

  1. Power on system.

  2. Hold down the CONTROL key until the Grub boot menu appears.

  3. Type "e" to edit the default kernel command-line.

  4. Use the arrow keys to go to the end of the line which starts "linux /boot/vmlinuz ...".

  5. Add a space character, followed by "plymouth:debug".
    Notes:

    • If you're interested in the overall boot, you may wish to remove the "quiet" keyword too)

  6. Type CONTROL+x to boot

  7. Once the system has booted, you can view all the Plymouth debug output in file var/log/plymouth-debug.log.

For older releases such as Maverick (10.10), hold down the SHIFT key rather than the CONTROL key to access the grub boot menu.

Notes:

Plymouth Logs

Plymouth will log all output sent to the console to a file. By default, the data is logged to file /var/log/boot.log. If Plymouth is running in debug mode, debug messages are logged to /var/log/plymouth-debug.log.

Note that plymouthd buffers all messages until told that the disk partition on which the logs are to be written (in other words the partition containing /var/log/) is writeable.

The Upstart job /etc/init/plymouth-log.conf is used to accomplish this by calling: 

  plymouth update-root-fs --read-write

Tips

Additional

"plymouth ask-question"

Used to prompt the user for an answer, echoing the answer text as it is typed. The answer is by default echoed to stdout to allow it to be piped to another command which expects to read the password on its stdin. Example: 

  plymouth ask-question --prompt "what is your name? " |\
    command-to-process-answer --read-from-stdin

Similar functionality is provided by a combination of "plymouth message" and "plymouth watch-keystroke".

"plymouth ask-for-password"

Used to prompt the user for a password securely (password text is not echoed). The password the user enters is by default echoed to stdout to allow it to be piped to another command which expects to read the password on its stdin. Example: 

  plymouth ask-for-password --prompt "specify password: " |\
    command-to-read-password-and-do-secret-things --read-from-stdin

Special FSCK messages

The Ubuntu Plymouth theme supports a "special" message that allows mountall to display fsck progress messages ("fsck is 20% complete"). You can make use of this functionality by using a special message format: 

  sudo plymouth --update=fsck:sda1:27

This will display a message like: 

  Checking disk 1 of 1 (27% complete)

See Also

CategoryBoot

Plymouth (last edited 2022-10-11 17:02:32 by nteodosio)