ag4ve / mkinitramfs-ll Goto Github PK

$Header: mkinitramfs-ll/README.textile,v 0.12.3 2013/04/27 06:13:54 -tclover Exp $

“an initramfs with optional RAID|LUKS|LVM|TOI|AUFS+SQUASHFS support
[with a handfull zsh and bash set of scripts to get going easily].”

WARNING: USE AT YOUR OWN RISK!

If you have a static busybox binary or if you use Gentoo
[you have already one: installed as /bin/bb],
you can make an initramfs in matter of secondes with locales settings:
keymap and consolefont, in addition to media-fonts/terminus-font if you use
the associated ebuild,
or if you have that package installed).

If you want GnuPG support, yo should have an app-crypt/gnupg-1.4*[static]
binary along with its options.skel file.
Or if you run Gentoo you can run either gnupg.{ba,z}sh to generate one.

gnupg.zsh -W/usr/share/mkinitramfs-ll if you installed the package
or simply gnupg.zsh will build a binary in the current directory
(with a usr/bin/gpg and usr/share/gnupg/options.skel).
Or else, run the bash script counterpart to get build a binary.

And then run mkinitramfs-ll.zsh -font -keymap -gpg
or the bash counterpart mkinitramfs-ll.bash --font --keymap --gpg
to generate an initramfs.

Gentoo users can build everything with: autogen.zsh -all -font -keymap
or bash counterpart autogen.bash --all --font --keymap

Of course, one can append extra fonts and keymaps with -fter-g12n -yfr-latin1
etc. and the -a option depend on mkinitramfs-ll.conf
so one can put many sane default values there.

One can get more info on the scripts by running $script -u

Warn: mkinitramfs-ll-0.12.0 or later require the associated usr directory.
There’s no support building at hand without the associated generating scripts!

New: mkinitramfs-ll-0.12.0 allow to be dropped on each read() (infinite loop).
Just type sh or shell and then hit Enter.

Only iroot is required else nothing will happen but a kernel panic.
And of course, when using this script, one does not need root=<arg>
nor resume=<arg> kernel command line options.

KERNEL-COMMAND-LINE-ARG: iroot=<PV|VG-LV>[:c:<fs>]
DESCRIPTION: root block device, required,
recommanded optional file system check :[c|chk|y|..]:[<filesystem>]
EXAMPLE: iroot=vg-root:c:ext4 for an ext4 rootfs in LVM (Volume Group is named vg),
or iroot=POOL/root::zfs for zfs rootfs in a zfs pool called POOL.

Note: :[n*|N*]: instead of [c*|y*|Y*:]
will disable a die after fsck failure.

KERNEL-COMMAND-LINE-ARG: imopt=<ro,inode64,...>
DESCRIPTION: optional rootfs mount options
EXAMPLE: imopt=inode64,noatime,ro for xfs file system@

KERNEL-COMMAND-LINE-ARG: imount=</usr:/var:...>
DESCRIPTION: mount /usr:/var using the included /etc/fstab
EXAMPLE: imount=/usr

Note: imount can be used to mount /usr:/var … using /etc/fstab.
Nothing more is required if using unencrypted volume.
However, if using LVM and/or LUKS and/or RAID array, one should make sure
that the underlaying volume are available before level 4m.

KERNEL-COMMAND-LINE-ARG: imod=<uvesafb:kms:...>
DESCRIPTION: optional modules to load (in the boot group)
EXAMPLE: imod=drm:drm_kms_helper:ttm:i915:radeon
EXAMPLE: if using the building scripts one can append imod=kms for basic
kms related drivers (one can append extra modules to opts[-mkms] in
mkinitramfs-ll.conf if need b).

KERNEL-COMMAND-LINE-ARG: ikmap=<kmap>[:<font>]
DESCRIPTION: optional keymap and font to load, handy for passwords
EXAMPLE: ikmap=fr-x86_64.bin:ter-g12n.psf

KERNEL-COMMAND-LINE-ARG: ishrl=<n>|:<n>
DESCRIPTION: interrupt init and drop to <n> level or pass <n> to real init
EXAMPLE: ishrl=3s drop to 3s (before squahsd()) init level,
or ishrl=:1 pass 1, so single to real init

KERNEL-COMMAND-LINE-ARG: rescue|rescueshell
DESCRIPTION: drops directly into a minimal shell
EXAMPLE:

Note: now with >=init-0.8.2 one can exit the rescue shell after beiing
dropped there, or simply after a rescue[shell] or ishrl=<n> on kernel
cmdline and the init will resume booting from there.

