BOOM(8)

NAME
Boom — linux boot manager

SYNOPSIS
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom
boom

DESCRIPTION
Boom is a boot manager for Linux systems using boot loaders that support the BootLoader Specification for boot entry configuration. Boom works best with a BLS compatible boot loader: either the systemd-boot project, or Grub2 with the `bls` patch. The grub2 boot loader included in CentOS, Fedora and Red Hat Enterprise Linux include this support. Boom also supports writing configuration in legacy boot loader format: currently the syntax used by the Grub1 configuration file is supported. All long options supported by boom may be written with or without dashes separating words. For example, --boot-id and --bootid are synonymous.

OPTIONS

-a|--add-opts opts
Specify additional boot options for this entry.

-d|--del-opts opts
Specify boot options to exclude from this entry.

-b|--boot-id|--bootid boot_id
Specify a boot identifier to operate on.

--boot-dir|--bootdir path
Specify the location of the /boot file system. Useful for testing or for accessing boom data from a system image.

-B|--btrfs-subvolme|--btrfssubvolume [subvol_path|subvol_id]
Specify a BTRFS subvolume by its path or identifier.

--btrfs-opts|--btrfsopts btrfs_options_template
An OS profile template string for BTRFS boot options.

--debug debug_flags
A comma-separated list of subsystem names to enable debugging output for, or 'all' to enable all debugging. The available debug classes are: profile, entry, command, report.

-e|--efi efi_image
Specify an EFI application image for a boot entry.

-H|--from-host|--fromhost
When creating a new OS profile, use os-release data from the running host.

-P|--host-profile
Use the specified host profile for search or create operations.

-i|--initrd image_path
A Linux initial ramfs image path.

-k|--kernel-pattern|--kernelpattern pattern
An OS profile template used to generate kernel image paths.

-l|--linux image_path
A Linux kernel image path.

-L|--root-lv|--rootlv root_lv
The logical volume containing the root file system for a boot entry. If --root-lv is given, but --root-device is not, the root device is assumed to be the specified logical volume.

--lvm-opts lvm_opts
An OS profile template used to generate LVM2 boot options.

-m|--machine-id|--machineid machine_id

-n|--name os_name
The name of a boom operating system profile.

--name-prefixes|--nameprefixes
Add a prefix to report field output names.

--no-headings|--noheadings
Suppress output of report headings.

-o|--options field_list
Specify which fields to display.

--os-version
The version string of a boom operating system profile.

-O|--sort key_list
A comma-separated list of sort keys (field names), with an optional per-field prefix of + or - to force ascending or descending sort order respectively for that field.

-I|--os-version-id|--osversionid os_version_id
A boom operating system profile version identifier.

--os-options|--osoptions options_template
An operating system profile template string used to generate the kernel command line options string.

--os-release|--osrelease os_release_path
A path to a file in os-release(5) from which to create a new operating system profile.

-p|--profile os_id
The operating system identifier (os_id) of a boom operating system profile to use for the current operation. Defaults to the OS profile of the running system if absent.

-r|--root-device|--rootdevice root_dev
The system root device for a new boot entry.

-R|--initramfs-pattern|--initramfspattern initramfs_pattern
An OS profile template used to generate initial ramfs image paths.

--rows
Output report columns as rows.

--separator separator
Report field separator

-s|--short-name|--shortname short_name The short name of a boom operating system profile.

-t|--title entry_title
The title for a new boot entry.

-u|--uname-pattern|--unamepattern uname_pattern
An uname pattern to match for an operating system profile.

-V|--verbose
Increase verbosity level. Specify multiple times, or set additional debug classed with --debug to enable more verbose messages.

-v|--version version
The kernel version of a boom boot entry.

