boom package

Module contents

This module provides classes and functions for creating, displaying, and manipulating boot loader entries complying with the Boot Loader Specification.

The boom package contains global definitions, functions to configure the Boom environment, logging infrastructure for the package and a Selection class used to select one or more OsProfile, BootEntry, or BootParams object according to specified selection criteria.

Individual sub-modules provide interfaces to the various components of Boom: operating system profiles, boot loader entries and boot parameters, the boom CLI and procedural API and a simple reporting module to produce tabular reports on Boom objects.

See the sub-module documentation for specific information on the classes and interfaces provided, and the boom tool help output and manual page for information on using the command line interface.

class boom.BoomConfig(boot_path=None, boom_path=None, legacy_enable=None, legacy_format=None, legacy_sync=None)

Bases: object

Class representing boom persistent configuration values.

__init__(boot_path=None, boom_path=None, legacy_enable=None, legacy_format=None, legacy_sync=None)

Initialise a new BoomConfig object with the supplied configuration values, or defaults for any unset arguments.

Parameters

• boot_path – the path to the system /boot volume

• boom_path – the path to the boom configuration dir

• legacy_enable – enable legacy bootloader support

• legacy_format – the legacy bootlodaer format to write

• legacy_sync – the legacy sync mode

__repr__()

Return a string representation of this BoomConfig in BoomConfig initialiser notation.

__str__()

Return a string representation of this BoomConfig in boom.conf (INI) notation.

boom_path = '/boot/boom'

boot_path = '/boot'

legacy_enable = False

legacy_format = 'grub1'

legacy_sync = True

exception boom.BoomError

Bases: Exception

Base class of all Boom exceptions.

boom.DEFAULT_BOOM_PATH = '/boot/boom'

The root directory for Boom configuration files.

boom.DEFAULT_BOOT_PATH = '/boot'

The location of the system /boot directory.

boom.FMT_BTRFS_ROOT_OPTS = 'btrfs_root_opts'

BTRFS kernel command line options

boom.FMT_BTRFS_SUBVOLUME = 'btrfs_subvolume'

BTRFS subvolume specification.

boom.FMT_BTRFS_SUBVOL_ID = 'btrfs_subvol_id'

BTRFS subvolume ID specification.

boom.FMT_BTRFS_SUBVOL_PATH = 'btrfs_subvol_path'

BTRFS subvolume path specification.

boom.FMT_INITRAMFS = 'initramfs'

Initramfs image

boom.FMT_KERNEL = 'kernel'

Linux kernel image

boom.FMT_LVM_ROOT_LV = 'lvm_root_lv'

LVM2 root logical volume in vg/lv format.

boom.FMT_LVM_ROOT_OPTS = 'lvm_root_opts'

LVM2 kernel command line options

boom.FMT_ROOT_DEVICE = 'root_device'

Root device path.

boom.FMT_ROOT_OPTS = 'root_opts'

Root device options.

boom.FMT_VERSION = 'version'

Kernel version string, in uname -r format.

boom.FORMAT_KEYS = ['version', 'lvm_root_lv', 'lvm_root_opts', 'btrfs_subvol_id', 'btrfs_subvol_path', 'btrfs_subvolume', 'btrfs_root_opts', 'root_device', 'root_opts', 'kernel', 'initramfs']

List of all possible format keys.

class boom.Selection

Bases: object

Selection criteria for boom BootEntry, OsProfile and BootParams.

Selection criteria specified as a simple boolean AND of all criteria with a non-None value.

__init__(boot_id=None, title=None, version=None, machine_id=None, linux=None, initrd=None, efi=None, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, os_id=None, os_name=None, os_short_name=None, os_version=None, os_version_id=None, os_options=None, os_uname_pattern=None, kernel_pattern=None, initramfs_pattern=None)

Initialise a new Selection object.

Initialise a new Selection object with the specified selection criteria.

Parameters

• boot_id – The boot_id to match

• title – The title to match

• version – The version to match

• machine_id – The machine_id to match

• linux – The BootEntry kernel image to match

• initrd – The BootEntry initrd image to match

• efi – The BootEntry efi image to match

• root_device – The root_device to match

• lvm_root_lv – The lvm_root_lv to match

• btrfs_subvol_path – The btrfs_subvol_path to match

• btrfs_subvol_id – The btrfs_subvol_id to match

• os_id – The os_id to match

• os_name – The os_name to match

• os_short_name – The os_short_name to match

• os_version – The os_version to match

• os_version_id – The os_version_id to match

• os_options – The os_options to match

• os_uname_pattern – The os_uname_pattern to match

• os_kernel_pattern – The kernel_pattern to match

• os_initramfs_pattern – The initramfs_pattern to match

Returns

A new Selection instance

Returntype

Selection

__repr__()

Format this Selection object as a machine readable string.

The returned string may be passed to the Selection initialiser to duplicate the original Selection.

Returns

A machine readable string representation of this Selection object

Returntype

string

__str__()

Format this Selection object as a human readable string.

Returns

A human readable string representation of this Selection object

Returntype

string

boot_id = None

btrfs_subvol_id = None

btrfs_subvol_path = None

check_valid_selection(entry=False, params=False, profile=False)

Check a Selection for valid criteria.

Check this Selection object to ensure it contains only criteria that are valid for the specified object type(s).

Returns None if the object passes the check, or raise ValueError if invalid criteria exist.

Parameters

• entry – Selection may include BootEntry data

• params – Selection may include BootParams data

• profile – Selection may include OsProfile data

Returns

None on success

Returntype

NoneType

Raises

ValueError if excluded criteria are present

devicetree = None

efi = None

entry_attrs = ['boot_id', 'title', 'version', 'machine_id', 'linux', 'initrd', 'efi', 'options', 'devicetree']

Selection criteria applying to BootEntry objects

classmethod from_cmd_args(args)

Initialise Selection from command line arguments.

Construct a new Selection object from the command line arguments in cmd_args. Each set selection attribute from cmd_args is copied into the Selection. The resulting object may be passed to either the BootEntry or OsProfile search functions (find_entries and find_profiles), as well as the boom.command calls that accept a selection argument.

Parameters

args – The command line selection arguments.

Returns

A new Selection instance

Returntype

Selection

initrd = None

is_null()

Test this Selection object for null selection criteria.

Return True if this Selection object matches all objects, or False otherwise.

Returns

True if this Selection is null

Returntype

bool

linux = None

lvm_root_lv = None

machine_id = None

options = None

os_id = None

os_initramfs_pattern = None

os_kernel_pattern = None

os_name = None

os_options = None

os_root_opts_btrfs = None

os_root_opts_lvm2 = None

os_short_name = None

os_uname_pattern = None

os_version = None

os_version_id = None

params_attrs = ['root_device', 'lvm_root_lv', 'btrfs_subvol_path', 'btrfs_subvol_id']

Selection criteria applying to BootParams objects

profile_attrs = ['os_id', 'os_name', 'os_short_name', 'os_version', 'os_version_id', 'os_uname_pattern', 'os_kernel_pattern', 'os_initramfs_pattern', 'os_root_opts_lvm2', 'os_root_opts_btrfs', 'os_options']

Selection criteria applying to OsProfile objects

root_device = None

title = None

version = None

boom.get_boom_config()

Return the active BoomConfig object.

Returntype

BoomConfig

Returns

the active configuration object

boom.get_boom_path()

Return the currently configured boom configuration path.

Returns

the path to the BOOT/boom directory.

Returntype

str

boom.get_boot_path()

Return the currently configured boot file system path.

Returns

the path to the /boot file system.

Returntype

str

