195 lines
6.9 KiB
Markdown
195 lines
6.9 KiB
Markdown
mkinitfs(1) "mkinitfs"
|
|
|
|
# NAME
|
|
|
|
mkinitfs
|
|
|
|
# DESCRIPTION
|
|
|
|
mkinitfs is a simple, generic tool for generating an initramfs, primarily
|
|
developed for use in postmarketOS
|
|
|
|
# CONCEPTS
|
|
|
|
mkinitfs is designed to generate two archives, "initramfs" and
|
|
"initramfs-extra", however it's possible to configure mkinitfs to run without
|
|
generating an initramfs-extra archive. mkinitfs is primarily configured through
|
|
the placement of files in specific directories detailed below in the
|
|
*DIRECTORIES* section. *deviceinfo* files are also used to provide other
|
|
configuration options to mkinitfs, these are covered under the *DEVICEINFO*
|
|
section below.
|
|
|
|
mkinitfs does not provide an init script, or any boot-time logic, it's purpose
|
|
is purely to generate the archive(s). mkinitfs does call *boot-deploy* after
|
|
creating the archive(s), in order to install/deploy them and any other relevant
|
|
boot-related items onto the system.
|
|
|
|
Design goals of this project are:
|
|
|
|
- Support as many distros as possible
|
|
- Simplify configuration, while still giving multiple opportunities to set or override defaults
|
|
- Execute an external app to do any boot install/setup finalization
|
|
- One such app is here: https://gitlab.com/postmarketOS/boot-deploy
|
|
- But implementation can be anything, see the section on *BOOT-DEPLOY*
|
|
for more info
|
|
|
|
# DEVICEINFO
|
|
|
|
The canonical deviceinfo "specification" is at
|
|
https://wiki.postmarketos.org/wiki/Deviceinfo_reference
|
|
|
|
mkinitfs reads deviceinfo values from */usr/share/deviceinfo/deviceinfo* and
|
|
*/etc/deviceinfo*, in that order. The following variables
|
|
are *required* by mkinitfs:
|
|
|
|
- deviceinfo_generate_systemd_boot
|
|
- deviceinfo_initfs_compression
|
|
- deviceinfo_initfs_extra_compression
|
|
- deviceinfo_uboot_boardname
|
|
|
|
It is a design goal to keep the number of required variables from deviceinfo to
|
|
a bare minimum, and to require only variables that don't hold lists of things.
|
|
|
|
*NOTE*: When deviceinfo_initfs_extra_compression is set, make sure that the
|
|
necessary tools to extract the configured archive format are in the initramfs
|
|
archive.
|
|
|
|
# ARCHIVE COMPRESSION
|
|
|
|
Archive compression parameters are specified in the
|
|
*deviceinfo_initfs_compression* and *deviceinfo_initfs_extra_compression*
|
|
deviceinfo variables. Their values do not have to match, but special
|
|
consideration should be taken since some formats may require additional kernel
|
|
options or tools in the initramfs to support it.
|
|
|
|
Supported compression *formats* for mkinitfs are:
|
|
|
|
- gzip
|
|
- lz4
|
|
- lzma
|
|
- none
|
|
- zstd
|
|
|
|
Supported compression *levels* for mkinitfs:
|
|
|
|
- best
|
|
- default
|
|
- fast
|
|
|
|
The value of these variables follows this syntax: *<format>:<level>*. For
|
|
example, *zstd* with the *fast* compression level would be:
|
|
*deviceinfo_initfs_compression="zstd:fast"*
|
|
|
|
Defaults to *gzip* and *default* for both archives if format and/or level is
|
|
unsupported or omitted.
|
|
|
|
|
|
# DIRECTORIES
|
|
|
|
The following directories are used by mkinitfs to generate the initramfs and
|
|
initramfs-extra archives. Directories that end in *-extra* indicate directories
|
|
that are used for constructing the initramfs-extra archive, while those without
|
|
it are for constructing the initramfs archive.
|
|
|
|
Configuration under */usr/share/mkinitfs* is intended to be managed by
|
|
distributions, while configuration under */etc/mkinitfs* is for users to
|
|
create/manage. mkinitfs reads configuration from */usr/share/mkinitfs* first, and then from */etc/mkinitfs*.
|
|
|
|
## /usr/share/mkinitfs/files, /etc/mkinitfs/files
|
|
## /usr/share/mkinitfs/files-extra, /etc/mkinitfs/files-extra
|
|
|
|
Files with the *.files* extension are read as a list of
|
|
files/directories. Each line is in the format:
|
|
|
|
```
|
|
<source path>:<destination path>
|
|
```
|
|
|
|
The source path is the location, at runtime, of the file or directory
|
|
which will be copied to the destination path within the initramfs
|
|
archive. Specifying a destination path, with *:<destination path>* is
|
|
optional. If it is omitted, then the source path will be used as the
|
|
destination path within the archive. The source and destination paths
|
|
are delimited by a *:* (colon.) Destination path is ignored if the source
|
|
path is a glob that returns more than 1 file. This may change in the future.
|
|
|
|
[[ *Line in .files*
|
|
:< Comment
|
|
| */usr/share/bazz*
|
|
: File or directory */usr/share/bazz* would be added to the archive under */usr/share/bazz*
|
|
| */usr/share/bazz:/bazz*
|
|
: File or directory */usr/share/bazz* would be added to the archive under */bazz*
|
|
| */root/something/\**
|
|
: Everything under */root/something* would be added to the archive under */root/something*
|
|
| */etc/foo/\*/bazz:/foo*
|
|
: Anything that matches the glob will be installed under the source path in the archive. For example, */etc/foo/bar/bazz* would be installed at */etc/foo/bar/bazz* in the archive. The destination path is ignored.
|
|
|
|
It's possible to overwrite file/directory destinations from
|
|
configuration in */usr/share/mkinitfs* by specifying the same source
|
|
path(s) under the relevant directory in */etc/mkinitfs*, and changing
|
|
the destination path.
|
|
|
|
Any lines in these files that start with *#* are considered comments, and
|
|
skipped.
|
|
|
|
## /usr/share/mkinitfs/hooks, /etc/mkinitfs/hooks
|
|
## /usr/share/mkinitfs/hooks-extra*, /etc/mkinitfs/hooks-extra
|
|
|
|
Any files listed under these directories are copied as-is into the
|
|
relevant archives. Hooks are generally script files, but how they are
|
|
treated in the initramfs is entirely up to whatever init script is run
|
|
there on boot.
|
|
|
|
Hooks are installed in the initramfs under the */hooks* directory, and
|
|
under */hooks-extra* for the initramfs-extra.
|
|
|
|
## /usr/share/mkinitfs/modules, /etc/mkinitfs/modules
|
|
## /usr/share/mkinitfs/modules-extra, /etc/mkinitfs/modules-extra
|
|
|
|
Files with the *.modules* extention in these directories are lists of
|
|
kernel modules to include in the initramfs. Individual modules and
|
|
directories can be listed in the files here. Globbing is also supported.
|
|
|
|
Modules are installed in the initramfs archive under the same path they
|
|
exist on the system where mkinitfs is executed.
|
|
|
|
Any lines in these files that start with *#* are considered comments, and
|
|
skipped.
|
|
|
|
## /usr/share/mkinitfs/dirs, /etc/mkinitfs/dirs
|
|
|
|
Files with the *.dirs* extension in these directories are lists of
|
|
directories to create within the initramfs. There is no *-extra* variant,
|
|
since directories are of negligible size.
|
|
|
|
Any lines in these files that start with *#* are considered comments, and
|
|
skipped.
|
|
|
|
# BOOT-DEPLOY
|
|
|
|
After generating archives, mkinitfs will execute *boot-deploy*, using *$PATH* to
|
|
search for the app. The following commandline options are passed to it:
|
|
|
|
*-i* <initramfs filename>
|
|
|
|
Currently this is hardcoded to be "initramfs"
|
|
|
|
*-k* <kernel filename>
|
|
|
|
*-d* <work directory>
|
|
|
|
Path to the directory containing the build artifacts from mkinitfs.
|
|
|
|
*-o* <destination directory>
|
|
|
|
Path to the directory that boot-deploy should use as its root when
|
|
installing files.
|
|
|
|
*initramfs-extra*
|
|
|
|
This string is the filename of the initramfs-extra archive.
|
|
|
|
# AUTHORS
|
|
|
|
*Clayton Craft* <clayton@craftyguy.net>
|