initramfs-tools man page on Debian

Man page or keyword search:  
man Server   8174 pages
apropos Keyword Search (all sections)
Output format
Debian logo
[printable version]

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.

Kernel Command Line
       The  root filesystem used by the kernel is specified by the boot loader
       as always. The traditional root=/dev/sda1 style device specification is
       allowed.	 If a label is used, as in root=LABEL=rootPart the initrd will
       search all available devices for	 a  filesystem	with  the  appropriate
       label,  and  mount that device as the root filesystem.  root=UUID=uuid‐
       number will mount the partition with that UUID as the root filesystem.

   Standard
	init= "<path to real init>"
	      the binary to hand over execution to on the root	fs  after  the
	      initramfs scripts are done.

	root= "<path to blockdevice>"
	      the  device  node	 to mount as the root file system.  The recom‐
	      mended usage is to specify the UUID as followed "root=UUID=xxx".

	rootfstype
	      set the root file system type.

	rootdelay
	      set delay in seconds. Determines how long	 mountroot  waits  for
	      root to appear.  The default is 180 seconds.

	rootflags
	      set the file system mount option string.

	nfsroot
	      can be either "auto" to try to get the relevant information from
	      DHCP or a string of the form NFSSERVER:NFSPATH or NFSSERVER:NFS‐
	      PATH:NFSOPTS.   Use root=/dev/nfs for NFS to kick to in. NFSOPTS
	      can be looked up in nfs(5).

	ip    tells how to configure the ip address. Allows to specify an dif‐
	      ferent   NFS   server  than  the	DHCP  server.  See  Documenta‐
	      tion/filesystems/nfsroot.txt in  any  recent  Linux  source  for
	      details. Optional parameter for NFS root.

	BOOTIF
	      is  a  mac address in pxelinux format with leading "01-" and "-"
	      as separations.  pxelinux passes mac  address  of	 network  card
	      used to PXE boot on with this bootarg.

	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  noresume
	      overrides it.

	resume_offset
	      Specify  the  offset  from  the  partition given by "resume=" at
	      which the swap header of the swap file is located.

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

	ro    mounts the rootfs read-only.

	rw    mounts the rootfs read-write.

	blacklist
	      disables load of specific modules.   Use	blacklist=module1,mod‐
	      ule2,module3 bootparameter.

   Debug
	panic sets  an timeout on panic.  panic=<sec> is a documented security
	      feature: it disables the debug shell.

	debug generates	  lots	 of   output.	It    writes	a    log    to
	      /dev/.initramfs/initramfs.debug.	 Instead  when invoked with an
	      arbitrary argument output is written to console.	Use for	 exam‐
	      ple "debug=vc".

	break spawns  a	 shell in the initramfs image at chosen run-time (top,
	      modules, premount, mount, mountroot, bottom, init).  The default
	      is  premount  without  any arg.  Beware that if both "panic" and
	      "break" are present, initramfs will not  spawn  any  shells  but
	      reboot instead.

	netconsole
	      loads netconsole linux modules with the chosen args.

	all_generic_ide
	      loads generic IDE/ATA chipset support on boot.

HOOK SCRIPTS
       Valid boot and hook scripts names consist solely of alphabetics, numer‐
       ics, dashes and underscores. Other scripts are discarded.

   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.  Hook scripts are executed under errexit. Thus a hook script can
       abort the mkinitramfs build on possible errors (exitcode != 0).

   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.

       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 set‐
       up 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

	      . /usr/share/initramfs-tools/hook-functions
	      # 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/KERNELVERSION/ into the initramfs image.

	      Example: copy_modules_dir kernel/drivers/ata

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

	      copy_exec /sbin/mdadm /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.

   Exported variables
       mkinitramfs sets several variables for the hook scripts environment.

	MODULESDIR
	      corresponds to the linux-2.6 modules dir.

	version
	      is the $(uname -r) linux-2.6 version against mkinitramfs is run.

	CONFDIR
	      is the path of the used initramfs-tools configurations.

	DESTDIR
	      is the root path of the newly build initramfs.

	DPKG_ARCH
	      allows arch specific hook additions.

	verbose
	      corresponds to the verbosity of the update-initramfs run.

	KEYMAP
	      sets if a keymap needs to be added to initramfs.

	MODULES
	      specifies	 which kind of modules should land on initramfs.  This
	      setting shouldn't be overridden by hook script,  but  can	 guide
	      them on how much they need to include on initramfs.

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 in /scripts/functions :

	      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 executed after sysfs and procfs have been mounted.   It  also
	      runs  the udev hook for populating the /dev tree (udev will keep
	      running until init-bottom).

	      init-premount happens  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  net‐
	      work 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.

	      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. udev is stopped.

   Boot parameters
	      /conf/param.conf allows boot scripts to  change  exported	 vari‐
	      ables  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

	      . /usr/share/initramfs-tools/hook-functions
	      # 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

	      . /scripts/functions
	      # 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

   Exported variables
       init sets several variables for the boot scripts environment.

	ROOT  corresponds to the root boot option.  Advanced boot scripts like
	      cryptsetup  or  live-initramfs  need  to play tricks.  Otherwise
	      keep it alone.

	ROOTDELAY, ROOTFLAGS, ROOTFSTYPE, IP
	      corresponds to the rootdelay, rootflags, rootfstype or  ip  boot
	      option.

	DPKG_ARCH
	      allows arch specific boot actions.

	blacklist, panic, quiet, resume, noresume, resume_offset
	      set according relevant boot option.

	break Useful  for  manual intervention during setup and coding an boot
	      script.

	REASON
	      Argument passed to the panic helper function.  Use to  find  out
	      why you landed in the initramfs shell.

	init  passes the path to init(8) usually /sbin/init.

	readonly
	      is  the  default	for  mounting  the  root corresponds to the ro
	      bootarg.	Overridden by rw bootarg.

	rootmnt
	      is the path where root gets mounted usually /root.

	debug indicates that a debug log is captured  for  further  investiga‐
	      tion.

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 /boot/initrd.img-2.6.18-1-686 | \
	      cpio -i -d -H newc --no-absolute-filenames


AUTHOR
       The initramfs-tools are written by Maximilian Attems <maks@debian.org>,
       Jeff Bailey <jbailey@raspberryginger.com> and numerous others.

       This manual was written by David	 Härdeman <david@hardeman.nu>, updated
       by Maximilian Attems <maks@debian.org>.

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

Linux				  2010/09/23		    INITRAMFS-TOOLS(8)
[top]

List of man pages available for Debian

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net