imgbase - Man Page

tool to manage writeable filesystems on read-only base images

Synopsis

imgbase [OPTION...] [<COMMAND> [OPTION...]]

Description

imgbase provides a specific management method to derive writeable filesystem layers from read-only base images. It also takes care that the layer which shall be used can be selected at boot time.

Warning

imgbase is a WIP. That means this manpage is probably out of date and data loss can happen.

This works by using LVM thinpools and thin volumes, combined if a filesystem which supports the TRIM commant (i..e ext4 when it’s used with the discard mount option). The creation of this layout is described under the section called “Usage”.

imgbase needs a volume group, which is then populated with one or more base images (which are read-only thin volumes in a thinpool).

For each of this base image one or more write-able layers can be added.

Usage

Creating the layout

imgbase makes assumptions about the existing LVM layout, if you start from scratch you can use imgbase to create the layout:

# imgbase layout --init --size 10G /dev/sdb /dev/sdc

This command will create the deafult volume group (HostVG) with a thinpool which is 10G in size, laying on /dev/sdb and /dev/sdc.

Adding a base

Once a valid layout was created you can add a base image using the following command:

# imgbase base --add --size 1G rootfs.img

This will create a new base image. It will create a 1G sized thin volume and populate it with the rootfs.img. The rootfs.img must be smaller than the given size.

Note

The base image name is derived from a pre-defined naming scheme.

Adding a layer

Once a base image exists you can add a layer by running:

# imgbase layer --add

This will add a new layer for the latest existing base image.

Note

The layer name is also derived from a pre-defined naming scheme.

Inspection at runtime

A summary over all base images and their layers can be determined by running:

# imgbase layout

To get the remaining free space in the used thinpool run:

# imgbase layout --free-space

Upgrade to new image

# imgbase update --format liveimg FILENAME

Example:

# imgbase update ovirt-node-ng-4.0.0-0.999.master.20160329.0.el7.squashfs.img

To verify a new base image was added:

# imgbase layout
ovirt-node-ng-4.0.0-0
 └╼ ovirt-node-ng-4.0.0-0+1
ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7
 └╼ ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7+1

To load the new image:

# reboot

To verify you are in the new image (after reboot):

# imgbase w
[INFO] You are on ovirt-node-ng-4.0.0-0+1

Recover from a failed upgrade

If the upgrade command has failed, imgbased may leave behind some LVs that are not used and prevent the user from reapplying the upgrade

To view the list of LVs that were created by imgbased but are identified as unused:

# imgbase --experimental recover --list

To remove unused LVs that were created by imgbased with user confirmation:

# imgbase --experimental recover

To remove unused LVs that were created by imgbased without user confirmation (dangerous)

# imgbase --experimental recover --force

Rollback to previous image

If you have updated and would like to return to a previous version. The rollback operation will set the bootloader to an earlier version. This defaults to rolling back one update. If you would like to return to a specific version, use --to.

---

Example 1:

The example below has two layers: ovirt-node-ng-4.0.0+1, and ovirt-node-ng-4.0.0-20160413.0+1. ovirt-node-ng-4.0.0-20160413.0+1 is the active layer, as shown below.

# imgbase layout ovirt-node-ng-4.0.0-0 └╼ ovirt-node-ng-4.0.0-0+1 ovirt-node-ng-4.0.0-0.20160413.0 └╼ ovirt-node-ng-4.0.0-0.20160413.0+1

# imgbase w [INFO] You are on ovirt-node-ng-4.0.0-0.20160413.0+1

imgbase rollback with no arguments will revert to the previous version. In this case, ovirt-node-ng-4.0.0.0+1

# imgbase rollback

Example 2: rollback to a specific version.

# imgbase rollback --to ovirt-node-ng-4.0.0-0+1

After the rollback operation, a reboot is required. # reboot ---

To verify you are in the new image (after reboot):

# imgbase w
[INFO] You are on ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7+1

Options

--debug

Output debug informations

--dry

Do not run the commands, just output what would be run.
Note

Combine this with --debug to see the commands This does not work with all commands.

Environment

You can change the behaviour of imgbase for debugging purposes only with environment variables as follows:

IMGBASED_KEEP_VOLUMES will not delete any volumes created by imgbase in case of a failing upgrade

IMGBASED_DISABLE_THREADS will not execute anything in parallel

Example

# imgbase --dry --debug layout --init --size 1G /dev/sda ... DEBUG:imgbase:Calling: ([vgcreate, HostVG, <open file /dev/sda, mode r at 0x22bf420>],) {} DEBUG:imgbase:Calling: ([lvcreate, --size, 1G, --thin, HostVG/ImagePool],) {}

**--vg=_VG_**::
    By default the volume group +HostVG+ is used. Use this argument to
    use the volume group name _VG_ instead.

**--thinpool=_THINPOOL_**::
    By default the thinpool +ImagePool+ is used. Use this argument to
    use the thinpool name _THINPOOL_ instead.

**--layerformat=_FMT_**::
    By default the format +Base-%d.%d+ is used to create and discover existing
    logical volumes. Use this argument to use the format _FMT_ instead.