Metadata-Version: 2.1
Name: boom_boot
Version: 1.6.5
Summary: The Boom Boot Manager
Home-page: https://github.com/snapshotmanager/boom
Author: Bryn M. Reeves
Author-email: "Bryn M. Reeves" <bmr@redhat.com>
License: 		    GNU GENERAL PUBLIC LICENSE
        		       Version 2, June 1991
        
         Copyright (C) 1989, 1991 Free Software Foundation, Inc.
         51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
         Everyone is permitted to copy and distribute verbatim copies
         of this license document, but changing it is not allowed.
        
        			    Preamble
        
          The licenses for most software are designed to take away your
        freedom to share and change it.  By contrast, the GNU General Public
        License is intended to guarantee your freedom to share and change free
        software--to make sure the software is free for all its users.  This
        General Public License applies to most of the Free Software
        Foundation's software and to any other program whose authors commit to
        using it.  (Some other Free Software Foundation software is covered by
        the GNU Library General Public License instead.)  You can apply it to
        your programs, too.
        
          When we speak of free software, we are referring to freedom, not
        price.  Our General Public Licenses are designed to make sure that you
        have the freedom to distribute copies of free software (and charge for
        this service if you wish), that you receive source code or can get it
        if you want it, that you can change the software or use pieces of it
        in new free programs; and that you know you can do these things.
        
          To protect your rights, we need to make restrictions that forbid
        anyone to deny you these rights or to ask you to surrender the rights.
        These restrictions translate to certain responsibilities for you if you
        distribute copies of the software, or if you modify it.
        
          For example, if you distribute copies of such a program, whether
        gratis or for a fee, you must give the recipients all the rights that
        you have.  You must make sure that they, too, receive or can get the
        source code.  And you must show them these terms so they know their
        rights.
        
          We protect your rights with two steps: (1) copyright the software, and
        (2) offer you this license which gives you legal permission to copy,
        distribute and/or modify the software.
        
          Also, for each author's protection and ours, we want to make certain
        that everyone understands that there is no warranty for this free
        software.  If the software is modified by someone else and passed on, we
        want its recipients to know that what they have is not the original, so
        that any problems introduced by others will not reflect on the original
        authors' reputations.
        
          Finally, any free program is threatened constantly by software
        patents.  We wish to avoid the danger that redistributors of a free
        program will individually obtain patent licenses, in effect making the
        program proprietary.  To prevent this, we have made it clear that any
        patent must be licensed for everyone's free use or not licensed at all.
        
          The precise terms and conditions for copying, distribution and
        modification follow.
        
        		    GNU GENERAL PUBLIC LICENSE
           TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
        
          0. This License applies to any program or other work which contains
        a notice placed by the copyright holder saying it may be distributed
        under the terms of this General Public License.  The "Program", below,
        refers to any such program or work, and a "work based on the Program"
        means either the Program or any derivative work under copyright law:
        that is to say, a work containing the Program or a portion of it,
        either verbatim or with modifications and/or translated into another
        language.  (Hereinafter, translation is included without limitation in
        the term "modification".)  Each licensee is addressed as "you".
        
        Activities other than copying, distribution and modification are not
        covered by this License; they are outside its scope.  The act of
        running the Program is not restricted, and the output from the Program
        is covered only if its contents constitute a work based on the
        Program (independent of having been made by running the Program).
        Whether that is true depends on what the Program does.
        
          1. You may copy and distribute verbatim copies of the Program's
        source code as you receive it, in any medium, provided that you
        conspicuously and appropriately publish on each copy an appropriate
        copyright notice and disclaimer of warranty; keep intact all the
        notices that refer to this License and to the absence of any warranty;
        and give any other recipients of the Program a copy of this License
        along with the Program.
        
        You may charge a fee for the physical act of transferring a copy, and
        you may at your option offer warranty protection in exchange for a fee.
        
          2. You may modify your copy or copies of the Program or any portion
        of it, thus forming a work based on the Program, and copy and
        distribute such modifications or work under the terms of Section 1
        above, provided that you also meet all of these conditions:
        
            a) You must cause the modified files to carry prominent notices
            stating that you changed the files and the date of any change.
        
            b) You must cause any work that you distribute or publish, that in
            whole or in part contains or is derived from the Program or any
            part thereof, to be licensed as a whole at no charge to all third
            parties under the terms of this License.
        
            c) If the modified program normally reads commands interactively
            when run, you must cause it, when started running for such
            interactive use in the most ordinary way, to print or display an
            announcement including an appropriate copyright notice and a
            notice that there is no warranty (or else, saying that you provide
            a warranty) and that users may redistribute the program under
            these conditions, and telling the user how to view a copy of this
            License.  (Exception: if the Program itself is interactive but
            does not normally print such an announcement, your work based on
            the Program is not required to print an announcement.)
        
        These requirements apply to the modified work as a whole.  If
        identifiable sections of that work are not derived from the Program,
        and can be reasonably considered independent and separate works in
        themselves, then this License, and its terms, do not apply to those
        sections when you distribute them as separate works.  But when you
        distribute the same sections as part of a whole which is a work based
        on the Program, the distribution of the whole must be on the terms of
        this License, whose permissions for other licensees extend to the
        entire whole, and thus to each and every part regardless of who wrote it.
        
        Thus, it is not the intent of this section to claim rights or contest
        your rights to work written entirely by you; rather, the intent is to
        exercise the right to control the distribution of derivative or
        collective works based on the Program.
        
        In addition, mere aggregation of another work not based on the Program
        with the Program (or with a work based on the Program) on a volume of
        a storage or distribution medium does not bring the other work under
        the scope of this License.
        
          3. You may copy and distribute the Program (or a work based on it,
        under Section 2) in object code or executable form under the terms of
        Sections 1 and 2 above provided that you also do one of the following:
        
            a) Accompany it with the complete corresponding machine-readable
            source code, which must be distributed under the terms of Sections
            1 and 2 above on a medium customarily used for software interchange; or,
        
            b) Accompany it with a written offer, valid for at least three
            years, to give any third party, for a charge no more than your
            cost of physically performing source distribution, a complete
            machine-readable copy of the corresponding source code, to be
            distributed under the terms of Sections 1 and 2 above on a medium
            customarily used for software interchange; or,
        
            c) Accompany it with the information you received as to the offer
            to distribute corresponding source code.  (This alternative is
            allowed only for noncommercial distribution and only if you
            received the program in object code or executable form with such
            an offer, in accord with Subsection b above.)
        
        The source code for a work means the preferred form of the work for
        making modifications to it.  For an executable work, complete source
        code means all the source code for all modules it contains, plus any
        associated interface definition files, plus the scripts used to
        control compilation and installation of the executable.  However, as a
        special exception, the source code distributed need not include
        anything that is normally distributed (in either source or binary
        form) with the major components (compiler, kernel, and so on) of the
        operating system on which the executable runs, unless that component
        itself accompanies the executable.
        
        If distribution of executable or object code is made by offering
        access to copy from a designated place, then offering equivalent
        access to copy the source code from the same place counts as
        distribution of the source code, even though third parties are not
        compelled to copy the source along with the object code.
        
          4. You may not copy, modify, sublicense, or distribute the Program
        except as expressly provided under this License.  Any attempt
        otherwise to copy, modify, sublicense or distribute the Program is
        void, and will automatically terminate your rights under this License.
        However, parties who have received copies, or rights, from you under
        this License will not have their licenses terminated so long as such
        parties remain in full compliance.
        
          5. You are not required to accept this License, since you have not
        signed it.  However, nothing else grants you permission to modify or
        distribute the Program or its derivative works.  These actions are
        prohibited by law if you do not accept this License.  Therefore, by
        modifying or distributing the Program (or any work based on the
        Program), you indicate your acceptance of this License to do so, and
        all its terms and conditions for copying, distributing or modifying
        the Program or works based on it.
        
          6. Each time you redistribute the Program (or any work based on the
        Program), the recipient automatically receives a license from the
        original licensor to copy, distribute or modify the Program subject to
        these terms and conditions.  You may not impose any further
        restrictions on the recipients' exercise of the rights granted herein.
        You are not responsible for enforcing compliance by third parties to
        this License.
        
          7. If, as a consequence of a court judgment or allegation of patent
        infringement or for any other reason (not limited to patent issues),
        conditions are imposed on you (whether by court order, agreement or
        otherwise) that contradict the conditions of this License, they do not
        excuse you from the conditions of this License.  If you cannot
        distribute so as to satisfy simultaneously your obligations under this
        License and any other pertinent obligations, then as a consequence you
        may not distribute the Program at all.  For example, if a patent
        license would not permit royalty-free redistribution of the Program by
        all those who receive copies directly or indirectly through you, then
        the only way you could satisfy both it and this License would be to
        refrain entirely from distribution of the Program.
        
        If any portion of this section is held invalid or unenforceable under
        any particular circumstance, the balance of the section is intended to
        apply and the section as a whole is intended to apply in other
        circumstances.
        
        It is not the purpose of this section to induce you to infringe any
        patents or other property right claims or to contest validity of any
        such claims; this section has the sole purpose of protecting the
        integrity of the free software distribution system, which is
        implemented by public license practices.  Many people have made
        generous contributions to the wide range of software distributed
        through that system in reliance on consistent application of that
        system; it is up to the author/donor to decide if he or she is willing
        to distribute software through any other system and a licensee cannot
        impose that choice.
        
        This section is intended to make thoroughly clear what is believed to
        be a consequence of the rest of this License.
        
          8. If the distribution and/or use of the Program is restricted in
        certain countries either by patents or by copyrighted interfaces, the
        original copyright holder who places the Program under this License
        may add an explicit geographical distribution limitation excluding
        those countries, so that distribution is permitted only in or among
        countries not thus excluded.  In such case, this License incorporates
        the limitation as if written in the body of this License.
        
          9. The Free Software Foundation may publish revised and/or new versions
        of the General Public License from time to time.  Such new versions will
        be similar in spirit to the present version, but may differ in detail to
        address new problems or concerns.
        
        Each version is given a distinguishing version number.  If the Program
        specifies a version number of this License which applies to it and "any
        later version", you have the option of following the terms and conditions
        either of that version or of any later version published by the Free
        Software Foundation.  If the Program does not specify a version number of
        this License, you may choose any version ever published by the Free Software
        Foundation.
        
          10. If you wish to incorporate parts of the Program into other free
        programs whose distribution conditions are different, write to the author
        to ask for permission.  For software which is copyrighted by the Free
        Software Foundation, write to the Free Software Foundation; we sometimes
        make exceptions for this.  Our decision will be guided by the two goals
        of preserving the free status of all derivatives of our free software and
        of promoting the sharing and reuse of software generally.
        
        			    NO WARRANTY
        
          11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
        FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
        OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
        PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
        OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
        MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
        TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
        PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
        REPAIR OR CORRECTION.
        
          12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
        WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
        REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
        INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
        OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
        TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
        YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
        PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGES.
        
        		     END OF TERMS AND CONDITIONS
        
        	    How to Apply These Terms to Your New Programs
        
          If you develop a new program, and you want it to be of the greatest
        possible use to the public, the best way to achieve this is to make it
        free software which everyone can redistribute and change under these terms.
        
          To do so, attach the following notices to the program.  It is safest
        to attach them to the start of each source file to most effectively
        convey the exclusion of warranty; and each file should have at least
        the "copyright" line and a pointer to where the full notice is found.
        
            <one line to give the program's name and a brief idea of what it does.>
            Copyright (C) <year>  <name of author>
        
            This program is free software; you can redistribute it and/or modify
            it under the terms of the GNU General Public License as published by
            the Free Software Foundation; either version 2 of the License, or
            (at your option) any later version.
        
            This program is distributed in the hope that it will be useful,
            but WITHOUT ANY WARRANTY; without even the implied warranty of
            MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
            GNU General Public License for more details.
        
            You should have received a copy of the GNU General Public License
            along with this program; if not, write to the Free Software
            Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
        
        
        Also add information on how to contact you by electronic and paper mail.
        
        If the program is interactive, make it output a short notice like this
        when it starts in an interactive mode:
        
            Gnomovision version 69, Copyright (C) year  name of author
            Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
            This is free software, and you are welcome to redistribute it
            under certain conditions; type `show c' for details.
        
        The hypothetical commands `show w' and `show c' should show the appropriate
        parts of the General Public License.  Of course, the commands you use may
        be called something other than `show w' and `show c'; they could even be
        mouse-clicks or menu items--whatever suits your program.
        
        You should also get your employer (if you work as a programmer) or your
        school, if any, to sign a "copyright disclaimer" for the program, if
        necessary.  Here is a sample; alter the names:
        
          Yoyodyne, Inc., hereby disclaims all copyright interest in the program
          `Gnomovision' (which makes passes at compilers) written by James Hacker.
        
          <signature of Ty Coon>, 1 April 1989
          Ty Coon, President of Vice
        
        This General Public License does not permit incorporating your program into
        proprietary programs.  If your program is a subroutine library, you may
        consider it more useful to permit linking proprietary applications with the
        library.  If this is what you want to do, use the GNU Library General
        Public License instead of this License.
        
Project-URL: Homepage, https://github.com/snapshotmanager/boom-boot
Project-URL: Issues, https://github.com/snapshotmanager/boom-boot/issues
Platform: Linux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: dbus-python>=1.2.16

![Boom CI](https://github.com/snapshotmanager/boom/actions/workflows/default.yml/badge.svg)
# Boom

Boom is a *boot manager* for Linux systems using boot loaders that
support the [BootLoader Specification][0] for boot entry configuration.
It is based on the boot manager design discussed in the
[Boot-to-snapshot design v0.6][1] document.

Boom requires a BLS compatible boot loader to function: either the
`systemd-boot` project, or `Grub2` with the `bls` patch (*Red Hat*
Grub2 builds include this support in both *Red Hat Enterprise Linux 7*
and *Fedora*).

Boom allows for flexible boot configuration and simplifies the
creation of new or modified boot entries: for example to boot
snapshot images of the system created using LVM2 or BTRFS.

Boom does not modify the existing boot loader configuration (other
than to insert the additional entries managed by boom - see
[Grub2 Integration](#grub2-integration)): the existing boot
configuration is maintained and any distribution integration (e.g.
kernel installation and update scripts) will continue to function as
before.


   * [Boom](#boom)
      * [Reporting bugs](#reporting-bugs)
      * [Mailing list](#mailing-list)
      * [Building and installing Boom](#building-and-installing-boom)
         * [Building an RPM package](#building-an-rpm-package)
      * [The boom command](#the-boom-command)
         * [Operating System Profiles and Boot Entries](#operating-system-profiles-and-boot-entries)
            * [OsProfile](#osprofile)
               * [OsProfile templates](#osprofile-templates)
            * [BootEntry](#bootentry)
         * [Boom subcommands](#boom-subcommands)
            * [create](#create)
            * [delete](#delete)
            * [clone](#clone)
            * [show](#show)
            * [list](#list)
            * [edit](#edit)
         * [Reporting commands](#reporting-commands)
         * [Getting help](#getting-help)
      * [Configuring Boom](#configuring-boom)
         * [Creating an OsProfile](#creating-an-osprofile)
         * [Creating a BootEntry](#creating-a-bootentry)
      * [Grub2 Integration](#grub2-integration)
         * [Submenu support](#submenu-support)
      * [Python API](#python-api)
         * [Command API](#command-api)
         * [Object API](#object-api)
      * [Patches and pull requests](#patches-and-pull-requests)
      * [Documentation](#documentation)

Boom aims to be a simple and extensible, and to be able to create boot
configurations for a wide range of Linux system configurations and boot
parameters.

This project is hosted at:

  * http://github.com/snapshotmanager/boom

For the latest version, to contribute, and for more information, please visit
the project pages or join the mailing list.

To clone the current main (development) branch run:

```
git clone git://github.com/snapshotmanager/boom.git
```
## Reporting bugs

Please report bugs via the mailing list or by opening an issue in the [GitHub
Issue Tracker][2]

## Mailing list

The [dm-devel][3] is the mailing list for any boom-related questions and
discussion. Patch submissions and reviews are welcome too.

## Building and installing Boom

A `setuptools` based build script is provided: local installations and
package builds can be performed by running `python setup.py` and a
setup command. See `python setup.py --help` for detailed information on
the available options and commands.

### Builds and packages
Binary packages for Fedora and Red Hat Enterprise Linux are available
from the distribution repositories.

Red Hat Enterprise Linux 7:

```
# yum -y install lvm2-python-boom
```

Red Hat Enterprise Linux 8 and Fedora:

```
# dnf -y install boom-boot
```

## The boom command

The `boom` command is the main interface to the boom boot manager.
It is able to create, delete, edit and display boot entries,
operating system and host profiles and provides reports showing the
available profiles and entries, and their configurations.

Boom commands normally operate on a particular object type: a boot
entry, a host profile or an OS profile. Commands are also provided
to manipulate legacy boot loader configurations (for systems that
do not natively support the BLS standard).

```
# boom [entry] <command> <options> # `BootEntry` command
```

```
# boom profile <command> <options> # `OsProfile` command
```

```
# boom hostprofile <command> <options> # `HostProfile` command
```

```
# boom legacy <command> <options> # Legacy boot loader commands
```

If no command type is given `entry` is assumed.

### Profiles and Boot Entries

The two main object types in boom are the `Profile` and `BootEntry`.
Profiles support tailoring boot entry configuration to either a
specific operating system distribution (`OsProfile`), or a specific
installation (`HostProfile`, based on the system `machine-id`).

Boom stores boot loader entries (`BootEntry`) in the system BLS loader
directory - normally `/boot/loader/entries`.

Boom `OsProfile` files are stored in the boom configuration directory,
`/boot/boom/profiles` and `HostProfile` data is found in
`/boot/boom/hosts`.

The location of the boot file system may be overridden using the
`--boot-dir` command line option and the location of both the boot
file system and boom configuration directory may be overridden by
calling the `boom.set_boot_path()` and `boom.set_boom_path()`
functions.

These options are primarily of use for testing, or for working with
boom data from a system other than the running host.

Boom configuration data is stored in the `/boot` file system to permit
the tool to be run from any booted instance of any installed operating
system.

#### OsProfile

An `OsProfile` stores identity information and templates used to write
bootloader configurations for an instance of an operating system. The
identity is based on values from the `/etc/os-release` file, and the
available templates allow customisation of the kernel and initramfs
images, kernel options and other properties required to boot an instance
of that OS.

A set of `OsProfile` files can be pre-installed with boom, or generated
using the command line tool.

An `OsProfile` is uniquely identified by its *OS Identifier*, or
*os_id*, a SHA2 hash computed on the `OsProfile` identity fields.
All SHA identifiers are displayed by default using the minimum width
necessary to ensure uniqueness: all command line arguments accepting
an identifier also accept any unique prefix of a valid identifier.

##### OsProfile templates

The template properties of an `OsProfile` (kernel pattern, initramfs
pattern, LVM2 and BTRFS root options and kernel command line options)
may include format strings that are expanded when creating a new
``BootEntry``.

The available keys are:

  * `%{version}` - the kernel version
  * `%{lvm_root_lv}` - the LVM2 logical volume containing the root file
    system in `vg/lv` notation.
  * `%{btrfs_subvol_id}` - the BTRFS subvolume identifier to use.
  * `%{btrfs_subvol_path}` - the BTRFS subvolume path to use.
  * `%{root_device}` - The system root device, relative to `/`.
  * `%{options}` - Kernel command line options, including the root
    device specification and options.

Default template values are supplied when creating a new `OsProfile`;
these can be overridden by specifying alternate values on the command
line. The defaults are suitable for most Linux operating systems but
can be customised to allow for particular OS requirements, or to set
custom behaviours.

#### HostProfile

A `HostProfile` provides an additional means to customise the boot
configuration on a per-installation basis. Use of host profiles is
optional: if no `HostProfile` exits for a given host then the
default values from the corresponding `OsProfile` are used.

Values specified in a Boom `HostProfile` are automatically applied
whenever a boot entry for the corresponding `machine-id` is created
or edited. Multiple Boom `HostProfile` templates can be defined for
a given system and distinguished by a *label*: for example
'production', 'debug' or other profile labels used to identify
and group commonly-used sets of boot options.

Host profiles can be used to add or remove kernel command line
options, or to modify existing template values provided by the
`OsProfile` (including the location and naming of the kernel,
initramfs and other boot images). This can be used to automatically
apply settings where required, for example adding `nomodeset` or
other kernel command line parameters if required for that
installation, or modifying the command line to enable or disable
debugging, logging or storage activation options.

Like the `OsProfile`, a `HostProfile` is uniquely identified by
a `HostId` identifier.

#### BootEntry

A `BootEntry` is an individual bootloader entry for one instance of an
operating system. It includes all the parameters required for the
boot loader to load the OS, and for the kernel and user space to
boot the environment (including configuration of LVM2 logical volumes
and BTRFS subvolumes).

The `BootEntry` stored on-disk is generated from the templates stored
in an associated `OsProfile` and boot parameters configuration provided
by command line arguments.

Boom uses BLS[0] notation as the canonical format for the boot entry
store.

An `BootEntry` is uniquely identified by its *Boot Identifier*, or
*boot_id*, a SHA2 hash computed on the `BootEntry` boot parameter
fields (note that this means that changing the parameters of an
existing `BootEntry` will also change its `boot_id`. All SHA
identifiers are displayed by default using the minimum width
necessary to ensure uniqueness: all command line arguments
accepting an identifier also accept any unique prefix of a valid
identifier.

### Boom subcommands

For both profile and boot entry command types, boom provides six
subcommands:

  * `create`
  * `delete --profile OS_ID | --host-profile HOST_ID | --boot-id BOOT_ID [...]`
  * `clone --profile OS_ID | --host-profile HOST_ID | --boot-id BOOT_ID [...]`
  * `show`
  * `list`
  * `edit`

#### create

Create a new `OsProfile` `HostProfile`, or `BootEntry` using the
values entered on the command line.

#### delete

Delete the specified profile or BootEntry.

#### clone

Create a new profile or `BootEntry` by cloning an existing object
and modifying its properties. A `boot_id`, `os_id` or `host_id`
must be used to select the object to clone. Any remaining command
line options modify the newly created object.

#### show

Display the specified objects in human readable format.

#### list

List objects matching selection criteria as a tabular report.

#### edit

Modify an existing profile or `BootEntry` by changing one or more
of its attributes.

It is not possible to change the name, short name, version, or
version identifier of an `OsProfile` using this command, since these
fields form the `OsProfile` identifier: to modify one of these
fields use the `clone` command to create a new profile specifying
the attribute to be changed.

When editing a BootEntry, the `boot_id` will change: this is
because the options that define an entry form the entry's identity.
The new `boot_id` is written to the terminal on success.

### Boot image cache

Boom can optionally back up the boot images used by a boom BootEntry
so that the entry can still be used if an operating system update
removes the kernel or initramfs image used.

To use backup images the boot image cache must be enabled in the
`boom.conf` configuration file and the `--backup` option should
be given to the `boom entry` `create`, `edit`, or `clone`
subcommands.

When `--backup` is used boom will make a copy of each boot image
used by the new entry by adding a '.boomN' suffix (where `N` is a
number) to the file name. The new BootEntry uses the backup copy
of the image rather than the original file name.

If the `auto_clean` configuration option is set cache entries are
automatically removed when they are no longer in use by any
BootEntry.

#### boom cache command

The `boom cache` command gives information about the paths and
images stored in the boom boot image cache. The `boom cache list`
command gives information on cache entries in a tabular report
format similar to other `list` commands.

Detailed information on selected cache entries is provided by the
`boom cache show` command.

### Reporting commands

The `boom entry list` and `boom host|profile list`, and `boom cache
list` commands generate a tabular report as output. To control the
list of displayed fields use the `-o/--options FIELDS` argument:

```
boom list -oboot_id,version
BootId  Version
fb3286f 3.10-1.el7.fc24.x86_64
1031ab0 3.10-23.el7
a559d3a 2.6.32-232.el6
a559d3a 2.6.32-232.el6
2c89556 2.2.2-2.fc24.x86_64
e79db6a 1.1.1-1.fc24.x86_64
d85f2c3 3.10.1-1.el7
2fc3f4f 4.1.1-100.fc24
d85f2c3 3.10.1-1.el7
```

To add extra fields to the default selection, prefix the field list
with the `+` character:

```
boom list -o+kernel,initramfs
BootID  Version                  OsID    Name                            OsVersion   Kernel                               Initramfs
fb3286f 3.10-1.el7.fc24.x86_64   3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo) /boot/vmlinuz-3.10-1.el7.fc24.x86_64 /boot/initramfs-3.10-1.el7.fc24.x86_64.img
1031ab0 3.10-23.el7              3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo) /boot/vmlinuz-3.10-23.el7            /boot/initramfs-3.10-23.el7.img
a559d3a 2.6.32-232.el6           98c3edb Red Hat Enterprise Linux Server 6 (Server)  /boot/kernel-2.6.32-232.el6          /boot/initramfs-2.6.32-232.el6.img
a559d3a 2.6.32-232.el6           98c3edb Red Hat Enterprise Linux Server 6 (Server)  /boot/kernel-2.6.32-232.el6          /boot/initramfs-2.6.32-232.el6.img
d85f2c3 3.10.1-1.el7             3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo) /boot/vmlinuz-3.10.1-1.el7           /boot/initramfs-3.10.1-1.el7.img
d85f2c3 3.10.1-1.el7             3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo) /boot/vmlinuz-3.10.1-1.el7           /boot/initramfs-3.10.1-1.el7.img
e19586b 7.7.7                    3fc389b Red Hat Enterprise Linux Server 7.2 (Maipo) /boot/vmlinuz-7.7.7                  /boot/initramfs-7.7.7.img
```

```
boom list -o+title
BootID  Version                  Name                     RootDevice                                    Title
635ed15 6.8.9-300.fc40.x86_64    Fedora Linux             /dev/mapper/fedora-root                       Fedora Linux (6.8.9-300.fc40.x86_64) 40 (Server Edition)
995b87e 6.8.9-300.fc40.x86_64    Fedora Linux             /dev/fedora/root-snapset_upgrade_1719340050_- Snapshot upgrade 2024-06-25 19:27:30 (6.8.9-300.fc40.x86_64)
029c307 6.8.9-300.fc40.x86_64    Fedora Linux             /dev/fedora/root                              Revert upgrade 2024-06-25 19:27:30 (6.8.9-300.fc40.x86_64)
```

To display the available fields for either report use the field
name `help`.

`BootEntry` 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]

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]

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]
```