OS Profiles and Boot Entries
Boom manages boot loader entries for one or more installed operating systems. Each operating system is identified by an OS Profile that provides identity information and a set of templates used to create boot loader entries. An OS profile is identified by its os_id, an alphanumeric string based on an SHA digest of the profile's identity fields. Identifiers reported in boom command output are automatically abbreviated to the minimum length required to ensure uniqueness and this short form may be used in any place where a boom OS identifier is expected. A Boot Entry represents one bootable instance of an installed operating system: a kernel, optional initial ramfs image, command line options, and other images or settings required for boot. Each boot entry is also identified by a SHA based unique identifier: the boot_id. An entry's ID is used to select an entry for display, modification, deletion or other operations. Since the boot entry's identifier is based on the boot parameters used to create the entry, the boot_id will change if an existing entry is modified (for e.g. with the boom entry edit command).

Host Profiles

Host profiles provide an additional mechanism to control boot entry templates on a per-host basis. A host profile is bound to a specific machine_id and is used whenever new boot entries are created for the corresponding host. A host profile can add and delete boot options from the set supplied by the active OS Profile, or override specific BOS Profile keys completely. Any keys not set in a host profile are mapped directly to the original OS profile.

Boot Entry Commands

boom
Create a new boot entry using the specified values. The title of the new entry must be set with the --title option. The kernel version for the new entry is given with --version. If --version is not present the version is assumed to be that of the currently running kernel. If --profile is given, it specifies the OS identifier of an existing OS profile to use for the new entry. If --profile is not given, and a profile exists that matches either the supplied or detected version then that profile will be automatically used. The machine-id of the new entry is automatically set to the current machine-id (read from /etc/machine-id) unless this is overridden by the --machine-id switch. A root device may be explicitly specified with the --root-device option or if an LVM2 logical volume is used this may be specified with --root-lv: in this case the root device is assumed to be the normal device path of the specified logical volume. A BTRFS subvolume may be set by either the subvolume path or subvolume identifier using the --btrfs-subvol option. Additional boot options not defined by the corresponding OsProfile templates may be specified with --add-opts. Options may also be removed from the entry using --del-opts (for example to disable graphical boot or the "quiet" flag for a particular entry). The newly created entry and its boot identifier are printed to the terminal on success:
# boom create --title 'System Snapshot' --root-lv vg00/lvol0
Created entry with boot_id 14d6b6e:
  title System Snapshot
  machine-id 611f38fd887d41dea7eb3403b2730a76
  version 4.13.5-200.fc26.x86_64
  linux /vmlinuz-4.13.5-200.fc26.x86_64
  initrd /initramfs-4.13.5-200.fc26.x86_64.img
  options BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64 root=/dev/vg00/lvol0 ro rd.lvm.lv=vg00/lvol0 rhgb quiet

boom
Delete the specified boot entry. The entry to delete may be specified either by its boot identifier, in which case at most one entry will be removed, or by specifying selection criteria which may match (and remove) multiple entries in a single operation. For example, by giving --version, all entries matching the specified kernel version can be removed at once. On success the number of entries removed is printed to the terminal. If the --verbose option is given then a report of the entries removed will also be displayed.

boom
Clone an existing boot entry and modify its configuration. The entry to clone must be specified by its boot identifier. Any remaining command line arguments are taken to be modifications to the original entry. On success the new entry and its boot identifier are printed to the terminal.

boom
Output a tabular report of boot entries. Displays a report with one boot entry per line, containing fields describing the properties of the configured boot entries. The list of fields to display is given with --options as a comma separated list of field names. To obtain a list of available fields run 'boom list -o help'. If the list of fields begins with the '+' character the specified fields are appended to the default field list. Otherwise the given list of fields replaces the default set of report fields. Report output may be sorted by multiple user-defined keys using the --sort option. The option expects a comma separated list of keys, with optional '+' and '-' prefixes indicating ascending and descending sort for that field respectively.

boom
Display boot entries matching selection criteria on standard out. Boot entries matching the criteria given on the command line are printed to the terminal in boot loader entry format.

OS Profile Commands