boom.get_debug_mask()

Return the current debug mask for the boom package.

Returns

The current debug mask value

Returntype

int

boom.set_boom_config(config)

Set the active configuration to the object config (which may be any class that includes the BoomConfig attributes).

Parameters

config – a configuration object

Returns

None

Raises

TypeError if config does not appear to have the correct attributes.

boom.set_boom_path(boom_path)

Set the location of the boom configuration directory.

Set the location of the boom configuration path stored in the active configuration to boom_path. This defaults to the ‘boom/’ sub-directory in the boot file system specified by config.boot_path: this may be overridden by calling this function with a different path.

Parameters

boom_path – the path to the ‘boom/’ directory containing boom profiles and configuration.

Returns

None

Raises

ValueError if boom_path does not exist.

boom.set_boot_path(boot_path)

Sets the location of the boot file system to boot_path.

The path defaults to the ‘/boot/’ mount directory in the root file system: this may be overridden by calling this function with a different path.

Calling set_boom_root_path() will re-set the value returned by get_boom_path() to the default boom configuration sub- directory within the new boot file system. The location of the boom configuration path may be configured separately by calling set_boom_root_path() after setting the boot path.

Parameters

boot_path – the path to the ‘boom/’ directory containing boom profiles and configuration.

ReturnsNone

None

Raises

ValueError if boot_path does not exist.

boom.set_debug_mask(mask)

Set the debug mask for the boom package.

Parameters

mask – the logical OR of the BOOM_DEBUG_* values to log.

Returntype

None

Submodules

boom.bootloader module

The boom.bootloader module defines classes for working with on-disk boot loader entries: the BootEntry class represents an individual boot loader entry, and the BootParams class encapsulates the parameters needed to boot an instance of the operating system. The kernel version and root device configuration of an existing BootEntry may be changed by modifying or substituting its BootParams object (this may also be used to ‘clone’ configuration from one entry to another).

Functions are provided to read and write boot loader entries from an on-disk store (normally located at /boot/loader/entries), and to retrieve particular BootEntry objects based on a variety of selection criteria.

The BootEntry class includes named properties for each boot entry attribute (“entry key”). In addition, the class serves as a container type, allowing attributes to be accessed via dictionary-style indexing. This simplifies iteration over a profile’s key / value pairs and allows straightforward access to all members in scripts and the Python shell.

All entry key names are made available as named members of the module: BOOT_ENTRY_*, and the ENTRY_KEYS list. A map of Boom key names to BLS keys is available in the KEY_MAP dictionary (a reverse map is also provided in the MAP_KEY member).

boom.bootloader.BOOT_DEVICETREE = 'BOOT_DEVICETREE'

The BootEntry device tree key.

boom.bootloader.BOOT_EFI = 'BOOT_EFI'

The BootEntry efi key.

boom.bootloader.BOOT_ENTRIES_FORMAT = '%s-%s-%s.conf'

The format used to construct entry file names.

boom.bootloader.BOOT_ENTRY_MODE = 420

The file mode with which BLS entries should be created.

boom.bootloader.BOOT_INITRD = 'BOOT_INITRD'

The BootEntry initrd key.

boom.bootloader.BOOT_LINUX = 'BOOT_LINUX'

The BootEntry linux key.

boom.bootloader.BOOT_MACHINE_ID = 'BOOT_MACHINE_ID'

The BootEntry machine_id key.

boom.bootloader.BOOT_OPTIONS = 'BOOT_OPTIONS'

The BootEntry options key.

boom.bootloader.BOOT_TITLE = 'BOOT_TITLE'

The BootEntry title key.

boom.bootloader.BOOT_VERSION = 'BOOT_VERSION'

The BootEntry version key.

exception boom.bootloader.BoomRootDeviceError

Bases: boom.BoomError

Boom exception indicating an invalid root device.

class boom.bootloader.BootEntry(title=None, machine_id=None, osprofile=None, boot_params=None, entry_file=None, entry_data=None, allow_no_dev=False)

Bases: object

A class representing a BLS compliant boot entry.

A BootEntry exposes two sets of properties that are the keys of a BootLoader Specification boot entry.

The properties of a BootEntry that is not associated with an OsProfile (for e.g. one read from disk) are the literal values read from a file or set through the API.

When an OSProfile is attached to a BootEntry, it is used as a template to fill out the values of keys for properties including the kernel and initramfs file name. This is used to create new BootEntry objects to be written to disk.

An OsProfile can be attached to a BootEntry when it is created, or at a later time by calling the set_os_profile() method.

__boot_id = None

__from_data(entry_data, boot_params)

Initialise a new BootEntry from in-memory data.

Initialise a new BootEntry object with data from the dictionary entry_data (and optionally the supplied BootParams object). The supplied dictionary should be indexed by Boom entry key names (BOOT_*).

Raises ValueError if required keys are missing (BOOT_TITLE, and either BOOT_LINUX or BOOT_EFI).

This method should not be called directly: to build a new BootEntry object from in-memory data, use the class initialiser with the entry_data argument.

Parameters

• entry_data – A dictionary mapping Boom boot entry key names to values

• boot_params – Optional BootParams to attach to the new BootEntry object

Returns

None

Returntype

None

Raises

ValueError

__from_file(entry_file, boot_params)

Initialise a new BootEntry from on-disk data.

Initialise a new BootEntry using the entry data in entry_file (and optionally the supplied BootParams object).

Raises ValueError if required keys are missing (BOOT_TITLE, and either BOOT_LINUX or BOOT_EFI).

This method should not be called directly: to build a new BootEntry object from entry file data, use the class initialiser with the entry_file argument.

Parameters

• entry_file – The path to a file containing a BLS boot entry

• boot_params – Optional BootParams to attach to the new BootEntry object

Returns

None

Returntype

None

Raises

ValueError

__generate_boot_id()

Generate a new boot_id value.

Generate a new sha1 profile identifier for this entry, using the title, version, root_device and any defined LVM2 or BTRFS snapshot parameters.

Returns

A boot_id string

Returntype

str

__getitem__(key)

Return an item from this BootEntry.

Returns

the item corresponding to the key requested.

Returntype

the corresponding type of the requested key.

Raises

TypeError if key is of an invalid type. KeyError if key is valid but not present.

__init__(title=None, machine_id=None, osprofile=None, boot_params=None, entry_file=None, entry_data=None, allow_no_dev=False)

Initialise new BootEntry.

Initialise a new BootEntry object from the specified file or using the supplied values.

If osprofile is specified the profile is attached to the new BootEntry and will be used to supply templates for BootEntry values.

A BootParams object may be supplied using the boot_params keyword argument. The object will be used to provide values for subsitution using the patterns defined by the configured OsProfile.