`OsProfile` 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]
```

`HostProfile` fields:
```
boom host list -o help
Host profiles Fields
--------------------
  hostid        - Host identifier [sha]
  machineid     - Machine identifier [sha]
  osid          - OS identifier [sha]
  hostname      - Host name [str]
  label         - Host label [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]
  addopts       - Added Options [str]
  delopts       - Deleted Options [str]
```

`Cache` fields:
```
Cache entries Fields
--------------------
  imgid       - Image identifier [sha]
  path        - Image path [str]
  mode        - Path mode [str]
  uid         - User ID [num]
  gid         - Group ID [num]
  ts          - Timestamp [num]
  state       - State [str]
  count       - Use Count [num]
```

#### JSON report output

The reporting commands can also produce output in JSON notation. The
output is an array of JSON objects mapping field names to values. The
full field name including the type prefix is used to ensure keys are
unambiguous.

```
# boom list --json
{
    "Entries": [
        {
            "entry_bootid": "635ed15b411495cffa0c1eece74d3756278f484a",
            "param_version": "6.8.9-300.fc40.x86_64",
            "profile_osname": "Fedora Linux",
            "param_rootdev": "/dev/mapper/fedora-root"
        },
        {
            "entry_bootid": "995b87eac66fa6b4507e4c5dbd8a30e196b13e2c",
            "param_version": "6.8.9-300.fc40.x86_64",
            "profile_osname": "Fedora Linux",
            "param_rootdev": "/dev/fedora/root-snapset_upgrade_1719340050_-"
        },
        {
            "entry_bootid": "029c3078f83df79bfc2240223c6f79c648b2fce3",
            "param_version": "6.8.9-300.fc40.x86_64",
            "profile_osname": "Fedora Linux",
            "param_rootdev": "/dev/fedora/root"
        }
    ]
}
```

To include all fields for a given prefix use the special field name
`all`:

```
# boom list --json -o+entry_all,param_all,profile_all
{
    "Entries": [
        {
            "entry_bootid": "635ed15b411495cffa0c1eece74d3756278f484a",
            "param_version": "6.8.9-300.fc40.x86_64",
            "profile_osname": "Fedora Linux",
            "param_rootdev": "/dev/mapper/fedora-root",
            "entry_title": "Fedora Linux (6.8.9-300.fc40.x86_64) 40 (Server Edition)",
            "entry_options": "root=/dev/mapper/fedora-root ro rd.lvm.lv=fedora/root rhgb quiet ",
            "entry_kernel": "/vmlinuz-6.8.9-300.fc40.x86_64",
            "entry_initramfs": "/initramfs-6.8.9-300.fc40.x86_64.img",
            "entry_machineid": "5d1e621b0c1349aea3bd47e4bb619024",
            "entry_entrypath": "/boot/loader/entries/5d1e621b0c1349aea3bd47e4bb619024-6.8.9-300.fc40.x86_64.conf",
            "entry_entryfile": "5d1e621b0c1349aea3bd47e4bb619024-6.8.9-300.fc40.x86_64.conf",
            "entry_readonly": true,
            "param_rootlv": "fedora/root",
            "param_subvolpath": "",
            "param_subvolid": -1,
            "profile_osid": "5ea08f4d8c4d6fbdfdb2c0b79829e7ff4dfce7d4",
            "profile_osshortname": "fedora",
            "profile_osversion": "40 (Server Edition)",
            "profile_osversion_id": "40",
            "profile_unamepattern": "fc40",
            "profile_kernelpattern": "/vmlinuz-%{version}",
            "profile_initrdpattern": "/initramfs-%{version}.img",
            "profile_lvm2opts": "rd.lvm.lv=%{lvm_root_lv}",
            "profile_btrfsopts": "rootflags=%{btrfs_subvolume}",
            "profile_options": "root=%{root_device} ro %{root_opts} rhgb quiet",
            "profile_profilepath": "/boot/boom/profiles/5ea08f4d8c4d6fbdfdb2c0b79829e7ff4dfce7d4-fedora40.profile"
        }
    ]
}
```

### Getting help

Help is available for the `boom` command and each command line option.

Run the command with `--help` to display the full usage message:

```
# boom --help
```

## Configuring Boom

### Creating an OsProfile
To automatically generate boot configuration Boom needs an *Operating
System Profile* for the system(s) for which it will create entries.

And *OsProfile* is a collection of attributes that describe the OS
identity and provide templates for boot loader entries.

The identity information comprising an `OsProfile` is taken from the
`os-release` file for the distribution. Additional properties,
such as the UTS release pattern to match for the distribution,
are either provided on the boom command line or are set to default
values.

To create an `OsProfile` for the running system, use the
`-H/--from-host'` command line option:

