.TH BOOM 8 "Oct 30 2017" "Linux" "MAINTENANCE COMMANDS"
.de ARG_CMD_TYPES
. RI [ entry | profile | host ]
..
.
.de ARG_COMMANDS
. RI [ create | delete | clone | show | list | edit ]
..
.
.de ARG_LEGACY_TYPES
. RI legacy
..
.
.de ARG_LEGACY_COMMAND
. RI [ write | clear | show ]
..
.
.de ARG_CACHE_TYPES
. RI cache
..
.
.de ARG_CACHE_COMMAND
. RI [ list | show ]
..
.
..
.SH NAME
.
Boom \(em linux boot manager
.
.SH SYNOPSIS
.
.PD 0
.HP
.B boom
.de CMD_COMMAND
. ad l
. ARG_CMD_TYPES
. ARG_COMMANDS
. ad b
..
.CMD_COMMAND
.
.HP
.B boom
.de CMD_LEGACY_COMMAND
. ad l
. ARG_LEGACY_TYPES
. ARG_LEGACY_COMMAND
. ad b
..
.CMD_LEGACY_COMMAND
.
.HP
.B boom
.de CMD_CACHE_COMMAND
. ad l
. ARG_CACHE_TYPES
. ARG_CACHE_COMMAND
. ad b
..
.CMD_CACHE_COMMAND
.
.HP
.B boom
.de CMD_ENTRY_CREATE
. ad l
. BR entry
. BR \fBcreate
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --root-device
. IR device ]
. RB [ --root-lv
. IR lv ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. RB [ --btrfs-subvol
. IR subvol ]
. RB [ --add-opts
. IR opts ]
. RB [ --del-opts
. IR opts ]
. ad b
..
.CMD_ENTRY_CREATE
.
.HP
.B boom
.de CMD_ENTRY_DELETE
. ad l
. BR entry
. BR \fBdelete
. IR [ boot_id ]
. RB [ --boot-id
. IR boot_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. ad b
..
.CMD_ENTRY_DELETE
.
.HP
.B boom
.de CMD_ENTRY_CLONE
. ad l
. BR entry
. BR \fBclone
. IR [ boot_id ]
. RB [ --boot-id
. IR boot_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --root-device
. IR device ]
. RB [ --root-lv
. IR lv ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. RB [ --btrfs-subvol
. IR subvol ]
. RB [ --add-opts
. IR opts ]
. RB [ --del-opts
. IR opts ]
. ad b
..
.CMD_ENTRY_CLONE
.
.HP
.B boom
.de CMD_ENTRY_LIST
. ad l
. BR entry
. BR \fBlist
. IR [ boot_id ]
. RB [ --boot-id
. IR boot_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. RB [ --root-device
. IR device ]
. RB [ --root-lv
. IR lv ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. RB [ --btrfs-subvol
. IR subvol ]
. ad b
..
.CMD_ENTRY_LIST
.
.HP
.B boom
.de CMD_ENTRY_SHOW
. ad l
. BR entry
. BR \fBshow
. IR [ boot_id ]
. RB [ --boot-id
. IR boot_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. RB [ --root-device
. IR device ]
. RB [ --root-lv
. IR lv ]
. RB [ --btrfs-subvol
. IR subvol ]
. ad b
..
.CMD_ENTRY_SHOW
.
.HP
.B boom
.de CMD_PROFILE_CREATE
. ad l
. BR profile
. BR \fBcreate
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR short_name ]
. RB [ --os-version
. IR version ]
. RB [ --os-version-id
. IR version_id ]
. BR [ --from-host ]
. RB [ --os-release
. IR os_release ]
. RB [ --uname-pattern
. IR uname_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_PROFILE_CREATE
.
.HP
.B boom
.de CMD_PROFILE_DELETE
. ad l
. BR profile
. BR \fBdelete
. IR [ profile_id ]
. RB [ --profile
. IR os_id ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR short_name ]
. RB [ --os-version
. IR version ]
. RB [ --os-version-id
. IR version_id ]
. BR [ --from-host ]
. RB [ --os-release
. IR os_release ]
. RB [ --uname-pattern
. IR uname_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_PROFILE_DELETE
.
.HP
.B boom
.de CMD_PROFILE_CLONE
. ad l
. BR profile
. BR \fBclone
. IR [ profile_id ]
. RB [ --profile
. IR os_id ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR short_name ]
. RB [ --os-version
. IR version ]
. RB [ --os-version-id
. IR version_id ]
. BR [ --from-host ]
. RB [ --os-release
. IR os_release ]
. RB [ --uname-pattern
. IR uname_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_PROFILE_CLONE
.
.HP
.B boom
.de CMD_PROFILE_LIST
. ad l
. BR profile
. BR \fBlist
. IR [ profile_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. ad b
..
.CMD_PROFILE_LIST
.
.HP
.B boom
.de CMD_PROFILE_SHOW
. ad l
. BR profile
. BR \fBshow
. IR [ profile_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. ad b
..
.CMD_PROFILE_SHOW
.
.HP
.B boom
.de CMD_HOST_CREATE
. ad l
. BR host
. BR \fBcreate
. RB [ --name
. IR name ]
. RB [ --short-name
. IR short_name ]
. RB [ --profile
. IR os_id ]
. RB [ --machine-id
. IR machine_id ]
. RB [ --kernel-pattern
. IR kernel_pattern ]
. RB [ --initramfs-pattern
. IR initramfs_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_HOST_CREATE
.
.HP
.B boom
.de CMD_HOST_DELETE
. ad l
. BR host
. BR \fBdelete
. IR [ host_id ]
. RB [ --host-profile
. IR host_id ]
. ad b
..
.CMD_HOST_DELETE
.
.HP
.B boom
.de CMD_HOST_CLONE
. ad l
. BR host
. BR \fBclone
. IR [ host_id ]
. RB [ --host-profile
. IR host_id ]
. RB [ --name
. IR name ]
. RB [ --short-name
. IR short_name ]
. RB [ --profile
. IR os_id ]
. RB [ --machine-id
. IR machine_id ]
. RB [ --kernel-pattern
. IR kernel_pattern ]
. RB [ --initramfs-pattern
. IR initramfs_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_HOST_CLONE
.
.HP
.B boom
.de CMD_HOST_EDIT
. ad l
. BR host
. BR \fBedit
. IR [ host_id ]
. RB [ --host-profile
. IR host_id ]
. RB [ --name
. IR name ]
. RB [ --short-name
. IR short_name ]
. RB [ --profile
. IR os_id ]
. RB [ --machine-id
. IR machine_id ]
. RB [ --kernel-pattern
. IR kernel_pattern ]
. RB [ --initramfs-pattern
. IR initramfs_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_HOST_EDIT
.
.HP
.B boom
.de CMD_HOST_LIST
. ad l
. BR host
. BR \fBlist
. IR [ host_id ]
. RB [ --host-profile
. IR host_id ]
. RB [ --name
. IR name ]
. RB [ --short-name
. IR short_name ]
. RB [ --profile
. IR os_id ]
. RB [ --machine-id
. IR machine_id ]
. RB [ --kernel-pattern
. IR kernel_pattern ]
. RB [ --initramfs-pattern
. IR initramfs_pattern ]
. RB [ --lvm-opts
. IR lvm_opts ]
. RB [ --btrfs-opts
. IR btrfs_opts ]
. RB [ --os-options
. IR os_options ]
. ad b
..
.CMD_HOST_LIST
.
.HP
.B boom
.de CMD_HOST_SHOW
. ad l
. BR host
. BR \fBshow
. IR [ profile_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. ad b
..
.CMD_HOST_SHOW
.
.HP
.B boom
.de CMD_LEGACY_WRITE
. ad l
. BR legacy
. BR \fBwrite
. IR [ boot_id ]
. RB [ --boot-id
. IR boot_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. RB [ --root-device
. IR device ]
. RB [ --root-lv
. IR lv ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. RB [ --btrfs-subvol
. IR subvol ]
. ad b
..
.CMD_LEGACY_WRITE
.
.HP
.B boom
.de CMD_LEGACY_CLEAR
. ad l
. BR legacy
. BR \fBclear
. ad b
..
.CMD_LEGACY_CLEAR
.
.HP
.B boom
.de CMD_LEGACY_SHOW
. ad l
. BR legacy
. BR \fBshow
. IR [ boot_id ]
. RB [ --boot-id
. IR boot_id ]
. RB [ --profile
. IR os_id ]
. RB [ --version
. IR version ]
. RB [ --name
. IR osname ]
. RB [ --short-name
. IR osshortname ]
. RB [ --os-version
. IR version ]
. RB [ --root-device
. IR device ]
. RB [ --root-lv
. IR lv ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. RB [ --btrfs-subvol
. IR subvol ]
. ad b
..
.CMD_LEGACY_SHOW
.
.HP
.B boom
.de CMD_CACHE_LIST
. ad l
. BR cache
. BR \fBlist
. IR [ img_id ]
. RB [ --image
. IR img_id ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. ad b
..
.CMD_CACHE_LIST
.
.HP
.B boom
.de CMD_CACHE_SHOW
. ad l
. BR cache
. BR \fBshow
. IR [ img_id ]
. RB [ --image
. IR img_id ]
. RB [ --linux
. IR kernel_path ]
. RB [ --initrd
. IR initrd_path ]
. ad b
..
.CMD_CACHE_SHOW
.
.PD
.ad b
.
.SH DESCRIPTION
.
Boom is a \fIboot manager\fP for Linux systems using boot loaders that
support the \fBBootLoader Specification\fP for boot entry configuration.
Boom works best with a BLS compatible boot loader: either the
\fIsystemd-boot\fP project, or \fIGrub2\fP with the `bls` patch. The
\fIgrub2\fP boot loader included in \fBCentOS\fP, \fBFedora\fP and
\fBRed Hat Enterprise Linux\fP include this support.
Boom also supports writing configuration in legacy boot loader format:
currently the syntax used by the \fBGrub1\fP configuration file is
supported.
All long options supported by boom may be written with or without
dashes separating words. For example, \fB--boot-id\fP and \fB--bootid\fP
are synonymous.
.SH OPTIONS
.
.HP
.BR -a | --add-opts
.IR opts
.br
Specify additional boot options for this entry.
.
.HP
.BR -d | --del-opts
.IR opts
.br
Specify boot options to exclude from this entry.
.
.HP
.BR -b | --boot-id | --bootid
.IR boot_id
.br
Specify a boot identifier to operate on.
.
.HP
.BR --boot-dir | --bootdir
.IR path
.br
Specify the location of the /boot file system. Useful for testing or
for accessing boom data from a system image.
.
.HP
.BR -B | --btrfs-subvolme | --btrfssubvolume
.RI [ subvol_path | subvol_id ]
.br
Specify a BTRFS subvolume by its path or identifier.
.br
.HP
.BR --btrfs-opts | --btrfsopts
.IR btrfs_options_template
.br
An OS profile template string for BTRFS boot options.
.
.HP
.BR --debug
.IR debug_flags
.br
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.
.
.HP
.BR -e | --efi
.IR efi_image
.br
Specify an EFI application image for a boot entry.
.
.HP
.BR -H | --from-host | --fromhost
.br
When creating a new OS profile, use \fIos-release\fP data from the
running host.
.
.HP
.BR -P | --host-profile
.br
Use the specified host profile for search or create operations.
.
.HP
.BR -i | --initrd
.IR image_path
.br
A Linux initial ramfs image path.
.
.HP
.BR -k | --kernel-pattern | --kernelpattern
.IR pattern
.br
An OS profile template used to generate kernel image paths.
.
.HP
.BR -l | --linux
.IR image_path
.br
A Linux kernel image path.
.
.HP
.BR -L | --root-lv | --rootlv
.IR root_lv
.br
The logical volume containing the root file system for a boot entry.
If \fB--root-lv\fP is given, but \fB--root-device\fP is not, the root
device is assumed to be the specified logical volume.
.
.HP
.BR --lvm-opts
.IR lvm_opts
.br
An OS profile template used to generate LVM2 boot options.
.
.HP
.BR -m | --machine-id | --machineid
.IR machine_id
.br
.
.HP
.BR -n | --name
.IR os_name
.br
The name of a boom operating system profile.
.
.HP
.BR --name-prefixes | --nameprefixes
.br
Add a prefix to report field output names.
.
.HP
.BR --no-headings | --noheadings
.br
Suppress output of report headings.
.
.HP
.BR -o | --options
.IR field_list
.br
Specify which fields to display.
.
.HP
.BR --os-version
.br
The version string of a boom operating system profile.
.
.HP
.BR -O | --sort
.IR key_list
.br
A comma-separated list of sort keys (field names), with an optional
per-field prefix of \fB+\fP or \fB-\fP to force ascending or
descending sort order respectively for that field.
.
.HP
.BR -I | --os-version-id | --osversionid
.IR os_version_id
.br
A boom operating system profile version identifier.
.
.HP
.BR --os-options | --osoptions
.IR options_template
.br
An operating system profile template string used to generate the
kernel command line options string.
.
.HP
.BR --os-release | --osrelease
.IR os_release_path
.br
A path to a file in \fIos-release(5)\fP from which to create a new
operating system profile.
.
.HP
.BR -p | --profile
.IR os_id
.br
The operating system identifier (\fIos_id\fP) of a boom operating
system profile to use for the current operation. Defaults to the
OS profile of the running system if absent.
.
.HP
.BR -r | --root-device | --rootdevice
.IR root_dev
.br
The system root device for a new boot entry.
.
.HP
.BR -R | --initramfs-pattern | --initramfspattern
.IR initramfs_pattern
.br
An OS profile template used to generate initial ramfs image paths.
.
.HP
.BR --rows
.br
Output report columns as rows.
.
.HP
.BR --separator
.IR separator
.br
Report field separator
.
.HP
.BR -s | --short-name | --shortname
.IR short_name
The short name of a boom operating system profile.
.
.HP
.BR -t | --title
.IR entry_title
.br
The title for a new boot entry.
.
.HP
.BR -u | --uname-pattern | --unamepattern
.IR uname_pattern
.br
An uname pattern to match for an operating system profile.
.
.HP
.BR -V | --verbose
.br
Increase verbosity level. Specify multiple times, or set additional
debug classed with \fB--debug\fP to enable more verbose messages.
.
.HP
.BR -v | --version
.IR version
.br
The kernel version of a boom boot entry.
.
.SH OS Profiles and Boot Entries
.
Boom manages boot loader entries for one or more installed operating
systems. Each operating system is identified by an \fBOS Profile\fP
that provides identity information and a set of templates used to
create boot loader entries.
An OS profile is identified by its \fBos_id\fP, 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 \fBBoot Entry\fP 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 \fBboot_id\fP. 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 \fBboot_id\fP will change if an
existing entry is modified (for e.g. with the \fBboom entry edit\fP
command).
.
.P
.B Host Profiles
.P
.
Host profiles provide an additional mechanism to control boot entry
templates on a per-host basis. A host profile is bound to a specific
\fBmachine_id\fP 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 \fBOS Profile\fP, or override specific BOS Profile keys
completely. Any keys not set in a host profile are mapped directly to
the original OS profile.
.
.P
.B Boot Entry Commands
.P
.
.HP
.B boom
.CMD_ENTRY_CREATE
.br
Create a new boot entry using the specified values.
The title of the new entry must be set with the \fB--title\fP option.
The kernel version for the new entry is given with \fB--version\fP.
If \fB--version\fP is not present the version is assumed to be that
of the currently running kernel.
If \fB--profile\fP is given, it specifies the OS identifier of an
existing OS profile to use for the new entry. If \fB--profile\fP is
not given, and a profile exists that matches either the supplied
or detected version then that profile will be automatically used.
The \fImachine-id\fP of the new entry is automatically set to the
current machine-id (read from /etc/machine-id) unless this is
overridden by the \fB--machine-id\fP switch.
A root device may be explicitly specified with the \fB--root-device\fP
option or if an LVM2 logical volume is used this may be specified
with \fB--root-lv\fP: 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 \fB--btrfs-subvol\fP option.
Additional boot options not defined by the corresponding \fBOsProfile\fP
templates may be specified with \fB--add-opts\fP. Options may also be
removed from the entry using \fB--del-opts\fP (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:
.br
#
.B boom create --title 'System Snapshot' --root-lv vg00/lvol0
.br
Created entry with boot_id 14d6b6e:
.br
title System Snapshot
.br
machine-id 611f38fd887d41dea7eb3403b2730a76
.br
version 4.13.5-200.fc26.x86_64
.br
linux /vmlinuz-4.13.5-200.fc26.x86_64
.br
initrd /initramfs-4.13.5-200.fc26.x86_64.img
.br
options BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64 root=/dev/vg00/lvol0 ro rd.lvm.lv=vg00/lvol0 rhgb quiet
.br
.
.HP
.B boom
.CMD_ENTRY_DELETE
.br
Delete the specified boot entry. The entry to delete may be specified
either by its \fBboot identifier\fP, 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 \fB--version\fP, 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 \fB--verbose\fP option is given then a report of the entries
removed will also be displayed.
.
.HP
.B boom
.CMD_ENTRY_CLONE
.br
Clone an existing boot entry and modify its configuration.
The entry to clone must be specified by its \fBboot identifier\fP.
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.
.
.HP
.B boom
.CMD_ENTRY_LIST
.br
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 \fB--options\fP as a
comma separated list of field names. To obtain a list of available
fields run '\fBboom list -o help\fP'. If the list of fields begins
with the '\fB+\fP' 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 \fB--sort\fP option. The option expects a comma separated list
of keys, with optional '\fB+\fP' and '\fB-\fP' prefixes indicating
ascending and descending sort for that field respectively.
.
.HP
.B boom
.CMD_ENTRY_SHOW
.br
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.
.
.P
.B OS Profile Commands
.P
.
.HP
.B boom
.CMD_PROFILE_CREATE
.br
Create a new OS profile using the specified values.
A new OS profile can be created either by specifying required values
on the \fBboom\fP command line, or by reading data from either the
hosts's \fIos-release\fP file (at /etc/os-release), or from another
file in \fIos-release\fP format specified on the command line.
The information read from \fIos-release\fP (or equivalent command line
options) form the profile's identity and are the basis for the profile
OS identifier.
In addition to the \fIos-release\fP 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 \fBprofile create\fP command
line and is a regular expression matching the UTS release
(\fBuname -r\fP) 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 \fBboom\fP 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 \fBboom\fP program at a later time.
To create a profile for the currently running host, use the
\fB--from-host\fP switch.
To create a profile from a saved \fIos-release\fP file use the
\fB--os-release\fP optiona and give the path to the file to be used.
.
.HP
.B boom
.CMD_PROFILE_DELETE
.br
Delete the specified Os profile or profiles.
Delete all OS profiles matching the provided selection criteria. If
the \fB--profile\fP 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 \fB--verbose\fP option is given then a report of the profiles
removed will also be displayed.
.
.HP
.B boom
.CMD_PROFILE_CLONE
.br
Clone an existing OS profile and modify its configuration.
The entry to clone must be specified by its \fBOS identifier\fP.
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.
.
.HP
.B boom
.CMD_PROFILE_LIST
.br
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 \fB--options\fP as a
comma separated list of field names. To obtain a list of available
fields run '\fBboom list -o help\fP'. If the list of fields begins
with the '\fB+\fP' 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 \fB--sort\fP option. The option expects a comma separated list
of keys, with optional '\fB+\fP' and '\fB-\fP' prefixes indicating
ascending and descending sort for that field respectively.
.
.HP
.B boom
.CMD_PROFILE_SHOW
.br
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.
.br
.
.P
.B Host Profile Commands
.P
.
.HP
.B boom
.CMD_HOST_CREATE
.br
Create a new host profile for the specified \fBmachine_id\fP and using
the given profile option arguments. Any \fBOS Profile\fP keys that are
given values will override the values in the underlying profile.
.
.HP
.B boom
.CMD_HOST_DELETE
.br
Delete the specified host profile or profiles.
Delete all host profiles matching the provided selection criteria. If
the \fB--host-profile\fP 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 \fB--verbose\fP option is given then a report of the profiles
removed will also be displayed.
.
.HP
.B boom
.CMD_HOST_CLONE
.br
Clone an existing host profile and modify its configuration.
The entry to clone must be specified by its \fBhost identifier\fP.
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.
.
.HP
.B boom
.CMD_HOST_EDIT
.br
Edit an existing host profile and modify its configuration.
The entry to edit must be specified by its \fBhost identifier\fP.
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.
.
.HP
.B boom
.CMD_HOST_LIST .
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 \fB--options\fP as a comma
separated list of field names. To obtain a list of available fields run
\&'\fBboom host list -o help\fP'. If the list of fields begins with the
\&'\fB+\fP' 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 \fB--sort\fP option. The option expects a comma separated list
of keys, with optional '\fB+\fP' and '\fB-\fP' prefixes indicating
ascending and descending sort for that field respectively.
.HP
.B boom
.CMD_HOST_SHOW
.br
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.
.SH 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 \fBboom.conf(5)\fP
configuration file.
.
.HP
.B boom
.CMD_LEGACY_WRITE
.br
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.
.
.HP
.B boom
.CMD_LEGACY_CLEAR
.br
Remove all Boom boot entries from the configured legacy
configuration file.
.
.HP
.B boom
.CMD_LEGACY_SHOW
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.
.SH 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.
.
.HP
.B boom
.CMD_CACHE_LIST
.br
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 \fB--options\fP as a comma
separated list of field names. To obtain a list of available fields run
'\fBboom host list -o help\fP'. If the list of fields begins with the
'\fB+\fP' 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 \fB--sort\fP option. The option expects a comma separated list
of keys, with optional '\fB+\fP' and '\fB-\fP' prefixes indicating
ascending and descending sort for that field respectively.
.
.HP
.B boom
.CMD_CACHE_SHOW
.br
Display matching cache entries on standard output.
Entries matching selection criteria are printed in a compact multi-line
format.
.
.SH REPORT FIELDS
.
The \fBboom\fP 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.
.
.SS Boot Parameters
.
Boot parameter fields represent the properties that distinguish
boot entries: the kernel version and root device configuration.
.TP
.B version
The kernel version of this Boot Entry.
.TP
.B rootdev
The root device of this Boot Entry.
.TP
.B rootlv
The root logical volume of this Boot Entry in 'VG/LV' notation.
.TP
.B subvolpath
The BTRFS subvolume path for this Boot Entry.
.TP
.B subvolid
The BTRFS subvolume ID for this BootEntry.
.
.SS 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.
.TP
.B bootid
Boot identifier.
.TP
.B title
The entry title as displayed in the boot loader.
.TP
.B options
The kernel command line options used to boot this entry.
.TP
.B kernel
The path to the bootable kernel image, relative to the boot loader.
.TP
.B initramfs
The path to the initramfs image, relative to the boot loader.
.TP
.B machineid
The machine-id associated with this Boot Entry.
.TP
.B entrypath
The absolute path to this Boot Entry's on-disk configuration file.
.
.SS 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.
.TP
.B osid
OS profile identifier.
.TP
.B osname
The name of this OS prorile as read from \fIos-release\fP.
.TP
.B osshortname
The short name of this OS profile as read from \fIos-release\fP.
.TP
.B osversion
The OS version of this OS profile as read from \fIos-release\fP.
.TP
.B osversion_id
The OS version identifier of this OS profile as read from
\fIos-release\fP.
.TP
.B unamepattern
The configured UTS release pattern for this OS profile.
.TP
.B kernelpattern
The configured kernel image template for this OS profile.
.TP
.B initrdpattern
The configured initramfs image template for this OS profile.
.TP
.B lvm2opts
The configured LVM2 root device options template for this OS profile.
.TP
.B btrfsopts
The configured BTRFS root options template for this OS profile.
.TP
.B options
The kernel command line options template for this OS profile.
.TP
.B profilepath
The absolute path to this OS Profile's on-disk configuration file.
.
.SS 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.
.TP
.B hostid
Host profile identifier.
.TP
.B hostname
The hostname of this host profile.
.TP
.B label
The label of this host profile.
.
.SS Cache Entry fields
.
Cache entry fields provide information on the paths and images
stored in the boom boot image cache.
.TP
.B imgid
Image identifier.
.TP
.B path
Path to the cached image, relative to the boot file system.
.TP
.B mode
Path file system mode in human-readable format.
.TP
.B uid
Image owner user identifier.
.TP
.B gid
Image owner group identifier.
.TP
.B ts
Image timestamp. The mtime of the image file at the time it was added
to the cache.
.TP
.B state
A string description of the cache entry state: \fBCACHED\fp,
\fBMISSING\fP, \fBRESTORED\fP, or \fBBROKEN\fp.
.TP
.B count
The number of boot entries that reference this boot image.
.
.SH REPORTING COMMANDS
Both the \fBentry list\fP and \fBprofile list\fP 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.
.P
Displaying the available boot entry fields
.br
#
.B boom list -o help
.br
Boot loader entries Fields
.br
--------------------------
.br
bootid - Boot identifier [sha]
.br
title - Entry title [str]
.br
options - Kernel options [str]
.br
kernel - Kernel image [str]
.br
initramfs - Initramfs image [str]
.br
machineid - Machine identifier [sha]
.br
entrypath - On-disk entry path [str]
.P
OS profiles Fields
.br
------------------
.br
osid - OS identifier [sha]
.br
osname - OS name [str]
.br
osshortname - OS short name [str]
.br
osversion - OS version [str]
.br
osversion_id - Version identifier [str]
.br
unamepattern - UTS name pattern [str]
.br
kernelpattern - Kernel image pattern [str]
.br
initrdpattern - Initrd pattern [str]
.br
lvm2opts - LVM2 options [str]
.br
btrfsopts - BTRFS options [str]
.br
options - Kernel options [str]
.br
profilepath - On-disk profile path [str]
.P
Boot parameters Fields
.br
----------------------
.br
version - Kernel version [str]
.br
rootdev - Root device [str]
.br
rootlv - Root logical volume [str]
.br
subvolpath - BTRFS subvolume path [str]
.br
subvolid - BTRFS subvolume ID [num]
.P
Displaying the available OS profile fields
.br
#
.B boom profile list -o help
.br
OS profiles Fields
.br
------------------
.br
osid - OS identifier [sha]
.br
osname - OS name [str]
.br
osshortname - OS short name [str]
.br
osversion - OS version [str]
.br
osversion_id - Version identifier [str]
.br
unamepattern - UTS name pattern [str]
.br
kernelpattern - Kernel image pattern [str]
.br
initrdpattern - Initrd pattern [str]
.br
lvm2opts - LVM2 options [str]
.br
btrfsopts - BTRFS options [str]
.br
options - Kernel options [str]
.br
profilepath - On-disk profile path [str]
.P
Selecting custom fields for the \fBentry list\fP and \fBprofile list\fP
commands
.br
#
.B boom list -o bootid,osname
.br
BootID Name
.br
0d3e547 Fedora
.br
bc18de2 Fedora
.br
576fe39 Fedora
.br
1838f58 Fedora
.br
81520ca Fedora
.br
327e24a Fedora
.P
Adding additional fields to the default set
.br
#
.B boom list -o +options
.br
BootID Version Name RootDevice Options
.br
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
.br
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
.br
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
.br
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
.br
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
.br
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
.P
Sort operating system profiles by ascending OS name and descending
OS version
.br
#
.B boom profile list -O+osname,-osversion
.br
OsID Name OsVersion
.br
d4439b7 Fedora 26 (Workstation Edition)
.br
9736c34 Fedora 25 (Server Edition)
.br
9cb53dd Fedora 24 (Workstation Edition)
.br
6bf746b Fedora 24 (Server Edition)
.br
b99ea5f Red Hat Enterprise Linux Server 8 (Server)
.br
3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
.br
c0b921e Red Hat Enterprise Linux Server 7 (Server)
.br
98c3edb Red Hat Enterprise Linux Server 6 (Server)
.br
b730331 Red Hat Enterprise Linux Server 5 (Server)
.br
efd6d41 Red Hat Enterprise Linux Server 4 (Server)
.br
21e37c8 Ubuntu 16.04 LTS (Xenial Xerus)
.P
.SH EXAMPLES
List the available operating system profiles
.br
#
.B boom profile list
.br
OsID Name OsVersion
.br
efd6d41 Red Hat Enterprise Linux Server 4 (Server)
.br
b730331 Red Hat Enterprise Linux Server 5 (Server)
.br
98c3edb Red Hat Enterprise Linux Server 6 (Server)
.br
c0b921e Red Hat Enterprise Linux Server 7 (Server)
.br
3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
.br
b99ea5f Red Hat Enterprise Linux Server 8 (Server)
.P
List the available boot entries
.br
#
.B boom list
.br
BootID Version Name RootDevice
.br
0d3e547 4.13.5-200.fc26.x86_64 Fedora /dev/mapper/vg00-lvol0
.br
bc18de2 4.13.5-200.fc26.x86_64 Fedora /dev/vg00/lvol0-snap10
.br
576fe39 4.13.5-200.fc26.x86_64 Fedora /dev/vg00/lvol0
.br
f52ba10 4.11.12-100.fc24.x86_64 Fedora /dev/vg00/lvol0-snap
.br
1838f58 4.13.5-200.fc26.x86_64 Fedora /dev/mapper/vg00-lvol0
.br
81520ca 4.13.13-200.fc26.x86_64 Fedora /dev/mapper/vg00-lvol0
.br
327e24a 4.13.5-200.fc26.x86_64 Fedora /dev/vg00/lvol0
.P
Create an OS profile for the running system (using Fedora 26 as an
example)
.br
#
.B boom profile create --from-host --uname-pattern fc26
.br
Created profile with os_id d4439b7:
.br
OS ID: "d4439b7d2f928c39f1160c0b0291407e5990b9e0",
.br
Name: "Fedora", Short name: "fedora",
.br
Version: "26 (Workstation Edition)", Version ID: "26",
.br
UTS release pattern: "fc26",
.br
Kernel pattern: "/kernel-%{version}", Initramfs pattern: "/initramfs-%{version}.img",
.br
Root options (LVM2): "rd.lvm.lv=%{lvm_root_lv}",
.br
Root options (BTRFS): "rootflags=%{btrfs_subvolume}",
.br
Options: "root=%{root_device} ro %{root_opts}"
.P
Create a new boot entry for a specific OS profile and version
.br
#
.B boom profile list --short-name rhel
.br
OsID Name OsVersion
.br
3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
.br
98c3edb Red Hat Enterprise Linux Server 6 (Server)
.br
c0b921e Red Hat Enterprise Linux Server 7 (Server)
.P
#
.B boom create --profile 3fc389b --title \(dqRHEL7 snapshot\(dq --version 3.10-272.el7 --root-lv vg00/lvol0-snap
.br
Created entry with boot_id a5aef11:
.br
title RHEL7 snapshot
.br
machine-id 611f38fd887d41dea7eb3403b2730a76
.br
version 3.10-272.el7
.br
linux /boot/vmlinuz-3.10-272.el7
.br
initrd /boot/initramfs-3.10-272.el7.img
.br
options root=/dev/vg00/lvol0-snap ro rd.lvm.lv=vg00/lvol0-snap rhgb quiet
.P
Create a new boot entry for the running system, changing only the root logical volume
.br
#
.B boom create --title Snap1 --root-lv vg00/lvol0-snap1
.br
Created entry with boot_id e077490:
.br
title Snap1
.br
machine-id 611f38fd887d41dea7eb3403b2730a76
.br
version 4.13.13-200.fc26.x86_64
.br
linux /vmlinuz-4.13.13-200.fc26.x86_64
.br
initrd /initramfs-4.13.13-200.fc26.x86_64.img
.br
options BOOT_IMAGE=/vmlinuz-4.13.13-200.fc26.x86_64 root=/dev/vg00/lvol0-snap1 ro rd.lvm.lv=vg00/lvol0-snap1
.P
Delete an entry by its boot identifier
.br
#
.B boom delete --boot-id e077490
.br
Deleted 1 entry
.P
Delete all entries for the Fedora 24 OS profile
.br
# boom delete --name Fedora --os-version-id 24
Deleted 4 entries
.P
.SH AUTHORS
.
Bryn M. Reeves <bmr@redhat.com>
.
.SH SEE ALSO
.
Boom project page: https://github.com/snapshotmanager/boom
.br
Boot to snapshot documentation: https://github.com/snapshotmanager/snapshot-boot-docs
.br
BootLoader Specification: https://systemd.io/BOOT_LOADER_SPECIFICATION
.br
LVM2 resource page: https://www.sourceware.org/lvm2/
.br
Device-mapper resource page: http://sources.redhat.com/dm/
.br