boom
Create a new OS profile using the specified values. A new OS profile can be created either by specifying required values on the boom command line, or by reading data from either the hosts's os-release file (at /etc/os-release), or from another file in os-release format specified on the command line. The information read from os-release (or equivalent command line options) form the profile's identity and are the basis for the profile OS identifier. In addition to the os-release data a new OS profile requires a uname version string pattern to match, and template values used to construct boot entries. The uname pattern must be given on the profile create command line and is a regular expression matching the UTS release (uname -r) values reported by that distribution. The pattern is only used to attempt to match unknown boot entries to a valid OS profile: for example entries that have been manually edited, or that were created by another tool. The boom command provides default templates that are suitable for most Linux distributions. Alternately, these values may be set on the command line at the time of profile creation, or modified using the boom program at a later time. To create a profile for the currently running host, use the --from-host switch. To create a profile from a saved os-release file use the --os-release optiona and give the path to the file to be used.

boom
Delete the specified Os profile or profiles. Delete all OS profiles matching the provided selection criteria. If the --profile option is used to specify an OS identifier then at most one profile will be removed. On success the number of profiles removed is printed to the terminal. If the --verbose option is given then a report of the profiles removed will also be displayed.

boom
Clone an existing OS profile and modify its configuration. The entry to clone must be specified by its OS identifier. Any remaining command line arguments are taken to be modifications to the original entry. On success the new entry and its OS identifier are printed to the terminal.

boom
Output a tabular report of OS profiles. Displays a report with one OS profile per line, containing fields describing the properties of the configured OS profiles. The list of fields to display is given with --options as a comma separated list of field names. To obtain a list of available fields run 'boom list -o help'. If the list of fields begins with the '+' character the specified fields are appended to the default field list. Otherwise the given list of fields replaces the default set of report fields. Report output may be sorted by multiple user-defined keys using the --sort option. The option expects a comma separated list of keys, with optional '+' and '-' prefixes indicating ascending and descending sort for that field respectively.

boom
Display OS profiles matching selection criteria on standard out. OS profiles matching the criteria given on the command line are printed to the terminal in a compact multi-line format.

Host Profile Commands

boom
Create a new host profile for the specified machine_id and using the given profile option arguments. Any OS Profile keys that are given values will override the values in the underlying profile.

boom
Delete the specified host profile or profiles. Delete all host profiles matching the provided selection criteria. If the --host-profile option is used to specify an host identifier then at most one profile will be removed. On success the number of profiles removed is printed to the terminal. If the --verbose option is given then a report of the profiles removed will also be displayed.

boom
Clone an existing host profile and modify its configuration. The entry to clone must be specified by its host identifier. Any remaining command line arguments are taken to be modifications to the original entry. On success the new entry and its host identifier are printed to the terminal.

boom
Edit an existing host profile and modify its configuration. The entry to edit must be specified by its host identifier. Any remaining command line arguments are taken to be modifications to the original profile. On success the new profile and its host identifier are printed to the terminal.

boom Output a tabular report of host profiles. Displays a report with one host profile per line, containing fields describing the properties of the configured host profiles. The list of fields to display is given with --options as a comma separated list of field names. To obtain a list of available fields run field list. Otherwise the given list of fields replaces the default set of report fields. Report output may be sorted by multiple user-defined keys using the --sort option. The option expects a comma separated list of keys, with optional '+' and '-' prefixes indicating ascending and descending sort for that field respectively.

boom
Display host profiles matching selection criteria on standard out. Host profiles matching the criteria given on the command line are printed to the terminal in a compact multi-line format.

LEGACY BOOTLOADER FORMATS
Boom is able to write the current set of boot entries into the configuration file of a legacy boot loader installed on the system. This may be used either on platforms that do not have a native bootloader supporting the Boot Loader Specification, or to allow upgrades and recovery from an installation lacking BLS support (if the system is updated to a distribution that does support the BLS boot loader configuration it will be used automatically when present). Legacy support is enabled and configured via the boom.conf(5) configuration file.

boom
Write out the current set of Boom boot entries in the configured legacy configuration file. The normal command line selection options may be used to control the set of entries written to the file.

boom
Remove all Boom boot entries from the configured legacy configuration file.

boom Display the selected boot entries as they would appear in the configured legacy boot loader format. The normal command line selection options may be used to control the set of entries written to the terminal.