```
# 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}"
```

The `--uname-pattern` `OsProfile` property is an optional but recommended
pattern (regular expression) that should match the UTS release (`uname`)
strings reported by the operating system.

The uname pattern is used when an on-disk boot loader entry is found that
does not contain an OS identifier (for e.g. a manually edited entry, or
one created by a different program).

### Creating a HostProfile
Boom can optionally apply further customisation to the boot entries
it creates by defining a *HostProfile*. The host profile can be used
to modify the templates (boot image names and paths, boot entry
titles, kernel command line options etc) provided by the `OsProfile`.

To create a new host profile for the current system use the
`host create` command, specifying the parameters to modify. For
example, to create a new host profile for a system running Fedora 30
that adds the "debug" kernel command line argument, and removes the
"rhgb" and "quiet" arguments run:

```
boom profile list --name Fedora --osversionid 30
OsID    Name                     OsVersion               
8896596 Fedora                   30 (Workstation Edition)

boom host create --profile 8896596 --add-opts debug --del-opts "rhgb quiet"
Created host profile with host_id ff4266a:
  Host ID: "ff4266a7a0ceac789d65df75a1edd47b832dd9c5",
  Host name: "localhost.localdomain",
  Machine ID: "653b444d513a43239c37deae4f5fe644",
  OS ID: "8896596a45fcc9e36e9c87aee77ab3e422da2635",
  Add options: "debug", Del options: "rhgb quiet",
  Name: "Fedora", Short name: "fedora", Version: "30 (Workstation Edition)",
  Version ID: "30", UTS release pattern: "fc30",
  Kernel pattern: "/vmlinuz-%{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}"
```

