2. data

Module providing the Data class for init script data sources management

The Data class defines an abstract object containing data, it has multiple subclasses for multiple types of data. The main methods of those classes are Data.load(), Data.unload(), and Data.set_final().

Most functions will write into a stream (text file) the content of the init script. Use a io.StringIO if you need to use strings rather than a stream.

class cmkinitramfs.data.Data[source]

Bases: object

Base class representing any data on the system

This is an abstract class representing data on the system. Its main methods are load() and unload(). set_final() declare the object as required for the final boot environment (e.g. root fs, usr fs), this will prevent the data from being unloaded.

Parameters

files – Files directly needed in the initramfs. Each file is a tuple in the format (src, dest), where src is the source file on the current system, and dest is the destination in the initramfs (relative to its root directory). If dest is None, then src is used.
execs – Executables directly needed in the initramfs. Same format as files.
libs – Libraries directly needed in the initramfs. Same format as files.
busybox – Busybox compatible commands needed in the initramfs. Any commands that are compatible with Busybox’s implementation should be added. Exception: special shell built-in commands and reserved words are guaranteed to be available and can be ommitted (a list is defined in cmkinitramfs.initramfs.SHELL_SPECIAL_BUILTIN and cmkinitramfs.initramfs.SHELL_RESERVED_WORDS).
kmods – Kernel modules directly needed in the initramfs. Each module is a tuple in the format (module, params), where params is a tuple of module parameters (may be empty).
_need – Loading and runtime dependencies
_lneed – Loading only dependencies
_needed_by – Reverse dependencies
_is_final – The Data should not be unloaded
_is_loaded – The Data is currently loaded

__str__()[source]

Get the name of the data

This string may be quoted with simple quotes in the script. This has to be implemented by subclasses.

Return type: str

_post_load(out)[source]

This function does post loading cleanup

If the object is a loading dependency only, it will load all its reverse dependencies in order to be unloaded as soon as possible. Unloading quickly can be useful when dealing with sensitive data (e.g. a LUKS key). It should be called from load() after the actual loading of the data.

Parameters: out (IO[str]) – Stream to write into
Return type: None

_post_unload(out)[source]

This function does post unloading cleanup

It removes itself from the _needed_by reverse dependencies of all its dependencies, and check if the dependency can be unloaded. This method should be called from unload() after the actual unloading of the data. This should not be called if the data is not loaded.

Parameters: out (IO[str]) – Stream to write into
Return type: None

_pre_load(out)[source]

This function does preparation for loading the Data

Loads all the needed dependencies. It should be called from load() before the actual loading of the data. This method should not be called if the Data is already loaded.

Parameters: out (IO[str]) – Stream to write into
Raises: DataError – Already loaded
Return type: None

_pre_unload(out)[source]

This function does pre unloading sanity checks

It should be called from unload() before the actual unloading of the data.

Parameters: out (IO[str]) – Stream to write into
Raises: DataError – Not loaded or dependency issue
Return type: None

add_dep(dep)[source]

Add a Data object to the hard dependencies

Parameters: dep (Data) –
Return type: None

add_load_dep(dep)[source]

Add a Data object to the loading dependencies

Parameters: dep (Data) –
Return type: None

classmethod initialize(out)[source]

Initialize the data class

Initialize the environment for the use of this data class: define needed functions and variables. A Data class should be initialized only once in the init script, before the first Data.load() call of the class.

Default initialization is a no-op and should be redefined by subclasses. Subclasses should call their parent Data class’ Data.initialize() method.

Parameters: out (IO[str]) – Stream to write into
Return type: None

is_final()[source]

Returns a bool indicating if the Data is final

Return type: bool

iter_all_deps()[source]

Recursivelly get dependencies

Returns: Iterator over all the dependencies
Return type: Iterator[Data]

load(out)[source]

This function loads the data

It should be redefined by subclasses, this definition is a no-op only dealing with dependencies.

Before loading, this function should load the dependencies with _pre_load(). After loading, this function should unload unnecessary dependencies with _post_load(). This method should not be called if the data is already loaded.

Parameters: out (IO[str]) – Stream to write into
Return type: None

path()[source]

Get the path of this data

This function provides a string allowing access to data from within the init environment, this string can be a path or a command in a subshell (e.g. "$(findfs UUID=foobar)"). This string should be ready to be used in the script without being quoted nor escaped. This has to be implemented by subclasses.