If entry_file is specified the BootEntry will be initialised from the values found in the file, which should contain a valid BLS snippet in UTF-8 encoding. The file may contain blank lines and comments (lines beginning with ‘#’), and these will be preserved if the entry is re-written.

If entry_file is not specified, both title and machine_id must be given.

The entry_data keyword argument is an optional argument used to initialise a BootEntry from a dictionary mapping BOOT_* keys to BootEntry values. It may be used to initialised a new BootEntry using the strings obtained from a call to BootEntry.__repr__().

Parameters

• title – The title for this BootEntry.

• machine_id – The machine_id of this BootEntry.

• osprofile – An optional OsProfile to attach to this BootEntry.

• boot_params – An optional BootParams object to initialise this BooyEntry.

• entry_file – An optional path to a file in the file system containing a boot entry in BLS notation.

• entry_data – An optional dictionary of BootEntry key to value mappings to initialise this BootEntry from.

Returns

A new BootEntry object.

Returntype

BootEntry

__len__()

Return the length (key count) of this BootEntry.

Returns

the BootEntry length as an integer.

Returntype

int

__match_os_profile()

Attempt to find a matching OsProfile for this BootEntry.

Attempt to guess the correct OsProfile to use with this BootEntry by probing each loaded OsProfile in turn until a profile recognises the entry. If no match is found the entrie’s OsProfile is set to None.

Probing is only used in the case that a loaded entry has no embedded OsIdentifier string. All entries written by Boom include the OsIdentifier value: probing is primarily useful for entries that have been manually written or edited.

__os_id_from_comment(comment)

Retrive OsProfile from BootEntry comment.

Attempt to set this BootEntry’s OsProfile using a comment string stored in the entry file. The comment must be of the form “OsIdentifier: <os_id>”. If found the value is treated as authoritative and a reference to the corresponding OsProfile is stored in the object’s _osp member.

Any comment lines that do not contain an OsIdentifier tag are returned as a multi-line string.

Parameters

comment – The comment to attempt to parse

Returns

Comment lines not containing an OsIdentifier

Returntype

str

__repr__()

Format BootEntry as a machine-readable string.

Return a machine readable representation of this BootEntry, in constructor notation.

Returns

A string in BootEntry constructor syntax.

Returntype

str

__setitem__(key, value)

Set the specified BootEntry key to the given value.

Parameters

• key – the BootEntry key to be set.

• value – the value to set for the specified key.

__str(quote=False, prefix='', suffix='', tail='\n', sep=' ', bls=True, no_boot_id=False)

Format BootEntry as a string.

Return a human or machine readable representation of this BootEntry.

Parameters

quote – True if values should be quoted or False otherwise.

:param prefix:An optional prefix string to be concatenated with

with the start of the formatted string.

Parameters

• suffix – An optional suffix string to be concatenated with the end of the formatted string.

• tail – A string to be concatenated between subsequent records in the formatted string.

• sep – A separator to be inserted between each name and value. Normally either ‘ ‘ or ‘=’.

• bls – Generate output using BootLoader Specification syntax and key names.

• no_boot_id – Do not include the BOOT_ID key in the returned string. Used internally in order to avoid recursion when calculating the BOOT_ID checksum.

Returns

A string representation.

Returntype

string

__str__()

Format BootEntry as a human-readable string in BLS notation.

Format this BootEntry as a string containing a BLS configuration snippet.

Returns

a BLS configuration snippet corresponding to this entry.

Returntype

string

_apply_format(fmt)

Apply key format string substitution.

Apply format key substitution to format string fmt, using values provided by an attached BootParams object, and string patterns from either an associated OsProfile object, or values set directly in this BootEntry.

If the source of data for a key is empty or None, the string is returned unchanged.

The currently defined format keys are:

• %{version} The kernel version string.

• %{lvm_root_lv} The LVM2 logical volume containing the root file system.

• %{btrfs_subvolume} The root flags specifying the BTRFS subvolume containing the root file system.

• %{root_device} The device containing the root file system.

• %{root_opts} The command line options required for the root file system.

• %{linux} The linux image to boot

Parameters

fmt – The string to be formatted.

Returns

The formatted string

Returntype

str

_comments = None

_dirty()

Mark this BootEntry as needing to be written to disk.

A newly created BootEntry object is always dirty and a call to its write_entry() method will always write a new boot entry file. Writes may be avoided for entries that are not marked as dirty.

A clean BootEntry is marked as dirty if a new value is written to any of its writable properties.

Returntype

None

_entry_data = None

_entry_data_property(name)

Return property value from entry data.

Parameters

name – The boom key name of the property to return

Returns

The property value from the entry data dictionary

property _entry_path

_osp = None

_unwritten = False

property boot_id

A SHA1 digest that uniquely identifies this BootEntry.

Getter

return this BootEntry’s boot_id.

Type

string

bp = None

delete_entry()

Remove on-disk BootEntry file.

Remove the on-disk entry corresponding to this BootEntry object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_entry()).

Returntype

NoneType

Raises

OsError if an error occurs removing the file or ValueError if the entry does not exist.

property devicetree

The devicetree archive for this BootEntry.

Getter

returns the configured device tree archive.

Getter

sets the configured device tree archive.

Type

string

property disp_boot_id

The display boot_id of this entry.

Return the shortest prefix of this BootEntry’s boot_id that is unique within the current set of loaded entries.

Getter

return this BootEntry’s boot_id.

Type

str

property efi

The loadable EFI image for this BootEntry.

Getter

returns the configured EFI application image.

Getter

sets the configured EFI application image.

Type

string

property initrd

The loadable initramfs image for this BootEntry.

Getter

returns the configured initrd image.

Getter

sets the configured initrd image.

Type

string

items()

Return the items list for this BootEntry.

Return a copy of this BootEntry’s (key, value) pairs as a list.

Returns

the current list of BotoEntry items.

Returntype

list of (key, value) tuples.

keys()

Return the list of keys for this BootEntry.

Return a copy of this BootEntry’s keys as a list of key name strings.

Returns

the current list of BotoEntry keys.

Returntype

list of str

property linux

The bootable Linux image for this BootEntry.

Getter

returns the configured linux image.

Setter

sets the configured linux image.

Type

string

property machine_id

The machine_id of this BootEntry.

Getter

returns this BootEntry object’s machine_id.

Setter

sets this BootEntry object’s machine_id.

Type

string

property options

The command line options for this BootEntry.

Getter

returns the command line for this BootEntry.

Setter

sets the command line for this BootEntry.

Type

string

property root_opts

The root options that should be used for this BootEntry.

Getter

Returns the root options string for this BootEntry.

Type

string

property title

The title of this BootEntry.

Getter

returns the BootEntry title.

Setter

sets this BootEntry object’s title.

Type

string

values()

Return the list of values for this BootEntry.

Return a copy of this BootEntry’s values as a list.

Returns

the current list of BotoEntry values.

Returntype

list

property version

The version string associated with this BootEntry.

Getter

returns this BootEntry object’s version.

Setter

sets this BootEntry object’s version.

Type

string

write_entry(force=False)

Write out entry to disk.

Write out this BootEntry’s data to a file in BLS format to the path specified by boom_entries_path().

The file will be named according to the entry’s key values, and the value of the BOOT_ENTRIES_FORMAT constant. Currently the machine_id and version keys are used to contstuct the file name.

If the value of force is False and the OsProfile is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters

force – Force this entry to be written to disk even if the entry is unmodified.

Raises

OSError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

Returntype

None

class boom.bootloader.BootParams(version, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None)

Bases: object

The BootParams class encapsulates the information needed to boot an instance of the operating system: the kernel version, root device, and root device options.

A BootParams object is used to configure a BootEntry and to generate configuration keys for the entry based on an attached OsProfile.

__init__(version, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None)

Initialise a new BootParams object.

The root device is specified via the root_device argument as a path relative to the root file system.

The LVM2 logical volume containing the root file system is specified using lvm_root_lv if LVM2 is used.

For instances using LVM2, if the lvm_root_lv argument is set and root_device is unset, root_device is assumed to be the normal path of the logical volume specified by the lvm_root_lv argument.

For instances using BTRFS, the root_device argument is always required.

Instances using BTRFS may select a subvolume to be mounted as the root file system by specifying either the subvolume path or id via btrfs_subvol_path and btrfs_subvol_id.

BootParams() raises ValueError if a required argument is missing, or if conflicting arguments are present.

Parameters

• version – The version string for this BootParams object.

• root_device – The root device for this BootParams object.