### Creating a BootEntry
To create a new boot entry using an existing `OsProfile`, use the
`boom create` command, specifying the `OsProfile` using its assigned
identifier:

```
# boom profile list --short-name rhel
OsID    Name                            OsVersion
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
```

Once the entry has been created it will appear in the boot loader
menu as configured:

```
      Red Hat Enterprise Linux Server (3.10.0-327.el7.x86_64) 7.2 (Maipo)
      Red Hat Enterprise Linux Server (3.10.0-272.el7.x86_64) 7.2 (Maipo)
      RHEL7 Snapshot











      Use the ↑ and ↓ keys to change the selection.
      Press 'e' to edit the selected item, or 'c' for a command prompt.
```

If creating an entry for the currently running kernel version, and the
OsProfile of the running host, these options can be omitted from the
create command:

```
# boom create --title "Fedora 26 snapshot" --root-lv vg_hex/root-snap-f26
Created entry with boot_id d12c177:
  title Fedora 26 snapshot
  machine-id 611f38fd887d41dea7eb3403b2730a76
  version 4.13.5-200.fc26.x86_64
  linux /kernel-4.13.5-200.fc26.x86_64
  initrd /initramfs-4.13.5-200.fc26.x86_64.img
  options root=/dev/vg_hex/root-snap-f26 ro rd.lvm.lv=vg_hex/root-snap-f26
```

