Plymouth

Revision 26 as of 2012-03-29 11:06:36

Clear message

plymouth.png

Contents

  1. Quick Facts
  2. Options
    1. Daemon
  3. Startup
    1. Splash Theme
  4. Testing
    1. Running Plymouth "post-boot"
  5. Debugging
    1. Showing old Text-based Boot
    2. Enabling Logging
  6. Tips
  7. Additional
    1. "plymouth ask-question"
    2. "plymouth ask-for-password"
    3. Special FSCK messages

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

Quick Facts

Plymouth:

  • Uses KMS (Kernel Mode Setting) (where possible) and the framebuffer to set the screen resolution.
  • Comprises 3 components:

    • A daemon (server) process called plymouthd

      • The daemon is responsible for the graphical display, animation and logging.

    • A client application called plymouth

      • The client sends commands to the daemon

    • A library libply.so to allow applications to be written to talk to the daemon

      • (The plymouth command is linked to libply.so for this reason).

  • Supports themes.

  • Is scriptable (see package plymouth-theme-script)

  • Runs at system startup and system shutdown:
    • Boot

      • plymouthd is started in the initramfs

        • (see file /usr/share/initramfs-tools/scripts/init-top/plymouth)

      • plymouthd is stopped at the point the Display Manager is starting

        • (see Upstart job configuration file file /etc/init/plymouth-stop.conf).

    • Shutdown

      • plymouthd is started by Upstart

        • (see Upstart job configuration file file /etc/init/plymouth.conf).

  • Writes a log to /var/log/boot.log.

Options

Daemon

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

  • --mode=boot

  • --mode=shutdown

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:

  • General configuration

    • /etc/plymouth/plymouthd.conf (unused on Ubuntu)

    • /lib/plymouth/plymouthd.defaults (unused on Ubuntu)

  • Splash Theme

    • /lib/plymouth/themes/default.plymouth

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)

  • "ImageDir" tells plymouthd which directory contains the images used by the "Ubuntu Logo" theme.

  • "ScriptFile" is the full path to the Plymouth script which creates the splash experience.

Testing

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:

  • To check if Plymouth really is running:

    • sudo plymouth --ping && echo plymouth is running || echo plymouth NOT running

  • To show a message on our "boot" screen

    1. Start another gnome-terminal terminal/tab

    2. Run the following to show the Plymouth window:

      • sudo plymouth show-splash

    3. Display a message

      • sudo plymouth message --text="hello world"

  • A slightly more useful example
    1. Show the splash screen

      • sudo plymouth show-splash

    2. Stop the graphical progress indicator

      • sudo plymouth pause-progress

    3. Display a message

      • sudo plymouth message --text="pausing boot - press 'c' or space bar to continue"

    4. Wait for the user to type either 'c', 'C' or space (no return required)

      • sudo plymouth watch-keystroke --keys="cC " --command="tee /tmp/c_key_pressed"

    5. Change the on-screen message

      • sudo plymouth message --text="resuming boot"

    6. Resume the graphical progress indicator

      • sudo plymouth unpause-progress

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:

  • sudo plymouth --quit

Debugging

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

Showing old Text-based Boot

If you want to see the text-based boot messages, press ESCAPE 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 if required.

Enabling Logging

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:

  • plymouth:debug

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:

  • If you are using the live CD, the process is slightly different:
    1. Power on system
    2. Hold down the SHIFT key until ISOLINUX "boot:" prompt appears

    3. Type, "live plymouth:debug"

Tips

  • Take care if you add "console=" options to your kernel command line since plymouthd will honour those over its own

    • "--tty=TTY" option!

Additional

"plymouth ask-question"

Note that the standard Ubuntu plymouth theme does not implement the display_question callback (see bug 509384).

This means that "plymouth ask-question" will not work. However, 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)

CategoryBoot