imgbase man page

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

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 https://github.com/fabiand/imgbased/

Authors

Fabian Deutsch

Info

06/17/2015 imgbase imgbase