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   Rollback to previous image
98       If you have updated and would like to return to a previous version. The
99       rollback operation will set the bootloader to an earlier version. This
100       defaults to rolling back one update. If you would like to return to a
101       specific version, use --to.
102
103       ---
104
105       Example 1:
106
107       The example below has two layers: ovirt-node-ng-4.0.0+1, and
108       ovirt-node-ng-4.0.0-20160413.0+1. ovirt-node-ng-4.0.0-20160413.0+1 is
109       the active layer, as shown below.
110
111       # imgbase layout ovirt-node-ng-4.0.0-0 └╼ ovirt-node-ng-4.0.0-0+1
112       ovirt-node-ng-4.0.0-0.20160413.0 └╼ ovirt-node-ng-4.0.0-0.20160413.0+1
113
114       # imgbase w [INFO] You are on ovirt-node-ng-4.0.0-0.20160413.0+1
115
116       imgbase rollback with no arguments will revert to the previous version.
117       In this case, ovirt-node-ng-4.0.0.0+1
118
119       # imgbase rollback
120
121       Example 2: rollback to a specific version.
122
123       # imgbase rollback --to ovirt-node-ng-4.0.0-0+1
124
125       After the rollback operation, a reboot is required. # reboot ---
126
127       To verify you are in the new image (after reboot):
128
129           # imgbase w
130           [INFO] You are on ovirt-node-ng-4.0.0-0.3.master.20160330132038.el7+1
131

OPTIONS

133       --debug
134           Output debug informations
135
136       --dry
137           Do not run the commands, just output what would be run.
138
139           Note
140           Combine this with --debug to see the commands This does not work
141           with all commands.
142
143       Example:
144
145           # imgbase --dry --debug layout --init --size 1G /dev/sda
146           ...
147           DEBUG:imgbase:Calling: (['vgcreate', 'HostVG', <open file '/dev/sda', mode 'r'
148           at 0x22bf420>],) {}
149           DEBUG:imgbase:Calling: (['lvcreate', '--size', '1G', '--thin',
150           'HostVG/ImagePool'],) {}
151
152       --vg=VG
153           By default the volume group HostVG is used. Use this argument to
154           use the volume group name VG instead.
155
156       --thinpool=THINPOOL
157           By default the thinpool ImagePool is used. Use this argument to use
158           the thinpool name THINPOOL instead.
159
160       --layerformat=FMT
161           By default the format Base-%d.%d is used to create and discover
162           existing logical volumes. Use this argument to use the format FMT
163           instead.
164

AVAILABILITY

166       The imgbase command is part of the imgbased package and is available
167       from https://github.com/fabiand/imgbased/
168

AUTHORS

170       Fabian Deutsch
171
172
173
174imgbase                           07/23/2018                        IMGBASE(8)