Return type: str

set_final()[source]

This function set the data object as final

This means the data is required by the final boot environment and should never be unloaded (it would be pointless). This will also mark its hard dependencies as final.

Return type: None

unload(out)[source]

This function unloads data

It should be redefined by subclasses, this definition is a no-op only dealing with dependencies.

Before unloading, this function should check for any dependency error, with _pre_unload(). After unloading, this function should unload all unneeded dependencies, with _post_unload().

Parameters: out (IO[str]) – Stream to write into
Return type: None

class cmkinitramfs.data.PathData(datapath)[source]

Bases: Data

Absolute path

Parameters: datapath (str) – Path of the data

class cmkinitramfs.data.UuidData(uuid, partition=False)[source]

Bases: Data

UUID of a data

The UUID can be a filesystem UUID, or other UUID known by other Data classes (e.g. a MD UUID).

Parameters

uuid (str) – UUID of the data
partition (bool) – If True, the UUID is treated as a partition UUID

class cmkinitramfs.data.LabelData(label, partition=False)[source]

Bases: Data

Label of a data

The label can be a filesystem or partition label, or a label known by other Data classes.

Parameters

label (str) – Label of the data
partition (bool) – If True, the label is treated as a partition label

class cmkinitramfs.data.LuksData(source, name, key=None, header=None, discard=False)[source]

Bases: Data

LUKS encrypted block device

Parameters

source (Data) – Data to unlock (crypto_LUKS volume), it will be set as a hard dependency
name (str) – Name for the LUKS volume
key (Optional[Data]) – Data to use as key file, it will be set as a load dependency
header (Optional[Data]) – Data containing the LUKS header, it will be set as a load dependency
discard (bool) – Enable discards

class cmkinitramfs.data.LvmData(vg_name, lv_name)[source]

Bases: Data

LVM logical volume

Parameters

vg_name (str) – Name of the volume group
lv_name (str) – Name of the logical volume

__lvm_conf()

Create LVM config in /etc/lvm/lvmlocal.conf

This override some configurations specific to the initramfs environment.

Note: if /etc/lvm/lvmlocal.conf exists, we append to it, which may cause duplicate configuration warnings from LVM.

Parameters: out (IO[str]) –
Return type: None

class cmkinitramfs.data.MountData(source, mountpoint, filesystem, options='ro')[source]

Bases: Data

Mount point

Parameters

source (Data) – Data to use as source (e.g. /dev/sda1, my-luks-data), it will be set as a hard dependency
mountpoint (str) – Absolute path of the mountpoint
filesystem (str) – Filesystem (used for mount -t filesystem)
options (str) – Mount options

__fun_fsck()

Define the mount_fsck function

This function takes any number of arguments, which will be passed to fsck. This function checks the return code of the fsck command and acts accordingly.

This functions calls fsck with $@. It checks the return code of fsck and :

No error: returns 0.
Non fatal error: prints an error and returns 0.
Non fatal error requiring reboot: prints an error and reboot.
Fatal error: returns 1.

Parameters: out (IO[str]) – Stream to write into
Return type: None

class cmkinitramfs.data.MdData(sources, name)[source]

Bases: Data

MD RAID

Parameters

sources (Tuple[Data, ...]) – Data to use as sources (e.g. /dev/sda1 and /dev/sdb1; or UUID=foo), they will be set as hard dependencies
name (str) – Name for the MD device

Raises

ValueError – No Data source

class cmkinitramfs.data.CloneData(source, dest)[source]

Bases: Data

Clone a Data to another

Parameters

source (Data) – Data to use as source, it will be set as a load dependency
dest (Data) – Data to use as destination, it will be set as a hard dependency

class cmkinitramfs.data.ZFSPoolData(pool, cache)[source]

Bases: Data

ZFS pool

Parameters

pool (str) – Pool name
cache (Optional[Data]) – Data containing a ZFS cache file, it will be set as a load dependency

class cmkinitramfs.data.ZFSCryptData(pool, dataset, key=None)[source]

Bases: Data

ZFS encrypted dataset

Parameters

pool (ZFSPoolData) – ZFSPoolData containing the encrypted dataset, it will be set as a hard dependency
dataset (str) – Dataset name
key (Optional[Data]) – Data to use as key file, it will be set as a load dependency

exception cmkinitramfs.data.DataError[source]

Bases: Exception

Error in the Data object