```
      Red Hat Enterprise Linux Server (3.10.0-327.el7.x86_64) 7.2 (Maipo)
      Red Hat Enterprise Linux Server (3.10.0-272.el7.x86_64) 7.2 (Maipo)
      Fedora 26 snapshot (4.13.5-200.fc26.x86_64)
      RHEL7 Snapshot











      Use the ↑ and ↓ keys to change the selection.
      Press 'e' to edit the selected item, or 'c' for a command prompt.
```
## Grub2 Integration

Support for the [BootLoader Specification][0] is enabled by default in
supported distributions beginning with Fedora 30 and Red Hat Enterprise Linux
8. No special steps are required to enable BLS for boot configuration on these
distributions.

### Submenu support

Previous versions of boom for distributions that included support for BLS but
did not enable it by default allowed boom-managed boot entries to be placed
into a separate Grub2 submenu. This is no longer possible with distributions
that use BLS by default since there is no way to separately load the boom
managed entries into a Grub2 submenu. Support for configuring this option was
removed in boom-1.4.

## Python API
Boom also supports programmatic use via a Python API. The API is flexible
and allows greater customisation than is possible using the command line
tool.

Two interfaces are provided: a procedural command-driven interface that
closely mimics the command line tool (the boom CLI is implemented using
this interface), and a native object interface that provides complete
access to boom's capabilities and full control over boom `OsProfile`
`BootEntry`, and `BootParams` objects. User-defined tabular reports
may also be created using the `boom.report` module.

