1BOOM(8)                      MAINTENANCE COMMANDS                      BOOM(8)
2
3
4

NAME

6       Boom — linux boot manager
7

SYNOPSIS

9       boom [entry|profile|host] [create|delete|clone|show|list|edit]
10
11       boom legacy [write|clear|show]
12
13       boom cache [list|show]
14
15       boom entry create [--profile os_id] [--version version] [--root-device
16              device] [--root-lv lv] [--linux kernel_path] [--initrd ini‐
17              trd_path] [--btrfs-subvol subvol] [--add-opts opts] [--del-opts
18              opts]
19       boom entry delete [boot_id] [--boot-id boot_id] [--profile os_id]
20              [--version version]
21       boom entry clone [boot_id] [--boot-id boot_id] [--profile os_id]
22              [--version version] [--root-device device] [--root-lv lv]
23              [--linux kernel_path] [--initrd initrd_path] [--btrfs-subvol
24              subvol] [--add-opts opts] [--del-opts opts]
25       boom entry list [boot_id] [--boot-id boot_id] [--profile os_id] [--ver‐
26              sion version] [--name osname] [--short-name osshortname] [--os-
27              version version] [--root-device device] [--root-lv lv] [--linux
28              kernel_path] [--initrd initrd_path] [--btrfs-subvol subvol]
29       boom entry show [boot_id] [--boot-id boot_id] [--profile os_id] [--ver‐
30              sion version] [--name osname] [--short-name osshortname] [--os-
31              version version] [--root-device device] [--root-lv lv] [--btrfs-
32              subvol subvol]
33
34       boom profile create [--name osname] [--short-name short_name] [--os-
35              version version] [--os-version-id version_id] [--from-host]
36              [--os-release os_release] [--uname-pattern uname_pattern]
37              [--lvm-opts lvm_opts] [--btrfs-opts btrfs_opts] [--os-options
38              os_options]
39       boom profile delete [profile_id] [--profile os_id] [--name osname]
40              [--short-name short_name] [--os-version version] [--os-version-
41              id version_id] [--from-host] [--os-release os_release] [--uname-
42              pattern uname_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
43              btrfs_opts] [--os-options os_options]
44       boom profile clone [profile_id] [--profile os_id] [--name osname]
45              [--short-name short_name] [--os-version version] [--os-version-
46              id version_id] [--from-host] [--os-release os_release] [--uname-
47              pattern uname_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
48              btrfs_opts] [--os-options os_options]
49       boom profile list [profile_id] [--profile os_id] [--version version]
50              [--name osname] [--short-name osshortname] [--os-version ver‐
51              sion]
52       boom profile show [profile_id] [--profile os_id] [--version version]
53              [--name osname] [--short-name osshortname] [--os-version ver‐
54              sion]
55
56       boom host create [--name name] [--short-name short_name] [--profile
57              os_id] [--machine-id machine_id] [--kernel-pattern kernel_pat‐
58              tern] [--initramfs-pattern initramfs_pattern] [--lvm-opts
59              lvm_opts] [--btrfs-opts btrfs_opts] [--os-options os_options]
60       boom host delete [host_id] [--host-profile host_id]
61       boom host clone [host_id] [--host-profile host_id] [--name name]
62              [--short-name short_name] [--profile os_id] [--machine-id
63              machine_id] [--kernel-pattern kernel_pattern] [--initramfs-pat‐
64              tern initramfs_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
65              btrfs_opts] [--os-options os_options]
66       boom host edit [host_id] [--host-profile host_id] [--name name]
67              [--short-name short_name] [--profile os_id] [--machine-id
68              machine_id] [--kernel-pattern kernel_pattern] [--initramfs-pat‐
69              tern initramfs_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
70              btrfs_opts] [--os-options os_options]
71       boom host list [host_id] [--host-profile host_id] [--name name]
72              [--short-name short_name] [--profile os_id] [--machine-id
73              machine_id] [--kernel-pattern kernel_pattern] [--initramfs-pat‐
74              tern initramfs_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
75              btrfs_opts] [--os-options os_options]
76       boom host show [profile_id] [--profile os_id] [--version version]
77              [--name osname] [--short-name osshortname] [--os-version ver‐
78              sion]
79
80       boom legacy write [boot_id] [--boot-id boot_id] [--profile os_id]
81              [--version version] [--name osname] [--short-name osshortname]
82              [--os-version version] [--root-device device] [--root-lv lv]
83              [--linux kernel_path] [--initrd initrd_path] [--btrfs-subvol
84              subvol]
85       boom legacy clear
86       boom legacy show [boot_id] [--boot-id boot_id] [--profile os_id]
87              [--version version] [--name osname] [--short-name osshortname]
88              [--os-version version] [--root-device device] [--root-lv lv]
89              [--linux kernel_path] [--initrd initrd_path] [--btrfs-subvol
90              subvol]
91
92       boom cache list [img_id] [--image img_id] [--linux kernel_path] [--ini‐
93              trd initrd_path]
94       boom cache show [img_id] [--image img_id] [--linux kernel_path] [--ini‐
95              trd initrd_path]
96
97

