tinyramfs/docs/tinyramfs.config.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.config" "5" "2020-09-07"
.P
.SH NAME
.P
Tinyramfs - configuration file
.P
.SH SYNOPSIS
.P
\fB/etc/tinyramfs/config\fR
.P
.SH DESCRIPTION
.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
.SS MAN PAGE SYNTAX
.P
.nf
.RS 4
|   - OR
*   - any value
[a] - optional value
\&.\&.\&. - can be repeated
.fi
.RE
.P
.SH GENERAL OPTIONS
.P
\fBmonolith\fR=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=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 will be 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
More detailed information and how to write your own hooks described in
\fBtinyramfs.\&hooks\fR(7).\&
.P
.RE
.SH HOOKS OPTIONS
.P
.SS LVM
.P
\fBlvm_tag\fR=tag
.P
.RS 4
Specify LVM tag which will be used to trigger LVM.\& This option will be
ignored if \fBlvm_name\fR/\fBlvm_group\fR was specified.\&
.P
.RE
\fBlvm_name\fR=name
.P
.RS 4
Specify LVM name which will be used to trigger LVM.\& \fBlvm_group\fR must be
specified.\&
.P
.RE
\fBlvm_group\fR=group
.P
.RS 4
Specify LVM group which will be used to trigger LVM.\&
.P
.RE
\fBlvm_config\fR=1
.P
.RS 4
Include \fB/etc/lvm/lvm.\&conf\fR in initramfs.\&
.P
.RE
\fBlvm_discard\fR=1
.P
.RS 4
Pass issue_discards to lvm.\& Useful for SSD's.\&
.P
.RE
.SS LUKS
.P
\fBluks_key\fR=/path/to/key
.RS 4
.P
Specify location to key.\&
GPG-encrypted key currently not supported.\&
.P
.RE
\fBluks_name\fR=name
.P
.RS 4
Specify which name will be registered to mapping table after cryptsetup
unlocks LUKS root.\&
.P
.RE
\fBluks_root\fR=UUID|LABEL|/dev/*|PARTUUID
.P
.RS 4
See \fBroot\fR for details.\&
.P
.RE
\fBluks_header\fR=/path/to/header
.P
.RS 4
Specify location to detached header.\&
.P
.RE
\fBluks_discard\fR=1
.P
.RS 4
Pass --allow-discards to \fBcryptsetup\fR.\& Useful for SSD's, but you must know
that security will be decreased.\&
.P
.RE
.SS KEYMAP
.P
\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, these just examples !\& \fIDon't copy blindly\fR !\& 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_discard=1
luks_key=/root/key
luks_header=/root/header
luks_root=PARTUUID=35f923c5-083a-4950-a4da-e611d0778121
.fi
.RE
.P
.SS ROOT + LVM + LUKS
.P
.nf
.RS 4
compress="lz4 -9"
hooks="eudev lvm luks"
root=/dev/disk/by-uuid/aa82d7bb-ab2b-4739-935f-fd8a5c9a6cb0

luks_discard=1
luks_root=/dev/sdb2

lvm_config=1
lvm_discard=1
lvm_name=lvm1
lvm_group=lvm_grp2
.fi
.RE
.P
.SH SEE ALSO
.P
\fBtinyramfs\fR(8) \fBtinyramfs.\&cmdline\fR(7) \fBtinyramfs.\&hooks\fR(7)