contrib/lvm2/dist/scripts/lvm2create_initrd/lvm2create_initrd.pod

   1 =head1 NAME
   2
   3 lvm2create_initrd - create initrd image for booting to root\-on\-LVM2
   4
   5 =head1 SYNOPSIS
   6
   7 B<lvm2create_initrd> [ B<-h|--help> ] [ B<-v|--verbose> ] [ B<-c|--lvmconf> I</path/to/lvm.conf> ] [ B<-m|--modules> "I<module1 module2 ...>" ] [ B<-e|--extra> "I<file1 file2 ...>" ] [ B<-r|--raid> "I</dev/md1 /dev/md2 ...>" ]
   8 [ B<-R|--raidconf> I</path/to/mdadm.conf> ] [ B<-M|--makedev> I<style> ]
   9
  10 =head1 DESCRIPTION
  11
  12 lvm2create_initrd creates an initial ramdisk (initrd) image suitable for booting to system that has an LVM2 volume as its root filesystem.
  13
  14 To boot to such a setup, you'll
  15 either need a bootloader that understands LVM2 volumes, or you'll need a
  16 filesystem on a regular volume to act as a boot partition (typically mounted
  17 on /boot).
  18
  19 The resulting initrd image is fairly full-featured. It can harbor and load
  20 kernel modules, start MD devices, and boot to a shell to perform rescue
  21 operations.
  22
  23 =head2 Booting to your initrd Image:
  24
  25 The filesystem image created is an ext2fs filesystem, hence your kernel must have
  26 ext2fs built into it statically in order to boot to the image.
  27
  28 Once you create your initrd image, you must pass the correct options to the kernel when
  29 you boot using it. Your kernel command line should look something like this:
  30
  31 B<root=/dev/ram0 lvm2root=/dev/rootvg/root [ lvm2rescue ]>
  32
  33 of course there may be other options.
  34
  35 =over
  36
  37 =item B<root=/dev/ram0>
  38
  39 This option is required. It tells the kernel that the root filesystem should initially
  40 be set to the ramdisk (/dev/ram0).
  41
  42 =item B<lvm2root=/dev/rootvg/root>
  43
  44 This option is also required. It tells the initrd image which LVM2 device the root filesystem is located on.
  45
  46 =item B<lvm2rescue>
  47
  48 Causes the initrd image to run a shell prior to mounting the root filesystem. This is
  49 helpful in disaster situations where your initrd image is accessable, but there is
  50 a problem with the root filesystem (corrupted image, incorrect device setup, etc.). This
  51 option is (of course) optional.
  52
  53 =back
  54
  55 =head1 OPTIONS
  56
  57 Most of parameters that can be set via command-line options can also be set
  58 via environment variables. Options specified on the command-line always take
  59 precedence.
  60
  61 =over
  62
  63 =item B<-h|--help>
  64
  65 Display short help text and exit. If used, other options are ignored.
  66
  67 =item B<-v|--verbose>
  68
  69 Turn on extra verbosity for debugging, etc.
  70
  71 =item B<-c|--lvmconf> I</path/to/lvm.conf>
  72
  73 Specify an lvm.conf file to include in the image. This is useful if you have
  74 special device filters or other options you wish to use during the initrd
  75 stage. If this option is not
  76 included, then a lvm.conf file is created that contains only the current
  77 device filter from an B<lvm dumpconfig>. This can also be set via the B<$LVMCONF>
  78 environment variable.
  79
  80 =item B<-m|--modules> "I</path/to/module1.ko /path/to/module2.ko ...>"
  81
  82 Specify modules to include and plug in during the initrd phase. This option
  83 takes a quoted, space-separated list of modules. Full pathnames are required.
  84 These modules are loaded into the kernel early in the initrd phase of the boot
  85 process. The current modprobe.conf file is also copied to the initrd image
  86 as well. This can also be specified via the B<$MODULES> environment variable.
  87
  88 =item B<-e|--extra> "I</path/to/file1 /path/to/file2 ...>"
  89
  90 Extra files that should be included in the initrd image. These files will be
  91 copied to the same location in the initrd image that they are in the current
  92 filesystem. Again full pathnames are required. This can also be specified via
  93 the B<$EXTRAFILES> environment variable.
  94
  95 =item B<-r|--raid> "I</dev/md1 /dev/md2...>"
  96
  97 RAID devices to be started prior to scanning for LVM2 volume groups. If this
  98 option is used then then B<mdadm> program must be installed. This can also be
  99 specified via the B<$RAID> environment variable.
 100
 101 =item B<-R|--raidconf> "I</path/to/mdadm.conf>"
 102
 103 Location of a mdadm.conf file to include. If this is not specified, then no
 104 files are included, and any devices specified with the B<-r> option above
 105 must have minor numbers that match their superblock values. This can also be
 106 specified via the B<$RAIDCONF> environment variable.
 107
 108 =item B<-M|--makedev> I<style>
 109
 110 Set MAKEDEV invocation style. The script currently supports 2 styles of
 111 MAKEDEV programs I<debian> and I<redhat>. The default is I<debian>. Set
 112 to I<redhat> if using the RedHat/Fedora binary MAKEDEV program. Please send
 113 a bug report to maintainer if your distrib doesn't work with any of the
 114 current options.
 115
 116 =back
 117
 118 =head1 ENVIRONMENT VARIABLES
 119
 120 Most of the options to this script can be set via environment variables. In
 121 situations where both are set, then the command-line options take precedence.
 122
 123 =over
 124
 125 =item B<$LVMCONF>
 126
 127 Same as -c option.
 128
 129 =item B<$MODULES>
 130
 131 Same as -m option.
 132
 133 =item B<$EXTRAFILES>
 134
 135 Same as -e option.
 136
 137 =item B<$RAID>
 138
 139 Same as -r option.
 140
 141 =item B<$RAIDCONF>
 142
 143 Same as -R option.
 144
 145 =item B<$MAKEDEV>
 146
 147 Same as -M option.
 148
 149 =item B<$BASICDEVICES>
 150
 151 Overrides the default value of $BASICDEVICES in the script (which is "std consoleonly fd"). These values are passed to the B<MAKEDEV> program to create device
 152 entries in the initrd image.
 153
 154 =item B<$BLOCKDEVICES>
 155
 156 Overrides the default value of $BLOCKDEVICES in the script (which is "md hda hdb hdc hdd sda sdb sdc sdd"). This value is passed to the B<MAKEDEV> program to
 157 create device entries in the initrd image.
 158
 159 =item B<$BINFILES>
 160
 161 Overrides the default value of $BINFILES (which is "/lib/lvm-200/lvm /bin/bash /bin/busybox /sbin/pivot_root"). The difference between using this and adding
 162 a file to the $EXTRAFILES list above is that libraries that these depend upon are also included. You can still use $EXTRAFILES to achieve the same effect, but
 163 you must resolve library dependencies youself.
 164
 165 =item B<$INITRDSIZE>
 166
 167 Force a particular size for your initrd image. The default is to total up the size of
 168 the included files and to add 512K as a buffer.
 169
 170 =back
 171
 172 =head1 BUGS
 173
 174 I don't like having to specify a -M option to set the MAKEDEV style, but I know
 175 of no way to reliably detect what type of MAKEDEV is being used. We'll probably
 176 have to add other MAKEDEV styles in the future as this script is tested on
 177 other distributions.
 178
 179 =head1 AUTHORS
 180
 181 The script was originally written by Miguel Cabeca, with significant
 182 improvements by Jeffrey Layton. Comments, bug reports and patches should be
 183 sent to Jeffrey Layton at S<B<jtlayton@poochiereds.net>>.
 184
 185 =head1 SEE ALSO
 186
 187 B<MAKEDEV>(8), B<mdadm>(8), B<busybox>(8), B<lvm.conf>(5)