KERNEL-COMMAND-LINE-ARG: ilvm=<map-PV>,...,<map-PV>
DESCRIPTION: LVM argument <mapping-PV> is collon ‘:’ separated list of PVs of
a Volume Group; and comma ‘,’ separated list of VG: 1st for root, 2nd for swap
and the 3rd for resume. Hence one can append commas to asign a particular group.
EXAMPLE: lvm=pva-sda1:pvb-sdb1,pvc-sda1 assigne a single PV to swap group,
and two PVs to root group with its mappings.

Note: This argument is used only in case of dm-crypt LUKS crypted PVs.
Unencrypted PVs do not require this!
Asingle character or word is sufficient in that case.

KERNEL-COMMAND-LINE-ARG: iraid=<array>+UUID=<uuid>[|<p>|<f>]
DESCRIPTION: comma separated list of arrays for root, swap and resume
EXAMPLE:

KERNEL-COMMAND-LINE-ARG: iswap=<type>:<VG-LV>[:signature]
DESCRIPTION: the equivalent of iroot for swap
EXAMPLE: e.g. iswap=swap:sda2 for an unencrypted swap device

KERNEL-COMMAND-LINE-ARG: iresume=<type>:<VG-LV>[:signature]
DESCRIPTION: the equivalent of iroot for resume, to resume from the already
swap passed in the command line, one need only a iresume=swap cmdline.
EXAMPLE: e.g. iresume=file:<VG-LV>[:<signature>] for a swapfile in a Logical Volume

KERNEL-COMMAND-LINE-ARG: ikroot=<mode>:<device>:</path/to/file>
DESCRIPTION: key [file] mode for iroot group
EXAMPLE: ikroot=gpg:sdc1:/key.gpg for a GnuPG crypted key file in sdc1

KERNEL-COMMAND-LINE-ARG: ikswap=<mode>:<device>:</path/to/file>
DESCRIPTION: key [file] mode for iswap group
EXAMPLE: iswap=reg:sdb1:/key.reg for a regular key file in root of sdb1

KERNEL-COMMAND-LINE-ARG: ikresume=<mode>:<device>:</path/to/key/file>
DESCRIPTION: key [file] mode for iresume group
EXAMPLE: ikresume=pwd for a password mode

KERNEL-COMMAND-LINE-ARG: isqfsd=y[|/sqfsdir],y[|[n|a]:<dir>]
DESCRIPTION: squashed directories, see below for more info
EXAMPLE: isqfsd=y,a:lib64 use default squashed dirs and append /lib64

KERNEL-COMMAND-LINE-ARG: idebug=<x:...>[,<log_level>]
DESCRIPTION: optionaly enable a colon separated list of sh (set) option,
like shell tracing etc.; and otptional dmesg console log level
EXAMPLE: idebug=x enable shell tracing
EXAMPLE: idebug=x:e,debug enable shell tracing, export every assigned variable
and set debug console log level

init script accept also single, ro, rw and init=/path/to/real/init
kernel cmdline argument and will append single runlevel to real init.

It also support splash=silent,fadein,theme:emergence console=[/dev/]tty1
or splash=silent,fadein,theme:emergenc,tty:1 esplash kernel cmdline arguments.

There’s no need to provide any /dev/ prefix for block devices,
blk() will take care of it.
Now one can use UUID=<uuid> or LABEL=<label> instead of
[/dev/]sd[a-z0-9] for any block device or physical volume.
However, a leading plus + is used as a separator for
detached header device|file when using dm-crypt LUKS:
<map-UUID=<uid>[+UUID=<uuid>|</path/to/header/file>]

Each encrypted PV, with a detached header is given like:

• <sda+sdc> for a detached header to /dev/sdc device
  passed as --header /dev/sdc to dmopen().
• <sda+/path/to/header/file> for a detached header file
  passed as --header /mnt/tok/path/to/header/file to dmopen().

Note: So in this case, the header file must be in the same removable device
or /boot volume used for key-files.
Because it’ll be too troublesome to make it otherwise.

Warning: Of course, a detached header to a device should use an UUID or a LABEL
instead of to a block device sd[a-z0-9] to avoid header mismatch!

iraid argument can take up to 3 comma separated list of RAID arrays:
the 1st for root, 2nd for swap and the 3rd for resume.
Each argument is of the forme <array>+UUID=<uuid>[|<part>|<format>].
<format> is a metadata format used to scan dmraid set and subset
software (ata)raid and <part> a partiton number.

Either way, one can use mdadm software raid like iraid=md<n>+UUID=<uuid>
and optionaly embed or not an config file /etc/mdadm.conf.
Either way iraid is sufficient to enable arrays:

