1virt-dib(1)                 Virtualization Support                 virt-dib(1)
2
3
4

NAME

6       virt-dib - Run diskimage-builder elements
7

SYNOPSIS

9        virt-dib -B DIB-LIB [options] elements...
10

DESCRIPTION

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

EXAMPLES

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

OPTIONS

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

ENVIRONMENT VARIABLES

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

HELPER DRIVE

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

RAMDISK BUILDING

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

TEMPORARY DIRECTORY

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

EXTRA DEPENDENCIES

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

COMPARISON WITH DISKIMAGE-BUILDER

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

MACHINE READABLE OUTPUT

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

TESTING

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

EXIT STATUS

579       This program returns 0 if successful, or non-zero if there was an
580       error.
581

SEE ALSO

583       guestfs(3), guestfish(1), virt-resize(1), http://libguestfs.org/.
584

AUTHOR

586       Pino Toscano ("ptoscano at redhat dot com")
587
589       Copyright (C) 2015 Red Hat Inc.
590

LICENSE

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

BUGS

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.49.7              2022-12-10                       virt-dib(1)
Impressum