imgbase (8) - Linux Manuals

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

NAME

imgbase - 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 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.

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

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.

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.

AVAILABILITY

The imgbase command is part of the imgbased package and is available from m[blue]https://github.com/fabiand/imgbased/m[]

AUTHORS

Fabian Deutsch

Pages related to imgbase