DESCRIPTION

99       Boom  is  a boot manager for Linux systems using boot loaders that sup‐
100       port the BootLoader Specification for boot entry configuration.
101
102       Boom works best with a BLS compatible boot loader: either the  systemd-
103       boot  project,  or  Grub2  with  the `bls` patch. The grub2 boot loader
104       included in CentOS, Fedora and Red Hat Enterprise  Linux  include  this
105       support.
106
107       Boom  also supports writing configuration in legacy boot loader format:
108       currently the syntax used by the Grub1 configuration file is supported.
109
110       All long options supported by boom  may  be  written  with  or  without
111       dashes  separating  words. For example, --boot-id and --bootid are syn‐
112       onymous.
113
114

OPTIONS

116       -a|--add-opts opts
117              Specify additional boot options for this entry.
118
119       -d|--del-opts opts
120              Specify boot options to exclude from this entry.
121
122       -b|--boot-id|--bootid boot_id
123              Specify a boot identifier to operate on.
124
125       --boot-dir|--bootdir path
126              Specify the location of the /boot file system. Useful for  test‐
127              ing or for accessing boom data from a system image.
128
129       -B|--btrfs-subvolme|--btrfssubvolume [subvol_path|subvol_id]
130              Specify a BTRFS subvolume by its path or identifier.
131
132       --btrfs-opts|--btrfsopts btrfs_options_template
133              An OS profile template string for BTRFS boot options.
134
135       --debug debug_flags
136              A  comma-separated  list  of subsystem names to enable debugging
137              output for, or 'all' to  enable  all  debugging.  The  available
138              debug classes are: profile, entry, command, report.
139
140       -e|--efi efi_image
141              Specify an EFI application image for a boot entry.
142
143       -H|--from-host|--fromhost
144              When  creating  a  new  OS profile, use os-release data from the
145              running host.
146
147       -P|--host-profile
148              Use the specified host profile for search or create operations.
149
150       -i|--initrd image_path
151              A Linux initial ramfs image path.
152
153       -k|--kernel-pattern|--kernelpattern pattern
154              An OS profile template used to generate kernel image paths.
155
156       -l|--linux image_path
157              A Linux kernel image path.
158
159       -L|--root-lv|--rootlv root_lv
160              The logical volume containing the root file system  for  a  boot
161              entry.   If  --root-lv  is  given, but --root-device is not, the
162              root device is assumed to be the specified logical volume.
163
164       --lvm-opts lvm_opts
165              An OS profile template used to generate LVM2 boot options.
166
167       -m|--machine-id|--machineid machine_id
168
169       -n|--name os_name
170              The name of a boom operating system profile.
171
172       --name-prefixes|--nameprefixes
173              Add a prefix to report field output names.
174
175       --no-headings|--noheadings
176              Suppress output of report headings.
177
178       -o|--options field_list
179              Specify which fields to display.
180
181       --os-version
182              The version string of a boom operating system profile.
183
184       -O|--sort key_list
185              A comma-separated list of  sort  keys  (field  names),  with  an
186              optional  per-field  prefix  of  +  or  -  to force ascending or
187              descending sort order respectively for that field.
188
189       -I|--os-version-id|--osversionid os_version_id
190              A boom operating system profile version identifier.
191
192       --os-options|--osoptions options_template
193              An operating system profile template string used to generate the
194              kernel command line options string.
195
196       --os-release|--osrelease os_release_path
197              A  path  to  a  file in os-release(5) from which to create a new
198              operating system profile.
199
200       -p|--profile os_id
201              The operating system identifier (os_id) of a boom operating sys‐
202              tem profile to use for the current operation. Defaults to the OS
203              profile of the running system if absent.
204
205       -r|--root-device|--rootdevice root_dev
206              The system root device for a new boot entry.
207
208       -R|--initramfs-pattern|--initramfspattern initramfs_pattern
209              An OS profile template used  to  generate  initial  ramfs  image
210              paths.
211
212       --rows
213              Output report columns as rows.
214
215       --separator separator
216              Report field separator
217
218       -s|--short-name|--shortname short_name The short name of a boom operat‐
219              ing system profile.
220
221       -t|--title entry_title
222              The title for a new boot entry.
223
224       -u|--uname-pattern|--unamepattern uname_pattern
225              An uname pattern to match for an operating system profile.
226
227       -V|--verbose
228              Increase verbosity level. Specify multiple times, or  set  addi‐
229              tional  debug  classed  with --debug to enable more verbose mes‐
230              sages.
231
232       -v|--version version
233              The kernel version of a boom boot entry.
234

OS Profiles and Boot Entries

