tinyramfs/docs/tinyramfs.5

.\" Generated by scdoc 1.11.0
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "tinyramfs" "5" "2020-09-04"
.P
.SH NAME
.P
Tinyramfs - configuration file
.P
.SH SYNOPSIS
\fB/etc/tinyramfs/config\fR
.P
.SH DESCRIPTION
.P
Let's reduce confusing situations and document everything !\&
.P
.SS MAN PAGE SYNTAX
.P
.nf
.RS 4
*   - any value
[a] - optional value
\&.\&.\&. - can be repeated
0|1 - choice between no and yes
.fi
.RE
.P
.SS CONFIG SYNTAX
.P
Tinyramfs configuration file is a list of environment variables.\&
Each variable must be written in POSIX way, bashism not allowed.\&
.P
Example:
.P
.nf
.RS 4
key=value
.fi
.RE
.P
If value contains spaces it must must be quoted.\&
.P
.nf
.RS 4
key="value value2"
.fi
.RE
.P
If value contains special symbols like $, it must be escaped
or quoted using single quotes.\&
.P
.nf
.RS 4
key=\\$value
key='$value'
.fi
.RE
.P
If line exceeded maximum space on your display and you want to make it
more readable, you can concatenate them.\&
.P
.nf
.RS 4
key=value
key="${key}value"
.fi
.RE
.P
If you want to temporary undefine variable without actually deleting it,
you can simply prepend #.\&
.P
.nf
.RS 4
#key=value
.fi
.RE
.P
.SH GENERAL OPTIONS
.P
\fBmonolith\fR=0|1
.P
.RS 4
Monolithic kernel means kernel with builtin modules.\&
If you didn't build kernel yourself, then in most cases you have
modular kernel and you don't need to enable this option.\& To check
if you have monolithic you need to check if \fB/lib/modules/<kernel
version>/modules\fR exist.\& If this directory doesn't exist you probably 
have monolithic kernel which means you need to set \fBmonolith\fR to \fB1\fR.\&
.P
.RE
\fBhostonly\fR=0|1
.P
.RS 4
Hostonly mode enumerates \fBsysfs\fR(5) and copies only neccessary modules
instead of copying all modules.\& Which means that this mode can dramatically
reduce initramfs size.\& This option ignored if \fBmonolith\fR was set to \fB1\fR.\&
.P
.RE
\fBcompress\fR=command [args .\&.\&.\&]
.P
.RS 4
Specify which command will be used to compress initramfs image.\&
There is a lot of commands you can use, such as:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
xz
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
zst (if supported by kernel)
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
gzip
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
bzip2
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
and many more .\&.\&.\&

.RE
.P
You can set compression level by specifing -[0-9] in args.\&
For example - gzip -9.\&
.P
.RE
\fBroot\fR=UUID|LABEL|/dev/*|PARTUUID
.P
.RS 4
Specify which way tinyramfs will use to look up root filesystem.\&
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
UUID     - lookup device by uuid
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
LABEL    - lookup device by label
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
/dev/*   - lookup device by full path
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
PARTUUID - lookup device by partition uuid

.RE
.P
You must install \fBblkid\fR(8) (avalable in toybox, busybox, util-linux)
for ability to use UUID, LABEL, PARTUUID.\& Note that PARTUUID only
supported in util-linux \fBblkid\fR(8).\&
.P
.RE
\fBroot_type\fR=type
.P
.RS 4
Explicitly set root filesystem type instead of automatically discovering via
/proc/mounts.\& This option must be specified if you booted from Live CD.\&
.P
.RE
\fBroot_opts\fR=opts
.RS 4
.P
See \fBfstab\fR(5) fourth field.\&
.P
.RE
\fBhooks\fR=hook [hook .\&.\&.\&]
.P
.RS 4
Hooks provide a flexible way to extend tinyramfs with custom scripts.\&
You must know that \fBhooks are launched in the order in which they are
specified\fR.\& List of shipped by default hooks:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
lvm - LVM support
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
luks - LUKS support 
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
mdev - mdev support
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
proc - CONFIG_UEVENT_HELPER support
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
mdevd - mdevd support
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
eudev - eudev support
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
keymap - keymap support
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
systemd-udevd - systemd udevd support

.RE
.P
See below how to use them.\&
If hook doesn't have options, then it's not yet documented or can be used
"as is".\&
.P
.P
.RE
.SH HOOKS OPTIONS
.P
\fBlvm_opts\fR=[tag, name, group, config, discard]
.P
.RS 4
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
tag - trigger lvm by tag
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
name - trigger lvm by logical volume name.\& group must be specified
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
group - trigger lvm by volume group name
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
config - embed /etc/lvm.\&conf config
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
discard - enable issue_discards

.RE
.P
.RE
\fBluks_opts\fR=root=UUID|LABEL|/dev/*|PARTUUID, [key, name, header, discard]
.P
.RS 4
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
key - embed key
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
name - device mapper name
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
root - encrypted root
.RS 4
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
UUID     - lookup device by uuid
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
LABEL    - lookup device by label
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
/dev/*   - lookup device by full path
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
PARTUUID - lookup device by partition uuid
.RE
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
header - embed header
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
discard - enable allow-discards

.RE
.P
.RE
\fBkeymap_path\fR=/path/to/keymap
.P
.RS 4
Specify location to binary keymap.\&
Currently, this hook supports loading keymap only via busybox loadkmap.\&
kbd loadkeys not supported.\&
.P
.RE
.SH EXAMPLES
.P
Remember, it's just examples !\& Don't copy blindly !\& Your configuration may
(and should) differ.\&
.P
.SS ROOT
.P
.nf
.RS 4
hooks=eudev
root=/dev/sda1
.fi
.RE
.P
.SS ROOT + MONOLITH + PROC (CONFIG_UEVENT_HELPER)
.P
.nf
.RS 4
hooks=proc
monolith=1
root=/dev/nvme0n1p1
.fi
.RE
.P
.SS ROOT + COMPRESS
.P
.nf
.RS 4
hostonly=1
hooks=mdevd
compress="gzip -9"
root=PARTUUID=8e05009d-a1d5-4fdb-b407-b0e79360555c
.fi
.RE
.P
.SS ROOT + KEYMAP
.P
.nf
.RS 4
root_type=f2fs
hooks="eudev keymap"
root=UUID=13bcb7cc-8fe5-4f8e-a1fe-e4b5b336f3ef
keymap_path=/usr/share/bkeymaps/colemak/en-latin9\&.bmap
.fi
.RE
.P
.SS ROOT + LUKS
.P
.nf
.RS 4
hooks="mdev luks"
root=LABEL=my_root
luks_opts=root=PARTUUID=35f923c5-083a-4950-a4da-e611d0778121
luks_opts="${luks_opts},key=/root/key,header=/root/header,discard=1"
.fi
.RE
.P
.SS ROOT + LVM + LUKS
.P
.nf
.RS 4
compress="lz4 -9"
hooks="eudev lvm luks"
luks_opts=root=/dev/sdb2,discard=1
lvm_opts=name=lvm1,group=lvm_grp2,config=1,discard=1
root=/dev/disk/by-uuid/aa82d7bb-ab2b-4739-935f-fd8a5c9a6cb0
.fi
.RE
.P
.SH SEE ALSO
.P
\fBtinyramfs\fR(8) \fBtinyramfs.\&cmdline\fR(7)