README.initramfs

   1 Assembling md arrays at boot time.
   2 ---------------------------------
   3 December 2005
   4
   5 These notes apply to 2.6 kernels only and, in some cases,
   6 to 2.6.15 or later.
   7
   8 Md arrays can be assembled at boot time using the 'autodetect' functionality
   9 which is triggered by storing components of an array in partitions of type
  10 'fd' - Linux Raid Autodetect.
  11 They can also be assembled by specifying the component devices in a
  12 kernel parameter such as
  13   md=0,/dev/sda,/dev/sdb
  14 In this case, /dev/md0 will be assembled (because of the 0) from the listed
  15 devices.
  16
  17 These mechanisms, while useful, do not provide complete functionality
  18 and are unlikely to be extended.  The preferred way to assemble md
  19 arrays at boot time is using 'mdadm'.  To assemble an array which
  20 contains the root filesystem, mdadm needs to be run before that
  21 filesystem is mounted, and so needs to be run from an initial-ram-fs.
  22 It is how this can work that is the primary focus of this document.
  23
  24 It should be noted up front that only the array containing the root
  25 filesystem should be assembled from the initramfs.  Any other arrays
  26 should be assembled under the control of files on the main filesystem
  27 as this enhanced flexibility and maintainability.
  28
  29 A minimal initramfs for assembling md arrays can be created using 3
  30 files and one directory.  These are:
  31
  32 /bin           Directory
  33 /bin/mdadm     statically linked mdadm binary
  34 /bin/busybox   statically linked busybox binary
  35 /bin/sh        hard link to /bin/busybox
  36 /init          a shell script which call mdadm appropriately.
  37
  38 An example init script is:
  39
  40 ==============================================
  41 #!/bin/sh
  42
  43 echo 'Auto-assembling boot md array'
  44 mkdir /proc
  45 mount -t proc proc /proc
  46 if [ -n "$rootuuid" ]
  47 then arg=--uuid=$rootuuid
  48 elif [ -n "$mdminor" ]
  49 then arg=--super-minor=$mdminor
  50 else arg=--super-minor=0
  51 fi
  52 echo "Using $arg"
  53 mdadm -Acpartitions $arg --auto=part /dev/mda
  54 cd /
  55 mount /dev/mda1 /root ||  mount /dev/mda /root
  56 umount /proc
  57 cd /root
  58 exec chroot . /sbin/init < /dev/console > /dev/console 2>&1
  59 =============================================
  60
  61 This could certainly be extended, or merged into a larger init script.
  62 Though tested and in production use, it is not presented here as
  63 "The Right Way" to do it, but as a useful example.
  64 Some key points are:
  65
  66   /proc needs to be mounted so that /proc/partitions can be accessed
  67   by mdadm, and so that /proc/filesystems can be accessed by mount.
  68
  69   The uuid of the array can be passed in as a kernel parameter
  70   (rootuuid).  As the kernel doesn't use this value, it is made available
  71   in the environment for /init
  72
  73   If no uuid is given, we default to md0, (--super-minor=0) which is a
  74   commonly used to store the root filesystem.  This may not work in
  75   all situations.
  76
  77   We assemble the array as a partitionable array (/dev/mda) even if we
  78   end up using the whole array.  There is no cost in using the partitionable
  79   interface, and in this context it is simpler.
  80
  81   We try mounting both /dev/mda1 and /dev/mda as they are the most like
  82   part of the array to contain the root filesystem.
  83
  84   The --auto flag is given to mdadm so that it will create /dev/md*
  85   files automatically.  This is needed as /dev will not contain
  86   and md files, and udev will not create them (as udev only created device
  87   files after the device exists, and mdadm need the device file to create
  88   the device).  Note that the created md files may not exist in /dev
  89   of the mounted root filesystem.  This needs to be deal with separately
  90   from mdadm - possibly using udev.
  91
  92   We do not need to create device files for the components which will
  93   be assembled into /dev/mda.  mdadm finds the major/minor numbers from
  94   /proc/partitions and creates a temporary /dev file if one doesn't already
  95   exist.
  96
  97 The script "mkinitramfs" which is included with the mdadm distribution
  98 can be used to create a minimal initramfs.  It creates a file called
  99 'init.cpio.gz' which can be specified as an 'initrd' to lilo or grub
 100 (or whatever boot loader is being used).
 101
 102
 103
 104
 105 Resume from an md array
 106 -----------------------
 107
 108 If you want to make use of the suspend-to-disk/resume functionality in Linux,
 109 and want to have swap on an md array, you will need to assemble the array
 110 before resume is possible.
 111 However, because the array is active in the resumed image, you do not want
 112 anything written to any drives during the resume process, such as superblock
 113 updates or array resync.
 114
 115 This can be achieved in 2.6.15-rc1 and later kernels using the
 116 'start_readonly' module parameter.
 117 Simply include the command
 118   echo 1 > /sys/module/md_mod/parameters/start_ro
 119 before assembling the array with 'mdadm'.
 120 You can then echo
 121   9:0
 122 or whatever is appropriate to /sys/power/resume to trigger the resume.