236       Boom manages boot loader entries for one or  more  installed  operating
237       systems. Each operating system is identified by an OS Profile that pro‐
238       vides identity information and a set of templates used to  create  boot
239       loader entries.
240
241       An  OS profile is identified by its os_id, an alphanumeric string based
242       on an  SHA  digest  of  the  profile's  identity  fields.   Identifiers
243       reported  in  boom  command output are automatically abbreviated to the
244       minimum length required to ensure uniqueness and this short form may be
245       used in any place where a boom OS identifier is expected.
246
247       A Boot Entry represents one bootable instance of an installed operating
248       system: a kernel, optional initial ramfs image, command  line  options,
249       and other images or settings required for boot.
250
251       Each  boot  entry  is also identified by a SHA based unique identifier:
252       the boot_id. An entry's ID is used to select an entry for display, mod‐
253       ification, deletion or other operations.
254
255       Since  the boot entry's identifier is based on the boot parameters used
256       to create the entry, the boot_id will change if an  existing  entry  is
257       modified (for e.g. with the boom entry edit command).
258
259
260       Host Profiles
261
262       Host  profiles  provide  an  additional mechanism to control boot entry
263       templates on a per-host basis. A host profile is bound  to  a  specific
264       machine_id  and  is  used whenever new boot entries are created for the
265       corresponding host.
266
267       A host profile can add and delete boot options from the set supplied by
268       the  active  OS  Profile,  or  override  specific BOS Profile keys com‐
269       pletely. Any keys not set in a host profile are mapped directly to  the
270       original OS profile.
271
272
273       Boot Entry Commands
274
275       boom entry create [--profile os_id] [--version version] [--root-device
276              device] [--root-lv lv] [--linux kernel_path] [--initrd ini‐
277              trd_path] [--btrfs-subvol subvol] [--add-opts opts] [--del-opts
278              opts]
279              Create a new boot entry using the specified values.
280
281              The title of the new entry must be set with the --title option.
282
283              The kernel version for the new entry is  given  with  --version.
284              If --version is not present the version is assumed to be that of
285              the currently running kernel.
286
287              If --profile is given, it specifies  the  OS  identifier  of  an
288              existing  OS  profile  to use for the new entry. If --profile is
289              not given, and a profile exists that matches either the supplied
290              or  detected  version  then  that  profile will be automatically
291              used.
292
293              The machine-id of the new entry is automatically set to the cur‐
294              rent machine-id (read from /etc/machine-id) unless this is over‐
295              ridden by the --machine-id switch.
296
297              A root device may be explicitly specified with the --root-device
298              option  or  if an LVM2 logical volume is used this may be speci‐
299              fied with --root-lv: in this case the root device is assumed  to
300              be the normal device path of the specified logical volume.
301
302              A  BTRFS  subvolume  may  be set by either the subvolume path or
303              subvolume identifier using the --btrfs-subvol option.
304
305              Additional boot options not defined by the corresponding  OsPro‐
306              file  templates  may  be  specified with --add-opts. Options may
307              also be removed from the entry using --del-opts (for example  to
308              disable  graphical  boot  or  the  "quiet" flag for a particular
309              entry).
310
311              The newly created entry and its boot identifier are  printed  to
312              the terminal on success:
313              # boom create --title 'System Snapshot' --root-lv vg00/lvol0
314              Created entry with boot_id 14d6b6e:
315                title System Snapshot
316                machine-id 611f38fd887d41dea7eb3403b2730a76
317                version 4.13.5-200.fc26.x86_64
318                linux /vmlinuz-4.13.5-200.fc26.x86_64
319                initrd /initramfs-4.13.5-200.fc26.x86_64.img
320                options             BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64
321              root=/dev/vg00/lvol0 ro rd.lvm.lv=vg00/lvol0 rhgb quiet
322
323       boom entry delete [boot_id] [--boot-id boot_id] [--profile os_id]
324              [--version version]
325              Delete  the  specified  boot  entry.  The entry to delete may be
326              specified either by its boot identifier, in which case  at  most
327              one  entry  will be removed, or by specifying selection criteria
328              which may match (and remove) multiple entries in a single opera‐
329              tion.
330
331              For example, by giving --version, all entries matching the spec‐
332              ified kernel version can be removed at once.
333
334              On success the number of entries removed is printed to the  ter‐
335              minal.   If  the  --verbose option is given then a report of the
336              entries removed will also be displayed.
337
338       boom entry clone [boot_id] [--boot-id boot_id] [--profile os_id]
339              [--version version] [--root-device device] [--root-lv lv]
340              [--linux kernel_path] [--initrd initrd_path] [--btrfs-subvol
341              subvol] [--add-opts opts] [--del-opts opts]
342              Clone an existing boot entry and modify its configuration.
343
344              The  entry  to  clone  must be specified by its boot identifier.
345              Any remaining command line arguments are taken to  be  modifica‐
346              tions to the original entry.
347
348              On  success the new entry and its boot identifier are printed to
349              the terminal.
350
351       boom entry list [boot_id] [--boot-id boot_id] [--profile os_id] [--ver‐
352              sion version] [--name osname] [--short-name osshortname] [--os-
353              version version] [--root-device device] [--root-lv lv] [--linux
354              kernel_path] [--initrd initrd_path] [--btrfs-subvol subvol]
355              Output a tabular report of boot entries.
356
357              Displays  a  report  with  one  boot  entry per line, containing
358              fields describing the properties of the configured boot entries.
359
360              The list of fields to display is given with --options as a comma
361              separated  list  of  field  names. To obtain a list of available
362              fields run 'boom list -o help'. If the  list  of  fields  begins
363              with  the '+' character the specified fields are appended to the
364              default field list. Otherwise the given list of fields  replaces
365              the default set of report fields.
366
367              Report  output may be sorted by multiple user-defined keys using
368              the --sort option. The option expects a comma separated list  of
369              keys,  with  optional  '+' and '-' prefixes indicating ascending
370              and descending sort for that field respectively.
371
372       boom entry show [boot_id] [--boot-id boot_id] [--profile os_id] [--ver‐
373              sion version] [--name osname] [--short-name osshortname] [--os-
374              version version] [--root-device device] [--root-lv lv] [--btrfs-
375              subvol subvol]
376              Display  boot  entries  matching  selection criteria on standard
377              out.
378
379              Boot entries matching the criteria given on the command line are
380              printed to the terminal in boot loader entry format.
381
382       OS Profile Commands
383
384       boom profile create [--name osname] [--short-name short_name] [--os-
385              version version] [--os-version-id version_id] [--from-host]
386              [--os-release os_release] [--uname-pattern uname_pattern]
387              [--lvm-opts lvm_opts] [--btrfs-opts btrfs_opts] [--os-options
388              os_options]
389              Create a new OS profile using the specified values.
390
391              A  new  OS  profile can be created either by specifying required
392              values on the boom command line, or by reading data from  either
393              the  hosts's  os-release  file  (at  /etc/os-release),  or  from
394              another file in os-release format specified on the command line.
395
396              The information read from os-release (or equivalent command line
397              options)  form  the profile's identity and are the basis for the
398              profile OS identifier.
399
400              In addition to the os-release data a new OS profile  requires  a
401              uname  version string pattern to match, and template values used
402              to construct boot entries.
403
404              The uname pattern must be given on the  profile  create  command
405              line and is a regular expression matching the UTS release (uname
406              -r) values reported by that distribution. The  pattern  is  only
407              used to attempt to match unknown boot entries to a valid OS pro‐
408              file: for example entries that have  been  manually  edited,  or
409              that were created by another tool.
410
411              The  boom  command  provides default templates that are suitable
412              for most Linux distributions. Alternately, these values  may  be
413              set on the command line at the time of profile creation, or mod‐
414              ified using the boom program at a later time.
415
416              To create a profile for the  currently  running  host,  use  the
417              --from-host switch.
418
419              To  create  a profile from a saved os-release file use the --os-
420              release optiona and give the path to the file to be used.
421
422       boom profile delete [profile_id] [--profile os_id] [--name osname]
423              [--short-name short_name] [--os-version version] [--os-version-
424              id version_id] [--from-host] [--os-release os_release] [--uname-
425              pattern uname_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
426              btrfs_opts] [--os-options os_options]
427              Delete the specified Os profile or profiles.
428
429              Delete all OS profiles matching the provided selection criteria.
430              If the --profile option is used to specify an OS identifier then
431              at most one profile will be removed.
432
433              On success the number of profiles removed is printed to the ter‐
434              minal.   If  the  --verbose option is given then a report of the
435              profiles removed will also be displayed.
436
437       boom profile clone [profile_id] [--profile os_id] [--name osname]
438              [--short-name short_name] [--os-version version] [--os-version-
439              id version_id] [--from-host] [--os-release os_release] [--uname-
440              pattern uname_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
441              btrfs_opts] [--os-options os_options]
442              Clone an existing OS profile and modify its configuration.
443
444              The entry to clone must be specified by its OS identifier.   Any
445              remaining  command  line arguments are taken to be modifications
446              to the original entry.
447
448              On success the new entry and its OS identifier  are  printed  to
449              the terminal.
450
451       boom profile list [profile_id] [--profile os_id] [--version version]
452              [--name osname] [--short-name osshortname] [--os-version ver‐
453              sion]
454              Output a tabular report of OS profiles.
455
456              Displays  a  report  with  one  OS  profile per line, containing
457              fields describing the properties of the configured OS profiles.
458
459              The list of fields to display is given with --options as a comma
460              separated  list  of  field  names. To obtain a list of available
461              fields run 'boom list -o help'. If the  list  of  fields  begins
462              with  the '+' character the specified fields are appended to the
463              default field list. Otherwise the given list of fields  replaces
464              the default set of report fields.
465
466              Report  output may be sorted by multiple user-defined keys using
467              the --sort option. The option expects a comma separated list  of
468              keys,  with  optional  '+' and '-' prefixes indicating ascending
469              and descending sort for that field respectively.
470
471       boom profile show [profile_id] [--profile os_id] [--version version]
472              [--name osname] [--short-name osshortname] [--os-version ver‐
473              sion]
474              Display OS profiles matching selection criteria on standard out.
475
476              OS profiles matching the criteria given on the command line  are
477              printed to the terminal in a compact multi-line format.
478
479       Host Profile Commands
480
481       boom host create [--name name] [--short-name short_name] [--profile
482              os_id] [--machine-id machine_id] [--kernel-pattern kernel_pat‐
483              tern] [--initramfs-pattern initramfs_pattern] [--lvm-opts
484              lvm_opts] [--btrfs-opts btrfs_opts] [--os-options os_options]
485              Create a new host profile for the specified machine_id and using
486              the given profile option arguments. Any OS Profile keys that are
487              given values will override the values in the underlying profile.
488
489       boom host delete [host_id] [--host-profile host_id]
490              Delete the specified host profile or profiles.
491
492              Delete all host profiles matching the provided selection  crite‐
493              ria.  If  the  --host-profile  option is used to specify an host
494              identifier then at most one profile will be removed.
495
496              On success the number of profiles removed is printed to the ter‐
497              minal.   If  the  --verbose option is given then a report of the
498              profiles removed will also be displayed.
499
500       boom host clone [host_id] [--host-profile host_id] [--name name]
501              [--short-name short_name] [--profile os_id] [--machine-id
502              machine_id] [--kernel-pattern kernel_pattern] [--initramfs-pat‐
503              tern initramfs_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
504              btrfs_opts] [--os-options os_options]
505              Clone an existing host profile and modify its configuration.
506
507              The entry to clone must be specified  by  its  host  identifier.
508              Any  remaining  command line arguments are taken to be modifica‐
509              tions to the original entry.
510
511              On success the new entry and its host identifier are printed  to
512              the terminal.
513
514       boom host edit [host_id] [--host-profile host_id] [--name name]
515              [--short-name short_name] [--profile os_id] [--machine-id
516              machine_id] [--kernel-pattern kernel_pattern] [--initramfs-pat‐
517              tern initramfs_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
518              btrfs_opts] [--os-options os_options]
519              Edit an existing host profile and modify its configuration.
520
521              The entry to edit must be specified by its host identifier.  Any
522              remaining command line arguments are taken to  be  modifications
523              to the original profile.
524
525              On  success  the new profile and its host identifier are printed
526              to the terminal.
527
528       boom host list [host_id] [--host-profile host_id] [--name name]
529              [--short-name short_name] [--profile os_id] [--machine-id
530              machine_id] [--kernel-pattern kernel_pattern] [--initramfs-pat‐
531              tern initramfs_pattern] [--lvm-opts lvm_opts] [--btrfs-opts
532              btrfs_opts] [--os-options os_options] Output a tabular report of
533              host profiles.
534
535              Displays  a  report  with  one host profile per line, containing
536              fields describing the properties of  the  configured  host  pro‐
537              files.
538
539              The list of fields to display is given with --options as a comma
540              separated list of field names. To obtain  a  list  of  available
541              fields  run  'boom  host  list  -o  help'. If the list of fields
542              begins with the '+' character the specified fields are  appended
543              to  the  default  field list. Otherwise the given list of fields
544              replaces the default set of report fields.
545
546              Report output may be sorted by multiple user-defined keys  using
547              the  --sort option. The option expects a comma separated list of
548              keys, with optional '+' and '-'  prefixes  indicating  ascending
549              and descending sort for that field respectively.
550
551       boom host show [profile_id] [--profile os_id] [--version version]
552              [--name osname] [--short-name osshortname] [--os-version ver‐
553              sion]
554              Display  host  profiles  matching selection criteria on standard
555              out.
556
557              Host profiles matching the criteria given on  the  command  line
558              are printed to the terminal in a compact multi-line format.
559
560

