imgbase man page

imgbase — tool to manage writeable filesystems on read-only base images


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


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.


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 volumens, 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.


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.


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.


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


# 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+1
 └╼ 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

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-

# 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



Output debug informations


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


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


# 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'],) {}

By default the volume group HostVG is used. Use this argument to use the volume group name VG instead.


By default the thinpool ImagePool is used. Use this argument to use the thinpool name THINPOOL instead.


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.


The imgbase command is part of the imgbased package and is available from


Fabian Deutsch


03/13/2017 imgbase