INITRAMFS-TOOLS

INITRAMFS-TOOLS(8)        mkinitramfs script overview       INITRAMFS-TOOLS(8)



NAME
       initramfs-tools - an introduction to writing scripts for mkinitramfs


DESCRIPTION
       initramfs-tools  has  one  main  script  and two different sets of sub-
       scripts which will be used during different phases of  execution.  Each
       of  these will be discussed separately below with the help of an imagi-
       nary tool which performs a frobnication of a  lvm  partition  prior  to
       mounting the root partition.


   Hook scripts
       These  are  used when an initramfs image is created and not included in
       the image itself. They can however cause files to be  included  in  the
       image.


   Boot scripts
       These  are included in the initramfs image and normally executed during
       kernel boot in the early user-space before the root partition has  been
       mounted.

       initramfs-tools  uses  shell  variable names for handling dependencies.
       Notice that `-' is not a valid shell variable name and thus should  not
       be used as script filename.


INIT SCRIPT
       The  script  which  is  executed  first and is in charge of running all
       other scripts can be found in /usr/share/initramfs-tools/init. It takes
       a number of arguments which influence the boot procedure:


   Boot options
         init the  binary  to  hand over execution to on the root fs after the
              initramfs scripts are done.


         root the device node to mount as the rootfs.


         nfsroot
              can be either "auto" to try to get the relevant information from
              DHCP or a string of the form NFSSERVER:NFSPATH


         boot either  local  or  NFS (affects which initramfs scripts are run,
              see the "Subdirectories" section under boot scripts).


         resume
              On install initramfs-tools tries to autodetect the resume parti-
              tion.   On   success   the   RESUME   variable   is  written  to
              /etc/initramfs-tools/conf.d/resume.  The boot variable overrides
              it.


         quiet
              reduces the amount of text output to the console during boot


         ro   mounts the rootfs read-only


         rw   mounts the rootfs read-write


         debug
              generates lots of output to /tmp/initramfs.debug


         break
              spawns a shell in the initramfs image at chosen run-time



HOOK SCRIPTS
       Hooks  can be found in two places: /usr/share/initramfs-tools/hooks and
       /etc/initramfs-tools/hooks. They are executed during generation of  the
       initramfs-image  and  are  responsible  for including all the necessary
       components in the image itself. No guarantees are made as to the  order
       in  which  the  different  scripts  are executed unless the prereqs are
       setup in the script.


   Header
       In order to support prereqs, each script should begin with the  follow-
       ing lines:

              #!/bin/sh
              PREREQ=""
              prereqs()
              {
                   echo "$PREREQ"
              }

              case $1 in
              prereqs)
                   prereqs
                   exit 0
                   ;;
              esac

              # Begin real processing below this line

       For  example, if you are writing a new hook script which relies on lvm,
       the line starting with PREREQ should be changed to  PREREQ="lvm"  which
       will  ensure that the lvm hook script is run before your custom script.


   Help functions
       /usr/share/initramfs-tools/hook-functions contains a  number  of  func-
       tions which deal with some common tasks in a hook script:


       manual_add_modules
              adds  a  module  (and  any  modules  which it depends on) to the
              initramfs image.

              Example: manual_add_modules isofs



       add_modules_from_file
              reads a file containing a list of modules (one per line)  to  be
              added  to  the  initramfs  image.  The file can contain comments
              (lines starting with #) and arguments to the modules by  writing
              the arguments on the same line as the name of the module.

              Example: add_modules_from_file /tmp/modlist



       force_load
              adds  a module (and its dependencies) to the initramfs image and
              also unconditionally loads the module during boot. Also supports
              passing arguments to the module by listing them after the module
              name.

              Example: force_load cdrom debug=1



       copy_modules_dir
              copies an entire module directory  from  /lib/modules/KERNELVER-
              SION/ into the initramfs image.

              Example: copy_modules_dir kernel/drivers/pci/foobar


   Including binaries
       If  you  need  to copy binaries to the initramfs module, a command like
       this should be used:

              copy_exec /sbin/mdadm "${DESTDIR}/sbin"

       mkinitramfs will automatically detect which  libraries  the  executable
       depends  on  and  copy them to the initramfs. This means that most exe-
       cutables, unless compiled with klibc, will automatically include  glibc
       in the image which will increase its size by several hundred kilobytes.



BOOT SCRIPTS
       Similarly to hook scripts, boot scripts can  be  found  in  two  places
       /usr/share/initramfs-tools/scripts/  and /etc/initramfs-tools/scripts/.
       There are a number of subdirectories to  these  two  directories  which
       control the boot stage at which the scripts are executed.


   Header
       Like for hook scripts, there are no guarantees as to the order in which
       the different scripts in one subdirectory (see "Subdirectories"  below)
       are  executed.  In order to define a certain order, a similar header as
       for hook scripts should be used:

              #!/bin/sh
              PREREQ=""
              prereqs()
              {
                   echo "$PREREQ"
              }

              case $1 in
              prereqs)
                   prereqs
                   exit 0
                   ;;
              esac

       Where PREREQ is modified to list other scripts in the same subdirectory
       if necessary.


   Help functions
       A number of functions (mostly dealing with output) are provided to boot
       scripts:



       log_success_msg
              Logs a success message

              Example: log_success_msg "Frobnication successful"



       log_failure_msg
              Logs a failure message

              Example: log_failure_msg "Frobnication component froobz missing"



       log_warning_msg
              Logs a warning message

              Example: log_warning_msg "Only partial frobnication possible"



       log_begin_msg
              Logs a message that some processing step has begun



       log_end_msg
              Logs a message that some processing step is finished

              Example:

                     log_begin_msg "Frobnication begun"
                     # Do something
                     log_end_msg



       panic  Logs  an  error  message  and  executes a shell in the initramfs
              image to allow the user to investigate the situation.

              Example: panic "Frobnication failed"


   Subdirectories
       Both     /usr/share/initramfs-tools/scripts     and     /etc/initramfs-
       tools/scripts contains the following subdirectories.



       init-top
              the  scripts  in this directory are the first scripts to be exe-
              cuted after sysfs and procfs have been mounted and  /dev/console
              and  /dev/null  have  been  created.   No other device files are
              present yet.



       init-premount
              runs the udev hooks for populating the /dev tree (udev will keep
              running  until init-bottom) after modules specified by hooks and
              /etc/initramfs-tools/modules have been loaded.



       local-top OR nfs-top
              After these scripts have been executed, the root device node  is
              expected  to  be  present  (local)  or  the network interface is
              expected to be usable (NFS).



       local-premount OR nfs-premount
              are run after the sanity of the root device  has  been  verified
              (local)  or the network interface has been brought up (NFS), but
              before the actual root fs has been mounted.



       local-bottom OR nfs-bottom
              are run after the rootfs has been mounted  (local)  or  the  NFS
              root share has been mounted. udev is stopped.



       init-bottom
              are  the last scripts to be executed before procfs and sysfs are
              moved to the real rootfs and execution is  turned  over  to  the
              init binary which should now be found in the mounted rootfs.


   Boot parameters
       /conf/param.conf
              allows boot scripts to change exported variables that are listed
              on top of init. Write the new values to it. It will  be  sourced
              after an boot script run if it exists.



EXAMPLES
   Hook script
       An  example  hook script would look something like this (and would usu-
       ally be placed in /etc/initramfs-tools/hooks/frobnicate):

              #!/bin/sh
              # Example frobnication hook script

              PREREQ="lvm"
              prereqs()
              {
                   echo "$PREREQ"
              }

              case $1 in
              prereqs)
                   prereqs
                   exit 0
                   ;;
              esac

              # Begin real processing below this line

              if [ ! -x "/sbin/frobnicate" ]; then
                   exit 0
              fi

              force_load frobnicator interval=10
              cp /sbin/frobnicate "${DESTDIR}/sbin"
              exit 0


   Boot script
       An example boot script would look something like this (and  would  usu-
       ally be placed in /etc/initramfs-tools/scripts/local-top/frobnicate):

              #!/bin/sh
              # Example frobnication boot script

              PREREQ="lvm"
              prereqs()
              {
                   echo "$PREREQ"
              }

              case $1 in
              prereqs)
                   prereqs
                   exit 0
                   ;;
              esac

              # Begin real processing below this line
              if [ ! -x "/sbin/frobnicate" ]; then
                   panic "Frobnication executable not found"
              fi

              if [ ! -e "/dev/mapper/frobb" ]; then
                   panic "Frobnication device not found"
              fi

              log_begin_msg "Starting frobnication"
              /sbin/frobnicate "/dev/mapper/frobb" || panic "Frobnication failed"
              log_end_msg

              exit 0


DEBUG
       It  is  easy  to check the generated initramfs for its content. One may
       need to double-check if it contains the relevant binaries, libs or mod-
       ules:
              mkdir tmp/initramfs
              cd tmp/initramfs
              gunzip -c -9 /boot/initrd.img-2.6.15-1-686 | \
              cpio -i -d -H newc --no-absolute-filenames



AUTHOR
       The initramfs-tools are written by Jeff Bailey <jbailey AT ubuntu.com>.

       This manual was written by David  Hardeman <david AT 2gen.com>, updated by
       Maximilian Attems <maks AT sternwelten.at>.


SEE ALSO
        initramfs.conf(5), mkinitramfs(8), update-initramfs(8).



                               Date: 2005/12/06             INITRAMFS-TOOLS(8)