### Command API
The command API is implemented in the `boom.command` sub-module. Programs
wishing to use the command API can just import this module:

```
import boom.command
```

The command API is [documented][7] at [readthedocs.org][6].

### Object API
The object API is implemented in several `boom` sub-modules:

  * `boom`
  * `boom.bootloader`
  * `boom.cache`
  * `boom.command`
  * `boom.config`
  * `boom.hostprofile`
  * `boom.legacy`
  * `boom.osprofile`
  * `boom.report`


Applications using the object API need only import the sub-modules that
contain the needed interfaces.

The object API is [documented][8] at [readthedocs.org][6].

## Patches and pull requests

Patches can be submitted via the mailing list or as GitHub pull requests. If
using GitHub please make sure your branch applies to the current main as a
'fast forward' merge (i.e. without creating a merge commit). Use the `git
rebase` command to update your branch to the current main branch if
necessary.

## Documentation

API [documentation][4] is automatically generated using [Sphinx][5]
and [Read the Docs][6].

Installation and user documentation will be added in a future update.

 [0]: https://systemd.io/BOOT_LOADER_SPECIFICATION
 [1]: https://github.com/snapshotmanager/snapshot-boot-docs
 [2]: https://github.com/snapshotmanager/boom/issues
 [3]: https://www.redhat.com/mailman/listinfo/dm-devel
 [4]: https://boom.readthedocs.org/en/latest/index.html#
 [5]: http://sphinx-doc.org/
 [6]: https://www.readthedocs.org/
 [7]: https://boom.readthedocs.io/en/latest/boom.html#module-boom.command
 [8]: https://boom.readthedocs.io/en/latest/boom.html