echo ARRAY <array> <uuid> >> /etc/mdadm.conf,
or else, iraid=md<n>+<part> to enable arrays like:
echo ARRAY <array> devices=/dev/sd*<part> >> /etc/mdadm.conf,
<part> could be something like [a-d]2.

Or else, an optional <format> can be used to enable mdraid software (ata)raid
e.g. asr|..|isw|jmicron|..|dos see mdraid -l. dmraid software raid can be
passed like iraid=<array>+isw:dos, ‘:’ as a metadata seperator.

Note: raid array can be used as the underlaying pyshical device of unencrypted
or encrypted with LVM on top.
<UUID=<uuid>> or <part> is required to enable mdadm software raid, nothing or
<format> can be used to enable dmraid sofware (ata)raid.

Actually a PV in a group, respectively root, swap, resume is given by
<mapping>-<device>, mapping being a mapping name for cryptsetup and
a block device/volume without the optional /dev/ prefix.

• LV, PV, VG: Logical Volume, Physical Volume, Volume Group.
• map-PV: is a colon separated list <mapping-PV> e.g. <pv1-sda1:pv2-sdb1:...>
  for a Volume Group, the 1st being for root, the 2nd for swap and the 3rd for resume;
  so this ilvm=,swp-sdc1, asign only a LV for swap.

NOTE: for unencrypted PVs, there’s no need to provide a list of PVs in ilvm arg.
A single character or word is enough to activate LVM like ilvm=y for root.

• PV list: now <map-PV> [list] can be replaced with </path/to/list> file,
  this require the use of keyfile to decrypt PV, which means that a removable media
  or /boot device is mounted.
  List can be a line separated list insted of a collon : of the forme:
  <mapping-UUID=<uid>[+UUID=<uuid>] for an UUID list.
  One can mix UUID, LABEL and [h|s]d??* in a list. However, it’s best to use UUID
  only for detached header from cyphertext device which prevent header mismatch.
  One can use multiple lists up to three, one for each group.

Say, you have a rootfs=xfs[|jsf|reiser|ext*] and want to mount your rootfs
with specific opts. In case of xfs, for exemple, just create your log volume
on a different volume than what you’re logging from and everything is set up—
well if the logging volume is in the swap group—and, in fact, you do
not need a swap volume there—you just use that group as if there were one.

For volume that are encrypted with a key, setting ikroot and/or ikswap
and/or ikresume is required, otherwise a passphrase is required for each
physical volume as a fall back.

• <mode>: defines how the init script shall treat the supplied key:

• gpg: key-file is GnuPG encrypted file
• ldk: key-file is LUKS encrypted, via loop back device
• reg: key-file is a regular file
• pwd: encrypted on a regular passphrase
• none: handy for unencrypted volumes

• <device|dev> is a block device that will be assigned to the removable media
• </path/to/file> is a full path to file inside the removable media

Notes on key modes

• gpg: GnuPG encrypted key-file support only gnupg-1.4*,
  used as gpg -qd /path/to/keyfile |. One can add a /root/.gnupg/gpg.conf
  in the initramfs root to avoid its creattion on each boot, a simple file
  is already included in the package
• ldk: encrypted key-file passed to cryptsetup as
  -d /dev/mapper/$(basename /path/to/keyfile) after decryption
• reg@: regular keyfile passed to cryptsetup as -d /path/to/keyfile
• pwd: regular passphrase: it’s mandatory to append any
  ikroot[|swap|resume]=pwd (fallback keymode for crypted devices)
• none: unencrypted block device, it’s not mandatory to append this
  key mode: this the default (v0.12.0)

One can use squashfs+aufs to squash directories like $PORTDIR:var/lib/layamn,
or system related directories like usr:lib32:lib64:bin:sbin. Advantages are
system speed, responsiveness and very small disk size footprint.

Squashed directories argument:

• isqfsd=y[|/sqfsdir],y[|[n|a]:<dir1>:<dirn>]
  using default or append directories after a [n|a]:
• isqfsd=/sqfsdir,n:<dir 1>:<dir n>
  neither sqfsdir nor sqfsd default is used, sqfsdir,sqfsd required
• isqfsd=y,y
  using sqfsd and sqfsdir default values do not require any additional argument.
• isqfsd=y,a:<dir 1>[:<dir n>]
  same as above, however, <dir 1>[:<dir n>] is appended to sqfsd variable.

DESCRIPTION: unencrypted Root LV
EXAMPLE: iroot=vgr-lvr ilvm=y ikroot=none ikmap=fr-latin1-i686.bin:ter-g12n.psf

