1IMGBASE(8) imgbase IMGBASE(8)
2
6 imgbase - tool to manage writeable filesystems on read-only base images
7
9 imgbase [OPTION...] [<COMMAND> [OPTION...]]
10
12 imgbase provides a specific management method to derive writeable
13 filesystem layers from read-only base images. It also takes care that
14 the layer which shall be used can be selected at boot time.
15 Warning
17 imgbase is a WIP. That means this manpage is probably out of date
18 and data loss can happen.
19 This works by using LVM thinpools and thin volumes, combined if a
21 filesystem which supports the TRIM commant (i..e ext4 when it’s used
22 with the discard mount option). The creation of this layout is
23 described under the section called “USAGE”.
24 imgbase needs a volume group, which is then populated with one or more
26 base images (which are read-only thin volumes in a thinpool).
27 For each of this base image one or more write-able layers can be added.
29
31 Creating the layout
32 imgbase makes assumptions about the existing LVM layout, if you start
33 from scratch you can use imgbase to create the layout:
34 # imgbase layout --init --size 10G /dev/sdb /dev/sdc
36 This command will create the deafult volume group (HostVG) with a
38 thinpool which is 10G in size, laying on /dev/sdb and /dev/sdc.
39 Adding a base
41 Once a valid layout was created you can add a base image using the
42 following command:
43 # imgbase base --add --size 1G rootfs.img
45 This will create a new base image. It will create a 1G sized thin
47 volume and populate it with the rootfs.img. The rootfs.img must be
48 smaller than the given size.
49 Note
51 The base image name is derived from a pre-defined naming scheme.
52 Adding a layer
54 Once a base image exists you can add a layer by running:
55 # imgbase layer --add
57 This will add a new layer for the latest existing base image.
59 Note
61 The layer name is also derived from a pre-defined naming scheme.
62 Inspection at runtime
64 A summary over all base images and their layers can be determined by
65 running:
66 # imgbase layout
68 To get the remaining free space in the used thinpool run:
70 # imgbase layout --free-space
72 Upgrade to new image
74 # imgbase update --format liveimg FILENAME
75 Example:
77 # imgbase update ovirt-node-ng-4.0.0-0.999.master.20160329.0.el7.squashfs.img
79 To verify a new base image was added:
81 # imgbase layout
83 ovirt-node-ng-4.0.0-0
84 └╼ ovirt-node-ng-4.0.0-0+1
85 ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7
86 └╼ ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7+1
87 To load the new image:
89 # reboot
91 To verify you are in the new image (after reboot):
93 # imgbase w
95 [INFO] You are on ovirt-node-ng-4.0.0-0+1
96 Recover from a failed upgrade
98 If the upgrade command has failed, imgbased may leave behind some LVs
99 that are not used and prevent the user from reapplying the upgrade
100 To view the list of LVs that were created by imgbased but are
102 identified as unused:
103 # imgbase --experimental recover --list
105 To remove unused LVs that were created by imgbased with user
107 confirmation:
108 # imgbase --experimental recover
110 To remove unused LVs that were created by imgbased without user
112 confirmation (dangerous)
113 # imgbase --experimental recover --force
115 Rollback to previous image
117 If you have updated and would like to return to a previous version. The
118 rollback operation will set the bootloader to an earlier version. This
119 defaults to rolling back one update. If you would like to return to a
120 specific version, use --to.
121 ---
123 Example 1:
125 The example below has two layers: ovirt-node-ng-4.0.0+1, and
127 ovirt-node-ng-4.0.0-20160413.0+1. ovirt-node-ng-4.0.0-20160413.0+1 is
128 the active layer, as shown below.
129 # imgbase layout ovirt-node-ng-4.0.0-0 └╼ ovirt-node-ng-4.0.0-0+1
131 ovirt-node-ng-4.0.0-0.20160413.0 └╼ ovirt-node-ng-4.0.0-0.20160413.0+1
132 # imgbase w [INFO] You are on ovirt-node-ng-4.0.0-0.20160413.0+1
134 imgbase rollback with no arguments will revert to the previous version.
136 In this case, ovirt-node-ng-4.0.0.0+1
137 # imgbase rollback
139 Example 2: rollback to a specific version.
141 # imgbase rollback --to ovirt-node-ng-4.0.0-0+1
143 After the rollback operation, a reboot is required. # reboot ---
145 To verify you are in the new image (after reboot):
147 # imgbase w
149 [INFO] You are on ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7+1
150
152 --debug
153 Output debug informations
154 --dry
156 Do not run the commands, just output what would be run.
157 Note
159 Combine this with --debug to see the commands This does not work
160 with all commands.
161
163 You can change the behaviour of imgbase for debugging purposes only
164 with environment variables as follows:
165 IMGBASED_KEEP_VOLUMES will not delete any volumes created by imgbase in
167 case of a failing upgrade
168 IMGBASED_DISABLE_THREADS will not execute anything in parallel
170
172 # imgbase --dry --debug layout --init --size 1G /dev/sda ...
173 DEBUG:imgbase:Calling: ([vgcreate, HostVG, <open file /dev/sda, mode r
174 at 0x22bf420>],) {} DEBUG:imgbase:Calling: ([lvcreate, --size, 1G,
175 --thin, HostVG/ImagePool],) {}
176 **--vg=_VG_**::
178 By default the volume group +HostVG+ is used. Use this argument to
179 use the volume group name _VG_ instead.
180 **--thinpool=_THINPOOL_**::
182 By default the thinpool +ImagePool+ is used. Use this argument to
183 use the thinpool name _THINPOOL_ instead.
184 **--layerformat=_FMT_**::
186 By default the format +Base-%d.%d+ is used to create and discover existing
187 logical volumes. Use this argument to use the format _FMT_ instead.
188
190 The imgbase command is part of the imgbased package and is available
191 from https://github.com/oVirt/imgbased
192
194 Fabian Deutsch
195imgbase 07/21/2022 IMGBASE(8)