- diskimage_builder.block_device.level0 package
- diskimage_builder.block_device.level1 package
- diskimage_builder.block_device.level1.lvm module
- diskimage_builder.block_device.level1.mbr module
- diskimage_builder.block_device.level1.partition module
- diskimage_builder.block_device.level1.partitioning module
- Module contents
- diskimage_builder.block_device.level2 package
- diskimage_builder.block_device.level3 package
- diskimage_builder.block_device.level4 package
- diskimage_builder.block_device.tests package
- diskimage_builder.block_device.tests.test_base module
- diskimage_builder.block_device.tests.test_config module
- diskimage_builder.block_device.tests.test_gpt module
- diskimage_builder.block_device.tests.test_lvm module
- diskimage_builder.block_device.tests.test_mbr module
- diskimage_builder.block_device.tests.test_mkfs module
- diskimage_builder.block_device.tests.test_mount_order module
- diskimage_builder.block_device.tests.test_state module
- diskimage_builder.block_device.tests.test_utils module
- Module contents
- class diskimage_builder.block_device.blockdevice.BlockDevice(params)¶
Handles block devices.
This class handles the complete setup and deletion of all aspects of the block device level.
A typical call sequence:
- cmd_init: initialize the block device level config. After this
call it is possible to e.g. query information from the (partially automatic generated) internal state like root-label.
- cmd_getval: retrieve information about the (internal) block device
state like the block image device (for bootloader) or the root-label (for writing fstab).
- cmd_create: creates all the different aspects of the block
device. When this call is successful, the complete block level device is set up, filesystems are created and are mounted at the correct position. After this call it is possible to copy / install all the needed files into the appropriate directories.
cmd_writefstab: creates the (complete) fstab for the system.
- cmd_umount: unmount and detaches all directories and used many
resources. After this call the used (e.g.) images are still available for further handling, e.g. converting from raw in some other format.
- cmd_cleanup: removes everything that was created with the
‘cmd_create’ call, i.e. all images files themselves and internal temporary configuration.
- cmd_delete: unmounts and removes everything that was created
during the ‘cmd_create’ all. This call should be used in error conditions when there is the need to remove all allocated resources immediately and as good as possible. From the functional point of view this is mostly the same as a call to ‘cmd_umount’ and ‘cmd_cleanup’ - but is typically more error tolerance.
In a script this should be called in the following way:
dib-block-device init … # From that point the database can be queried, like ROOT_LABEL=$(dib-block-device getval root-label)
Please note that currently the dib-block-device executable can only be used outside the chroot.
dib-block-device create … trap “dib-block-device delete …” EXIT # copy / install files dib-block-device umount … # convert image(s) dib-block-device cleanup … trap - EXIT
Cleanup all remaining relicts - in good case
Creates the block device
Cleanup all remaining relicts - in case of an error
Retrieve value from block device level
The value of SYMBOL is printed to stdout. This is intended to be captured into bash-variables for backward compatibility (non python) access to internal configuration.
Arguments: :param symbol: the symbol to get
Initialize block device setup
This initializes the block device setup layer. One major task is to parse and check the configuration, write it down for later examiniation and execution.
Unmounts the blockdevice and cleanup resources
Creates the fstab
- class diskimage_builder.block_device.blockdevice.BlockDeviceState(filename=None)¶
The global state singleton
An reference to an instance of this object is saved into nodes as a global repository. It wraps a single dictionary “state” and provides a few helper functions.
The state ends up used in two contexts:
The node list (including this state) is pickled and dumped between cmd_create() and later cmd_* calls that need to call the nodes.
Some other cmd_* calls, such as cmd_writefstab, only need access to values inside the state and not the whole node list, and load it from the json dump created after cmd_create()
Log state to debug
Persist the state to disk
filename – The file to persist state to
- class diskimage_builder.block_device.cmd.BlockDeviceCmd¶
Turn a YAML config into a graph config
Our YAML config is a list of entries. Each
Arguments: :parm config: YAML config; either graph or tree :return: graph-based result
- diskimage_builder.block_device.config.create_graph(config, default_config, state)¶
Generate configuration digraph
Generate the configuration digraph from the config
config – graph configuration file
default_config – default parameters (from –params)
state – reference to global state dictionary. Passed to
tuple with the graph object (a
nx.Digraph), ordered list of
- diskimage_builder.block_device.config.recurse_config(config, parent_base=None)¶
Convert a config “tree” to it’s canonical name/base graph version
This is a recursive function to convert a YAML layout “tree” config into a “flat” graph-based config.
Arguments: :param config: the incoming config dictionary :param parent_base: the name of the parent node, if any :return: a list of expanded, graph-based config items
- exception diskimage_builder.block_device.exception.BlockDeviceSetupException¶
- class diskimage_builder.block_device.plugin.NodeBase(name, state)¶
A configuration node entry
This is the main driver class for dib-block-device operation.
The final operations graph is composed of instantiations of this class. The graph undergoes a topological sort (i.e. is linearised in dependency order) and each node has
create()called in order to perform its operations.
Every node has a unique string
name. This is its key in the graph and used for edge relationships. Implementations must ensure they initalize it; e.g.
class FooNode(NodeBase): def __init__(name, arg1, ...): super(FooNode, self).__init__(name)
- add_rollback(func, *args, **kwargs)¶
Add a call for rollback
Functions registered with this method will be called in reverse-order in the case of failures during
func – function to call
args – arguments
kwargs – keyword arguments
Actions to taken when
dib-block-device cleanupis called. This is the cleanup path in the success case. The nodes are called in the reverse order to
- abstract create()¶
Main creation driver
This is the main driver function. After the graph is linearised, each node has it’s
Exception – A failure should raise an exception. This will initiate a rollback. See
Actions to taken when
dib-block-device deleteis called. This is the cleanup path in case of a reported external failure. The nodes are called in the reverse order to
- abstract get_edges()¶
Return the dependencies/edges for this node
This function will be called after all nodes are created (this is because some plugins need to know the global state of all nodes to decide their dependencies).
This function returns a tuple with two lists
edges_from: a list of node names that point to us
edges_to: a list of node names we point to
In most cases, node creation will have saved a single parent that was given in the
baseparameter of the configuration. A usual return might look like:
def get_edges(self): return ( [self.base],  )
Some nodes (
level0) don’t have a base, however
Call registered rollback in reverse order. This method is called by the driver in the case of failures during
- Return None:
- class diskimage_builder.block_device.plugin.PluginBase¶
The base plugin object
This is the base plugin object. Plugins are an instantiation of this class. There should be an entry-point (see setup.cfg) defined under
diskimage_builder.block_device.pluginfor each plugin, e.g.
foo = diskimage_builder.block_device.levelX.foo:Foo
A configuration entry in the graph config that matches this entry point will create an instance of this class, e.g.
foo: name: foo_node base: parent_node argument_a: bar argument_b: baz
__init__function will be passed three arguments:
The full configuration dictionary for the entry. A unique
nameentry can be assumed. In most cases a
baseentry will be present giving the parent node (see
A reference to the gobal state dictionary. This should be passed to
NodeBase.__init__()on node creation
The global defaults dictionary (see
get_nodes()should return the node object(s) created by the config for insertion into the final configuration graph. In the simplest case, this is probably a single node created during instantiation. e.g.
class Foo(PluginBase): def __init__(self, config, defaults, state): super(Foo, self).__init__() self.node = FooNode(config.name, state, ...) def get_nodes(self): return [self.node]
Some plugins require more, however.
Run a command under sudo
Run command under sudo, with debug trace of output. This is like subprocess.check_call() but sudo wrapped and with output tracing at debug levels.
cmd – str command list; for Popen()
the stdout+stderror of the called command
BlockDeviceSetupException – if return code != 0.
Exception values similar to
returncode: returncode of child
cmd: the command run
output: stdout+stderr output
- diskimage_builder.block_device.utils.parse_rel_size_spec(size_spec, abs_size)¶
Parses size specifications - can be relative like 50%
In addition to the absolute parsing also a relative parsing is done. If the size specification ends in ‘%’, then the relative size of the given ‘abs_size’ is returned.
Attempt to remove a device-mapper device
Convenience rollback function to attempt to delete a device, logging a warning if the delete fails.
device_name – Name of device to run dmsetup remove on