• lvm_root_lv – The LVM2 logical volume containing the root file system, for systems that use LVM.

• btrfs_subvol_path – The BTRFS subvolume path containing the root file system, for systems using BTRFS.

• btrfs_subvol_id – The BTRFS subvolume ID containing the root file system, for systems using BTRFS.

Returns

a newly initialised BootParams object.

Returntype

class BootParams

Raises

ValueError

__repr__()

Format BootParams as a machine-readable string.

Format this BootParams object as a machine-readable string. The string returned is in the form of a call to the BootParams constructor.

Returns

a machine readable string represenatation of this BootParams object.

__str(quote=False, prefix='', suffix='')

Format BootParams as a string.

Format this BootParams object as a string, with optional prefix, suffix, and value quoting.

Parameters

• quote – A bool indicating whether to quote values.

• prefix – An optional prefix string to be concatenated with the start of the formatted string.

• suffix – An optional suffix string to be concatenated with the end of the formatted string.

Returns

a formatted representation of this BootParams.

Returntype

string

__str__()

Format BootParams as a human-readable string.

Format this BootParams object as a human-readable string.

Returns

A human readable string representation of this BootParams object.

Returntype

string

btrfs_subvol_id = None

The ID of the BTRFS subvolume to be used as the root file system.

btrfs_subvol_path = None

The BTRFS subvolume path to be used as the root file system.

classmethod from_entry(be)

Recover BootParams from BootEntry.

Recover BootParams values from a templated BootEntry: each key subject to template substitution is transformed into a regular expression, matching the element and capturing the corresponding BootParams value.

A BootEntry object that has no attached OsProfile cannot be reversed since no templates exist to match the entry against: in this case None is returned but no exception is raised. The entry may be modified and re-written, but no templating is possible unless a new, valid, OsProfile is attached.

Parameters

be – The BootEntry to recover BootParams from.

Returns

A newly initialised BootParams object.

Returntype

BootParams

Raises

ValueError if expected values cannot be matched.

has_btrfs()

Return True if this BootParams object is configured to use BTRFS.

Returns

True if BTRFS is in use, or False otherwise

Returntype

bool

has_lvm2()

Return True if this BootParams object is configured to use LVM2.

Returns

True if LVM2 is in use, or False otherwise

Returntype

bool

lvm_root_lv = None

The LVM2 logical volume containing the root file system

root_device = None

The path to the root device

version = None

The kernel version of the instance.

boom.bootloader.DEV_PATTERN = '/dev/%s'

Pattern for forming root device paths from LVM2 names.

boom.bootloader.boom_entries_path()

Return the path to the boom profiles directory.

Returns

The boom profiles path.

Returntype

str

boom.bootloader.check_bootloader()

Check the configuration state of the system bootloader to ensure that Boom integration is enabled. Currently only Grub2 with the Red Hat BLS patches is supported.

boom.bootloader.find_entries(selection=None)

Find boot entries matching selection criteria.

Return a list of BootEntry objects matching the specified criteria. Matching proceeds as the logical ‘and’ of all criteria. Criteria that are unset (None) are ignored.

If no BootEntry matches the specified criteria the empty list is returned.

Boot entries will be automatically loaded from disk if they are not already in memory.

Parameters

selection – A Selection object specifying the match criteria for the operation.

Returns

a list of BootEntry objects.

Returntype

list

boom.bootloader.load_entries(machine_id=None)

Load boot entries into memory.

Load boot entries from boom.bootloader.boom_entries_path().

If machine_id is specified only matching entries will be considered.

Parameters

machine_id – A machine_id value to match.

boom.bootloader.min_boot_id_width()

Calculate the minimum unique width for boot_id values.

Calculate the minimum width to ensure uniqueness when displaying boot_id values.

Returns

the minimum boot_id width.

Returntype

int

boom.bootloader.write_entries()

Write out boot entries.

Write all currently loaded boot entries to boom.bootloader.boom_entries_path().

boom.osprofile module

The boom.osprofile module defines the OsProfile class that represents an operating system profile. An OsProfile defines the identity of a profile and includes template values used to generate boot loader entries.

Functions are provided to read and write operating system profiles from an on-disk store, and to retrieve OsProfile instances using various selection criteria.

The OsProfile class includes named properties for each profile attribute (“profile key”). In addition, the class serves as a container type, allowing attributes to be accessed via dictionary-style indexing. This simplifies iteration over a profile’s key / value pairs and allows straightforward access to all members in scripts and the Python shell.

All profile key names are made available as named members of the module: BOOM_OS_*, and the PROFILE_KEYS list. Human-readable names for all the profile keys are stored in the KEY_NAMES dictionary: these are suitable for display use and are used by default by the OsProfile string formatting routines.

boom.osprofile.BOOM_OS_ID = 'BOOM_OS_ID'

Constant for the Boom OS identifier profile key.

boom.osprofile.BOOM_OS_INITRAMFS_PATTERN = 'BOOM_OS_INITRAMFS_PATTERN'

Constant for the Boom OS initramfs pattern profile key.

boom.osprofile.BOOM_OS_KERNEL_PATTERN = 'BOOM_OS_KERNEL_PATTERN'

Constant for the Boom OS kernel pattern profile key.

boom.osprofile.BOOM_OS_NAME = 'BOOM_OS_NAME'

Constant for the Boom OS name profile key.

boom.osprofile.BOOM_OS_OPTIONS = 'BOOM_OS_OPTIONS'

Constant for the Boom OS command line options key.

boom.osprofile.BOOM_OS_PROFILE_FORMAT = '%s-%s%s.profile'

File name format for Boom profiles.

boom.osprofile.BOOM_OS_ROOT_OPTS_BTRFS = 'BOOM_OS_ROOT_OPTS_BTRFS'

Constant for the Boom OS BTRFS root options key.

boom.osprofile.BOOM_OS_ROOT_OPTS_LVM2 = 'BOOM_OS_ROOT_OPTS_LVM2'

Constant for the Boom OS LVM2 root options key.

boom.osprofile.BOOM_OS_SHORT_NAME = 'BOOM_OS_SHORT_NAME'

Constant for the Boom OS short name profile key.

boom.osprofile.BOOM_OS_UNAME_PATTERN = 'BOOM_OS_UNAME_PATTERN'

Constant for the Boom OS uname pattern profile key.

boom.osprofile.BOOM_OS_VERSION = 'BOOM_OS_VERSION'

Constant for the Boom OS version string profile key.

boom.osprofile.BOOM_OS_VERSION_ID = 'BOOM_OS_VERSION_ID'

Constant for the Boom OS version ID string profile key.

boom.osprofile.BOOM_PROFILES = 'profiles'

Boom profiles directory name.

boom.osprofile.BOOM_PROFILE_MODE = 420

The file mode with which to create Boom profiles.

boom.osprofile.KEY_NAMES = {'BOOM_OS_ID': 'OS ID', 'BOOM_OS_INITRAMFS_PATTERN': 'Initramfs pattern', 'BOOM_OS_KERNEL_PATTERN': 'Kernel pattern', 'BOOM_OS_NAME': 'Name', 'BOOM_OS_OPTIONS': 'Options', 'BOOM_OS_ROOT_OPTS_BTRFS': 'Root options (BTRFS)', 'BOOM_OS_ROOT_OPTS_LVM2': 'Root options (LVM2)', 'BOOM_OS_SHORT_NAME': 'Short name', 'BOOM_OS_UNAME_PATTERN': 'UTS release pattern', 'BOOM_OS_VERSION': 'Version', 'BOOM_OS_VERSION_ID': 'Version ID'}

