1IMGBASE(8)                          imgbase                         IMGBASE(8)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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
16           Warning
17           imgbase is a WIP. That means this manpage is probably out of date
18           and data loss can happen.
19
20       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
25       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
28       For each of this base image one or more write-able layers can be added.
29

USAGE

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
35           # imgbase layout --init --size 10G /dev/sdb /dev/sdc
36
37       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
40   Adding a base
41       Once a valid layout was created you can add a base image using the
42       following command:
43
44           # imgbase base --add --size 1G rootfs.img
45
46       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
50           Note
51           The base image name is derived from a pre-defined naming scheme.
52
53   Adding a layer
54       Once a base image exists you can add a layer by running:
55
56           # imgbase layer --add
57
58       This will add a new layer for the latest existing base image.
59
60           Note
61           The layer name is also derived from a pre-defined naming scheme.
62
63   Inspection at runtime
64       A summary over all base images and their layers can be determined by
65       running:
66
67           # imgbase layout
68
69       To get the remaining free space in the used thinpool run:
70
71           # imgbase layout --free-space
72
73   Upgrade to new image
74           # imgbase update --format liveimg FILENAME
75
76       Example:
77
78           # imgbase update ovirt-node-ng-4.0.0-0.999.master.20160329.0.el7.squashfs.img
79
80       To verify a new base image was added:
81
82           # 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
88       To load the new image:
89
90           # reboot
91
92       To verify you are in the new image (after reboot):
93
94           # imgbase w
95           [INFO] You are on ovirt-node-ng-4.0.0-0+1
96
97   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
101       To view the list of LVs that were created by imgbased but are
102       identified as unused:
103
104           # imgbase --experimental recover --list
105
106       To remove unused LVs that were created by imgbased with user
107       confirmation:
108
109           # imgbase --experimental recover
110
111       To remove unused LVs that were created by imgbased without user
112       confirmation (dangerous)
113
114           # imgbase --experimental recover --force
115
116   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
122       ---
123
124       Example 1:
125
126       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
130       # 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
133       # imgbase w [INFO] You are on ovirt-node-ng-4.0.0-0.20160413.0+1
134
135       imgbase rollback with no arguments will revert to the previous version.
136       In this case, ovirt-node-ng-4.0.0.0+1
137
138       # imgbase rollback
139
140       Example 2: rollback to a specific version.
141
142       # imgbase rollback --to ovirt-node-ng-4.0.0-0+1
143
144       After the rollback operation, a reboot is required. # reboot ---
145
146       To verify you are in the new image (after reboot):
147
148           # imgbase w
149           [INFO] You are on ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7+1
150

OPTIONS

152       --debug
153           Output debug informations
154
155       --dry
156           Do not run the commands, just output what would be run.
157
158           Note
159           Combine this with --debug to see the commands This does not work
160           with all commands.
161

ENVIRONMENT

163       You can change the behaviour of imgbase for debugging purposes only
164       with environment variables as follows:
165
166       IMGBASED_KEEP_VOLUMES will not delete any volumes created by imgbase in
167       case of a failing upgrade
168
169       IMGBASED_DISABLE_THREADS will not execute anything in parallel
170

EXAMPLE

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
177           **--vg=_VG_**::
178               By default the volume group +HostVG+ is used. Use this argument to
179               use the volume group name _VG_ instead.
180
181           **--thinpool=_THINPOOL_**::
182               By default the thinpool +ImagePool+ is used. Use this argument to
183               use the thinpool name _THINPOOL_ instead.
184
185           **--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

AVAILABILITY

190       The imgbase command is part of the imgbased package and is available
191       from https://github.com/oVirt/imgbased
192

AUTHORS

194       Fabian Deutsch
195
196
197
198imgbase                           01/29/2020                        IMGBASE(8)
Impressum