mkinitramfs-ll.5

.\"
.\" CopyLeft (c) 2015-2017 -tclover <tokiclover@gmail.com>
.\"
.\" Distributed under the terms of the 2-clause BSD License as
.\" stated in the COPYING file that comes with the source files
.\"
.pc
.TH MKINITRAMFS-LL 5 "2019-02-18" "0.22.12" "File Format Manual"
.SH NAME
init \- an initramfs init script
.SH DESCRIPTION
.B init
require
.IR /lib/mkinitramfs-ll/functions
shell function library
.IR /lib/mdev/dm_link
for device-mapper (symlink) and optional files (see
.B FILES
) sections to be fully
.IR functionnal
depending on the requirements and set up. The
.IR configuration
files are kept in
.IR /etc/mkinitramfs-ll
directory and will be used if present or nothing if not.
Kernel module [un]loading support is required as well.
.SH SYNOPSIS
Append the appropriate
.I OPTIONS
according to the boot set up following
.B OVERVIEW
and 
.B OPTIONS
to the kernel command line.
And do not forget to append the initramfs to the boot loader.
.rb

GRUB[2] has, for example, `linux \fIpath/\fR' prepended to the kernel image and
`initrd \fIpath/\fR' prepended to the initramfs image.

.B vmlinuz\fI-$VERSION\fR [\fIOPTIONS\fR]
.rb
.B initramfs\fI-$VERSION\fR.cpio.xz

When using this initramfs, only `root' kernel command line argument is required.
Similarly, `swap' and `resume' are available as well. Of course, resuming for
the regular swap device is supported by setting `resume=swap'.

Each \fIfeature\fR,--
.B SQUASHD (AUFS|OverlayFS+SquashFS),
.B BTRFS,
.B LUKS,
.B LVM,
.B RAID,
.B ZFS,
.B ZRAM,
-- require an appropriate kernel command line argument `\fR\fIfeature\fR' if used.

