1. init

Module providing functions to build an init script

The mkinit() function will generate a /init script.

do_foo() functions write a string performing the foo action into a stream. This stream should be the init script.

_fun_foo() functions write a string defining the foo function into a stream. This stream should be the init script.

Helper functions available in the init script that can be used by cmkinitramfs.data.Data classes:

  • _fun_die(): Fatal error handler (does not return).

  • _fun_log(): Logging functions (always successful).

Special helper function available in the init script: _fun_rescue_shell(), _fun_panic().

Init environment variables:

  • HOME

  • PATH

Init global variables:

  • PRINTK: Initial kernel log level.

  • INIT: Program to run as init process after the initramfs.

  • RD_XXX: If set, feature XXX is enabled.

  • RD_BREAK_XXX: If set, breakpoint XXX is enabled.

The init script should never rely on global variables being set or unset, it should always assign a default value if not set.

class cmkinitramfs.init.Breakpoint(value)[source]

Bases: Enum

Breakpoint in the boot process

Breakpoints can be enabled by adding rd.break to the kernel command-line (e.g. ./kernel.img foo rd.break=init). Setting rd.break=foo,bar will enable both foo and bar. Environment variables can also be set to enable them (e.g. ./kernel.img foo RD_BREAK_EARLY=true).

EARLY = 1

Early break: break before any action, including command-line parsing. Can be set with the RD_BREAK_EARLY environment variable.

INIT = 2

init: Break after initramfs initialization. Can also be set with the RD_BREAK_INIT environment variable.

MODULE = 3

module: Break after loading kernel modules. Can also be set with the RD_BREAK_MODULE environment variable. Alias: modules.

MOUNT = 5

mount: Break after mounting all filesystems. Can also be set with the RD_BREAK_MOUNT environment variable. Alias: mounts.

ROOTFS = 4

rootfs: Break after mounting the root filesystem. Can also be set with the RD_BREAK_ROOTFS environment variable.

cmkinitramfs.init._fun_rescue_shell(out)[source]

Define the rescue_shell function

rescue_shell drop the user to /bin/sh.

Arguments: none.

This function should not be called from a subshell.

This function does not return.

Parameters

out (IO[str]) – Stream to write into

Return type

None

cmkinitramfs.init._fun_panic(out)[source]

Define the panic function

panic causes a kernel panic by exiting /init.

Arguments: none.

This function should not be called from a subshell.

This function does not return.

Parameters

out (IO[str]) – Stream to write into

Return type

None

cmkinitramfs.init._fun_die(out)[source]

Define the die function

die will either start a rescue shell or cause a kernel panic, wether RD_PANIC is set or not.

Arguments: error message.

This function should not be called from a subshell.

This function does not return.

Parameters

out (IO[str]) – Stream to write into

Return type

None

cmkinitramfs.init._fun_log(out)[source]

Define the logging functions

log: log a message.

  • Argument 1: syslog level number, from 0 to 7.

  • Additionnal arguments: message to log.

Logs printed to stderr:

  • Level ≤ 4: always

  • 5 ≤ level ≤ 6: if debug enabled or quiet disabled

  • Level = 7: if debug enabled

Helper functions:

  • emerg: log a message for a panic condition. The message is prepended by ‘FATAL:’.

  • alert: log a critical error message requiring immediate action. The message is prepended by ‘ERROR:’.

  • crit: log a critical error message. The message is prepended by ‘ERROR:’.

  • err: log an error message. The message is prepended by ‘ERROR:’.

  • warn: log a warning message. The message is prepended by ‘WARNING:’.

  • notice: log a significant/unusual informational message.

  • info: log an informational message.

  • debug: log a debug-level message.

Helper functions will call log with the coresponding syslog level.

Logging functions always return successfully.

Parameters

out (IO[str]) – Stream to write into

Return type

None

cmkinitramfs.init.do_header(out, home='/root', path='/bin:/sbin')[source]

Create the /init header

  • Create the shebang /bin/sh

  • Configure environment variables

  • Define global functions (panic, logging, …)

Parameters

  • out (IO[str]) – Stream to write into

  • home (str) – HOME environment variable

  • path (str) – PATH environment variable

Return type

None

cmkinitramfs.init.do_init(out)[source]

Initialize the init environment

  • Check the current PID is 1

  • Mount /proc, /sys, /dev

  • Set the kernel log level to 4 (KERN_ERR and higher priority)

Parameters

out (IO[str]) – Stream to write into

Return type

None

cmkinitramfs.init.do_cmdline(out)[source]

Parse the kernel command line for known parameters

Note: the command line is parsed up to “–”, arguments after this are passed through to the final init process.

Parsed parameters:

  • init=<path to init>: Set the program to run as init process after the initramfs.

  • debug: Enable debugging, see rd.debug.

  • quiet: Enable quiet mode, see rd.quiet.

  • rd.break={init|rootfs|mount}: Stops the boot process, defaults to rootfs. See Breakpoint.

  • rd.debug: Enable debugging mode: output verbose informations. If quiet mode is disabled, enable shell trace (with set -x).

  • rd.panic: On fatal error: cause a kernel panic rather than dropping into a shell.

  • rd.quiet: Enable quiet mode: reduce verbosity.

Parameters

out (IO[str]) – Stream to write into

Return type

None

cmkinitramfs.init.do_keymap(out, keymap_file, unicode=True)[source]

Load a keymap

Parameters

  • out (IO[str]) – Stream to write into

  • keymap_file (str) – Absolute path of the file to load

  • unicode (bool) – Set the keyboard in unicode mode (rather than ASCII)

Return type

None

cmkinitramfs.init.do_module(out, module, *args)[source]

Load a kernel module

Parameters

  • out (IO[str]) – Stream to write into

  • module (str) – Name of the module to load

  • args (str) – Arguments for the module (passed to modprobe)

Return type

None

cmkinitramfs.init.do_break(out, breakpoint_, scripts=())[source]

Drop into a shell if rd.break is set

Parameters

  • out (IO[str]) – Stream to write into

  • breakpoint – Which breakpoint to check

  • scripts (Iterable[str]) – User commands to run before the breakpoint

  • breakpoint_ (Breakpoint) –

Return type

None

cmkinitramfs.init.do_switch_root(out, newroot, init='/sbin/init')[source]

Cleanup and switch root

  • Print debugging information

  • Restore kernel log level (set to boot-time default if not possible)

  • Kill all processes

  • Unmount /dev, /sys, /proc

  • Switch root

Parameters

  • out (IO[str]) – Stream to write into

  • newroot (Data) – Data to use as new root

  • init (str) – Init process to execute from the new root

Return type

None

cmkinitramfs.init.mkinit(out, root, mounts=(), keymap=None, modules=None, scripts=None)[source]

Create the init script

Parameters

  • out (IO[str]) – Stream to write into

  • root (Data) – Data to use as rootfs

  • mounts (Iterable[Data]) – Data needed in addition of rootfs

  • keymap (Optional[str]) – Path of the keymap to load, None means no keymap

  • modules (Optional[Mapping[str, Iterable[str]]]) – Kernel modules to be loaded in the initramfs: {module: (arg, ...)}. module is the module name string, and (arg, ...)` is the iterable with the module parameters.

  • scripts (Optional[Mapping[Breakpoint, Iterable[str]]]) – User commands to run. {breakpoint: commands}: breakpoint is the Breakpoint where the commands will be run. commands is the iterable with the commands.

Return type

None