# diskimage_builder.block_device package

## Subpackages

- diskimage_builder.block_device.level0 package
  - Submodules
  - diskimage_builder.block_device.level0.localloop module
  - Module contents
- diskimage_builder.block_device.level1 package
  - Submodules
  - 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
  - Submodules
  - diskimage_builder.block_device.level2.mkfs module
  - Module contents
- diskimage_builder.block_device.level3 package
  - Submodules
  - diskimage_builder.block_device.level3.mount module
  - Module contents
- diskimage_builder.block_device.level4 package
  - Submodules
  - diskimage_builder.block_device.level4.fstab module
  - Module contents
- diskimage_builder.block_device.tests package
  - Subpackages
    - diskimage_builder.block_device.tests.plugin package
      - Submodules
      - diskimage_builder.block_device.tests.plugin.test_a module
      - diskimage_builder.block_device.tests.plugin.test_b module
      - Module contents
  - Submodules
  - 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

## 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: `collections.abc.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.

## Module contents

this page last updated: 2022-01-12 16:32:54

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug