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       -x  Enable tracing of libguestfs API calls.
377

ENVIRONMENT VARIABLES

379       Unlike with "diskimage-builder", the environment of the host is not
380       inherited in the appliance when running most of the elements (i.e. all
381       except the ones in the "extra-data.d" phase).
382
383       To set environment for the elements being run, it is necessary to tell
384       virt-dib to use them, with the option --envvar.  Such option allows to
385       selectively export environment variables when running the elements, and
386       it is the preferred way to pass environment variables to the elements.
387
388       To recap: if you want the environment variable "MYVAR" (and its
389       content) to be available to the elements, you can do either
390
391        export MYVAR   # whichever is its value
392        virt-dib ... --envvar MYVAR ...
393
394       or
395
396        virt-dib ... --envvar MYVAR=value_of_it ...
397

HELPER DRIVE

399       Virt-dib runs most of the element in its own appliance, and thus not on
400       the host.  Because of this, there is no possibility for elements to
401       cache resources directly on the host.
402
403       To solve this issue, virt-dib allows the usage of an helper drive where
404       to store cached resources, like disk images, distribution packages,
405       etc. While this means that there is a smaller space available for
406       caching, at least it allows to limit the space on the host for caches,
407       without assuming that elements will do that by themselves.
408
409       Currently this disk is either required to have a single partition on
410       it, or the first partition on it will be used.  A disk with the latter
411       configuration can be easily created with guestfish(1) like the
412       following:
413
414        guestfish -N filename.img=fs:ext4:10G exit
415
416       The above will create a disk image called filename.img, 10G big, with a
417       single partition of type ext4; see "PREPARED DISK IMAGES" in
418       guestfish(1).
419
420       It is recommended for it to be ≥ 10G or even more, as elements will
421       cache disk images, distribution packages, etc.  As with any disk image,
422       the helper disk can be easily resized using virt-resize(1) if more
423       space in it is needed.
424
425       The drive can be accessed like any other disk image, for example using
426       other tools of libguestfs such as guestfish(1):
427
428        guestfish -a filename.img -m /dev/sda1
429
430       If no helper drive is specified with --drive, all the resources cached
431       during a virt-dib run will be discarded.
432
433   RESOURCES INSIDE THE DRIVE
434       Inside the helper drive, it is possible to find the following
435       resources:
436
437       /home
438           This directory is set as "HOME" environment variable during the
439           build.  It contains mostly the image cache (saved as
440           /home/.cache/image-create), and whichever other resource is cached
441           in the home directory of the user running the various tools.
442
443       /virt-dib-*.log
444           These are the logs of the elements being run within the libguestfs
445           appliance, which means all the phases except "extra-data.d".
446

RAMDISK BUILDING

448       Virt-dib can emulate also "ramdisk-image-create", which is a secondary
449       operation mode of "diskimage-builder".  Instead of being a different
450       tool name, virt-dib provides easy access to this mode using the
451       --ramdisk switch.
452
453       In this mode:
454
455       ·   there is an additional ramdisk element added (see
456           --ramdisk-element)
457
458       ·   no image is produced (so --formats is ignored)
459
460       ·   $NAME.d (see --name) will contain initrd, kernel, etc
461

TEMPORARY DIRECTORY

463       Virt-dib uses the standard temporary directory used by libguestfs, see
464       "ENVIRONMENT VARIABLES" in guestfs(3).
465
466       By default this location is /tmp (default value for "TMPDIR"), which on
467       some systems may be on a tmpfs filesystem, and thus defaulting to a
468       maximum size of half of physical RAM.  If virt-dib exceeds this, it may
469       hang or exit early with an error.  The solution is to point "TMPDIR" to
470       a permanent location used as temporary location, for example:
471
472        mkdir local-tmp
473        env TMPDIR=$PWD/local-tmp virt-dib ...
474        rm -rf local-tmp
475

EXTRA DEPENDENCIES

477       Because of virt-dib runs most of the elements in its own appliance, all
478       the tools and libraries used by elements running outside the guest
479       (typically "root.d", "block-device.d", and "cleanup.d") need to be
480       present in the appliance as well.  In case they are not, scripts will
481       fail typically with a "command not found" error.
482
483       For tools and libraries packaged by the distribution, the easy solution
484       is to tell libguestfs to include additional packages in the appliance.
485       This is doable by e.g. creating a new file with the additional
486       packages:
487
488        # echo wget > /usr/lib64/guestfs/supermin.d/dib-my-extra
489
490       The actual path to the supermin.d directory depends on the
491       distribution; additional files can list more packages, each in its own
492       line.  For more details, see supermin(1).
493

