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           This option is used to make the output more machine friendly when
224           being parsed by other programs.  See "MACHINE READABLE OUTPUT"
225           below.
226
227       -m MB
228       --memsize MB
229           Change the amount of memory allocated to the appliance. Increase
230           this if you find that the virt-dib execution runs out of memory.
231
232           The default can be found with this command:
233
234            guestfish get-memsize
235
236       --mkfs-options "OPTION STRING"
237           Add the specified options to mkfs(1), to be able to fine-tune the
238           root filesystem creation; the options are passed to the driver of
239           mfks(1), and not to mfks(1) itself.  Note that --fs-type is used to
240           change the filesystem type.
241
242           You should use --mkfs-options at most once.  To pass multiple
243           options, separate them with space, eg:
244
245            virt-dib ... --mkfs-options '-O someopt -I foo'
246
247       --network
248       --no-network
249           Enable or disable network access from the guest during the
250           installation.
251
252           Enabled is the default.  Use --no-network to disable access.
253
254           The network only allows outgoing connections and has other minor
255           limitations.  See "NETWORK" in virt-rescue(1).
256
257           This does not affect whether the guest can access the network once
258           it has been booted, because that is controlled by your hypervisor
259           or cloud environment and has nothing to do with virt-dib.
260
261           If you use --no-network, then the environment variable
262           "DIB_OFFLINE" is set to 1, signaling the elements that they should
263           use only cached resources when available.  Note also that, unlike
264           with "diskimage-builder" where elements may still be able to access
265           to the network even with "DIB_OFFLINE=", under virt-dib network
266           will not be accessible at all.
267
268       --name NAME
269           Set the name of the output image file.  The default is "image".
270
271           According to the chosen name, there will be the following in the
272           current directory:
273
274           $NAME.ext
275               For each output format, a file named after the output image
276               with the extension depending on the format; for example:
277               $NAME.qcow2, $NAME.raw, etc.
278
279               Not applicable in ramdisk mode, see "RAMDISK BUILDING".
280
281           $NAME.d
282               A directory containing any files created by the elements, for
283               example dib-manifests directory (created by the "manifests"
284               element), ramdisks and kernels in ramdisk mode, and so on.
285
286           $NAME.ext.checksum
287               When --checksum is specified, there will be files for each
288               supported checksum type; for example: $NAME.ext.md5,
289               $NAME.ext.sha256, etc.
290
291               Not applicable in ramdisk mode, see "RAMDISK BUILDING".
292
293       --no-delete-on-failure
294           Don’t delete the output files on failure to build.  You can use
295           this to debug failures to run scripts.
296
297           The default is to delete the output files if virt-dib fails (or,
298           for example, some script that it runs fails).
299
300       --python PYTHON
301           Specify a different Python interpreter to use.  Parts of
302           "diskimage-builder" are implemented in Python, and thus an
303           interpreter is needed.
304
305           "PYTHON" can either be an executable filename (e.g. python2, which
306           is then searched in $PATH), or a full path (e.g.
307           /usr/bin/python2).  If not specified, the default value is python.
308
309       -q
310       --quiet
311           Don’t print ordinary progress messages.
312
313       --qemu-img-options option[,option,...]
314           Pass --qemu-img-options option(s) to the qemu-img(1) command to
315           fine-tune the output format.  Options available depend on the
316           output format (see --formats) and the installed version of the
317           qemu-img program.
318
319           You should use --qemu-img-options at most once.  To pass multiple
320           options, separate them with commas, eg:
321
322            virt-dib ... --qemu-img-options cluster_size=512,preallocation=metadata ...
323
324       --ramdisk
325           Set the ramdisk building mode.
326
327           See "RAMDISK BUILDING".
328
329       --ramdisk-element NAME
330           Set the name for the additional element added in ramdisk building
331           mode.  The default is "ramdisk".
332
333           See "RAMDISK BUILDING".
334
335       --root-label LABEL
336           Set the label for the root filesystem in the created image.
337
338           Please note that some filesystems have different restrictions on
339           the length of their labels; for example, on "ext2/3/4" filesystems
340           labels cannot be longer than 16 characters, while on "xfs" they
341           have at most 12 characters.
342
343           The default depends on the actual filesystem for the root partition
344           (see --fs-type): on "xfs" is "img-rootfs", while "cloudimg-rootfs"
345           on any other filesystem.
346
347       --size SIZE
348           Select the size of the output disk, where the size can be specified
349           using common names such as "32G" (32 gigabytes) etc.  The default
350           size is "5G".
351
352           To specify size in bytes, the number must be followed by the
353           lowercase letter b, eg: "--size 10737418240b".
354
355           See also virt-resize(1) for resizing partitions of an existing disk
356           image.
357
358       --skip-base
359           Skip the inclusion of the "base" element.
360
361       --smp N
362           Enable N ≥ 2 virtual CPUs for scripts to use.
363
364       -u  Do not compress resulting qcow2 images.  The default is to compress
365           them.
366
367       -v
368       --verbose
369           Enable debugging messages.
370
371       -V
372       --version
373           Display version number and exit.
374
375       -x  Enable tracing of libguestfs API calls.
376

ENVIRONMENT VARIABLES

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

HELPER DRIVE

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

RAMDISK BUILDING

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

TEMPORARY DIRECTORY

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

EXTRA DEPENDENCIES

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

COMPARISON WITH DISKIMAGE-BUILDER

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

MACHINE READABLE OUTPUT

541       The --machine-readable option can be used to make the output more
542       machine friendly, which is useful when calling virt-dib from other
543       programs, GUIs etc.
544
545       Use the option on its own to query the capabilities of the virt-dib
546       binary.  Typical output looks like this:
547
548        $ virt-dib --machine-readable
549        virt-dib
550        output:qcow2
551        output:tar
552        output:raw
553        output:vhd
554
555       A list of features is printed, one per line, and the program exits with
556       status 0.
557
558       The "output:" features refer to the output formats (--formats command
559       line option) supported by this binary.
560

TESTING

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

EXIT STATUS

569       This program returns 0 if successful, or non-zero if there was an
570       error.
571

SEE ALSO

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

AUTHOR

576       Pino Toscano ("ptoscano at redhat dot com")
577
579       Copyright (C) 2015 Red Hat Inc.
580

LICENSE

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

BUGS

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