3. initramfs

Module providing functions and classes to build an initramfs

This library provides a class Initramfs which handles the content of an initramfs. This class supports creating an initramfs tree inside a directlry. It also can generate a CPIO file list compatible with the Linux kernel’s gen_init_cpio utility. (See https://www.kernel.org/doc/html/latest/filesystems/ramfs-rootfs-initramfs.html for mor details.)

The main function is mkinitramfs() to build the complete initramfs.

cmkinitramfs.initramfs.busybox_get_applets(busybox_exec)[source]

Get BusyBox applets

Parameters: busybox_exec (str) – BusyBox executable (e.g. busybox)
Returns: Iterator of absolute paths of BusyBox applets
Raises: subprocess.CalledProcessError – Error during busybox_exec
Return type: Iterator[str]

cmkinitramfs.initramfs.mkcpio_from_dir(src, dest)[source]

Create CPIO archive from a given directory

Parameters

src (str) – Directory from which the archive is created
dest (IO[bytes]) – Destination stream of the CPIO data

Raises

subprocess.CalledProcessError – Error during find or cpio

Return type

None

cmkinitramfs.initramfs.mkcpio_from_list(src, dest)[source]

Create CPIO archive from a given CPIO list

Parameters

src (str) – Path of the CPIO list
dest (IO[bytes]) – Destination stream of the CPIO data

Raises

subprocess.CalledProcessError – Error during gen_init_cpio

Return type

None

cmkinitramfs.initramfs.keymap_build(src, dest, unicode=True)[source]

Generate a binary keymap from a keymap name

This keymap can then be loaded with loadkmap from the initramfs environment.

Parameters

src (str) – Name of the keymap to convert, can be a keyboard layout name or a file path
dest (IO[bytes]) – Destination stream to write into
unicode (bool) – Generate a unicode keymap (rather than ASCII)

Raises

subprocess.CalledProcessError – Error during loadkeys

Return type

None

cmkinitramfs.initramfs.SHELL_SPECIAL_BUILTIN = frozenset({'.', ':', 'break', 'continue', 'eval', 'exec', 'exit', 'export', 'readonly', 'return', 'set', 'shift', 'times', 'trap', 'unset'}): Set of shell special built-in commands. They are guaranteed to be available in the initramfs’ /bin/sh.

cmkinitramfs.initramfs.SHELL_RESERVED_WORDS = frozenset({'!', 'case', 'do', 'done', 'elif', 'else', 'esac', 'fi', 'for', 'if', 'in', 'then', 'until', 'while', '{', '}'}): Set of shell reserved words. They are guaranteed to be available in the initramfs’ /bin/sh.

class cmkinitramfs.initramfs.Initramfs(user=0, group=0, binroot='/', kernels=None)[source]

Bases: object

An initramfs archive

Parameters

user (int) – Default user to use when creating items
group (int) – Default group to use when creating items
binroot (str) – Root directory where binary files are found (executables and libraries)
kernels (Set[str]) – Kernel versions of the initramfs, defaults to the running kernel version
items – Items in the initramfs

__contains__(path)[source]

Check if a path exists on the initramfs

Parameters: path (str) – Path to check
Returns: True if path exists on the initramfs, False otherwise
Return type: bool

__iter__()[source]

Iterate over the Item instances in the initramfs

Return type: Iterator[Item]

__normalize()

Normalize a path for the initramfs filesystem

Strip /usr[/local] directory, warns if spaces are present in the path.

Parameters: path (str) – Destination path to normalize
Returns: Normalized path
Raises: ValueError – Invalid path
Return type: str

add_busybox(needed=(), sys_busybox=None)[source]

Add busybox and its applets to the initramfs

Applets will be ignored if a file with the same path already exists. To avoid collision, this method should be called after all needed files have been added.

If any command listed in needed is not available in busybox (either as an applet, a shell special built-in, or a reserved word), the default system one will be included (from PATH).

Parameters

needed (Iterable[str]) – Needed Busybox compatible shell commands
sys_busybox (Optional[str]) – Busybox executable to use to get the list of applets, defaults to the one in PATH

Raises

FileNotFoundError – Busybox executable or ELF dependency not found
MergeError – Destination file exists and is different, or missing parent directory (raised from add_item(), not raised for applets)

Return type

None

add_executable(src, dest=None, mode=None)[source]

Add an executable to the initramfs

Parameters

src (str) – Path or base name of the executable to add, if it is not a path, it is searched on the system with find_exec()
dest (Optional[str]) – Absolute path of the destination, relative to the initramfs root, defaults to the path of the source executable
mode (Optional[int]) – File permissions to use, defaults to same as src

Raises

FileNotFoundError – Executable or ELF dependency not found
MergeError – Destination file exists and is different, or missing parent directory (raised from add_item())

Return type

None

add_file(src, dest=None, mode=None)[source]

Add a file to the initramfs

If the file is a symlink, it is dereferenced. If it is a dynamically linked ELF file, its dependencies are also added.

Parameters

src (str) – Absolute or relative path of the source file
dest (Optional[str]) – Absolute path of the destination, relative to the initramfs root, defaults to src
mode (Optional[int]) – File permissions to use, defaults to same as src

Raises

FileNotFoundError – Source file or ELF dependency not found
MergeError – Destination file exists and is different, or missing parent directory (raised from add_item())

Return type

None

add_item(new_item)[source]

Add an item to the initramfs

If an identical item is already present, merges them together.

Parameters: new_item (Item) – Item instance to add
Raises: MergeError – Item cannot be merged into the initramfs (missing parent directory or file conflict)
Return type: None

add_kmod(module, mode=None)[source]

Add a kernel module to the initramfs

Parameters

module (str) – Path or name of the kernel module to add
mode (Optional[int]) – File permissions to use, defaults to same as module

Return type

None

add_library(src, dest=None, mode=None)[source]

Add a library to the initramfs

Parameters

src (str) – Path or base name of the library to add, if it is not a path, it is searched on the system with find_lib()
dest (Optional[str]) – Absolute path of the destination, relative to the initramfs root, defaults to the path of the source library
mode (Optional[int]) – File permissions to use, defaults to same as src

Raises

FileNotFoundError – Library or ELF dependency not found
MergeError – Destination file exists and is different, or missing parent directory (raised from add_item())

Return type

None

build_to_cpio_list(dest)[source]

Write a CPIO list into a file

This list is compatible with Linux’s gen_init_cpio. See Item.build_to_cpio_list().

Parameters: dest (IO[str]) – Stream in which the list is written
Return type: None

build_to_directory(dest, do_nodes=True)[source]

Copy or create all items to a real filesystem

See Item.build_to_directory().

Parameters

dest (str) – Path to use as root directory of the initramfs
do_nodes (bool) – Also creates Node items, (used for debugging: CAP_MKNOD is needed to create some special devices)

Return type

None

mkdir(path, mode=493, parents=False)[source]

Create a directory on the initramfs

Parameters

path (str) – Absolute path of the directory, relative to the initramfs root
mode (int) – File permissions to use
parents (bool) – If True, missing parent directories will also be created

Raises

MergeError – Destination file exists and is different, or missing parent directory (raised from add_item())

Return type

None