1virt-dib(1) Virtualization Support virt-dib(1)
2
3
4
6 virt-dib - Run diskimage-builder elements
7
9 virt-dib -B DIB-LIB [options] elements...
10
12 Virt-dib is a tool for using the elements of "diskimage-builder" to
13 build a new disk image, generate new ramdisks, etc.
14
15 Virt-dib is intended as safe replacement for "diskimage-builder" and
16 its "ramdisk-image-create" mode, see "COMPARISON WITH DISKIMAGE-
17 BUILDER" for a quick comparison with usage of "diskimage-builder".
18
19 "diskimage-builder" is part of the TripleO OpenStack project:
20 https://wiki.openstack.org/wiki/TripleO.
21
23 Build simple images of distributions
24 virt-dib \
25 -B /path/to/diskimage-builder/lib \
26 -p /path/to/diskimage-builder/elements \
27 --envvar DIB_RELEASE=jessie \
28 --name debian-jessie \
29 debian vm
30
31 This builds a Debian Jessie (8.x) disk image, suitable for running as
32 virtual machine, saved as debian-jessie.qcow2.
33
34 Build ramdisks
35 virt-dib \
36 -B /path/to/diskimage-builder/lib \
37 -p /path/to/diskimage-builder/elements \
38 --ramdisk \
39 --name ramdisk \
40 ubuntu deploy-ironic
41
42 This builds a ramdisk for the Ironic OpenStack component based on the
43 Ubuntu distribution.
44
46 --help
47 Display help.
48
49 -B PATH
50 Set the path to the library directory of "diskimage-builder". This
51 is usually the lib subdirectory in the sources and when installed,
52 and /usr/share/diskimage-builder/lib when installed in /usr.
53
54 This parameter is mandatory, as virt-dib needs to provide it for
55 the elements (as some of them might use scripts in it). Virt-dib
56 itself does not make use of the library directory.
57
58 --arch ARCHITECTURE
59 Use the specified architecture for the output image. The default
60 value is the same as the host running virt-dib.
61
62 Right now this option does nothing more than setting the "ARCH"
63 environment variable for the elements, and it’s up to them to
64 produce an image for the requested architecture.
65
66 --checksum
67 Generate checksum files for the generated image. The supported
68 checksums are MD5, and SHA256.
69
70 --colors
71 --colours
72 Use ANSI colour sequences to colourize messages. This is the
73 default when the output is a tty. If the output of the program is
74 redirected to a file, ANSI colour sequences are disabled unless you
75 use this option.
76
77 --debug LEVEL
78 Set the debug level to "LEVEL", which is a non-negative integer
79 number. The default is 0.
80
81 This debug level is different than what -x and -v set, and it
82 increases the debugging information printed out. Specifically,
83 this sets the "DIB_DEBUG_TRACE", and any value > 0 enables tracing
84 in the scripts executed.
85
86 --docker-target TARGET
87 Set the repository and tag for docker.
88
89 This is used only when the formats include "docker", and it is
90 required in that case.
91
92 --drive DISK
93 Add the specified disk to be used as helper drive where to cache
94 files of the elements, like disk images, distribution packages,
95 etc.
96
97 See "HELPER DRIVE".
98
99 --drive-format raw
100 --drive-format qcow2
101 Specify the format of the helper drive. If this flag is not given
102 then it is auto-detected from the drive itself.
103
104 If working with untrusted raw-format guest disk images, you should
105 ensure the format is always specified.
106
107 This option is used only if --drive is specified.
108
109 See "HELPER DRIVE".
110
111 -p PATH
112 --element-path PATH
113 Add a new path with elements. Paths are used in the same order as
114 the -p parameters appear, so a path specified first is looked
115 first, and so on.
116
117 Obviously, it is recommended to add the path to the own elements of
118 "diskimage-builder", as most of the other elements will rely on
119 them.
120
121 --extra-packages PACKAGE,...
122 Install additional packages in the image being built.
123
124 This relies on the "install-packages" binary provided by the
125 package management elements.
126
127 This option can be specified multiple times, each time with
128 multiple packages separated by comma.
129
130 --envvar VARIABLE
131 --envvar VARIABLE=VALUE
132 Carry or set an environment variable for the elements.
133
134 See "ENVIRONMENT VARIABLES" below for more information on the
135 interaction and usage of environment variables.
136
137 This option can be used in two ways:
138
139 --envvar VARIABLE
140 Carry the environment variable "VARIABLE". If it is not set,
141 nothing is exported to the elements.
142
143 --envvar VARIABLE=VALUE
144 Set the environment variable "VARIABLE" with value "VALUE" for
145 the elements, regardless whether an environment variable with
146 the same name exists.
147
148 This can be useful to pass environment variable without
149 exporting them in the environment where virt-dib runs.
150
151 --exclude-element ELEMENT
152 Ignore the specified element.
153
154 --exclude-script SCRIPT
155 Ignore any element script named "SCRIPT", whichever element it is
156 in.
157
158 This can be useful in case some script does not run well with virt-
159 dib, for example when they really need "diskimage-builder"'s
160 environment.
161
162 --formats FORMAT,...
163 Set the list of output formats, separating them with comma.
164
165 Supported formats are:
166
167 "docker"
168 Import the image to docker, running docker import. The target
169 for the image must be specified using --docker-target.
170
171 Please note this operation usually requires the docker service
172 to be enabled, otherwise it will fail. Furthermore, docker is
173 run using sudo(8), so make sure the user has the permissions to
174 run at least docker.
175
176 "qcow2" (enabled by default)
177 QEMU’s qcow2. This output format requires the "qemu-img" tool.
178
179 "raw"
180 Raw disk format.
181
182 "squashfs"
183 An squashfs filesystem, compressed with XZ. This output format
184 requires the "squashfs" feature; see also "AVAILABILITY" in
185 guestfs(3).
186
187 "tar"
188 An uncompressed tarball.
189
190 "tgz"
191 A tarball compressed with gzip.
192
193 "vhd"
194 "Virtual Hard Disk" disk image. This output format requires
195 the "vhd-util" tool.
196
197 Please note that the version of "vhd-util" tool needs to be
198 patched to support the "convert" subcommand, and to be
199 bootable. The patch is available here:
200 https://github.com/emonty/vhd-util/blob/master/debian/patches/citrix.
201
202 --fs-type FILESYSTEM
203 Set the filesystem type to use for the root filesystem. The
204 default is "ext4".
205
206 See also "guestfs_filesystem_available" in guestfs(3).
207
208 --image-cache DIRECTORY
209 Set the path in the host where cache the resources used by the
210 elements of the "extra-data.d" phase. The default is
211 ~/.cache/image-create.
212
213 Please note that most of the resources fetched in phases other than
214 "extra-data.d" will be cached in the helper drive specified with
215 --drive; see also "HELPER DRIVE".
216
217 --install-type TYPE
218 Specify the default installation type. Defaults to "source".
219
220 Set to "package" to use package based installations by default.
221
222 --machine-readable
223 --machine-readable=format
224 This option is used to make the output more machine friendly when
225 being parsed by other programs. See "MACHINE READABLE OUTPUT"
226 below.
227
228 -m MB
229 --memsize MB
230 Change the amount of memory allocated to the appliance. Increase
231 this if you find that the virt-dib execution runs out of memory.
232
233 The default can be found with this command:
234
235 guestfish get-memsize
236
237 --mkfs-options "OPTION STRING"
238 Add the specified options to mkfs(1), to be able to fine-tune the
239 root filesystem creation; the options are passed to the driver of
240 mfks(1), and not to mfks(1) itself. Note that --fs-type is used to
241 change the filesystem type.
242
243 You should use --mkfs-options at most once. To pass multiple
244 options, separate them with space, eg:
245
246 virt-dib ... --mkfs-options '-O someopt -I foo'
247
248 --network
249 --no-network
250 Enable or disable network access from the guest during the
251 installation.
252
253 Enabled is the default. Use --no-network to disable access.
254
255 The network only allows outgoing connections and has other minor
256 limitations. See "NETWORK" in virt-rescue(1).
257
258 This does not affect whether the guest can access the network once
259 it has been booted, because that is controlled by your hypervisor
260 or cloud environment and has nothing to do with virt-dib.
261
262 If you use --no-network, then the environment variable
263 "DIB_OFFLINE" is set to 1, signaling the elements that they should
264 use only cached resources when available. Note also that, unlike
265 with "diskimage-builder" where elements may still be able to access
266 to the network even with "DIB_OFFLINE=", under virt-dib network
267 will not be accessible at all.
268
269 --name NAME
270 Set the name of the output image file. The default is "image".
271
272 According to the chosen name, there will be the following in the
273 current directory:
274
275 $NAME.ext
276 For each output format, a file named after the output image
277 with the extension depending on the format; for example:
278 $NAME.qcow2, $NAME.raw, etc.
279
280 Not applicable in ramdisk mode, see "RAMDISK BUILDING".
281
282 $NAME.d
283 A directory containing any files created by the elements, for
284 example dib-manifests directory (created by the "manifests"
285 element), ramdisks and kernels in ramdisk mode, and so on.
286
287 $NAME.ext.checksum
288 When --checksum is specified, there will be files for each
289 supported checksum type; for example: $NAME.ext.md5,
290 $NAME.ext.sha256, etc.
291
292 Not applicable in ramdisk mode, see "RAMDISK BUILDING".
293
294 --no-delete-on-failure
295 Don’t delete the output files on failure to build. You can use
296 this to debug failures to run scripts.
297
298 The default is to delete the output files if virt-dib fails (or,
299 for example, some script that it runs fails).
300
301 --python PYTHON
302 Specify a different Python interpreter to use. Parts of
303 "diskimage-builder" are implemented in Python, and thus an
304 interpreter is needed.
305
306 "PYTHON" can either be an executable filename (e.g. python2, which
307 is then searched in $PATH), or a full path (e.g.
308 /usr/bin/python2). If not specified, the default value is python.
309
310 -q
311 --quiet
312 Don’t print ordinary progress messages.
313
314 --qemu-img-options option[,option,...]
315 Pass --qemu-img-options option(s) to the qemu-img(1) command to
316 fine-tune the output format. Options available depend on the
317 output format (see --formats) and the installed version of the
318 qemu-img program.
319
320 You should use --qemu-img-options at most once. To pass multiple
321 options, separate them with commas, eg:
322
323 virt-dib ... --qemu-img-options cluster_size=512,preallocation=metadata ...
324
325 --ramdisk
326 Set the ramdisk building mode.
327
328 See "RAMDISK BUILDING".
329
330 --ramdisk-element NAME
331 Set the name for the additional element added in ramdisk building
332 mode. The default is "ramdisk".
333
334 See "RAMDISK BUILDING".
335
336 --root-label LABEL
337 Set the label for the root filesystem in the created image.
338
339 Please note that some filesystems have different restrictions on
340 the length of their labels; for example, on "ext2/3/4" filesystems
341 labels cannot be longer than 16 characters, while on "xfs" they
342 have at most 12 characters.
343
344 The default depends on the actual filesystem for the root partition
345 (see --fs-type): on "xfs" is "img-rootfs", while "cloudimg-rootfs"
346 on any other filesystem.
347
348 --size SIZE
349 Select the size of the output disk, where the size can be specified
350 using common names such as "32G" (32 gigabytes) etc. The default
351 size is "5G".
352
353 To specify size in bytes, the number must be followed by the
354 lowercase letter b, eg: "--size 10737418240b".
355
356 See also virt-resize(1) for resizing partitions of an existing disk
357 image.
358
359 --skip-base
360 Skip the inclusion of the "base" element.
361
362 --smp N
363 Enable N ≥ 2 virtual CPUs for scripts to use.
364
365 -u Do not compress resulting qcow2 images. The default is to compress
366 them.
367
368 -v
369 --verbose
370 Enable debugging messages.
371
372 -V
373 --version
374 Display version number and exit.
375
376 --wrap
377 Wrap error, warning, and informative messages. This is the default
378 when the output is a tty. If the output of the program is
379 redirected to a file, wrapping is disabled unless you use this
380 option.
381
382 -x Enable tracing of libguestfs API calls.
383
385 Unlike with "diskimage-builder", the environment of the host is not
386 inherited in the appliance when running most of the elements (i.e. all
387 except the ones in the "extra-data.d" phase).
388
389 To set environment for the elements being run, it is necessary to tell
390 virt-dib to use them, with the option --envvar. Such option allows to
391 selectively export environment variables when running the elements, and
392 it is the preferred way to pass environment variables to the elements.
393
394 To recap: if you want the environment variable "MYVAR" (and its
395 content) to be available to the elements, you can do either
396
397 export MYVAR # whichever is its value
398 virt-dib ... --envvar MYVAR ...
399
400 or
401
402 virt-dib ... --envvar MYVAR=value_of_it ...
403
405 Virt-dib runs most of the element in its own appliance, and thus not on
406 the host. Because of this, there is no possibility for elements to
407 cache resources directly on the host.
408
409 To solve this issue, virt-dib allows the usage of an helper drive where
410 to store cached resources, like disk images, distribution packages,
411 etc. While this means that there is a smaller space available for
412 caching, at least it allows to limit the space on the host for caches,
413 without assuming that elements will do that by themselves.
414
415 Currently this disk is either required to have a single partition on
416 it, or the first partition on it will be used. A disk with the latter
417 configuration can be easily created with guestfish(1) like the
418 following:
419
420 guestfish -N filename.img=fs:ext4:10G exit
421
422 The above will create a disk image called filename.img, 10G big, with a
423 single partition of type ext4; see "PREPARED DISK IMAGES" in
424 guestfish(1).
425
426 It is recommended for it to be ≥ 10G or even more, as elements will
427 cache disk images, distribution packages, etc. As with any disk image,
428 the helper disk can be easily resized using virt-resize(1) if more
429 space in it is needed.
430
431 The drive can be accessed like any other disk image, for example using
432 other tools of libguestfs such as guestfish(1):
433
434 guestfish -a filename.img -m /dev/sda1
435
436 If no helper drive is specified with --drive, all the resources cached
437 during a virt-dib run will be discarded.
438
439 RESOURCES INSIDE THE DRIVE
440 Inside the helper drive, it is possible to find the following
441 resources:
442
443 /home
444 This directory is set as "HOME" environment variable during the
445 build. It contains mostly the image cache (saved as
446 /home/.cache/image-create), and whichever other resource is cached
447 in the home directory of the user running the various tools.
448
449 /virt-dib-*.log
450 These are the logs of the elements being run within the libguestfs
451 appliance, which means all the phases except "extra-data.d".
452
454 Virt-dib can emulate also "ramdisk-image-create", which is a secondary
455 operation mode of "diskimage-builder". Instead of being a different
456 tool name, virt-dib provides easy access to this mode using the
457 --ramdisk switch.
458
459 In this mode:
460
461 • there is an additional ramdisk element added (see
462 --ramdisk-element)
463
464 • no image is produced (so --formats is ignored)
465
466 • $NAME.d (see --name) will contain initrd, kernel, etc
467
469 Virt-dib uses the standard temporary directory used by libguestfs, see
470 "ENVIRONMENT VARIABLES" in guestfs(3).
471
472 By default this location is /tmp (default value for "TMPDIR"), which on
473 some systems may be on a tmpfs filesystem, and thus defaulting to a
474 maximum size of half of physical RAM. If virt-dib exceeds this, it may
475 hang or exit early with an error. The solution is to point "TMPDIR" to
476 a permanent location used as temporary location, for example:
477
478 mkdir local-tmp
479 env TMPDIR=$PWD/local-tmp virt-dib ...
480 rm -rf local-tmp
481
483 Because of virt-dib runs most of the elements in its own appliance, all
484 the tools and libraries used by elements running outside the guest
485 (typically "root.d", "block-device.d", and "cleanup.d") need to be
486 present in the appliance as well. In case they are not, scripts will
487 fail typically with a "command not found" error.
488
489 For tools and libraries packaged by the distribution, the easy solution
490 is to tell libguestfs to include additional packages in the appliance.
491 This is doable by e.g. creating a new file with the additional
492 packages:
493
494 # echo wget > /usr/lib64/guestfs/supermin.d/dib-my-extra
495
496 The actual path to the supermin.d directory depends on the
497 distribution; additional files can list more packages, each in its own
498 line. For more details, see supermin(1).
499
501 Virt-dib is intended as safe replacement for "diskimage-builder" and
502 its "ramdisk-image-create" mode; the user-notable differences consist
503 in:
504
505 • the command line arguments; some of the arguments are the same as
506 available in "diskimage-builder", while some have different names:
507
508 disk-image-create virt-dib
509 ----------------- --------
510 -a ARCH --arch ARCH
511 --image-size SIZE --size SIZE
512 --max-online-resize SIZE doable using --mkfs-options
513 -n --skip-base
514 -o IMAGENAME --name IMAGENAME
515 -p PACKAGE(S) --extra-packages PACKAGE(S)
516 -t FORMAT(S) --formats FORMAT(S)
517 -x --debug 1
518 -x -x --debug 2
519 -x -x [-x ...] --debug 3/4/etc
520
521 • the location of non-image output files (like ramdisks and kernels)
522
523 • the way some of the cached resources are saved: using an helper
524 drive, not directly on the disk where virt-dib is run
525
526 • the need to specify a target size for the output disk, as opposed
527 to "diskimage-builder" calculating an optimal one
528
529 • the handling of environment variables, see "ENVIRONMENT VARIABLES".
530
531 Furthermore, other than the libguestfs own environment variables
532 (see "ENVIRONMENT VARIABLES" in guestfs(3)), virt-dib does not read
533 any other environment variable: this means that all the options and
534 behaviour changes are specified solely using command line arguments
535
536 • extra tools needed on some out-of-chroot phases need to be
537 available in the appliance, see "EXTRA DEPENDENCIES".
538
539 Elements themselves should notice no difference in they way they are
540 run; behaviour differences may due to wrong assumptions in elements, or
541 not correct virt-dib emulation.
542
543 Known issues at the moment:
544
545 • (none)
546
548 The --machine-readable option can be used to make the output more
549 machine friendly, which is useful when calling virt-dib from other
550 programs, GUIs etc.
551
552 Use the option on its own to query the capabilities of the virt-dib
553 binary. Typical output looks like this:
554
555 $ virt-dib --machine-readable
556 virt-dib
557 output:qcow2
558 output:tar
559 output:raw
560 output:vhd
561
562 A list of features is printed, one per line, and the program exits with
563 status 0.
564
565 The "output:" features refer to the output formats (--formats command
566 line option) supported by this binary.
567
568 It is possible to specify a format string for controlling the output;
569 see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
570
572 Virt-dib has been tested with "diskimage-builder" (and its elements) ≥
573 0.1.43; from time to time also with "tripleo-image-elements" and
574 "sahara-image-elements".
575
576 Previous versions may work, but it is not guaranteed.
577
579 This program returns 0 if successful, or non-zero if there was an
580 error.
581
583 guestfs(3), guestfish(1), virt-resize(1), http://libguestfs.org/.
584
586 Pino Toscano ("ptoscano at redhat dot com")
587
589 Copyright (C) 2015 Red Hat Inc.
590
592 This program is free software; you can redistribute it and/or modify it
593 under the terms of the GNU General Public License as published by the
594 Free Software Foundation; either version 2 of the License, or (at your
595 option) any later version.
596
597 This program is distributed in the hope that it will be useful, but
598 WITHOUT ANY WARRANTY; without even the implied warranty of
599 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
600 General Public License for more details.
601
602 You should have received a copy of the GNU General Public License along
603 with this program; if not, write to the Free Software Foundation, Inc.,
604 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
605
607 To get a list of bugs against libguestfs, use this link:
608 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
609
610 To report a new bug against libguestfs, use this link:
611 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
612
613 When reporting a bug, please supply:
614
615 • The version of libguestfs.
616
617 • Where you got libguestfs (eg. which Linux distro, compiled from
618 source, etc)
619
620 • Describe the bug accurately and give a way to reproduce it.
621
622 • Run libguestfs-test-tool(1) and paste the complete, unedited output
623 into the bug report.
624
625
626
627guestfs-tools-1.48.2 2022-05-26 virt-dib(1)