$Header: mkinitramfs-ll/README.textile,v 0.14.2 2014/10/10 10:59:54 -tclover Exp $
“an initramfs with *optional RAID (dmraid/mdadm), DM-Crypt LUKS, LVM,
TuxOnIce, AUFS+squashfs, ZFS, zram support; and maybe much more; and
with a handfull zsh and bash set of scripts to get going easily and quickly.”
BIG FAT NOTE: SUPPORTED BLOCK DEVICE STACK IS:
[RAID][LUKS][LVM] or [LUKS]+[ZFS]
It is possible to add ZFS on the first stack variant, but it does not make any
sense and expect horrible performance with such a mix bag. And this variant is
not implemented although it could be done easily.
The order of LUKS/LVM can be changed, that is LUKS+LVM or LVM+LUKS is possible.
WARNING: USE AT YOUR OWN RISK! EVERYTHING IS GIVEN “AS IS”, SEE COPYRIGHT FILE
If you have a static busybox binary 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.
*WARNING: no static busybox support require a very minimal effort, however,
this is discrouraged as it could lead easily to kernel panics without care.
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 will build a binary in the current directory
(with a usr/bin/gpg and usr/share/gnupg/options.skel) if not installed
or else in /usr/local/mkiniramfs-ll/ directory if installed.
Or else, run the bash script counterpart to get build a binary.
And then run mkinitramfs-ll.$shell -a -fter-g14n -yfr to build an initramfs.
The appended font and keymap will be the default if there is no ikmap kernel
cmdline argument.
Of course, one can append extra fonts and keymaps with -f:ter-g12n -y:fr-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 -h
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>[:<fs>:chk]
DESCRIPTION: root block device, required,
recommanded optional file system check :[<filesystem>]:[c|chk|yes|1|...]
EXAMPLE: iroot=vg-root:ext4:1 for an ext4 rootfs in LVM (Volume Group is named vg),
or iroot=POOL/ROOT izfs=yes for a zfs rootfs (ROOT) in a pool called POOL.
Note: :[no|NO:No:false:FALSE:0] instead of :[c|chk|true|TRUE|yes|YES:1]
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 kernel modules to load (in the boot group)
EXAMPLE: imod=kms:uvesafb
EXAMPLE: if using the building scripts one can append imod=kms for basic
kms related drivers group (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: irsh=<n>|:<m>
DESCRIPTION: interrupt init and drop to a Rescue SHell (<n> level);
or pass <m> run level to real init if present
EXAMPLE: irsh=3s drop to 3s (before squahsd()) init level,
or irsh=:1 pass 1, so single to real init
KERNEL-COMMAND-LINE-ARG: rescue|rescueshell|RSH|RSHELL
DESCRIPTION: drops directly into a minimal shell
EXAMPLE: RSH
Note: one can exit a rescue shell and then resume booting !
Type in exit and hit Enter
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: iroot=md1 iraid=sd[ab]+UUID=<uuid>
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: isquashd=/var/aufs:+LOCAL:<dir>]
DESCRIPTION: squashed directories, see below for more info
EXAMPLE: isquashd=:+L:var/portage use default local squashed directories,
append var/portage and use default /aufs squash root directory.
KERNEL-COMMAND-LINE-ARG: idebug=ax[:2]
DESCRIPTION: optionaly enable a list of sh (set) options string,
like shell tracing etc.; and otptional dmesg console log level
EXAMPLE: idebug=ax:3 enable shell tracing, export every variable
and set log level to error.
KERNEL-COMMAND-LINE: ihook
DESCRIPTION: execute colon separated list of named hooks or scripts
EXAMPLE: ihook=zram
Note: Nobody would ever want to append zram hook to ihook as zram
script would be executed if izram kernel cmdline argument is present.
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.
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 fileldk: key-file is LUKS encrypted, via loop back devicereg: key-file is a regular filepwd: encrypted on a regular passphrasenone: 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
gpg: GnuPG encrypted key-file support only gnupg-1.4*,
used asgpg -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 packageldk: encrypted key-file passed to cryptsetup as
-d /dev/mapper/$(basename /path/to/keyfile)after decryptionreg: regular keyfile passed to cryptsetup as-d /path/to/keyfilepwd: 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)
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/sdcdevice
passed as--header /dev/sdcto dmopen().<sda+/path/to/header/file>for a detached header file
passed as--header /mnt/tok/path/to/header/fileto 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!
If one need uncompressed initramfs e.g. to integrate directly into the kernel
to be able to self sign the kernel for UEFI, just pass -c'none' to building
script. Just remember to include the initramfs to the kernel .config file:
CONFIG_INITRAMFS_SOURCE=/boot/initramfs-${KV}.cpio.
Of course, one can decompress existant initramfs for this purpose as well.
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 /dev/sd[a-d]2|sd[a-d]2|[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 thisilvm=,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/bootdevice 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.
One can use squashfs+aufs to squash local directories like
$PORTDIR:var/lib/layamn:var/db:var/cache/edb,
or system related directories like usr:lib32:lib64:bin:sbin. Advantages are
system speed, responsiveness and very small disk size footprint. To favor speed,
one should use ‘lzo -Xcompression-level 1’, which is the default, until lz4 get
proper support in squashfs-tools and in kernel (squashfs module).
- default squashed root directory is
/aufs - default system wide squashed directories is
usr:bin:sbin:lib32:lib64 - default local wide squashed directories is
var/cache/edb:var/db:var/lib/layman
isquashd=:+sys:+local:[<dir1>:<dirn>]
use default root directory, and sytem/local wide directories and optionaly
append directories to the list of squashed directories;isquashd=/var/aufs:<dir 1>:<dir n>
no default directory-ies used, and append everything on kernel commmand line;isquashd=:+l
use default root directory and local squashed directories (no extra argument);isquashd=:+l:var/portage
same as above and appendvar/portageto squashed directories.
- lastly, sys|local are case insensitive and the first character is valid.
Now, one can add hooks/scripts to hooks/ directory, or else directly in
$gitdir/usr/lib/mkinitramfs-ll if using mkinitramfs-ll.$shell generating script.
Basically, each script is considered to be a hook! So one can append -H$script
to mkinitramfs-ll.$shell; and if there is a opts[-m$script] kernel module group
line in mkinitramfs-ll.conf, the modules and module group will be added!
Each script should have a $level- prefix as the follwing $level values if the
execution is bound to a specific init shell run level.
- runlevel 1: initialization – splash – keymap – font – boot logo/message -
- runlevel 2: 2 – hooks –
2s– swap –2r– resume - - runlevel 3: 3 – rootfs –
3f– rootfs fsck –3m– root mount - - runlevel 4: 4 – clean up
4m– extra mount –4u– umount –4s– switch root
Else, ihook kernel command line could be used to execute a hook/script now and
then e.g. ihook=zram append zram to script execution.
Info: See zfs/zram hook for more info and a praticable examples.
KERNEL-COMMAND-LINE-ARG: izfs=zva-sda:zvb-sdb
DESCRIPTION: Required argument for crypted zfs vdev (devices), or else, izfs=1
(1 can be replaced by case insensitive enable|on|true|yes) for un-encryoted vdev
EXEMPLE: iroot=POOL/ROOT izfs=zva-sda:zvb-sdb ikroot=pwd
To get support for zfs append Hzfs or -a|-all to building script.
Several pools (one containing root, another for swap and another one for resume)
are supported along with a single pool. Just append a coma and an argument (2nd
for swap and 3rd for resume like the other options).
So iroot=POOL/ROOT ikroot=pwd iresume=swap:POOL/SWAP ikresume=pwd izfs=,,zva-sda:zvb-sdb;
Optional (useless) swap arguments can be appended when resuming after a suspend;
Root arguments is not required (handy to continue booting if resuming fails).
And lastly specifying only iroot=POOL/ROOT ikroot=pwd izfs=zva-sda:zvb-sdb will
import the whole pool (so no need to append swap related arguments).
KERNEL-COMMAND-LIE-ARG: izram=4-2-lzo:512M:4G-ext4
DESCRIPTION: zram basic initialisation kernel command line argument
EXEMPLE: :512M:4G:512M
This hook/script take care of basic zram initialisation:
- First integer: passed as num_devices= to modprobe;
- Second integer is passed to max_comp_streams;
- Third string is passed comp_algorithm (compressor);
- Following arguments are pair of size-filesystem: just make sure to include
the related mkfs.$fs binaries if the fie system string is appended! - Lastly, the first string
4-2-lzocan be omited so the default will be
picked up4-2-lz4as in the last kernel cmdline example.
Just appand -H:zram to mkinitramfs-ll.$shell to get support for this hook.
bcache cache and backing device are grouped as a colon separated list of block
device, registered using: echo device >/sys/fs/bcache/register_quiet
KERNEL-COMMAND-LIE-ARG: ibcache=sda:sdb2:sdc2
DESCRIPTION: bcache cache:backing-device block device list
EXEMPLE: ibcache=sda:sdb1
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:xfs:chk 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.
init script support an environment profile that can be used to define every
kernel cmdline option (and boot with an empty cmdline). See the configuration file.
To load kernel modules, one could either create needed groups in the configuration
file as the kms kernel module group example.
Afterwards, one only need to append generaed groups as imod=kms instead of
appending a long list to imod. Module group name can be used in the boot group
like the kms group.
Supported groups:
boot: boot up kernel modules, loaded but never removeddm-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 removedremdev: modules required to access removable devicegpg: modules required to access gpg crypted key-filesquashd: modules required for squashfs+aufs, can be built into the kernelkms: kms esential kernel module group, see mkinitramfs-ll.confzfs: zfs related kernel module group, see configuration filezram: zram related kernel module group
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[-kmod] variable to be able to append kernel mdoules to
imod= kernel cmdline argument.
vim:fenc=utf-8:ci:pi:sts=0:sw=4:ts=4: