diskimage_builder.block_device package

Subpackages

Submodules

diskimage_builder.block_device.blockdevice module

class diskimage_builder.block_device.blockdevice.BlockDevice(params)

Bases: object

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

cmd_cleanup()

Cleanup all remaining relicts - in good case

cmd_create()

Creates the block device

cmd_delete()

Cleanup all remaining relicts - in case of an error

cmd_getval(symbol)

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

cmd_init()

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.

cmd_umount()

Unmounts the blockdevice and cleanup resources

cmd_writefstab()

Creates the fstab

class diskimage_builder.block_device.blockdevice.BlockDeviceState(filename=None)

Bases: MutableMapping

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()

debug_dump()

Log state to debug

save_state(filename)

Persist the state to disk

Parameters:

filename – The file to persist state to

diskimage_builder.block_device.cmd module

class diskimage_builder.block_device.cmd.BlockDeviceCmd

Bases: object

cmd_cleanup()
cmd_create()
cmd_delete()
cmd_getval()
cmd_init()
cmd_umount()
cmd_writefstab()
main()
diskimage_builder.block_device.cmd.main()

diskimage_builder.block_device.config module

diskimage_builder.block_device.config.config_tree_to_graph(config)

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

Parameters:

  • config – graph configuration file

  • default_config – default parameters (from –params)

  • state – reference to global state dictionary. Passed to PluginBase.__init__()

Returns:

tuple with the graph object (a nx.Digraph), ordered list of NodeBase objects

diskimage_builder.block_device.config.is_a_plugin(name)
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

diskimage_builder.block_device.exception module

exception diskimage_builder.block_device.exception.BlockDeviceSetupException

Bases: Exception

Generic exception

diskimage_builder.block_device.plugin module

class diskimage_builder.block_device.plugin.NodeBase(name, state)

Bases: object

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 Nodebase.create().

Parameters:

  • func – function to call

  • args – arguments

  • kwargs – keyword arguments

Returns:

None

cleanup()

Cleanup actions

Actions to taken when dib-block-device cleanup is called. This is the cleanup path in the success case. The nodes are called in the reverse order to create()

Returns:

None

abstract create()

Main creation driver

This is the main driver function. After the graph is linearised, each node has it’s create() function called.

Raises:

Exception – A failure should raise an exception. This will initiate a rollback. See Nodebase.add_rollback().

Returns:

None

delete()

Cleanup actions

Actions to taken when dib-block-device delete is called. This is the cleanup path in case of a reported external failure. The nodes are called in the reverse order to create()

Returns:

None

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 base parameter 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

get_name()
rollback()

Initiate rollback

Call registered rollback in reverse order. This method is called by the driver in the case of failures during Nodebase.create().

Return None:

umount()

Umount actions

Actions to taken when dib-block-device umount is called. The nodes are called in the reverse order to create()

Returns:

None

class diskimage_builder.block_device.plugin.PluginBase

Bases: object

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.plugin for 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

The __init__ function will be passed three arguments:

config

The full configuration dictionary for the entry. A unique name entry can be assumed. In most cases a base entry will be present giving the parent node (see NodeBase.get_edges()).

state

A reference to the gobal state dictionary. This should be passed to NodeBase.__init__() on node creation

defaults

The global defaults dictionary (see --params)

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.

abstract get_nodes()

Return nodes created by the plugin

Returns:

a list of NodeBase objects for insertion into the graph

diskimage_builder.block_device.utils module

diskimage_builder.block_device.utils.exec_sudo(cmd)

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.

Arguments:

Parameters:

cmd – str command list; for Popen()

Returns:

the stdout+stderror of the called command

Raises:

BlockDeviceSetupException – if return code != 0.

Exception values similar to subprocess.CalledProcessError

  • returncode : returncode of child

  • cmd : the command run

  • output : stdout+stderr output

diskimage_builder.block_device.utils.parse_abs_size_spec(size_spec)
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.

diskimage_builder.block_device.utils.remove_device(device_name)

Attempt to remove a device-mapper device

Convenience rollback function to attempt to delete a device, logging a warning if the delete fails.

Parameters:

device_name – Name of device to run dmsetup remove on

Module contents