LEGACY BOOTLOADER FORMATS

562       Boom is able to write the current set of boot entries into the configu‐
563       ration file of a legacy boot loader installed on the system.  This  may
564       be  used  either on platforms that do not have a native bootloader sup‐
565       porting the Boot Loader Specification, or to allow upgrades and  recov‐
566       ery  from an installation lacking BLS support (if the system is updated
567       to a distribution that does support the BLS boot  loader  configuration
568       it will be used automatically when present).
569
570       Legacy  support is enabled and configured via the boom.conf(5) configu‐
571       ration file.
572
573       boom legacy write [boot_id] [--boot-id boot_id] [--profile os_id]
574              [--version version] [--name osname] [--short-name osshortname]
575              [--os-version version] [--root-device device] [--root-lv lv]
576              [--linux kernel_path] [--initrd initrd_path] [--btrfs-subvol
577              subvol]
578              Write out the current set of Boom boot entries in the configured
579              legacy  configuration  file.  The  normal command line selection
580              options may be used to control the set of entries written to the
581              file.
582
583       boom legacy clear
584              Remove all Boom boot entries from the configured legacy configu‐
585              ration file.
586
587       boom legacy show [boot_id] [--boot-id boot_id] [--profile os_id]
588              [--version version] [--name osname] [--short-name osshortname]
589              [--os-version version] [--root-device device] [--root-lv lv]
590              [--linux kernel_path] [--initrd initrd_path] [--btrfs-subvol
591              subvol] Display the selected boot entries as they  would  appear
592              in  the configured legacy boot loader format. The normal command
593              line selection options may be used to control the set of entries
594              written to the terminal.
595
596