Note: one can append any character or word like ilvm=lvr
when using LVM on unencrypted PVs.

DESCRIPTION: Root—regular passphrase—and fbsplash
EXAMPLE: iroot=root-sda3 video=1280x800-24 imod=drm:drm_kms_helper:ttm:i915 ikroot=pwd splash=verbose,theme:livecd-20007.0,tty:1

DESCRIPTION: Root—regular key-file—on usb device
EXAMPLE: iroot=root-sda3 ikroot=reg:sdb1:/path/to/keyfile

DESCRIPTION: Root—gpg encrypted key-file on usb drive
EXAMPLE: iroot=sda3 ikroot=gpg:sdb1:/path/to/file

DESCRIPTION: Swap and root—ldk encrypted—key-files
EXAMPLE: iroot=root-sda3 iswap=swap[|file]:data-sda2[:signature] ikroot=ldk:sdb1:/path/to/rootkey ikswap=ldk:sdb1:/path/to/swapkey

DESCRIPTION: Regular swap and TuxOnIce resume on a different volume
EXAMPLE: iswap=swap-sda2 iresume=toi-sda3:0x4400 ikswap=pwd ikresume=pwd

DESCRIPTION: Swap file—resuming from hibernation—ldk protected key-file
EXAMPLE: iswap=file:swap-sda3:0x4400 iresume=toi[|CHAR|WORD] ikswap=ldk:sdb1:/path/to/swapkey

DESCRIPTION: crypted volume [root,swap] using LVM—ldk crypted keyfile and—
and mount options for rootfs
EXAMPLE: iroot=vgr-lvr:c:xfs iswap=file:vgs-lvs:0x4400 imopt=logdev=/dev/mapper/vgs-lvl,inode64,barrier ilvm=pva1-UUID=uuida:pvb2-UUID=uuidb,pvc1-UID=uuidc ikroot=ldk:LABEL=PENDRIVE:/path/to/keyfile ikswap=ldk:LABEL=PENDRIVE:/path/to/keyfile

NOTE: multiple key-files (one for each group) are supported along with single
a key file.

To load kernel modules, one could either create needed groups in
mknitramfs-ll.conf as the kms kernel module group example.
Afterwards, one only need to append generaed groups as imod=kms instead of
append a long list of modules like @imod=

Supported groups:

• boot: boot up modules, loaded but not removed
• dm-crypt: automaticaly generated with mkinitramfs-ll.$shell (dm-crypt module group)
• devide-mapper: automaticaly generated included script (device-mapper module group)
• dm-raid: automaticaly generated with included script (dmraid module group)
• raid: automaticaly generated with mkinitramfs-ll.$shell (mdadm/raid module group)
• tuxonice: tuxonice module, wich aren’t removed
• remdev: modules required to access removable device
• gpg: modules required to access gpg crypted key-file
• sqfsd: modules required for squashfs+aufs, can be built into the kernel

Modules should exist in /lib/modules/$KV/, the kernel should support modules
[un]loading. Just make sure to append the necessary modules to the right group
in mkinitramfs-ll.conf for autoloading, or create your own groups, or else append
kernel modules to opts[-mdep] variable to be able to append kernel mdoules to
imod= kernel cmdline argument.

Now one can add scripts to /etc/mkinitramfs-ll.d of the initramfs root, or else in
$gitdir/usr/etc/mkinitramfs-ll.d if using mkinitramfs-ll.$shell generating script.

Each script should have a .$level sufix as the follwing:

• runlevel 1: initialization — splash — keymap — font — print boot msg — 1
• runlevel 2?: 2s — swap — 2r — resume - rootfs -
• runlevel 3?: 3d — decrypt — 3f — rootfs fsck — 3m - root mount -
• runlevel 4?: 4c — clean up — 4m — mount /usr:/var… - 4u -
  umount — 4s — switch root

Info: See zfs module for more info and a praticable example.

One can use something like iroot=POOL/ROOT[::zfs][ izfs=zva-sda:zvb-sdb].
Notice that izfs= argument is required for crypted vdev(s). Do not forget to
include zfs module or build an initramfs with something like:
mkinitramfs-ll.$shell -a -f -y -Mzfs -b:zpool:zfs
(kernel modules would be rightly added).

IMPORTANT: So either way one can append ::zfs to iroot argument for
[un]encrypted vdev(s) or :zfs to iswap or iresume;
or either izfs will suffice for encrypted vdev(s); or else both.

vim:fenc=utf-8:ci:pi:sts=0:sw=4:ts=4: