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)[source]¶
Bases:
object
Class representing boom persistent configuration values.
- __init__(boot_path=None, boom_path=None, legacy_enable=None, legacy_format=None, legacy_sync=None)[source]¶
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__()[source]¶
Return a string representation of this
BoomConfig
in BoomConfig initialiser notation.
- boom_path = '/boot/boom'¶
- boot_path = '/boot'¶
- legacy_enable = False¶
- legacy_format = 'grub1'¶
- legacy_sync = True¶
- 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[source]¶
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)[source]¶
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__()[source]¶
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__()[source]¶
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)[source]¶
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 raiseValueError
if invalid criteria exist.- Parameters
entry –
Selection
may include BootEntry dataparams –
Selection
may include BootParams dataprofile –
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)[source]¶
Initialise Selection from command line arguments.
Construct a new
Selection
object from the command line arguments incmd_args
. Each set selection attribute fromcmd_args
is copied into the Selection. The resulting object may be passed to either theBootEntry
orOsProfile
search functions (find_entries
andfind_profiles
), as well as theboom.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()[source]¶
Test this Selection object for null selection criteria.
Return
True
if thisSelection
object matches all objects, orFalse
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()[source]¶
Return the active
BoomConfig
object.- Returntype
BoomConfig
- Returns
the active configuration object
- boom.get_boom_path()[source]¶
Return the currently configured boom configuration path.
- Returns
the path to the BOOT/boom directory.
- Returntype
str
- boom.get_boot_path()[source]¶
Return the currently configured boot file system path.
- Returns
the path to the /boot file system.
- Returntype
str
- boom.get_debug_mask()[source]¶
Return the current debug mask for the
boom
package.- Returns
The current debug mask value
- Returntype
int
- boom.set_boom_config(config)[source]¶
Set the active configuration to the object
config
(which may be any class that includes theBoomConfig
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)[source]¶
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 byconfig.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)[source]¶
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 byget_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 callingset_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.
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[source]¶
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)[source]¶
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 anOsProfile
(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 aBootEntry
, 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 newBootEntry
objects to be written to disk.An
OsProfile
can be attached to aBootEntry
when it is created, or at a later time by calling theset_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 dictionaryentry_data
(and optionally the suppliedBootParams
object). The supplied dictionary should be indexed by Boom entry key names (BOOT_*
).Raises
ValueError
if required keys are missing (BOOT_TITLE
, and eitherBOOT_LINUX
orBOOT_EFI
).This method should not be called directly: to build a new
BootEntry
object from in-memory data, use the class initialiser with theentry_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 inentry_file
(and optionally the suppliedBootParams
object).Raises
ValueError
if required keys are missing (BOOT_TITLE
, and eitherBOOT_LINUX
orBOOT_EFI
).This method should not be called directly: to build a new
BootEntry
object from entry file data, use the class initialiser with theentry_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)[source]¶
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 ifkey
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)[source]¶
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 newBootEntry
and will be used to supply templates forBootEntry
values.A
BootParams
object may be supplied using theboot_params
keyword argument. The object will be used to provide values for subsitution using the patterns defined by the configuredOsProfile
.If
entry_file
is specified theBootEntry
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, bothtitle
andmachine_id
must be given.The
entry_data
keyword argument is an optional argument used to initialise aBootEntry
from a dictionary mappingBOOT_*
keys toBootEntry
values. It may be used to initialised a newBootEntry
using the strings obtained from a call toBootEntry.__repr__()
.- Parameters
title – The title for this
BootEntry
.machine_id – The
machine_id
of thisBootEntry
.osprofile – An optional
OsProfile
to attach to thisBootEntry
.boot_params – An optional
BootParams
object to initialise thisBooyEntry
.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 thisBootEntry
from.
- Returns
A new
BootEntry
object.- Returntype
BootEntry
- __len__()[source]¶
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 thisBootEntry
by probing each loadedOsProfile
in turn until a profile recognises the entry. If no match is found the entrie’sOsProfile
is set toNone
.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__()[source]¶
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)[source]¶
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__()[source]¶
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)[source]¶
Apply key format string substitution.
Apply format key substitution to format string
fmt
, using values provided by an attachedBootParams
object, and string patterns from either an associatedOsProfile
object, or values set directly in thisBootEntry
.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()[source]¶
Mark this
BootEntry
as needing to be written to disk.A newly created
BootEntry
object is always dirty and a call to itswrite_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)[source]¶
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
’sboot_id
.- Type
string
- bp = None¶
- delete_entry()[source]¶
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 callingwrite_entry()
).- Returntype
NoneType
- Raises
OsError
if an error occurs removing the file orValueError
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()[source]¶
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()[source]¶
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’smachine_id
.- Setter
sets this
BootEntry
object’smachine_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()[source]¶
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’sversion
.- Setter
sets this
BootEntry
object’sversion
.- Type
string
- write_entry(force=False)[source]¶
Write out entry to disk.
Write out this
BootEntry
’s data to a file in BLS format to the path specified byboom_entries_path()
.The file will be named according to the entry’s key values, and the value of the
BOOT_ENTRIES_FORMAT
constant. Currently themachine_id
andversion
keys are used to contstuct the file name.If the value of
force
isFalse
and theOsProfile
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)[source]¶
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 aBootEntry
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)[source]¶
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 androot_device
is unset,root_device
is assumed to be the normal path of the logical volume specified by thelvm_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
andbtrfs_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__()[source]¶
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 theBootParams
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__()[source]¶
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)[source]¶
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()[source]¶
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()[source]¶
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()[source]¶
Return the path to the boom profiles directory.
- Returns
The boom profiles path.
- Returntype
str
- boom.bootloader.check_bootloader()[source]¶
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)[source]¶
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)[source]¶
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.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)[source]¶
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 theprofile_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 theprofile_file
argument.- Returns
None
- __getitem__(key)[source]¶
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 ifkey
is valid but not present.
- __init__(name=None, short_name=None, version=None, version_id=None, profile_file=None, profile_data=None)[source]¶
Initialise a new
OsProfile
object.If neither
profile_file
norprofile_data
is given, all ofname
,short_name
,version
, andversion_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__()[source]¶
Return the length (key count) of this
OsProfile
.- Returns
the
OsProfile
length as an integer.- Returntype
int
- __repr__()[source]¶
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)[source]¶
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__()[source]¶
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()[source]¶
Mark this
OsProfile
as needing to be written to disk.A newly created
OsProfile
object is always dirty and a call to itswrite_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()[source]¶
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()[source]¶
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()[source]¶
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 callingwrite_profile()
before the object is disposed of).- Returntype
NoneType
- Raises
OsError
if an error occurs removing the file orValueError
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()[source]¶
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)[source]¶
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)[source]¶
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()[source]¶
Return the items list for this OsProfile.
Return a list of
(key, value)
tuples representing the key items in thisOsProfile
.- 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()[source]¶
Return the list of keys for this OsProfile.
- Returntype
list
- Returns
A list of OsProfile key names
- make_format_regexes(fmt)[source]¶
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)[source]¶
Test OsProfile for options template match.
Test the supplied
BootEntry
to determine whether it matches the options template defined by thisOsProfile
.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, orFalse
otherwise.- Returntype
bool
- match_uname_version(version)[source]¶
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, orFalse
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()[source]¶
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)[source]¶
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
andversion_id
keys are used to construct the file name.If the value of
force
isFalse
and theOsProfile
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()[source]¶
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>)[source]¶
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 eachOsProfile
is tested in turn by callingmatch_fn
. If the matching function returnsTrue
theOsProfile
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)[source]¶
Find an OsProfile by its os_id.
Return the OsProfile object corresponding to
os_id
, orNone
if it is not found.- Returntype
OsProfile
- Returns
An OsProfile matching os_id or None if no match was found
- boom.osprofile.load_profiles()[source]¶
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)[source]¶
Attempt to match a BootEntry to a corresponding OsProfile.
Probe all loaded
OsProfile
objects with the suppliedBootEntry
in turn, until anOsProfile
reports a match. Checking terminates on the first matchingOsProfile
.- Parameters
entry – A
BootEntry
object with no attachedOsProfile
.- Returns
The corresponding
OsProfile
for the suppliedBootEntry
orNone
if no match is found.- Returntype
BootEntry
orNoneType
.
- boom.osprofile.match_os_profile_by_version(version)[source]¶
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()[source]¶
Test whether profiles have been loaded from disk.
- Returntype
bool
- Returns
True
if profiles are loaded in memory orFalse
otherwise
- boom.osprofile.select_profile(s, osp)[source]¶
Test the supplied profile against selection criteria.
Test the supplied
OsProfile
against the selection criteria ins
and returnTrue
if it passes, orFalse
otherwise.- Parameters
osp – The OsProfile to test
- Returntype
bool
- Returns
True if osp passes selection or
False
otherwise.
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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 theprofile_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)[source]¶
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. Ifboot_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)[source]¶
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. Ifos_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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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 inout_file
, orsys.stdout
ifout_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)[source]¶
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[source]¶
Bases:
object
A
BoomField
represents an instance of aBoomFieldType
including its associated data values.- __init__(report, props)[source]¶
Initialise a new BoomField object.
Initialise a BoomField object and configure the supplied
report
andprops
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Report an arbitrary value for this BoomField object.
Set the value for this field to the supplied
value
, and set the field’ssort_value
to the suppliedsort_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[source]¶
Bases:
object
- align = None¶
- compact_one = False¶
- compacted = False¶
- dtype = None¶
- field_num = None¶
- implicit = False¶
- initial_width = 0¶
- objtype = None¶
- sort_dir = None¶
- sort_key = False¶
- sort_posn = None¶
- width = 0¶
- class boom.report.BoomFieldType[source]¶
Bases:
object
The
BoomFieldType
class describes the properties of a field available in aBoomReport
instance.- __init__(objtype, name, head, desc, width, dtype, report_fn, align=None)[source]¶
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[source]¶
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 ofBoomField
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’sreport_types
mask to include the field’s type identifier. Iftype_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 requestedBoomFieldType
, andimplicit
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)[source]¶
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’sreport_types
mask to include the field’s type identifier. Iftype_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 thereport_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 thereport_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 correspondingBoomFieldProperties
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()[source]¶
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()[source]¶
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)[source]¶
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()[source]¶
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)[source]¶
Report data for object.
Add a row of data to this
BoomReport
. Thedata
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()[source]¶
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[source]¶
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 thedata_fn
member may be simplylambda x: x
.- __init__(objtype, desc, prefix, data_fn)[source]¶
Initialise BoomReportObjType.
Initialise a new
BoomReportObjType
object with the specifiedobjtype
,desc
, optionalprefix
anddata_fn
. Theobjtype
must be an integer power of two that is unique within a given report. Thedata_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[source]¶
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'>)[source]¶
Initialise BoomReportOpts object.
Initialise a
BoomReportOpts
object to control output of aBoomReport
.- 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¶