virt-dib(1) | Virtualization Support | virt-dib(1) |
virt-dib - Run diskimage-builder elements
virt-dib -B DIB-LIB [options] elements...
Virt-dib is a tool for using the elements of "diskimage-builder" to build a new disk image, generate new ramdisks, etc.
Virt-dib is intended as safe replacement for "diskimage-builder" and its "ramdisk-image-create" mode, see "COMPARISON WITH DISKIMAGE-BUILDER" for a quick comparison with usage of "diskimage-builder".
"diskimage-builder" is part of the TripleO OpenStack project: https://wiki.openstack.org/wiki/TripleO.
virt-dib \ -B /path/to/diskimage-builder/lib \ -p /path/to/diskimage-builder/elements \ --envvar DIB_RELEASE=jessie \ --name debian-jessie \ debian vm
This builds a Debian Jessie (8.x) disk image, suitable for running as virtual machine, saved as debian-jessie.qcow2.
virt-dib \ -B /path/to/diskimage-builder/lib \ -p /path/to/diskimage-builder/elements \ --ramdisk \ --name ramdisk \ ubuntu deploy-ironic
This builds a ramdisk for the Ironic OpenStack component based on the Ubuntu distribution.
This parameter is mandatory, as virt-dib needs to provide it for the elements (as some of them might use scripts in it). Virt-dib itself does not make use of the library directory.
Right now this option does nothing more than setting the "ARCH" environment variable for the elements, and it’s up to them to produce an image for the requested architecture.
This debug level is different than what -x and -v set, and it increases the debugging information printed out. Specifically, this sets the "DIB_DEBUG_TRACE", and any value > 0 enables tracing in the scripts executed.
This is used only when the formats include "docker", and it is required in that case.
See "HELPER DRIVE".
If working with untrusted raw-format guest disk images, you should ensure the format is always specified.
This option is used only if --drive is specified.
See "HELPER DRIVE".
Obviously, it is recommended to add the path to the own elements of "diskimage-builder", as most of the other elements will rely on them.
This relies on the "install-packages" binary provided by the package management elements.
This option can be specified multiple times, each time with multiple packages separated by comma.
See "ENVIRONMENT VARIABLES" below for more information on the interaction and usage of environment variables.
This option can be used in two ways:
This can be useful to pass environment variable without exporting them in the environment where virt-dib runs.
This can be useful in case some script does not run well with virt-dib, for example when they really need "diskimage-builder"'s environment.
Supported formats are:
Please note this operation usually requires the docker service to be enabled, otherwise it will fail. Furthermore, docker is run using sudo(8), so make sure the user has the permissions to run at least docker.
Please note that the version of "vhd-util" tool needs to be patched to support the "convert" subcommand, and to be bootable. The patch is available here: https://github.com/emonty/vhd-util/blob/master/debian/patches/citrix.
See also "guestfs_filesystem_available" in guestfs(3).
Please note that most of the resources fetched in phases other than "extra-data.d" will be cached in the helper drive specified with --drive; see also "HELPER DRIVE".
Set to "package" to use package based installations by default.
The default can be found with this command:
guestfish get-memsize
You should use --mkfs-options at most once. To pass multiple options, separate them with space, eg:
virt-dib ... --mkfs-options '-O someopt -I foo'
Enabled is the default. Use --no-network to disable access.
The network only allows outgoing connections and has other minor limitations. See "NETWORK" in virt-rescue(1).
This does not affect whether the guest can access the network once it has been booted, because that is controlled by your hypervisor or cloud environment and has nothing to do with virt-dib.
If you use --no-network, then the environment variable "DIB_OFFLINE" is set to 1, signaling the elements that they should use only cached resources when available. Note also that, unlike with "diskimage-builder" where elements may still be able to access to the network even with "DIB_OFFLINE=", under virt-dib network will not be accessible at all.
According to the chosen name, there will be the following in the current directory:
Not applicable in ramdisk mode, see "RAMDISK BUILDING".
Not applicable in ramdisk mode, see "RAMDISK BUILDING".
The default is to delete the output files if virt-dib fails (or, for example, some script that it runs fails).
"PYTHON" can either be an executable filename (e.g. python2, which is then searched in $PATH), or a full path (e.g. /usr/bin/python2). If not specified, the default value is python.
You should use --qemu-img-options at most once. To pass multiple options, separate them with commas, eg:
virt-dib ... --qemu-img-options cluster_size=512,preallocation=metadata ...
See "RAMDISK BUILDING".
See "RAMDISK BUILDING".
Please note that some filesystems have different restrictions on the length of their labels; for example, on "ext2/3/4" filesystems labels cannot be longer than 16 characters, while on "xfs" they have at most 12 characters.
The default depends on the actual filesystem for the root partition (see --fs-type): on "xfs" is "img-rootfs", while "cloudimg-rootfs" on any other filesystem.
To specify size in bytes, the number must be followed by the lowercase letter b, eg: "--size 10737418240b".
See also virt-resize(1) for resizing partitions of an existing disk image.
Unlike with "diskimage-builder", the environment of the host is not inherited in the appliance when running most of the elements (i.e. all except the ones in the "extra-data.d" phase).
To set environment for the elements being run, it is necessary to tell virt-dib to use them, with the option --envvar. Such option allows to selectively export environment variables when running the elements, and it is the preferred way to pass environment variables to the elements.
To recap: if you want the environment variable "MYVAR" (and its content) to be available to the elements, you can do either
export MYVAR # whichever is its value virt-dib ... --envvar MYVAR ...
or
virt-dib ... --envvar MYVAR=value_of_it ...
Virt-dib runs most of the element in its own appliance, and thus not on the host. Because of this, there is no possibility for elements to cache resources directly on the host.
To solve this issue, virt-dib allows the usage of an helper drive where to store cached resources, like disk images, distribution packages, etc. While this means that there is a smaller space available for caching, at least it allows to limit the space on the host for caches, without assuming that elements will do that by themselves.
Currently this disk is either required to have a single partition on it, or the first partition on it will be used. A disk with the latter configuration can be easily created with guestfish(1) like the following:
guestfish -N filename.img=fs:ext4:10G exit
The above will create a disk image called filename.img, 10G big, with a single partition of type ext4; see "PREPARED DISK IMAGES" in guestfish(1).
It is recommended for it to be ≥ 10G or even more, as elements will cache disk images, distribution packages, etc. As with any disk image, the helper disk can be easily resized using virt-resize(1) if more space in it is needed.
The drive can be accessed like any other disk image, for example using other tools of libguestfs such as guestfish(1):
guestfish -a filename.img -m /dev/sda1
If no helper drive is specified with --drive, all the resources cached during a virt-dib run will be discarded.
Inside the helper drive, it is possible to find the following resources:
Virt-dib can emulate also "ramdisk-image-create", which is a secondary operation mode of "diskimage-builder". Instead of being a different tool name, virt-dib provides easy access to this mode using the --ramdisk switch.
In this mode:
Virt-dib uses the standard temporary directory used by libguestfs, see "ENVIRONMENT VARIABLES" in guestfs(3).
By default this location is /tmp (default value for "TMPDIR"), which on some systems may be on a tmpfs filesystem, and thus defaulting to a maximum size of half of physical RAM. If virt-dib exceeds this, it may hang or exit early with an error. The solution is to point "TMPDIR" to a permanent location used as temporary location, for example:
mkdir local-tmp env TMPDIR=$PWD/local-tmp virt-dib ... rm -rf local-tmp
Because of virt-dib runs most of the elements in its own appliance, all the tools and libraries used by elements running outside the guest (typically "root.d", "block-device.d", and "cleanup.d") need to be present in the appliance as well. In case they are not, scripts will fail typically with a "command not found" error.
For tools and libraries packaged by the distribution, the easy solution is to tell libguestfs to include additional packages in the appliance. This is doable by e.g. creating a new file with the additional packages:
# echo wget > /usr/lib64/guestfs/supermin.d/dib-my-extra
The actual path to the supermin.d directory depends on the distribution; additional files can list more packages, each in its own line. For more details, see supermin(1).
Virt-dib is intended as safe replacement for "diskimage-builder" and its "ramdisk-image-create" mode; the user-notable differences consist in:
disk-image-create virt-dib ----------------- -------- -a ARCH --arch ARCH --image-size SIZE --size SIZE --max-online-resize SIZE doable using --mkfs-options -n --skip-base -o IMAGENAME --name IMAGENAME -p PACKAGE(S) --extra-packages PACKAGE(S) -t FORMAT(S) --formats FORMAT(S) -x --debug 1 -x -x --debug 2 -x -x [-x ...] --debug 3/4/etc
Furthermore, other than the libguestfs own environment variables (see "ENVIRONMENT VARIABLES" in guestfs(3)), virt-dib does not read any other environment variable: this means that all the options and behaviour changes are specified solely using command line arguments
Elements themselves should notice no difference in they way they are run; behaviour differences may due to wrong assumptions in elements, or not correct virt-dib emulation.
Known issues at the moment:
The --machine-readable option can be used to make the output more machine friendly, which is useful when calling virt-dib from other programs, GUIs etc.
Use the option on its own to query the capabilities of the virt-dib binary. Typical output looks like this:
$ virt-dib --machine-readable virt-dib output:qcow2 output:tar output:raw output:vhd
A list of features is printed, one per line, and the program exits with status 0.
The "output:" features refer to the output formats (--formats command line option) supported by this binary.
It is possible to specify a format string for controlling the output; see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
Virt-dib has been tested with "diskimage-builder" (and its elements) ≥ 0.1.43; from time to time also with "tripleo-image-elements" and "sahara-image-elements".
Previous versions may work, but it is not guaranteed.
This program returns 0 if successful, or non-zero if there was an error.
guestfs(3), guestfish(1), virt-resize(1), http://libguestfs.org/.
Pino Toscano ("ptoscano at redhat dot com")
Copyright (C) 2015 Red Hat Inc.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
When reporting a bug, please supply:
2023-05-23 | guestfs-tools-1.48.2 |