BOOT IMAGE CACHE

598       Boom  can optionally cache or back up the images used by a boom BootEn‐
599       try. This allows an entry to be booted in the case  that  a  subsequent
600       update  has removed the original kernel and initramfs images and can be
601       used to recover an earlier system state from a snapshot following  even
602       major operating system updates.
603
604       boom cache list [img_id] [--image img_id] [--linux kernel_path] [--ini‐
605              trd initrd_path]
606              Output a tabular report of  paths  present  in  the  boot  image
607              cache.
608
609              Displays  a  report  with  one  cache entry per line, containing
610              fields describing the properties of the cache entry.
611
612              The list of fields to display is given with --options as a comma
613              separated  list  of  field  names. To obtain a list of available
614              fields run field  list.  Otherwise  the  given  list  of  fields
615              replaces the default set of report fields.
616
617              Report  output may be sorted by multiple user-defined keys using
618              the --sort option. The option expects a comma separated list  of
619              keys,  with  optional  '+' and '-' prefixes indicating ascending
620              and descending sort for that field respectively.
621
622       boom cache show [img_id] [--image img_id] [--linux kernel_path] [--ini‐
623              trd initrd_path]
624              Display matching cache entries on standard output.
625
626              Entries  matching  selection  criteria  are printed in a compact
627              multi-line format.
628