BOOT IMAGE CACHE
Boom can optionally cache or back up the images used by a boom BootEntry. This allows an entry to be booted in the case that a subsequent update has removed the original kernel and initramfs images and can be used to recover an earlier system state from a snapshot following even major operating system updates.

boom
Output a tabular report of paths present in the boot image cache. Displays a report with one cache entry per line, containing fields describing the properties of the cache entry. The list of fields to display is given with --options as a comma separated list of field names. To obtain a list of available fields run field list. Otherwise the given list of fields replaces the default set of report fields. Report output may be sorted by multiple user-defined keys using the --sort option. The option expects a comma separated list of keys, with optional '+' and '-' prefixes indicating ascending and descending sort for that field respectively.

boom
Display matching cache entries on standard output. Entries matching selection criteria are printed in a compact multi-line format.

REPORT FIELDS
The boom report provides several types of field that may be added to the default field set for either Boot Entry or OS Profile reports, or used to create custom reports.

  Boot Parameters
Boot parameter fields represent the properties that distinguish boot entries: the kernel version and root device configuration.

version
    The kernel version of this Boot Entry.

rootdev
    The root device of this Boot Entry.

rootlv
    The root logical volume of this Boot Entry in 'VG/LV' notation.

subvolpath
    The BTRFS subvolume path for this Boot Entry.

subvolid
    The BTRFS subvolume ID for this BootEntry.

  Boot Entry fields
Boot Entry fields provide information about an entry not specified by its Boot Parameters, including the title, boot identifier, boot image locations, and options required to boot the entry.

bootid
    Boot identifier.

title
    The entry title as displayed in the boot loader.

options
    The kernel command line options used to boot this entry.

kernel
    The path to the bootable kernel image, relative to the boot loader.

initramfs
    The path to the initramfs image, relative to the boot loader.

machineid
    The machine-id associated with this Boot Entry.

entrypath
    The absolute path to this Boot Entry's on-disk configuration file.

  OS Profile fields
OS Profile fields provide access to the details of a profile's configuration including identity fields and the template strings used to generate entries. Since each Boot Entry has an attached OS Profile all profile fields are also available to add to any Boot Entry report.

osid
    OS profile identifier.

osname
    The name of this OS prorile as read from os-release.

osshortname
    The short name of this OS profile as read from os-release.

osversion
    The OS version of this OS profile as read from os-release.

osversion_id
    The OS version identifier of this OS profile as read from os-release.

unamepattern
    The configured UTS release pattern for this OS profile.

kernelpattern
    The configured kernel image template for this OS profile.

initrdpattern
    The configured initramfs image template for this OS profile.

lvm2opts
    The configured LVM2 root device options template for this OS profile.

btrfsopts
    The configured BTRFS root options template for this OS profile.

options
    The kernel command line options template for this OS profile.

profilepath
    The absolute path to this OS Profile's on-disk configuration file.

  Host Profile fields
Host Profile fields provide access to the details of a profile's configuration including identity fields and the template strings used to generate entries. This includes all fields available in the OS Profile report as well as additional Host Profile identity fields.

hostid
    Host profile identifier.

hostname
    The hostname of this host profile.

label
    The label of this host profile.

  Cache Entry fields
Cache entry fields provide information on the paths and images stored in the boom boot image cache.

imgid
    Image identifier.

path
    Path to the cached image, relative to the boot file system.

mode
    Path file system mode in human-readable format.

uid Image owner user identifier.

gid Image owner group identifier.

ts  Image timestamp. The mtime of the image file at the time it was added to the cache.

state
    A string description of the cache entry state: CACHED, MISSING, RESTORED, or BROKEN.

count
    The number of boot entries that reference this boot image.

REPORTING COMMANDS
Both the entry list and profile list commands use a common reporting system to display the results of the query. The selection of fields, and the order in which they are displayed, may be controlled to produce custom report formats.

Displaying the available boot entry fields
# boom list -o help
Boot loader entries Fields
--------------------------
  bootid - Boot identifier [sha]
  title - Entry title [str]
  options - Kernel options [str]
  kernel - Kernel image [str]
  initramfs - Initramfs image [str]
  machineid - Machine identifier [sha]
  entrypath - On-disk entry path [str]

