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 volumens, 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
162       Example:
163
164           # imgbase --dry --debug layout --init --size 1G /dev/sda
165           ...
166           DEBUG:imgbase:Calling: (['vgcreate', 'HostVG', <open file '/dev/sda', mode 'r'
167           at 0x22bf420>],) {}
168           DEBUG:imgbase:Calling: (['lvcreate', '--size', '1G', '--thin',
169           'HostVG/ImagePool'],) {}
170
171       --vg=VG
172           By default the volume group HostVG is used. Use this argument to
173           use the volume group name VG instead.
174
175       --thinpool=THINPOOL
176           By default the thinpool ImagePool is used. Use this argument to use
177           the thinpool name THINPOOL instead.
178
179       --layerformat=FMT
180           By default the format Base-%d.%d is used to create and discover
181           existing logical volumes. Use this argument to use the format FMT
182           instead.
183

AVAILABILITY

185       The imgbase command is part of the imgbased package and is available
186       from https://github.com/fabiand/imgbased/
187

AUTHORS

189       Fabian Deutsch
190
191
192
193imgbase                           07/25/2019                        IMGBASE(8)
Impressum