REPORT FIELDS

630       The boom report provides several types of field that may  be  added  to
631       the  default  field set for either Boot Entry or OS Profile reports, or
632       used to create custom reports.
633
634   Boot Parameters
635       Boot parameter fields represent the properties  that  distinguish  boot
636       entries: the kernel version and root device configuration.
637
638       version
639              The kernel version of this Boot Entry.
640
641       rootdev
642              The root device of this Boot Entry.
643
644       rootlv The root logical volume of this Boot Entry in 'VG/LV' notation.
645
646       subvolpath
647              The BTRFS subvolume path for this Boot Entry.
648
649       subvolid
650              The BTRFS subvolume ID for this BootEntry.
651
652   Boot Entry fields
653       Boot  Entry  fields provide information about an entry not specified by
654       its Boot Parameters, including the title, boot identifier,  boot  image
655       locations, and options required to boot the entry.
656
657       bootid Boot identifier.
658
659       title  The entry title as displayed in the boot loader.
660
661       options
662              The kernel command line options used to boot this entry.
663
664       kernel The  path  to  the  bootable  kernel image, relative to the boot
665              loader.
666
667       initramfs
668              The path to the initramfs image, relative to the boot loader.
669
670       machineid
671              The machine-id associated with this Boot Entry.
672
673       entrypath
674              The absolute path to this  Boot  Entry's  on-disk  configuration
675              file.
676
677   OS Profile fields
678       OS Profile fields provide access to the details of a profile's configu‐
679       ration including identity fields and the template strings used to  gen‐
680       erate entries.
681
682       Since each Boot Entry has an attached OS Profile all profile fields are
683       also available to add to any Boot Entry report.
684
685       osid   OS profile identifier.
686
687       osname The name of this OS prorile as read from os-release.
688
689       osshortname
690              The short name of this OS profile as read from os-release.
691
692       osversion
693              The OS version of this OS profile as read from  os-release.
694
695       osversion_id
696              The OS version identifier of this OS profile as  read  from  os-
697              release.
698
699       unamepattern
700              The configured UTS release pattern for this OS profile.
701
702       kernelpattern
703              The configured kernel image template for this OS profile.
704
705       initrdpattern
706              The configured initramfs image template for this OS profile.
707
708       lvm2opts
709              The  configured  LVM2  root  device options template for this OS
710              profile.
711
712       btrfsopts
713              The configured BTRFS root options template for this OS profile.
714
715       options
716              The kernel command line options template for this OS profile.
717
718       profilepath
719              The absolute path to this  OS  Profile's  on-disk  configuration
720              file.
721
722   Host Profile fields
723       Host  Profile  fields provide access to the details of a profile's con‐
724       figuration including identity fields and the template strings  used  to
725       generate  entries. This includes all fields available in the OS Profile
726       report as well as additional Host Profile identity fields.
727
728       hostid Host profile identifier.
729
730       hostname
731              The hostname of this host profile.
732
733       label  The label of this host profile.
734
735   Cache Entry fields
736       Cache entry fields provide information on the paths and  images  stored
737       in the boom boot image cache.
738
739       imgid  Image identifier.
740
741       path   Path to the cached image, relative to the boot file system.
742
743       mode   Path file system mode in human-readable format.
744
745       uid    Image owner user identifier.
746
747       gid    Image owner group identifier.
748
749       ts     Image  timestamp. The mtime of the image file at the time it was
750              added to the cache.
751
752       state  A string description of the cache entry state: CACHED,  MISSING,
753              RESTORED, or BROKEN.
754
755       count  The number of boot entries that reference this boot image.
756