OS profiles Fields
------------------
  osid - OS identifier [sha]
  osname - OS name [str]
  osshortname - OS short name [str]
  osversion - OS version [str]
  osversion_id - Version identifier [str]
  unamepattern - UTS name pattern [str]
  kernelpattern - Kernel image pattern [str]
  initrdpattern - Initrd pattern [str]
  lvm2opts - LVM2 options [str]
  btrfsopts - BTRFS options [str]
  options - Kernel options [str]
  profilepath - On-disk profile path [str]

Boot parameters Fields
----------------------
  version - Kernel version [str]
  rootdev - Root device [str]
  rootlv - Root logical volume [str]
  subvolpath - BTRFS subvolume path [str]
  subvolid - BTRFS subvolume ID [num]

Displaying the available OS profile fields
# boom profile list -o help
OS profiles Fields
------------------
  osid - OS identifier [sha]
  osname - OS name [str]
  osshortname - OS short name [str]
  osversion - OS version [str]
  osversion_id - Version identifier [str]
  unamepattern - UTS name pattern [str]
  kernelpattern - Kernel image pattern [str]
  initrdpattern - Initrd pattern [str]
  lvm2opts - LVM2 options [str]
  btrfsopts - BTRFS options [str]
  options - Kernel options [str]
  profilepath - On-disk profile path [str]

Selecting custom fields for the entry list and profile list commands
# boom list -o bootid,osname
BootID Name
0d3e547 Fedora
bc18de2 Fedora
576fe39 Fedora
1838f58 Fedora
81520ca Fedora
327e24a Fedora

Adding additional fields to the default set
# boom list -o +options
BootID Version Name RootDevice Options
0d3e547 4.13.5-200.fc26.x86_64 Fedora /dev/mapper/vg_hex-root BOOT_IMAGE=/vmlinuz-4.11.12-100.fc24.x86_64 root=/dev/mapper/vg_hex-root ro rd.lvm.lv=vg_hex/root rhgb quiet rd.auto=1
bc18de2 4.13.5-200.fc26.x86_64 Fedora /dev/vg_hex/root-snap10 BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64 root=/dev/vg_hex/root-snap10 ro rd.lvm.lv=vg_hex/root-snap10
576fe39 4.13.5-200.fc26.x86_64 Fedora /dev/vg_hex/root BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64 root=/dev/vg_hex/root ro rd.lvm.lv=vg_hex/root
1838f58 4.13.5-200.fc26.x86_64 Fedora /dev/mapper/vg_hex-root BOOT_IMAGE=/vmlinuz-4.11.12-100.fc24.x86_64 root=/dev/mapper/vg_hex-root ro rd.lvm.lv=vg_hex/root rhgb quiet
81520ca 4.13.13-200.fc26.x86_64 Fedora /dev/mapper/vg_hex-root BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64 root=/dev/mapper/vg_hex-root ro rd.lvm.lv=vg_hex/root rhgb quiet LANG=en_GB.UTF-8
327e24a 4.13.5-200.fc26.x86_64 Fedora /dev/vg_hex/root BOOT_IMAGE=%{linux} root=/dev/vg_hex/root ro rd.lvm.lv=vg_hex/root

Sort operating system profiles by ascending OS name and descending OS version
# boom profile list -O+osname,-osversion
OsID Name OsVersion
d4439b7 Fedora 26 (Workstation Edition)
9736c34 Fedora 25 (Server Edition)
9cb53dd Fedora 24 (Workstation Edition)
6bf746b Fedora 24 (Server Edition)
b99ea5f Red Hat Enterprise Linux Server 8 (Server)
3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
c0b921e Red Hat Enterprise Linux Server 7 (Server)
98c3edb Red Hat Enterprise Linux Server 6 (Server)
b730331 Red Hat Enterprise Linux Server 5 (Server)
efd6d41 Red Hat Enterprise Linux Server 4 (Server)
21e37c8 Ubuntu 16.04 LTS (Xenial Xerus)