The following conventions apply to
.B SYNOPSIS
,
.B OVERVIEW
and
.B OPTIONS
section and can be applied to the command line arguments.
.TS
tab (@);
l lx.
\fBbold text\fR@T{
type exactly as shown
T}
\fIitalic text\fR@T{
replace with appropriate argument
T}
[\|text\|]@T{
any or all argument within [ ] are optional
T}
(\|text|text\|)@T{
replace with any argument within ( ) and remove the parenthesis
T}
\fIYes\fR@T{
can be replaced with (case insensitive) Yes|Enable|On|True|1
T}
\fINo\fR@T{
can be replaced with (case insensitive) No|Disable|Off|False|0
T}
dev|device@T{
replace with the appropriate device|UUID|LABEL
T}
map|mapping@T{
replace with the appropriate mapping (name)
T}
LV/PV@T{
replace with the appropriate Logical/Physical Volume
T}
VG@T{
replace with the appropriate Volume Group
T}
POOL/VOL@T{
replace with the appropriate ZFS Pool/Volume
T}
.TE
.SH OVERVIEW
.TP
.RB video=\fI2560x1600-32\fR
.br
This will set the video settings if
.I fb-video
hooks is included in the initramfs.
This can be used to force the correct video settings for buggy firmware.
.TP
.RB root=\fIdevice\fR
.rb
Set root required cmdline argument: \fIdevice\fR should be
\fImap\fR-\fIdev\fR for dm-crypt LUKS crypted volume;
Or \fIVG\fR-\fILV\fR for LVM volume;
Or \fIPOOL\fR/\fIVOL\fR for a ZFS volume.
See \fBDEVICES\fR for more info.
.TP
.RB rootfstype=\fIFileSystem\fR[:(Yes|No)]
.RB rootfs=\fIFileSystem\fR[:(Yes|No)]
.rb
Set root FS with optional fsck. \fIYes\fR enable fsck and a `die' on fsck failure
while \fINo\fR disable it; And nothing to disable fsck at all.
.TP
.RB rootflags=[\fIoption\fR]
.rb
Set root mount option e.g. `rootflags=user_xattr' for an ext4 FS
.TP
.RB swap=\fItype\fR:\fIdevice\fR[:\fIsignature\fR]
Set swap cmdline argument: refer to above `root' cmdline for more info
on \fIdevice\fR. \fItype\fR is either `swap' for a device or `file' for a swap file.
.TP
.RB resume\ (same\ as\ above\ `swap')
.rb
(It is unecessary to set a key(mode/file) for `resume=swap'.)
.TP
.RB luks=[\fImode\fR[:\fIdevice\fR:\fIfile\fR]],[\fImode\fR[:...]],[\fImode\fR[:...]]
.rb
Set key mode for dm-crypt LUKS crypted volume; 1st group for root, 2nd for swap
and 3rd for resume (like LVM... argument.) See
.B KEYMODES
for more info on key modes, and
.B DM-CRYPT LUKS
for more info.
.rb
When a keyfile is used, a
.RI device
is required along with the full path to
.RI keyfile
e.g. `luks=ldk:sdb1:/key.ldk,,reg:sdb1:/key.reg'
to set `ldk' keymode for root (in a removable device);
`none', no key, for swap; and a regular keyfile for resume.
.TP
.RB lvm=[\fImap-dev\fR][,\fImap-dev\fR][,\fIYes\fR]
.rb
Set LVM[2] optional argument; 1st  group for root, 2nd group for swap and 3rd
group for resume. Comma can be used to append a particular group. And a group
is a colon separated list of `\fImapping\fR-\fIdevice\fR' for crypted PV e.g.
`lvm=pva-sda:pvb-sdb' for two crypted PV for root VG; Or else, \fIYes\fR is enough
to enable LV on plain devices.
See \fBDEVICE-MAPPER (LVM[2])\fR for more info.
.TP
.RB raid=[md\fIi\fR+UUID=\fIuuid\fR][,md\fIj\fR+isw[:\fIformat\fR][,md\fIk\fR+sd[\fIX\fR-\fIY\fR]\fIn\fR]
.rb
Set RAID optinal argument (comma separated list): first group for root, second for
swap and third for resume. Hence using comma to asign an array to a particular
group can be used. Three different layouts are used above, so just replace \fIi\fR,
\fIj\fR, \fIk\fR and \fIn\fR by actual integer; \fIX\fR and \fIY\fR by actual letter
in the range of `[a-z]';
and \fIuuid\fR by an actual UUID value to get a functional argument.
See \fBRAID\fR for more info.
.TP
.RB btrfs=[\fImap-dev\fR][,\fIdev\fR]
.rb
Enable
.B BTRFS
by setting a comma separated list of
.I mapping-device
to three groups (1st for root, ...
like RAID and LVM[2] argument.) Like LVM[2], the `\fImapping-device\fR' is required
only for crypted devices; Or else, a device list (without `\fImapping\fR-' prefix)
will suffice otherwise. See
.B BTRFS
for more info.
.TP
.RB zfs=[\fImap-dev\fR][,\fImap-dev\fR][,\fIYes\fR]
.rb
Enable
.B ZFS
by setting a comma separated list of
.I mapping-device
to three groups (1st for root, 2nd for swap and 3rd for resume
like RAID and LVM[2] argument.)
Like LVM[2], the list is required for crypted physical volume only,
`\fIYes\fR' will suffice otherwise for plain device.
.rb
Of course, an appropriate
.rb root
and or
.rb swap
and or
.rb resume
is required. See
.B ZFS
for more info.
.TP
.RB zram=[4-2-lzo]:[\fIsize\fR[-\fIFileSystem\fR]]
.rb
Set optional zram internal options (\fIdevices\fR-\fIstreams\fR-\fIcompressor\fR);
Followed by device pair e.g. `4G-ext4' for a 4GB ext4 filesystem device.
Just make sure to have the appropriate binary & symlink in the initramfs.
.rb
.B ZRAM
internal options  can be tweaked
e.g. `8-4-lz4' would set up 8 devices, 4 streams per device and use lz4 compressor;
Default options are `4-2-lz4' (e.g. `zram=:4G:4G' setup 2 devices.)
.TP
.RB debug=[\fIoption\fR]:[\fIn\fR]
.rb
Set extra init shell options; And/Or
dmesg console log level e.g. `debug=ax:3' (to enable shell tracing & export
every variable; and set log level to error.)
.I l
option cause standard error to be duplicated to $LOGFILE or file descriptor 3.
.TP
.RB fsmount=[/usr:/var:\fIdirectory\fR]|\fBall\fR
.rb
Mount file system according to (required in this case)
.RI `/etc/fstab'
file. Every file system shoud be available before shell run level
.RI 4m
(see
.B SHELL RUN LEVELS
). Or else, use case insensitive
.B a|all
to mount everything.
(Or use \fBfstab\fR instead of \fBfsmount\fR to get the same effect.)
.TP
.RB hook=[\fIname\fR]
.rb
Append hook or script to the hook stack for execution e.g. `hook=zfs:zram'
(unecessary because zram & zfs are executed if `zfs' or `zram' are set.)
.TP
.RB keymap=[\fIkmap\fR][:\fIfont\fR]
.rb
Optional keymap and font to load, if not set,
default will be picked if present e.g.
.RB keymap=fr-latin1-x86_64:ter-g12n
.TP
.RB module=:\fImodule\fR
.rb
Colon separated list of kernel module to load at boot time
e.g. `module=uvesafb:hid-multitouch'
.TP
.RB squashd=[\fIdir\fR]:[\fIoption\fR]:[\fIdir\fR]
.rb
Set up squash-dir (AUFS|OverlayFS+SquashFS) argument. See
.B SQUASHED DIRECTORY
for more info.
.TP
.RB splash=(silent|verbose),fade(in|out),theme:\fITHEME\fR[,tty:\fITTY\fR]
.rb
Legacy
.RB splash
command line argument, along with
.RB console|CONSOLE
e.g. `CONSOLE=tty1', are supported for fbsplash.
.TP
.RB env=No|:\fIVAR\fR:\fIVAR\fR:
.rb
Disable default `env' environment variables; Or disable only appended colon
separated list e.g. `env=:root:init:' to disable `root' & `init' default.
NOTE: The list start & end with a colon!
.TP
.RB level=[\fIlevel\fR]
.rb
Set
.I level
to halt init in a particular shell run level.
.TP
.RB rescue[shell]|rsh[ell]\ (case\ insensitive)
.rb
Halt init and drop to a rescue shell at shell run level 1.
Exit the rescue shell to resume booting.

A rescue shell is also available in any `read' loop (when a password or a device
is requested.) Any (case insensitive) `Rsh|Sh|Shell|Rescue' (Enter) may be used
to get a rescue shell (`exit' to leave it.)
.TP
.RB cryptsetup_args=--allow-discards:--some-option:--some-other-option
.rb
Pass arbitrary extra command line arguments to cryptsetup.
.SH OPTIONS
.TP
.SS KEYMODES
.rb
.B init
support the following optional key[-file] mode.
.rb
.TS
tab (@);
l lx.
\fBgpg\fR@T{
GnuPG crypted key-file (require gnupg-1.4.x)
T}
\fBldk\fR@T{
dm-crypt LUKS crypted key-file (using a loop back device)
T}
\fBreg\fR@T{
key-file is a regular file
T}
\fBpwd\fR@T{
key is a regular password
T}
\fBnone\fR@T{
no usage of crypted device (this is the default)
T}
.TE
.TP
.SS DEVICES
.rb
Block Device can be provided using a canonical name, that is, with or without
`/dev/[mapper/]' prefix in any command line argument.
Device can also be specifed using UUID/LABEL (part of an UUID/LABEL is supported.)

.B WARNING:
PARTUUID/LABEL is also supported if util-linux \fBblkid(1)\fR is used;
the default configuration. Use only UUID/LABEL if blkid(1) is removed from the
binary set becaue busybox blkid does not support the \fBPART\fR variant.
.TP
.SS DM-CRYPT (LUKS)
Each member of
.B luks
cmdline argument, is given following \fImode\fR:[\fIdevice\fR:\fIfile\fR] syntax.
(Note, it is unecessary to set up `none' keymode.)
When a keymode is specifed, just use the appropriate argument in
.RB root
and or
.RB swap
and or
.RB resume
which should have
.RB \fImapping\fR-\fIdevice\fR[+\fIHEADER\fR]
instead of plain
.RI device
with an optional header for detached header support.
.rb

So, detached header is simply enabled by appending an appropriate +\fIHEADER\fR
to any crypted device.
.IR HEADER
should be a valid dm-crypt LUKS header by being either a block device or a
regular file in the removable device \-\- a key mode other than \fBnone\fR is
required e.g. \fIluks=pwd:sdb1\fR for a detached header file.
Using something like `dma-sda+(/dev/sdb1|/dma.header)'
is correct but using UUID e.g. `dma-UUID=cyphertext+(UUID=header|/dma.header)'
instead of plain path is prefered to avoid header mis-match.
.TP
.SS DEVICE-MAPPER (LVM[2])
.rb
Each
.RB \fImapping\fR-\fIdevice\fR
list in
.rb lvm
kernel command line argument can be a colon seprated list, or a
.IR /path/file
inside a removable device (key \fIfile\fR mode is required.)
However,
.RB \fImap\fR-\fIPV\fR
list is \fIonly\fR required for crypted Phycal Volume. LVM[2] on plain device
can be enabled with `\fIYes\fR' in the appropriate field e.g. `lvm=pva-sda2,\fIYes\fR'
would be enough to open a crypted VG/LV for root and another VG/LV on a plain
device for swap. Just append the appropriate `root' and `swap' accordingly e.g.
`root=vgr-root rootfs=ext4:\fIYes\fR swap=swap:vgs-swap'.
.TP
.SS RAID (FAKE ATA RAID & SOFTWARE RAID)
.rb
To complete the
.B OVERVIEW RAID
sub-section,
.B FAKE ATA RAID
can be enabled using the \fIarray\fR[+\fIformat\fR] syntax
(format is optional and can be a colon separated list of format, see `dmraid -l');
while
.B SOFTWARE RAID
can be enabled using the \fIarray\fR+(UUID=\fIuuid\fR|\fIdevices\fR) syntax
(\fIuuid\fR being a valid UUID value and \fIdevices\fR being a supported
device set described in the
.B OVERVIEW
sub-section (`[/dev/]sd[\fIX\fR-\fIY\fR]\fIn\fR').)

To get support of
.B SOFTWARE RAID
on top of
.B DM-CRYPT LUKS
, replace the previous syntax with
.B /dev/mapper/*[X-Y]:[/dev]sd[X-Y]n
with
.B `[/dev]'
being optional prefix, and
.B `[X-Y]'
being a valid device range e.g `[a-d]', and
.B n
being a valid integer e.g. `3'. The device range would be decrypted to
.B `/dev/mapper/md-sd[X-Y]n
and used for the array instead of the plain block devices.
.TP
.SS SQUASHED DIRECTORY (AUFS|OVERLAYFS+SQUAHFS)
Squashed directory require
.B AUFS|OverlayFS+SquahsFS
kernel module and
.RB squashd
kernel command line argument.
.rb
The first optional
.IR direcory
is the root directory where to mount the merged directories hierarchy (default is `/squash'.)
A case insensitive
.RB [:+S[system]][:+L[ocal]]
to use system default (`usr:bin:sbin') and local default
(`var/cache/edb:var/db:var/lib/layman') directory sets.
An optional
.IR :(aufs|overlay)
option selects a union filesystem implementation to use.
Eextra squashed directories (colon separated list) can be appended
e.g `squashd=:aufs:+l:usr/src:opt'.
.rb
.TP
.SS BTRFS
.rb
.B BTRFS
requires
.RB btrfs
kernel command line argument and
.rb \fBLABEL=\fR\fIlabel\fR|\fBUUID=\fR\fIuuid\fR
BTRFS filesystem provided (in another argument) like
\fBroot=LABEL=btrootfs\fR [rootfs=:\fIYes\fR] for root.
.rb
.RB btrfs
is a comma `,' sepratated list of volume (1st for root, ...);
And each group is colon `:' separated list of
.rb \fImapping\fR-\fIdevice\fR
.rb if,\ and\ only\ if,
the physical devices are
.B DM-CRYPT
LUKS crypted (like LVM[2] & ZFS.) Or else, a device list (without
`\fImapping\fR-' prefix ) will suffice for plain devices.
.TP
.SS ZFS
.rb
.B ZFS
requires
.RB zfs
kernel command line argument and
.rb \fIPOOL\fR/\fIVOL\fR
volume provided by either \fBroot=\fR\fIPOOL\fR/\fIVOL\fR and or
\fBswap=\fR\fItype\fR:\fIPOOL\fR/\fIVOL\fR[:\fIsignature\fR] and or
\fBresume=\fR\fItype\fR:\fIPOOL\fR/\fIVOL\fR[:\fIsignature\fR].
.rb
.RB zfs
is a comma `,' sepratated list of dataset (1st for root, 2nd for swap and 3rd for
resume); and each group is colon `:' separated list of
.rb \fImapping\fR-\fIdevice\fR
.rb if,\ and\ only\ if,
the physical volumes or devices are
.B DM-CRYPT
LUKS crypted. Or else, `\fIYes\fR' would be sufficient for plain devices.
.TP
.SS SHELL RUN LEVELS
.TS
tab (@);
l lx.
\fB1\fR@T{
initialization, splash... keymap and font (if any)
T}
\fB2\fR@T{
resume `2r' and swap `2s' if `resume' and `swap' are set
T}
\fB3\fR@T{
rootfs fsck `3f', mount `3m' and squashed directories `3s' if `squashd' is set
T}
\fB4\fR@T{
extra mount `4m' if `fsmount' is set, sysfs umount `4u' and root switch `4s'
T}
.TE
.TP
.SS HOOKS
User scripts (hooks) can be included in the initramfs (\fBLIBDIR\fR),
and can be thus executed if appended to `hook' command line argument.
Or else, a script can be bound to a particular shell run level for automatic execution,
just prepend \fIlevel\fR- to the script name.
See
.B SHELL RUN LEVELS
for more info on level values.
.SH EXAMPLES
Unencrypted Root LVM[2] (keymap & font)
  root=vgr-lvr lvm=Yes keymap=fr-latin1-i686:ter-g12n

Root(LUKS)--regular passphrase--& fbsplash
  root=root-sda3 luks=pwd splash=verbose,theme:emergence,tty:1 video=1280x800-24

Root(ZFS/LUKS)--regular keyfile--& detached header
  root=POOL/ROOT zfs=vda-sda+/vda.hdr luks=reg:sdb1:/key.reg

Root(BTRFS/LUKS)--gpg crypted keyfile--on usb drive
  root=LABEL=btrootfs rootfs=:Yes btrfs=pva-sda luks=gpg:sdb1:/key.gpg

Swap & root(LUKS)--ldk/reg crypted--keyfile
  root=root-sda3 swap=file:data-sda2:0x4400
  luks=ldk:sdb1:/key.ldk,reg:sdb1:/key.reg

Regular swap & TuxOnIce resume on a different volume
  swap=swap:sda2 resume=swap:sda3:0x4400

Root(LUKS/SOFTWARE RAID)--ldk crypted--key-file
  root=root-md2 raid=md2+UUID=uuid luks=ldk:sdb1:/key.ldk

Root & swap(LVM/LUKS)--ldk crypted keyfile--& rootfs mount options
  root=vgr-lvr rootfs=xfs:1 swap=file:vgs-lvs:0x4400
  rootflags=logdev=/dev/mapper/vgs-lvl,inode64,barrier
  lvm=pva1-UUID=uuida:pvb1-UUID=<uuidb>,pvc1-UID=<uuidc>
  luks=ldk:LABEL=PENDRIVE:/root.ldk,ldk:LABEL=PENDRIVE:/swap.ldk
.SH ENVIRONMENTS
.TP
.B SYSFS
.rb
Filesystem to keep mounted e.g. `SYSFS=/dev:/sys:/proc'
.TP
.B INTERNAL
Other Environment Variables are defined internaly in
.B init.
.SH FILES
An image like file system hierarchy is installed in @DATADIR@/mkinitramfs-ll/
.TP
.RB /etc/mkinitramfs-ll/\ (CONFDIR)
.rb
busybox.applets
  BusyBox applets list
.rb
env
  Environment Variables file (kernel command line less is possible)
.rb
font
  Default console font
.rb
id
  ID of the build script
.rb
kmap
  Deafult keymap
.rb
KERNEL-MODULE-GROUPS
  Optional kernel module group; Refer to the following (supported) auto generated groups.
.rb

.B KERNEL-MODULE-GROUPS:\ \c
.RB [\| bcache \|]\ \c
.RB [\| boot \|]\ \c
.RB [\| btrfs \|]\ \c
.RB [\| device-mapper \|]\ \c
.RB [\| dm-crypt \|]\ \c
.RB [\| dm-raid \|]\ \c
.RB [\| gpg \|]\ \c
.RB [\| raid \|]\ \c
.RB [\| remdev \|]\ \c
.RB [\| squashd \|]\ \c
.RB [\| swsusp \|]\ \c
.RB [\| tuxonice \]\ \c
.RB [\| zfs \|]\ \c
.RB [\| zram \|]
.TP
.RB /etc/mdev.conf
mdev 
.IR configuration
file (BUG: use uid:gid instead of user:group, see BUGS.)
.TP
.RB /etc/group
Group/gid list (usefull to get user:group instead of uid:gid)
.TP
.RB /etc/modprobe.d/zfs.conf
ZFS configuration file to set arc to a reasonable value
.TP
.RB /lib/mkinitramfs-ll/\ (LIBDIR)
.rb
functions
.rb
helpers
.rb
HOOKS/SCRIPTS
  Optional (user) script are supported; Refer to the following supported list.

.B HOOKS: \c
.RB [\| bcache \|]\ \c
.RB [\| btrfs \|]\ \c
.RB [\| zfs \|]\ \c
.RB [\| zram \|]
  Supported hooks used when the appropriate kernel cmdline is present
.rb
.B SCRIPTS: \c
.RB [\| mkswap-zfs \|]\ \c
.RB [\| disable-bcache \|]
.rb
  Use this syntax `$sh $LIBDIR/\fIscript\fR \fIARGS\fR' to execute a script in the rescue shell;
  (sh/LIBDIR are defined, just append the appropriate arguments.)
.TP
.RB /lib/mdev/
.rb
dm_link
.rb
SCRIPTS
  Extra mdev scripts are supported
.TP 
.RB /usr/share/consolefonts
console fonts directory used to search and load font
.TP
.RB /usr/share/keymaps
key map directory used to search and load keymap
.SH "SEE ALSO"
.rb mkinitramfs-ll (8)
.SH AUTHORS
-tclover <tokiclover@mkinitramfs-ll.project>
.\"
.\" vim:fenc=utf-8:ft=groff:ci:pi:sts=2:sw=2:ts=2:expandtab:
.\"