COMPARISON WITH DISKIMAGE-BUILDER

495       Virt-dib is intended as safe replacement for "diskimage-builder" and
496       its "ramdisk-image-create" mode; the user-notable differences consist
497       in:
498
499       ·   the command line arguments; some of the arguments are the same as
500           available in "diskimage-builder", while some have different names:
501
502            disk-image-create             virt-dib
503            -----------------             --------
504            -a ARCH                       --arch ARCH
505            --image-size SIZE             --size SIZE
506            --max-online-resize SIZE      doable using --mkfs-options
507            -n                            --skip-base
508            -o IMAGENAME                  --name IMAGENAME
509            -p PACKAGE(S)                 --extra-packages PACKAGE(S)
510            -t FORMAT(S)                  --formats FORMAT(S)
511            -x                            --debug 1
512            -x -x                         --debug 2
513            -x -x [-x ...]                --debug 3/4/etc
514
515       ·   the location of non-image output files (like ramdisks and kernels)
516
517       ·   the way some of the cached resources are saved: using an helper
518           drive, not directly on the disk where virt-dib is run
519
520       ·   the need to specify a target size for the output disk, as opposed
521           to "diskimage-builder" calculating an optimal one
522
523       ·   the handling of environment variables, see "ENVIRONMENT VARIABLES".
524
525           Furthermore, other than the libguestfs own environment variables
526           (see "ENVIRONMENT VARIABLES" in guestfs(3)), virt-dib does not read
527           any other environment variable: this means that all the options and
528           behaviour changes are specified solely using command line arguments
529
530       ·   extra tools needed on some out-of-chroot phases need to be
531           available in the appliance, see "EXTRA DEPENDENCIES".
532
533       Elements themselves should notice no difference in they way they are
534       run; behaviour differences may due to wrong assumptions in elements, or
535       not correct virt-dib emulation.
536
537       Known issues at the moment:
538
539       ·   (none)
540

MACHINE READABLE OUTPUT

542       The --machine-readable option can be used to make the output more
543       machine friendly, which is useful when calling virt-dib from other
544       programs, GUIs etc.
545
546       Use the option on its own to query the capabilities of the virt-dib
547       binary.  Typical output looks like this:
548
549        $ virt-dib --machine-readable
550        virt-dib
551        output:qcow2
552        output:tar
553        output:raw
554        output:vhd
555
556       A list of features is printed, one per line, and the program exits with
557       status 0.
558
559       The "output:" features refer to the output formats (--formats command
560       line option) supported by this binary.
561
562       It is possible to specify a format string for controlling the output;
563       see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
564

TESTING

566       Virt-dib has been tested with "diskimage-builder" (and its elements) ≥
567       0.1.43; from time to time also with "tripleo-image-elements" and
568       "sahara-image-elements".
569
570       Previous versions may work, but it is not guaranteed.
571

EXIT STATUS

573       This program returns 0 if successful, or non-zero if there was an
574       error.
575

SEE ALSO

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

AUTHOR

580       Pino Toscano ("ptoscano at redhat dot com")
581
583       Copyright (C) 2015 Red Hat Inc.
584

LICENSE

586       This program is free software; you can redistribute it and/or modify it
587       under the terms of the GNU General Public License as published by the
588       Free Software Foundation; either version 2 of the License, or (at your
589       option) any later version.
590
591       This program is distributed in the hope that it will be useful, but
592       WITHOUT ANY WARRANTY; without even the implied warranty of
593       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
594       General Public License for more details.
595
596       You should have received a copy of the GNU General Public License along
597       with this program; if not, write to the Free Software Foundation, Inc.,
598       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
599

BUGS

601       To get a list of bugs against libguestfs, use this link:
602       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
603
604       To report a new bug against libguestfs, use this link:
605       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
606
607       When reporting a bug, please supply:
608
609       ·   The version of libguestfs.
610
611       ·   Where you got libguestfs (eg. which Linux distro, compiled from
612           source, etc)
613
614       ·   Describe the bug accurately and give a way to reproduce it.
615
616       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
617           into the bug report.
618
619
620
621libguestfs-1.44.0                 2021-01-05                       virt-dib(1)
Impressum