A map of Boom profile keys to human readable key names suitable for use in formatted output. These key names are used when an OsProfile object is formatted as a string.

class boom.osprofile.OsProfile(name=None, short_name=None, version=None, version_id=None, profile_file=None, profile_data=None)

Bases: object

Class OsProfile implements Boom operating system profiles. Objects of type OsProfile define the paths, kernel command line options, root device flags and file name patterns needed to boot an instance of that operating system.

__from_data(profile_data, dirty=True)

Initialise an OsProfile from in-memory data.

Initialise a new OsProfile object using the profile data in the profile_data dictionary.

This method should not be called directly: to build a new Osprofile object from in-memory data, use the class initialiser with the profile_data argument.

Returns

None

__from_file(profile_file)

Initialise a new OsProfile from data stored in a file.

Initialise a new OsProfile object using the profile data in profile_file.

This method should not be called directly: to build a new Osprofile object from in-memory data, use the class initialiser with the profile_file argument.

Returns

None

__getitem__(key)

Return an item from this OsProfile.

Returns

the item corresponding to the key requested.

Returntype

the corresponding type of the requested key.

Raises

TypeError if key is of an invalid type. KeyError if key is valid but not present.

__init__(name=None, short_name=None, version=None, version_id=None, profile_file=None, profile_data=None)

Initialise a new OsProfile object.

If neither profile_file nor profile_data is given, all of name, short_name, version, and version_id must be given.

These values form the profile identity and are used to generate the profile unique identifier.

Parameters

• name – The name of the operating system.

• short_name – A short name for the operating system, suitable for use in file names.

• version – A string describing the version of the operating system.

• version_id – A short alphanumeric string representing the operating system version and suitable for use in generating file names.

• profile_data – An optional dictionary mapping from BOOM_OS_* keys to profile values.

• profile_file – An optional path to a file from which profile data should be loaded. The file should be in Boom profile format, with BOOM_OS_* key=value pairs.

Returns

A new OsProfile object.

Returntype

class OsProfile

__len__()

Return the length (key count) of this OsProfile.

Returns

the OsProfile length as an integer.

Returntype

int

__repr__()

Format this OsProfile as a machine readable string.

Return a machine-readable representation of this OsProfile object. The string is formatted as a call to the OsProfile constructor, with values passed as a dictionary to the profile_data keyword argument.

Returns

a string representation of this OsProfile.

Returntype

<class ‘boom.osprofile.OsProfile>

__setitem__(key, value)

Set the specified OsProfile key to the given value.

Parameters

• key – the OsProfile key to be set.

• value – the value to set for the specified key.

__str__()

Format this OsProfile as a human readable string.

Profile attributes are printed as “Name: value, ” pairs, with like attributes grouped together onto lines.

Returns

A human readable string representation of this OsProfile.

Returntype

string

_comments = None

_dirty()

Mark this OsProfile as needing to be written to disk.

A newly created OsProfile object is always dirty and a call to its write_profile() method will always write a new profile file. Writes may be avoided for profiles that are not marked as dirty.

A clean OsProfile is marked as dirty if a new value is written to any of its writable properties.

Returns None

_generate_os_id()

Generate a new OS identifier.

Generate a new sha1 profile identifier for this profile, using the short_name, version, and version_id values and store it in _profile_data.

Returns

None

_profile_data = None

_profile_path()

Return the path to this profile’s on-disk data.

Return the full path to this OsProfile in the Boom profiles directory (or the location to which it will be written, if it has not yet been written).

Returntype

str

Returns

The absolute path for this OsProfile’s file

_unwritten = False

delete_profile()

Delete on-disk data for this profile.

Remove the on-disk profile corresponding to this OsProfile object. This will permanently erase the current file (although the current data may be re-written at any time by calling write_profile() before the object is disposed of).

Returntype

NoneType

Raises

OsError if an error occurs removing the file or ValueError if the profile does not exist.

property disp_os_id

The display os_id of this profile.

Return the shortest prefix of this OsProfile’s os_id that is unique within the current set of loaded profiles.

Getter

return this OsProfile’s os_id.

Type

str

classmethod from_host_os_release()

Build an OsProfile from the current hosts’s os-release.

Construct a new OsProfile object using data obtained from the running hosts’s /etc/os-release file.

Returns

A new OsProfile for the current host

Returntype

OsProfile

classmethod from_os_release(os_release)

Build an OsProfile from os-release file data.

Construct a new OsProfile object using data obtained from a file in os-release(5) format.

Parameters

os_release – String data in os-release(5) format

Returns

A new OsProfile for the specified os-release data

Returntype

OsProfile

classmethod from_os_release_file(path)

Build an OsProfile from an on-disk os-release file.

Construct a new OsProfile object using data obtained from the file specified by ‘path’.

Parameters

os_release – Path to a file in os-release(5) format

Returns

A new OsProfile for the specified os-release file

Returntype

OsProfile

property initramfs_pattern

The current initramfs_pattern setting of this profile.

Getter

returns the initramfs_pattern as a string.

Setter

store a new initramfs_pattern setting.

Type

string

items()

Return the items list for this OsProfile.

Return a list of (key, value) tuples representing the key items in this OsProfile.

Returntype

list

Returns

A list of OsProfile key item tuples

property kernel_pattern

The current kernel_pattern setting of this profile.

Getter

returns the kernel_pattern as a string.

Setter

stores a new kernel_pattern setting.

Type

string

keys()

Return the list of keys for this OsProfile.

Returntype

list

Returns

A list of OsProfile key names

make_format_regexes(fmt)

Generate regexes matching format string

Generate a list of (key, expr) tuples containing key and regular expression pairs capturing the format key values contained in the format string. Any non-format key words contained in the string are returned as a ('', expr) tuple containing no capture groups.

The resulting list may be matched against the words of a BootEntry object’s value strings in order to extract the parameters used to create them.

Parameters

fmt – The format string to build a regex list from.

Returns

A list of key and word regex tuples.

Returntype

list of (str, str)

match_options(entry)

Test OsProfile for options template match.

Test the supplied BootEntry to determine whether it matches the options template defined by this OsProfile.

Used as a match of last resort when no uname pattern match exists.

Parameters

entry – A BootEntry to match against this profile.

Returns

True if this entry matches this profile, or False otherwise.

Returntype

bool

match_uname_version(version)

Test OsProfile for version string match.

Test the supplied version string to determine whether it matches the uname_pattern of this OsProfile.

Parameters

version – A uname release version string to match.

Returns

True if thi version matches this profile, or False otherwise.

Returntype

bool

property name

The name of this profile.

Getter

returns the name as a string.

Type

string

property options

The current kernel command line options setting for this profile.

Getter

returns the options value as a string.

Setter

store a new options value.

Type

string

property os_id

The os_id of this profile.

Getter

returns the os_id as a string.

Type

string

property root_opts_btrfs

The current BTRFS root options setting of this profile.

Getter

returns the root_opts_btrfs value as a string.

Setter

store a new root_opts_btrfs value.

Type

string

property root_opts_lvm2

The current LVM2 root options setting of this profile.

Getter

returns the root_opts_lvm2 value as a string.

Setter

store a new root_opts_lvm2 value.

Type

string

property short_name

The short_name of this profile.

Getter

returns the short_name as a string.

Type

string

property uname_pattern

The current uname_pattern setting of this profile.

Getter

returns the uname_pattern as a string.

Setter

stores a new uname_pattern setting.

Type

string

values()

Return the list of key values for this OsProfile.

Returntype

list

Returns

A list of OsProfile key values

property version

The version of this profile.

Getter

returns the version as a string.

Type

string

property version_id

The version_id of this profile.

Getter

returns the version_id as a string.

Type

string

write_profile(force=False)

Write out profile data to disk.

Write out this OsProfile’s data to a file in Boom format to the paths specified by the current configuration.

Currently the os_id, short_name and version_id keys are used to construct the file name.

If the value of force is False and the OsProfile is not currently marked as dirty (either new, or modified since the last load operation) the write will be skipped.

Parameters

force – Force this profile to be written to disk even if the entry is unmodified.

Raises

OsError if the temporary entry file cannot be renamed, or if setting file permissions on the new entry file fails.

boom.osprofile.PROFILE_KEYS = ['BOOM_OS_ID', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_UNAME_PATTERN', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN', 'BOOM_OS_ROOT_OPTS_LVM2', 'BOOM_OS_ROOT_OPTS_BTRFS', 'BOOM_OS_OPTIONS']

Ordered list of possible profile keys, partitioned into mandatory keys, root option keys, and optional keys (currently the Linux kernel command line).

boom.osprofile.REQUIRED_KEYS = ['BOOM_OS_ID', 'BOOM_OS_NAME', 'BOOM_OS_SHORT_NAME', 'BOOM_OS_VERSION', 'BOOM_OS_VERSION_ID', 'BOOM_OS_UNAME_PATTERN', 'BOOM_OS_KERNEL_PATTERN', 'BOOM_OS_INITRAMFS_PATTERN']

Boom profile keys that must exist in a valid profile.

boom.osprofile.ROOT_KEYS = ['BOOM_OS_ROOT_OPTS_BTRFS']

Boom profile keys for different forms of root device specification.

boom.osprofile.boom_profiles_path()

Return the path to the boom profiles directory.

Returns

The boom profiles path.

Returntype

str

boom.osprofile.find_profiles(selection=None, match_fn=<function select_profile>)

Find profiles matching selection criteria.

Return a list of OsProfile objects matching the specified criteria. Matching proceeds as the logical ‘and’ of all criteria. Criteria that are unset (None) are ignored.

If the optional match_fn parameter is specified, the match criteria parameters are ignored and each OsProfile is tested in turn by calling match_fn. If the matching function returns True the OsProfile will be included in the results.

If no OsProfile matches the specified criteria the empty list is returned.

OS profiles will be automatically loaded from disk if they are not already in memory.

Parameters

• selection – A Selection object specifying the match criteria for the operation.

• match_fn – An optional match function to test profiles.

Returns

a list of OsProfile objects.

Returntype

list

boom.osprofile.get_os_profile_by_id(os_id)

Find an OsProfile by its os_id.

Return the OsProfile object corresponding to os_id, or None if it is not found.

Returntype

OsProfile

Returns

An OsProfile matching os_id or None if no match was found

boom.osprofile.load_profiles()

Load OsProfile data from disk.

Load the set of profiles found at the path boom.osprofile.boom_profiles_path() into the global profile list.

This function may be called to explicitly load, or reload the set of profiles on-disk. Profiles are also loaded implicitly if an API function or method that requires access to profiles is invoked (for example, boom.bootloader.load_entries().

Returns

None

boom.osprofile.match_os_profile(entry)

Attempt to match a BootEntry to a corresponding OsProfile.

Probe all loaded OsProfile objects with the supplied BootEntry in turn, until an OsProfile reports a match. Checking terminates on the first matching OsProfile.

Parameters

entry – A BootEntry object with no attached OsProfile.

Returns

The corresponding OsProfile for the supplied BootEntry or None if no match is found.

Returntype

BootEntry or NoneType.

boom.osprofile.match_os_profile_by_version(version)

Attempt to match a version string to an OsProfile.

Attempt to find a profile with a uname pattern that matches version. The first OsProfile with a match is returned.

Parameters

version – A uname release version string to match.

Returntype

OsProfile

Returns

An OsProfile matching version or None if not match was found

boom.osprofile.profiles_loaded()

Test whether profiles have been loaded from disk.

Returntype

bool

Returns

True if profiles are loaded in memory or False otherwise

boom.osprofile.select_profile(s, osp)

Test the supplied profile against selection criteria.

Test the supplied OsProfile against the selection criteria in s and return True if it passes, or False otherwise.

Parameters

osp – The OsProfile to test

Returntype

bool

Returns

True if osp passes selection or False otherwise.

boom.osprofile.write_profiles(force=False)

Write all OsProfile data to disk.

Write the current list of profiles to the directory located at boom.osprofile.boom_profiles_path().

Returntype

None

boom.command module

The boom.command module provides both the Boom command line interface infrastructure, and a simple procedural interface to the boom library modules.

The procedural interface is used by the boom command line tool, and may be used by application programs, or interactively in the Python shell by users who do not require all the features present in the Boom object API.

In addition the module contains definitions for BoomReport object types and fields that may be of use in implementing custom reports using the boom.report module.

boom.command.clone_entry(selection=None, title=None, version=None, machine_id=None, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, osprofile=None, write=True)

Clone an existing boot loader entry.

Create the specified boot entry in the configured loader directory by cloning all un-set parameters from the boot entry selected by the selection argument.

An error is raised if a matching entry already exists.

Parameters

• selection – criteria matching the entry to clone.

• title – the title of the new entry.

• version – the version string for the new entry.

• root_device – the root device path for the new entry.

• lvm_root_lv – an optional LVM2 root logical volume.

• btrfs_subvol_path – an optional BTRFS subvolume path.

• btrfs_subvol_id – an optional BTRFS subvolume id.

• osprofile – The OsProfile for this entry.

Returns

a BootEntry object corresponding to the new entry.

Returntype

BootEntry

Raises

ValueError if either required values are missing or a duplicate entry exists, or``OsError`` if an error occurs while writing the entry file.

boom.command.clone_profile(selection=None, name=None, short_name=None, version=None, version_id=None, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None)

Clone an existing operating system profile.

Create the specified profile in the configured profile directory by cloning all un-set parameters from the profile selected by the selection argument.

An error is raised if a matching profile already exists.

Parameters

• selection – criteria matching the profile to clone.

• name – the name of the new profile.

• short_name – the short name of the new profile.

• version – the version string for the new profile.

• version_id – the version ID string for the new profile.

• uname_pattern – a uname pattern to match this profile.

• root_opts_lvm2 – LVM2 root options template.

• root_opts_btrfs – BTRFS root options template.

• options – Kernel options template.

Returns

a new OsProfile object.

Returntype

OsProfile

Raises

ValueError if either required values are missing or a duplicate profile exists, or``OsError`` if an error occurs while writing the profile file.

boom.command.create_entry(title, version, machine_id, root_device, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, osprofile=None, write=True, allow_no_dev=False)

Create new boot loader entry.

Create the specified boot entry in the configured loader directory. An error is raised if a matching entry already exists.

Parameters

• title – the title of the new entry.

• version – the version string for the new entry.

• root_device – the root device path for the new entry.

• lvm_root_lv – an optional LVM2 root logical volume.

• btrfs_subvol_path – an optional BTRFS subvolume path.

• btrfs_subvol_id – an optional BTRFS subvolume id.

• osprofile – The OsProfile for this entry.

• allow_no_dev – Accept a non-existent or invalid root dev.

Returns

a BootEntry object corresponding to the new entry.

Returntype

BootEntry

Raises

ValueError if either required values are missing or a duplicate entry exists, or``OsError`` if an error occurs while writing the entry file.

boom.command.create_profile(name, short_name, version, version_id, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None, profile_data=None, profile_file=None)

Create new operating system profile.

Create the specified OsProfile in the configured profiles directory.

OsProfile key values may be specified either by passing individual keyword arguments, or by passing a dictionary of OsProfile key name to value pairs as the profile_data argument. If a key is present as both a keyword argument and in the profile_data dictionary, the argument will take precedence.

An error is raised if a matching profile already exists.

Parameters

• name – The name of the new OsProfile

• short_name – The short name of the new OsProfile

• version – The version string of the new OsProfile

• version_id – The version ID string of the new OsProfile

• uname_pattern – A uname pattern to match for this profile

• kernel_pattern – Pattern to generate kernel paths

• initramfs_pattern – Pattern to generate initramfs paths

• root_opts_lvm2 – Template options for LVM2 entries

• root_opts_btrfs – Template options for BTRFS entries

• options – Template kernel command line options

• profile_data – Dictionary of profile key:value pairs

Returns

an OsProfile object for the new profile

Returntype

OsProfile

Raises

ValueError if either required values are missing or a duplicate profile exists, or``OsError`` if an error occurs while writing the profile file.

boom.command.delete_entries(selection=None)

Delete entries matching selection criteria.

Delete the specified boot entry or entries from the configured loader directory. If boot_id is used, or if the criteria specified match exactly one entry, a single entry is removed. If boot_id is not used, and more than one matching entry is present, all matching entries will be removed.

Selection criteria may also be expressed via a Selection object passed to the call using the selection parameter.

On success the number of entries removed is returned.

Parameters

selection – A Selection object giving selection criteria for the operation.

Returns

the number of entries removed.

Returntype

int

boom.command.delete_profiles(selection=None)

Delete profiles matching selection criteria.

Delete the specified OsProfile or profiles from the configured profile directory. If os_id is used, or if the criteria specified match exactly one profile, a single entry is removed. If os_id is not used, and more than one matching profile is present, all matching profiles will be removed.

Selection criteria are expressed via a Selection object passed to the call using the selection parameter.

On success the number of profiles removed is returned.

Parameters

selection – A Selection object giving selection criteria for the operation.

Returns

the number of entries removed.

Returntype

int

boom.command.edit_entry(selection=None, title=None, version=None, machine_id=None, root_device=None, lvm_root_lv=None, btrfs_subvol_path=None, btrfs_subvol_id=None, osprofile=None, write=True)

Edit an existing boot loader entry.

Modify an existing BootEntry by changing one or more of the entry values or boot parameters.

The modified BootEntry is written to disk and returned on success.

Modifying a BootEntry causes the entry’s boot_id to change, since the ID is based on the values of all configured boot keys.

Parameters

• selection – A Selection specifying the boot_id to edit

• title – The new entry title

• version – The new entry version

• machine_id – The new machine_id

• root_device – The new root device

• lvm_root_lv – The new LVM root LV

• btrfs_subvol_path – The new BTRFS subvolume path

• btrfs_subvol_id – The new BTRFS subvolme ID

Returns

The modified BootEntry

Returntype

BootEntry

boom.command.edit_profile(selection=None, uname_pattern=None, kernel_pattern=None, initramfs_pattern=None, root_opts_lvm2=None, root_opts_btrfs=None, options=None)

Edit an existing operating system profile.

Modify an existing OsProfile by changing one or more of the profile values.

The modified OsProfile is written to disk and returned on success.

Parameters

• selection – A Selection specifying the boot_id to edit

• uname_pattern – The new uname pattern

• kernel_pattern – The new kernel pattern

• initramfs_pattern – The new initramfs pattern

• root_opts_lvm2 – The new LVM2 root options

• root_opts_btrfs – The new BTRFS root options

• options – The new kernel options template

Returns

The modified OsProfile

Returntype

OsProfile

boom.command.list_entries(selection=None)

List entries matching selection criteria.

Return a list of boom.bootloader.BootEntry objects matching the given criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters

selection – A Selection object giving selection criteria for the operation.

Returns

A list of matching BootEntry objects.

Returntype

list

boom.command.list_profiles(selection=None)

List operating system profiles matching selection criteria.

Return a list of boom.osprofile.OsProfile objects matching the given criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters

selection – A Selection object giving selection criteria for the operation.

Returns

a list of OsProfile objects.

Returntype

list

boom.command.print_entries(selection=None, output_fields=None, opts=None, sort_keys=None)

Print boot loader entries matching selection criteria.

Format a set of boom.bootloader.BootEntry objects matching the given criteria, and output them as a report to the file given in out_file, or sys.stdout if out_file is unset.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

Returns

the boot_id of the new entry

Returntype

str

boom.command.print_profiles(selection=None, opts=None, output_fields=None, sort_keys=None)

Print operating system profiles matching selection criteria.

Selection criteria may be expressed via a Selection object passed to the call using the selection parameter.

Parameters

• selection – A Selection object giving selection criteria for the operation

• output_fields – a comma-separated list of output fields

• opts – output formatting and control options

• sort_keys – a comma-separated list of sort keys

Returns

the number of matching profiles output.

Returntype

int

boom.report module

The Boom reporting module contains a set of classes for creating simple text based tabular reports for a user-defined set of object types and fields. No restrictions are placed on the types of object that can be reported: users of the BoomReport classes may define additional object types outside the boom package and include these types in reports generated by the module.

The fields displayed in a specific report may be selected from the available set of fields by specifying a simple comma-separated string list of field names (in display order). In addition, custom multi-column sorting is possible using a similar string notation.

The BoomReport module is closely based on the device-mapper reporting engine and shares many features and behaviours with device mapper reports.

class boom.report.BoomField

Bases: object

A BoomField represents an instance of a BoomFieldType including its associated data values.

__init__(report, props)

Initialise a new BoomField object.

Initialise a BoomField object and configure the supplied report and props attributes.

Parameters

• report – The BoomReport that owns this field

• props – The BoomFieldProperties object for this field

_props = None

reference to the BoomFieldProperties describing this field

_report = None

reference to the containing BoomReport

report_num(value)

Report a numeric value for this BoomField object.

Set the value for this field to the supplied value.

Parameters

value – The numeric value to set

Returntype

None

report_sha(value)

Report a SHA value for this BoomField object.

Set the value for this field to the supplied value.

Parameters

value – The SHA value to set

Returntype

None

report_str(value)

Report a string value for this BoomField object.

Set the value for this field to the supplied value.

Parameters

value – The string value to set

Returntype

None

report_string = None

The formatted string to be reported for this field.

set_value(report_string, sort_value=None)

Report an arbitrary value for this BoomField object.

Set the value for this field to the supplied value, and set the field’s sort_value to the supplied sort_value.

Parameters

value – The string value to set

Returntype

None

sort_value = None

The raw value of this field. Used for sorting.

class boom.report.BoomFieldProperties

Bases: object

align = None

compact_one = False

compacted = False

dtype = None

field_num = None

hidden = False

implicit = False

initial_width = 0

objtype = None

sort_dir = None

sort_key = False

sort_posn = None

width = 0

class boom.report.BoomFieldType

Bases: object

The BoomFieldType class describes the properties of a field available in a BoomReport instance.

__init__(objtype, name, head, desc, width, dtype, report_fn, align=None)

Initialise new BoomFieldType object.

Initialise a new BoomFieldType object with the specified properties.

Parameters

• objtype – The numeric object type ID (power of two)

• name – The field name used to select display fields

• desc – A human-readable description of the field

• width – The default (initial) field width

• dtype – The BoomReport data type of the field

• report_fn – The field reporting function

• align – The field alignment value

Returns

A new BoomReportFieldType object

Returntype

BoomReportFieldType

align = None

desc = None

dtype = None

head = None

name = None

objtype = -1

report_fn = None

width = 8

class boom.report.BoomReport

Bases: object

A class representing a configurable text report with multiple caller-defined fields. An optional title may be provided and he fields argument must contain a list of BoomField objects describing the required report.

__add_field(field_num, implicit)

Add a field to this BoomReport.

Add the specified BoomFieldType to this BoomReport and configure BoomFieldProperties for it.

Parameters

• field_num – The number of this field (fields order)

• implicit – True if this field is implicit, else False

__add_sort_key(field_num, sort, implicit, type_only)

Add a new sort key to this BoomReport

Add the sort key identified by field_num to this list of sort keys for this BoomReport.

Parameters

• field_num – The field number of the key to add

• sort – The sort direction for this key

• implicit – True if field_num is implicit, else False

• type_only – True if this call should only update types

__copy_field(field_num, implicit)

Copy field definition to BoomFieldProperties

Copy values from a BoomFieldType to BoomFieldProperties.

Parameters

• field_num – The number of this field (fields order)

• implicit – True if this field is implicit, else False

__display_fields(display_field_types)

Display report fields help message.

Display a list of valid fields for this BoomReport.

Parameters

• fields – The list of fields to display

• display_field_types – A boolean controling whether field types (str, SHA, num) are included in help output

__field_match(field_name, type_only)

Attempt to match a field and optionally update report type.

Look up the named field and, if type_only is True, update this BoomReport’s report_types mask to include the field’s type identifier. If type_only is False the field is also added to this BoomReport’s field list.

Parameters

• field_name – A string identifying the field

• type_only – True if this call should only update types

__find_type(report_type)

Resolve numeric type to corresponding BoomReportObjType.

Parameters

report_type – The numeric report type to look up

Returns

The requested BoomReportObjType.

Raises

ValueError if no matching type was found.

__get_field(field_name)

Look up a field by name.

Attempt to find the field named in field_name in this BoomReport’s tables of implicit and user-defined fields, returning the a (field, implicit) tuple, where field contains the requested BoomFieldType, and implicit is a boolean indicating whether this field is implicit or not.

Parameters

• field_num – The number of this field (fields order)

• implicit – True if this field is implicit, else False

__get_longest_field_name_len(fields)

Find the longest field name length.

Returns

the length of the longest configured field name

__help_requested()

Check for presence of ‘help’ fields in output selection.

Check the fields making up this BoomReport and return True if any valid ‘help’ field synonym is present.

Returns

True if help was requested or False otherwise

__init__(types, fields, output_fields, opts, sort_keys, private)

Initialise BoomReport.

Initialise a new BoomReport object with the specified fields and output control options.

Parameters

• types – List of BoomReportObjType used in this report.

• fields – A list of BoomField field descriptions.

• output_fields – An optional list of output fields to be rendered by this report.

• opts – An instance of BoomReportOpts or None.

Returns

A new report object.

Returntype

BoomReport.

__key_match(key_name, type_only)

Attempt to match a sort key and update report type.

Look up the named sort key and, if type_only is True, update this BoomReport’s report_types mask to include the field’s type identifier. If type_only is False the field is also added to this BoomReport’s field list.

Parameters

• field_name – A string identifying the sort key

• type_only – True if this call should only update types

__parse_fields(field_format, type_only)

Parse report field list.

Parse field_format and attempt to match the names of field names found to registered BoomFieldType fields.

If type_only is True only the report_types field is updated: otherwise the parsed fields are added to the BoomReport’s field list.

Parameters

• field_format – The list of fields to parse

• type_only – True if this call should only update types

__parse_keys(keys, type_only)

Parse report sort key list.

Parse keys and attempt to match the names of sort keys found to registered BoomFieldType fields.

If type_only is True only the report_types field is updated: otherwise the parsed fields are added to the BoomReport’s sort key list.

Parameters

• field_format – The list of fields to parse

• type_only – True if this call should only update types

__recalculate_fields()

Recalculate field widths.

For each field, recalculate the minimum field width by finding the longest report_string value for that field and updating the dynamic width stored in the corresponding BoomFieldProperties object.

Returntype

None

__recalculate_sha_width()

Recalculate minimum SHA field widths.

For each REP_SHA field present, recalculate the minimum field width required to ensure uniqueness of the displayed values.

Returntype

None

__report_headings()

Output report headings.

Output the column headings for this BoomReport.

Returntype

None

__row_key_fn()

Return a Python key function to compare report rows.

The cmp argument of sorting functions has been removed in Python 3.x: to maintain similarity with the device-mapper report library we keep a traditional “cmp”-style function (that is structured identically to the version in the device mapper library), and dynamically wrap it in a __RowKey object to conform to the Python sort key model.

Returns

A __RowKey object wrapping _row_cmp()

Returntype

__RowKey

_already_reported = False

_data = None

_field_calc_needed = True

_field_properties = None

_fields = None

_header_written = False

_implicit_fields = [<boom.report.BoomFieldType object>]

_implicit_types = [<boom.report.BoomReportObjType object>]

_keys_count = 0

_output_as_columns()

Output this report in column format.

Output the data contained in this BoomReport in column format, one row per line. If column headings have not been printed already they will be automatically displayed by this call.

Returns

None

_output_as_rows()

Output this report in column format.

Output the data contained in this BoomReport in column format, one row per line. If column headings have not been printed already they will be automatically displayed by this call.

Returns

None

_output_field(field)

Output field data.

Generate string data for one field in a report row.

Field

The field to be output

Returns

The output report string for this field

Returntype

str

_rows = None

_sort_required = False

_sort_rows()

Sort the rows of this BoomReport.

Sort this report’s rows, according to the configured sort keys.

Returns

None

_types = None

opts = None

private = None

report_object(obj)

Report data for object.

Add a row of data to this BoomReport. The data argument should be an object of the type understood by this report’s fields. It will be passed in turn to each field to obtain data for the current row.

Parameters

data – the object to report on for this row.

report_output()

Output report data.

Output this report’s data to the configured report file, using the configured output controls and fields.

On success the number of rows output is returned. On error an exception is raised.

Returns

the number of rows of output written.

Returntype

int

report_types = 0

class boom.report.BoomReportObjType

Bases: object

Class representing a type of objecct to be reported on. Instances of BoomReportObjType must specify an identifier, a description, and a data function that will return the correct type of object from a compound object containing data objects of different types. For reports that use only a single object type the data_fn member may be simply lambda x: x.

__init__(objtype, desc, prefix, data_fn)

Initialise BoomReportObjType.

Initialise a new BoomReportObjType object with the specified objtype, desc, optional prefix and data_fn. The objtype must be an integer power of two that is unique within a given report. The data_fn should accept an object as its only argument and return an object of the requested type.

data_fn = None

desc = ''

objtype = -1

prefix = ''

class boom.report.BoomReportOpts

Bases: object

Options controlling the formatting and output of a boom report.

__init__(columns=80, headings=True, buffered=True, separator=' ', field_name_prefix='', unquoted=True, aligned=True, report_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Initialise BoomReportOpts object.

Initialise a BoomReportOpts object to control output of a BoomReport.

Parameters

• columns – the number of columns to use for output.

• headings – a boolean indicating whether to output column headings for this report.

• buffered – a boolean indicating whether to buffer output from this report.

• report_file – a file to which output will be sent.

Returns

a new BoomReportOpts object.

Returntype

<class BoomReportOpts>

aligned = True

buffered = True

columns = 0

columns_as_rows = False

field_name_prefix = None

headings = True

report_file = None

separator = None

unquoted = True