scripts/lvm2create_initrd/lvm2create_initrd.8

.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "lvm2create_initrd 8"
.TH lvm2create_initrd 8 "2011-11-12" "lvm2create_initrd" "create LVM2 initrd"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
lvm2create_initrd \- create initrd image for booting to root\e\-on\e\-LVM2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBlvm2create_initrd\fR [ \fB\-h|\-\-help\fR ] [ \fB\-v|\-\-verbose\fR ] [ \fB\-c|\-\-lvmconf\fR \fI/path/to/lvm.conf\fR ] [ \fB\-m|\-\-modules\fR "\fImodule1 module2 ...\fR" ] [ \fB\-e|\-\-extra\fR "\fIfile1 file2 ...\fR" ] [ \fB\-r|\-\-raid\fR "\fI/dev/md1 /dev/md2 ...\fR" ]
[ \fB\-R|\-\-raidconf\fR \fI/path/to/mdadm.conf\fR ] [ \fB\-M|\-\-makedev\fR \fIstyle\fR ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
lvm2create_initrd creates an initial ramdisk (initrd) image suitable for booting to system that has an \s-1LVM2\s0 volume as its root filesystem.
.PP
To boot to such a setup, you'll
either need a bootloader that understands \s-1LVM2\s0 volumes, or you'll need a
filesystem on a regular volume to act as a boot partition (typically mounted
on /boot).
.PP
The resulting initrd image is fairly full-featured. It can harbor and load
kernel modules, start \s-1MD\s0 devices, and boot to a shell to perform rescue
operations.
.SS "Booting to your initrd Image:"
.IX Subsection "Booting to your initrd Image:"
The filesystem image created is an ext2fs filesystem, hence your kernel must have
ext2fs built into it statically in order to boot to the image.
.PP
Once you create your initrd image, you must pass the correct options to the kernel when
you boot using it. Your kernel command line should look something like this:
.PP
\&\fBroot=/dev/ram0 lvm2root=/dev/rootvg/root [ lvm2rescue ]\fR
.PP
of course there may be other options.
.IP "\fBroot=/dev/ram0\fR" 4
.IX Item "root=/dev/ram0"
This option is required. It tells the kernel that the root filesystem should initially
be set to the ramdisk (/dev/ram0).
.IP "\fBlvm2root=/dev/rootvg/root\fR" 4
.IX Item "lvm2root=/dev/rootvg/root"
This option is also required. It tells the initrd image which \s-1LVM2\s0 device the root filesystem is located on.
.IP "\fBlvm2rescue\fR" 4
.IX Item "lvm2rescue"
Causes the initrd image to run a shell prior to mounting the root filesystem. This is
helpful in disaster situations where your initrd image is accessable, but there is
a problem with the root filesystem (corrupted image, incorrect device setup, etc.). This
option is (of course) optional.
.SH "OPTIONS"
.IX Header "OPTIONS"
Most of parameters that can be set via command-line options can also be set
via environment variables. Options specified on the command-line always take
precedence.
.IP "\fB\-h|\-\-help\fR" 4
.IX Item "-h|--help"
Display short help text and exit. If used, other options are ignored.
.IP "\fB\-v|\-\-verbose\fR" 4
.IX Item "-v|--verbose"
Turn on extra verbosity for debugging, etc.
.IP "\fB\-c|\-\-lvmconf\fR \fI/path/to/lvm.conf\fR" 4
.IX Item "-c|--lvmconf /path/to/lvm.conf"
Specify an lvm.conf file to include in the image. This is useful if you have
special device filters or other options you wish to use during the initrd
stage. If this option is not
included, then a lvm.conf file is created that contains only the current
device filter from an \fBlvm dumpconfig\fR. This can also be set via the \fB\f(CB$LVMCONF\fB\fR
environment variable.
.ie n .IP "\fB\-m|\-\-modules\fR ""\fI/path/to/module1.ko /path/to/module2.ko ...\fR""" 4
.el .IP "\fB\-m|\-\-modules\fR ``\fI/path/to/module1.ko /path/to/module2.ko ...\fR''" 4
.IX Item "-m|--modules ""/path/to/module1.ko /path/to/module2.ko ..."""
Specify modules to include and plug in during the initrd phase. This option
takes a quoted, space-separated list of modules. Full pathnames are required.
These modules are loaded into the kernel early in the initrd phase of the boot
process. The current modprobe.conf file is also copied to the initrd image
as well. This can also be specified via the \fB\f(CB$MODULES\fB\fR environment variable.
.ie n .IP "\fB\-e|\-\-extra\fR ""\fI/path/to/file1 /path/to/file2 ...\fR""" 4
.el .IP "\fB\-e|\-\-extra\fR ``\fI/path/to/file1 /path/to/file2 ...\fR''" 4
.IX Item "-e|--extra ""/path/to/file1 /path/to/file2 ..."""
Extra files that should be included in the initrd image. These files will be
copied to the same location in the initrd image that they are in the current
filesystem. Again full pathnames are required. This can also be specified via
the \fB\f(CB$EXTRAFILES\fB\fR environment variable.
.ie n .IP "\fB\-r|\-\-raid\fR ""\fI/dev/md1 /dev/md2...\fR""" 4
.el .IP "\fB\-r|\-\-raid\fR ``\fI/dev/md1 /dev/md2...\fR''" 4
.IX Item "-r|--raid ""/dev/md1 /dev/md2..."""
\&\s-1RAID\s0 devices to be started prior to scanning for \s-1LVM2\s0 volume groups. If this
option is used then then \fBmdadm\fR program must be installed. This can also be
specified via the \fB\f(CB$RAID\fB\fR environment variable.
.ie n .IP "\fB\-R|\-\-raidconf\fR ""\fI/path/to/mdadm.conf\fR""" 4
.el .IP "\fB\-R|\-\-raidconf\fR ``\fI/path/to/mdadm.conf\fR''" 4
.IX Item "-R|--raidconf ""/path/to/mdadm.conf"""
Location of a mdadm.conf file to include. If this is not specified, then no
files are included, and any devices specified with the \fB\-r\fR option above
must have minor numbers that match their superblock values. This can also be
specified via the \fB\f(CB$RAIDCONF\fB\fR environment variable.
.IP "\fB\-M|\-\-makedev\fR \fIstyle\fR" 4
.IX Item "-M|--makedev style"
Set \s-1MAKEDEV\s0 invocation style. The script currently supports 3 styles of
\&\s-1MAKEDEV\s0 programs \fIdebian\fR, \fIredhat\fR and \fIgentoo\fR. The default is \fIdebian\fR.
Set to \fIredhat\fR if using the RedHat/Fedora binary \s-1MAKEDEV\s0 program. \fIgentoo\fR
has the same binary but in /sbin instead of /dev. Please send a bug report to
maintainer if your distribution doesn't work with any of the current options.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
Most of the options to this script can be set via environment variables. In
situations where both are set, then the command-line options take precedence.
.ie n .IP "\fB\fB$LVMCONF\fB\fR" 4
.el .IP "\fB\f(CB$LVMCONF\fB\fR" 4
.IX Item "$LVMCONF"
Same as \-c option.
.ie n .IP "\fB\fB$MODULES\fB\fR" 4
.el .IP "\fB\f(CB$MODULES\fB\fR" 4
.IX Item "$MODULES"
Same as \-m option.
.ie n .IP "\fB\fB$EXTRAFILES\fB\fR" 4
.el .IP "\fB\f(CB$EXTRAFILES\fB\fR" 4
.IX Item "$EXTRAFILES"
Same as \-e option.
.ie n .IP "\fB\fB$RAID\fB\fR" 4
.el .IP "\fB\f(CB$RAID\fB\fR" 4
.IX Item "$RAID"
Same as \-r option.
.ie n .IP "\fB\fB$RAIDCONF\fB\fR" 4
.el .IP "\fB\f(CB$RAIDCONF\fB\fR" 4
.IX Item "$RAIDCONF"
Same as \-R option.
.ie n .IP "\fB\fB$MAKEDEV\fB\fR" 4
.el .IP "\fB\f(CB$MAKEDEV\fB\fR" 4
.IX Item "$MAKEDEV"
Same as \-M option.
.ie n .IP "\fB\fB$BASICDEVICES\fB\fR" 4
.el .IP "\fB\f(CB$BASICDEVICES\fB\fR" 4
.IX Item "$BASICDEVICES"
Overrides the default value of \f(CW$BASICDEVICES\fR in the script (which is \*(L"std consoleonly fd\*(R"). These values are passed to the \fB\s-1MAKEDEV\s0\fR program to create device
entries in the initrd image.
.ie n .IP "\fB\fB$BLOCKDEVICES\fB\fR" 4
.el .IP "\fB\f(CB$BLOCKDEVICES\fB\fR" 4
.IX Item "$BLOCKDEVICES"
Overrides the default value of \f(CW$BLOCKDEVICES\fR in the script (which is \*(L"md hda hdb hdc hdd sda sdb sdc sdd\*(R"). This value is passed to the \fB\s-1MAKEDEV\s0\fR program to
create device entries in the initrd image.
.ie n .IP "\fB\fB$BINFILES\fB\fR" 4
.el .IP "\fB\f(CB$BINFILES\fB\fR" 4
.IX Item "$BINFILES"
Overrides the default value of \f(CW$BINFILES\fR (which is \*(L"/lib/lvm\-200/lvm /bin/bash /bin/busybox /sbin/pivot_root\*(R"). The difference between using this and adding
a file to the \f(CW$EXTRAFILES\fR list above is that libraries that these depend upon are also included. You can still use \f(CW$EXTRAFILES\fR to achieve the same effect, but
you must resolve library dependencies youself.
.ie n .IP "\fB\fB$INITRDSIZE\fB\fR" 4
.el .IP "\fB\f(CB$INITRDSIZE\fB\fR" 4
.IX Item "$INITRDSIZE"
Force a particular size for your initrd image. The default is to total up the size of
the included files and to add 512K as a buffer.
.SH "BUGS"
.IX Header "BUGS"
I don't like having to specify a \-M option to set the \s-1MAKEDEV\s0 style, but I know
of no way to reliably detect what type of \s-1MAKEDEV\s0 is being used. We'll probably
have to add other \s-1MAKEDEV\s0 styles in the future as this script is tested on
other distributions.
.SH "AUTHORS"
.IX Header "AUTHORS"
The script was originally written by Miguel Cabeca, with significant
improvements by Jeffrey Layton. Comments, bug reports and patches should be
sent to Jeffrey Layton at \fBjtlayton@poochiereds.net\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB\s-1MAKEDEV\s0\fR(8), \fBmdadm\fR(8), \fBbusybox\fR(8), \fBlvm.conf\fR(5)