REPORTING COMMANDS

758       Both  the  entry  list and profile list commands use a common reporting
759       system to display the results of the query. The  selection  of  fields,
760       and the order in which they are displayed, may be controlled to produce
761       custom report formats.
762
763       Displaying the available boot entry fields
764       # boom list -o help
765       Boot loader entries Fields
766       --------------------------
767         bootid        - Boot identifier [sha]
768         title         - Entry title [str]
769         options       - Kernel options [str]
770         kernel        - Kernel image [str]
771         initramfs     - Initramfs image [str]
772         machineid     - Machine identifier [sha]
773         entrypath     - On-disk entry path [str]
774
775       OS profiles Fields
776       ------------------
777         osid          - OS identifier [sha]
778         osname        - OS name [str]
779         osshortname   - OS short name [str]
780         osversion     - OS version [str]
781         osversion_id  - Version identifier [str]
782         unamepattern  - UTS name pattern [str]
783         kernelpattern - Kernel image pattern [str]
784         initrdpattern - Initrd pattern [str]
785         lvm2opts      - LVM2 options [str]
786         btrfsopts     - BTRFS options [str]
787         options       - Kernel options [str]
788         profilepath   - On-disk profile path [str]
789
790       Boot parameters Fields
791       ----------------------
792         version       - Kernel version [str]
793         rootdev       - Root device [str]
794         rootlv        - Root logical volume [str]
795         subvolpath    - BTRFS subvolume path [str]
796         subvolid      - BTRFS subvolume ID [num]
797
798       Displaying the available OS profile fields
799       # boom profile list -o help
800       OS profiles Fields
801       ------------------
802         osid          - OS identifier [sha]
803         osname        - OS name [str]
804         osshortname   - OS short name [str]
805         osversion     - OS version [str]
806         osversion_id  - Version identifier [str]
807         unamepattern  - UTS name pattern [str]
808         kernelpattern - Kernel image pattern [str]
809         initrdpattern - Initrd pattern [str]
810         lvm2opts      - LVM2 options [str]
811         btrfsopts     - BTRFS options [str]
812         options       - Kernel options [str]
813         profilepath   - On-disk profile path [str]
814
815       Selecting custom fields for the entry list and profile list commands
816       # boom list -o bootid,osname
817       BootID  Name
818       0d3e547 Fedora
819       bc18de2 Fedora
820       576fe39 Fedora
821       1838f58 Fedora
822       81520ca Fedora
823       327e24a Fedora
824
825       Adding additional fields to the default set
826       # boom list -o +options
827       BootID   Version                   Name                      RootDevice
828       Options
829       0d3e547   4.13.5-200.fc26.x86_64    Fedora                    /dev/map‐
830       per/vg_hex-root             BOOT_IMAGE=/vmlinuz-4.11.12-100.fc24.x86_64
831       root=/dev/mapper/vg_hex-root   ro   rd.lvm.lv=vg_hex/root   rhgb  quiet
832       rd.auto=1
833       bc18de2                 4.13.5-200.fc26.x86_64                   Fedora
834       /dev/vg_hex/root-snap10      BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64
835       root=/dev/vg_hex/root-snap10 ro rd.lvm.lv=vg_hex/root-snap10
836       576fe39                 4.13.5-200.fc26.x86_64                   Fedora
837       /dev/vg_hex/root             BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64
838       root=/dev/vg_hex/root ro rd.lvm.lv=vg_hex/root
839       1838f58  4.13.5-200.fc26.x86_64    Fedora                     /dev/map‐
840       per/vg_hex-root             BOOT_IMAGE=/vmlinuz-4.11.12-100.fc24.x86_64
841       root=/dev/mapper/vg_hex-root ro rd.lvm.lv=vg_hex/root rhgb quiet
842       81520ca  4.13.13-200.fc26.x86_64   Fedora                     /dev/map‐
843       per/vg_hex-root              BOOT_IMAGE=/vmlinuz-4.13.5-200.fc26.x86_64
844       root=/dev/mapper/vg_hex-root  ro   rd.lvm.lv=vg_hex/root   rhgb   quiet
845       LANG=en_GB.UTF-8
846       327e24a                 4.13.5-200.fc26.x86_64                   Fedora
847       /dev/vg_hex/root         BOOT_IMAGE=%{linux}  root=/dev/vg_hex/root  ro
848       rd.lvm.lv=vg_hex/root
849
850       Sort  operating  system profiles by ascending OS name and descending OS
851       version
852       # boom profile list -O+osname,-osversion
853       OsID    Name                            OsVersion
854       d4439b7 Fedora                          26 (Workstation Edition)
855       9736c34 Fedora                          25 (Server Edition)
856       9cb53dd Fedora                          24 (Workstation Edition)
857       6bf746b Fedora                          24 (Server Edition)
858       b99ea5f Red Hat Enterprise Linux Server 8 (Server)
859       3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
860       c0b921e Red Hat Enterprise Linux Server 7 (Server)
861       98c3edb Red Hat Enterprise Linux Server 6 (Server)
862       b730331 Red Hat Enterprise Linux Server 5 (Server)
863       efd6d41 Red Hat Enterprise Linux Server 4 (Server)
864       21e37c8 Ubuntu                          16.04 LTS (Xenial Xerus)
865