EXAMPLES
List the available operating system profiles
# boom profile list
OsID Name OsVersion
efd6d41 Red Hat Enterprise Linux Server 4 (Server)
b730331 Red Hat Enterprise Linux Server 5 (Server)
98c3edb Red Hat Enterprise Linux Server 6 (Server)
c0b921e Red Hat Enterprise Linux Server 7 (Server)
3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
b99ea5f Red Hat Enterprise Linux Server 8 (Server)

List the available boot entries
# boom list
BootID Version Name RootDevice
0d3e547 4.13.5-200.fc26.x86_64 Fedora /dev/mapper/vg00-lvol0
bc18de2 4.13.5-200.fc26.x86_64 Fedora /dev/vg00/lvol0-snap10
576fe39 4.13.5-200.fc26.x86_64 Fedora /dev/vg00/lvol0
f52ba10 4.11.12-100.fc24.x86_64 Fedora /dev/vg00/lvol0-snap
1838f58 4.13.5-200.fc26.x86_64 Fedora /dev/mapper/vg00-lvol0
81520ca 4.13.13-200.fc26.x86_64 Fedora /dev/mapper/vg00-lvol0
327e24a 4.13.5-200.fc26.x86_64 Fedora /dev/vg00/lvol0

Create an OS profile for the running system (using Fedora 26 as an example)
# boom profile create --from-host --uname-pattern fc26
Created profile with os_id d4439b7:
  OS ID: "d4439b7d2f928c39f1160c0b0291407e5990b9e0",
  Name: "Fedora", Short name: "fedora",
  Version: "26 (Workstation Edition)", Version ID: "26",
  UTS release pattern: "fc26",
  Kernel pattern: "/kernel-%{version}", Initramfs pattern: "/initramfs-%{version}.img",
  Root options (LVM2): "rd.lvm.lv=%{lvm_root_lv}",
  Root options (BTRFS): "rootflags=%{btrfs_subvolume}",
  Options: "root=%{root_device} ro %{root_opts}"

Create a new boot entry for a specific OS profile and version
# boom profile list --short-name rhel
OsID Name OsVersion
3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
98c3edb Red Hat Enterprise Linux Server 6 (Server)
c0b921e Red Hat Enterprise Linux Server 7 (Server)

# boom create --profile 3fc389b --title "RHEL7 snapshot" --version 3.10-272.el7 --root-lv vg00/lvol0-snap
Created entry with boot_id a5aef11:
title RHEL7 snapshot
machine-id 611f38fd887d41dea7eb3403b2730a76
version 3.10-272.el7
linux /boot/vmlinuz-3.10-272.el7
initrd /boot/initramfs-3.10-272.el7.img
options root=/dev/vg00/lvol0-snap ro rd.lvm.lv=vg00/lvol0-snap rhgb quiet

Create a new boot entry for the running system, changing only the root logical volume
# boom create --title Snap1 --root-lv vg00/lvol0-snap1
Created entry with boot_id e077490:
  title Snap1
  machine-id 611f38fd887d41dea7eb3403b2730a76
  version 4.13.13-200.fc26.x86_64
  linux /vmlinuz-4.13.13-200.fc26.x86_64
  initrd /initramfs-4.13.13-200.fc26.x86_64.img
  options BOOT_IMAGE=/vmlinuz-4.13.13-200.fc26.x86_64 root=/dev/vg00/lvol0-snap1 ro rd.lvm.lv=vg00/lvol0-snap1

Delete an entry by its boot identifier
# boom delete --boot-id e077490
Deleted 1 entry

Delete all entries for the Fedora 24 OS profile
# boom delete --name Fedora --os-version-id 24 Deleted 4 entries

AUTHORS
Bryn M. Reeves <bmr@redhat.com>

SEE ALSO
Boom project page: https://github.com/snapshotmanager/boom
Boot to snapshot documentation: https://github.com/snapshotmanager/snapshot-boot-docs
BootLoader Specification: https://systemd.io/BOOT_LOADER_SPECIFICATION
LVM2 resource page: https://www.sourceware.org/lvm2/
Device-mapper resource page: http://sources.redhat.com/dm/