From 5c46534e22a0e5d70f650ae100c4b6c52dbbce74 Mon Sep 17 00:00:00 2001 From: illiliti Date: Fri, 4 Sep 2020 08:49:45 +0300 Subject: [PATCH] introduce man pages --- Makefile | 3 + README.md | 29 +-- docs/tinyramfs.5 | 529 +++++++++++++++++++++++++++++++++++++++++++ docs/tinyramfs.5.scd | 226 ++++++++++++++++++ 4 files changed, 767 insertions(+), 20 deletions(-) create mode 100644 docs/tinyramfs.5 create mode 100644 docs/tinyramfs.5.scd diff --git a/Makefile b/Makefile index 5d8a248..7706020 100644 --- a/Makefile +++ b/Makefile @@ -4,16 +4,19 @@ PREFIX = /usr SYSCONFDIR = /etc BINDIR = ${PREFIX}/bin DATADIR = ${PREFIX}/share +MANDIR = ${PREFIX}/share/man install: mkdir -p ${DESTDIR}${SYSCONFDIR}/tinyramfs \ ${DESTDIR}${DATADIR}/tinyramfs \ + ${DESTDIR}${MANDIR}/man5 \ ${DESTDIR}${BINDIR} cp config ${DESTDIR}${SYSCONFDIR}/tinyramfs cp -R hooks ${DESTDIR}${DATADIR}/tinyramfs cp device-helper ${DESTDIR}${DATADIR}/tinyramfs cp init ${DESTDIR}${DATADIR}/tinyramfs cp tinyramfs ${DESTDIR}${BINDIR}/tinyramfs + cp docs/tinyramfs.5 ${DESTDIR}${MANDIR}/man5 uninstall: rm -f ${DESTDIR}${BINDIR}/tinyramfs diff --git a/README.md b/README.md index a3dbf47..2996937 100644 --- a/README.md +++ b/README.md @@ -31,15 +31,11 @@ Dependencies - Required for LVM support * `cryptsetup` - Required for LUKS support +* `busybox loadkmap` + - Required for loading keymap * `kmod` OR `busybox modutils` with [this patch](https://gist.github.com/illiliti/ef9ee781b5c6bf36d9493d99b4a1ffb6) (already included in KISS Linux) - Not required for monolithic kernel -Notes ------ - -* busybox modutils doesn't handle soft dependencies (modules.softdep). You must manually copy them using hooks -* busybox and toybox blkid doesn't support PARTUUID. You must use util-linux blkid for PARTUUID support - Installation ------------ @@ -47,25 +43,18 @@ Installation git clone https://github.com/illiliti/tinyramfs cd tinyramfs make install -vi /etc/tinyramfs/config # edit config for your needs +``` + +Usage +----- + +```sh +# read man pages and setup /etc/tinyramfs/config tinyramfs -o /boot/initramfs- # replace with current kernel version # update your bootloader # reboot... ``` -Configuration -------------- - -Statically via config ------------------ - -See [config](config) - -Dynamically via kernel parameters ------------------------------ - -TODO finalize and document kernel command-line parameters - Thanks ------ diff --git a/docs/tinyramfs.5 b/docs/tinyramfs.5 new file mode 100644 index 0000000..9106b61 --- /dev/null +++ b/docs/tinyramfs.5 @@ -0,0 +1,529 @@ +.\" 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//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) diff --git a/docs/tinyramfs.5.scd b/docs/tinyramfs.5.scd new file mode 100644 index 0000000..c917ee9 --- /dev/null +++ b/docs/tinyramfs.5.scd @@ -0,0 +1,226 @@ +tinyramfs(5) + +# NAME + +Tinyramfs - configuration file + +# SYNOPSIS +*/etc/tinyramfs/config* + +# DESCRIPTION + +Let's reduce confusing situations and document everything ! + +## MAN PAGE SYNTAX + +``` +* - any value +[a] - optional value +... - can be repeated +0|1 - choice between no and yes +``` + +## CONFIG SYNTAX + +Tinyramfs configuration file is a list of environment variables. +Each variable must be written in POSIX way, bashism not allowed. + +Example: + +``` +key=value +``` + +If value contains spaces it must must be quoted. + +``` +key="value value2" +``` + +If value contains special symbols like $, it must be escaped +or quoted using single quotes. + +``` +key=\\$value +key='$value' +``` + +If line exceeded maximum space on your display and you want to make it +more readable, you can concatenate them. + +``` +key=value +key="${key}value" +``` + +If you want to temporary undefine variable without actually deleting it, +you can simply prepend \#. + +``` +#key=value +``` + +# GENERAL OPTIONS + +*monolith*=0|1 + + 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 */lib/modules//modules* exist. If this directory doesn't exist you probably + have monolithic kernel which means you need to set *monolith* to *1*. + +*hostonly*=0|1 + + Hostonly mode enumerates *sysfs*(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 *monolith* was set to *1*. + +*compress*=command [args ...] + + Specify which command will be used to compress initramfs image. + There is a lot of commands you can use, such as: + + - xz + - zst (if supported by kernel) + - gzip + - bzip2 + - and many more ... + + You can set compression level by specifing -[0-9] in args. + For example - gzip -9. + +*root*=UUID|LABEL|/dev/\*|PARTUUID + + Specify which way tinyramfs will use to look up root filesystem. + + - UUID - lookup device by uuid + - LABEL - lookup device by label + - /dev/\* - lookup device by full path + - PARTUUID - lookup device by partition uuid + + You must install *blkid*(8) (avalable in toybox, busybox, util-linux) + for ability to use UUID, LABEL, PARTUUID. Note that PARTUUID only + supported in util-linux *blkid*(8). + +*root_type*=type + + Explicitly set root filesystem type instead of automatically discovering via + /proc/mounts. This option must be specified if you booted from Live CD. + +*root_opts*=opts + + See *fstab*(5) fourth field. + +*hooks*=hook [hook ...] + + Hooks provide a flexible way to extend tinyramfs with custom scripts. + You must know that *hooks are launched in the order in which they are + specified*. List of shipped by default hooks: + + - lvm - LVM support + - luks - LUKS support + - mdev - mdev support + - proc - CONFIG_UEVENT_HELPER support + - mdevd - mdevd support + - eudev - eudev support + - keymap - keymap support + - systemd-udevd - systemd udevd support + + See below how to use them. + If hook doesn't have options, then it's not yet documented or can be used + "as is". + + ; TODO tinyramfs.hooks(7) + ; More detailed information and how to write your own hooks described in + ; *tinyramfs.hooks*(7). + +# HOOKS OPTIONS + +*lvm_opts*=[tag, name, group, config, discard] + + - tag - trigger lvm by tag + - name - trigger lvm by logical volume name. group must be specified + - group - trigger lvm by volume group name + - config - embed /etc/lvm.conf config + - discard - enable issue_discards + +*luks_opts*=root=UUID|LABEL|/dev/\*|PARTUUID, [key, name, header, discard] + + - key - embed key + - name - device mapper name + - root - encrypted root + - UUID - lookup device by uuid + - LABEL - lookup device by label + - /dev/\* - lookup device by full path + - PARTUUID - lookup device by partition uuid + - header - embed header + - discard - enable allow-discards + +*keymap_path*=/path/to/keymap + + Specify location to binary keymap. + Currently, this hook supports loading keymap only via busybox loadkmap. + kbd loadkeys not supported. + +# EXAMPLES + +Remember, it's just examples ! Don't copy blindly ! Your configuration may +(and should) differ. + +## ROOT + +``` +hooks=eudev +root=/dev/sda1 +``` + +## ROOT + MONOLITH + PROC (CONFIG_UEVENT_HELPER) + +``` +hooks=proc +monolith=1 +root=/dev/nvme0n1p1 +``` + +## ROOT + COMPRESS + +``` +hostonly=1 +hooks=mdevd +compress="gzip -9" +root=PARTUUID=8e05009d-a1d5-4fdb-b407-b0e79360555c +``` + +## ROOT + KEYMAP + +``` +root_type=f2fs +hooks="eudev keymap" +root=UUID=13bcb7cc-8fe5-4f8e-a1fe-e4b5b336f3ef +keymap_path=/usr/share/bkeymaps/colemak/en-latin9.bmap +``` + +## ROOT + LUKS + +``` +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" +``` + +## ROOT + LVM + LUKS + +``` +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 +``` + +# SEE ALSO + +*tinyramfs*(8) *tinyramfs.cmdline*(7)