EXAMPLES

867       List the available operating system profiles
868       # boom profile list
869       OsID    Name                            OsVersion
870       efd6d41 Red Hat Enterprise Linux Server 4 (Server)
871       b730331 Red Hat Enterprise Linux Server 5 (Server)
872       98c3edb Red Hat Enterprise Linux Server 6 (Server)
873       c0b921e Red Hat Enterprise Linux Server 7 (Server)
874       3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
875       b99ea5f Red Hat Enterprise Linux Server 8 (Server)
876
877       List the available boot entries
878       # boom list
879       BootID  Version                  Name                     RootDevice
880       0d3e547  4.13.5-200.fc26.x86_64    Fedora                     /dev/map‐
881       per/vg00-lvol0
882       bc18de2                 4.13.5-200.fc26.x86_64                   Fedora
883       /dev/vg00/lvol0-snap10
884       576fe39                 4.13.5-200.fc26.x86_64                   Fedora
885       /dev/vg00/lvol0
886       f52ba10                 4.11.12-100.fc24.x86_64                  Fedora
887       /dev/vg00/lvol0-snap
888       1838f58  4.13.5-200.fc26.x86_64    Fedora                     /dev/map‐
889       per/vg00-lvol0
890       81520ca   4.13.13-200.fc26.x86_64   Fedora                    /dev/map‐
891       per/vg00-lvol0
892       327e24a                 4.13.5-200.fc26.x86_64                   Fedora
893       /dev/vg00/lvol0
894
895       Create  an  OS  profile  for  the running system (using Fedora 26 as an
896       example)
897       # boom profile create --from-host --uname-pattern fc26
898       Created profile with os_id d4439b7:
899         OS ID: "d4439b7d2f928c39f1160c0b0291407e5990b9e0",
900         Name: "Fedora", Short name: "fedora",
901         Version: "26 (Workstation Edition)", Version ID: "26",
902         UTS release pattern: "fc26",
903         Kernel    pattern:    "/kernel-%{version}",    Initramfs     pattern:
904       "/initramfs-%{version}.img",
905         Root options (LVM2): "rd.lvm.lv=%{lvm_root_lv}",
906         Root options (BTRFS): "rootflags=%{btrfs_subvolume}",
907         Options: "root=%{root_device} ro %{root_opts}"
908
909       Create a new boot entry for a specific OS profile and version
910       # boom profile list --short-name rhel
911       OsID    Name                            OsVersion
912       3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo)
913       98c3edb Red Hat Enterprise Linux Server 6 (Server)
914       c0b921e Red Hat Enterprise Linux Server 7 (Server)
915
916       #  boom  create  --profile  3fc389b  --title "RHEL7 snapshot" --version
917       3.10-272.el7 --root-lv vg00/lvol0-snap
918       Created entry with boot_id a5aef11:
919       title RHEL7 snapshot
920       machine-id 611f38fd887d41dea7eb3403b2730a76
921       version 3.10-272.el7
922       linux /boot/vmlinuz-3.10-272.el7
923       initrd /boot/initramfs-3.10-272.el7.img
924       options  root=/dev/vg00/lvol0-snap  ro  rd.lvm.lv=vg00/lvol0-snap  rhgb
925       quiet
926
927       Create  a new boot entry for the running system, changing only the root
928       logical volume
929       # boom create --title Snap1 --root-lv vg00/lvol0-snap1
930       Created entry with boot_id e077490:
931         title Snap1
932         machine-id 611f38fd887d41dea7eb3403b2730a76
933         version 4.13.13-200.fc26.x86_64
934         linux /vmlinuz-4.13.13-200.fc26.x86_64
935         initrd /initramfs-4.13.13-200.fc26.x86_64.img
936         options                   BOOT_IMAGE=/vmlinuz-4.13.13-200.fc26.x86_64
937       root=/dev/vg00/lvol0-snap1 ro rd.lvm.lv=vg00/lvol0-snap1
938
939       Delete an entry by its boot identifier
940       # boom delete --boot-id e077490
941       Deleted 1 entry
942
943       Delete all entries for the Fedora 24 OS profile
944       # boom delete --name Fedora --os-version-id 24 Deleted 4 entries
945

AUTHORS

947       Bryn M. Reeves <bmr@redhat.com>
948

SEE ALSO

950       Boom project page: https://github.com/snapshotmanager/boom
951       Boot   to   snapshot   documentation:   https://github.com/snapshotman
952       ager/snapshot-boot-docs
953       BootLoader Specification: https://systemd.io/BOOT_LOADER_SPECIFICATION
954       LVM2 resource page: https://www.sourceware.org/lvm2/
955       Device-mapper resource page: http://sources.redhat.com/dm/
956
957
958
959Linux                             Oct 30 2017                          BOOM(8)
Impressum