Provided by: libguestfs-tools_1.36.13-1ubuntu3.3_amd64 
НАЗВА
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 /шлях/до/diskimage-builder/lib \
-p /шлях/до/diskimage-builder/elements \
--envvar DIB_RELEASE=jessie \
--name debian-jessie \
debian vm
Ця команда збирає образ диска Debian Jessie (8.x), який є придатним для запуску у форматі
віртуальної машини, який буде збережено як debian-jessie.qcow2.
Збирання дисків у пам’яті
virt-dib \
-B /шлях/до/diskimage-builder/lib \
-p /шлях/до/diskimage-builder/elements \
--ramdisk \
--name ramdisk \
ubuntu deploy-ironic
Ця команда збирає диск у пам’яті для компонента Ironic OpenStack на основі дистрибутива
Ubuntu.
ПАРАМЕТРИ
--help
Показати довідкове повідомлення.
-B ШЛЯХ
Set the path to the library directory of "diskimage-builder". This is usually the lib
subdirectory in the sources and when installed, and /usr/share/diskimage-builder/lib
when installed in /usr.
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.
--arch АРХІТЕКТУРА
Використовувати для образу-результату вказану архітектуру. Типовим є значення, яке
збігається зі значенням архітектури для основної системи, на якій запущено virt-dib.
У поточній версії цей параметр виконує лише встановлення змінної середовища "ARCH" для
елементів, а елементи вже створюють образ для потрібної користувачу архітектури.
--checksum
Generate checksum files for the generated image. The supported checksums are MD5, and
SHA256.
--colors
--colours
Use ANSI colour sequences to colourize messages. This is the default when the output
is a tty. If the output of the program is redirected to a file, ANSI colour sequences
are disabled unless you use this option.
--debug РІВЕНЬ
Set the debug level to "LEVEL", which is a non-negative integer number. The default
is 0.
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.
--docker-target TARGET
Set the repository and tag for docker.
This is used only when the formats include "docker", and it is required in that case.
--drive ДИСК
Додати вказаний диск як допоміжний, такий, де зберігатимуться файли кешу елементів,
зокрема образи дисків, пакунки дистрибутива тощо.
Див. "ДОПОМІЖНИЙ ДИСК".
--drive-format raw
--drive-format qcow2
Specify the format of the helper drive. If this flag is not given then it is auto-
detected from the drive itself.
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.
Див. "ДОПОМІЖНИЙ ДИСК".
-p ШЛЯХ
--element-path ШЛЯХ
Додати новий шлях з елементами. Шляхи використовуватимуться у тому самому порядку, у
якому з’являються параметри -p, отже, пошук за шляхом, вказаним першим,
відбуватиметься спочатку.
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.
--extra-packages ПАКУНОК,...
Встановити додаткові пакунки у образ, який збиратиметься.
This relies on the "install-packages" binary provided by the package management
elements.
Цей параметр може бути використано декілька разів, декілька пакунків у аргументах слід
відокремлювати комами.
--envvar ЗМІННА
--envvar ЗМІННА=ЗНАЧЕННЯ
Передати або встановити змінну середовища для елементів.
See "ENVIRONMENT VARIABLES" below for more information on the interaction and usage of
environment variables.
Цим параметром можна скористатися у декілька способів:
--envvar ЗМІННА
Передати змінну середовища "ЗМІННА". Якщо змінну не встановлено, до елементів
нічого не експортуватиметься.
--envvar ЗМІННА=ЗНАЧЕННЯ
Set the environment variable "VARIABLE" with value "VALUE" for the elements,
regardless whether an environment variable with the same name exists.
This can be useful to pass environment variable without exporting them in the
environment where virt-dib runs.
--exclude-element ЕЛЕМЕНТ
Ігнорувати вказаний елемент.
--exclude-script СКРИПТ
Ігнорувати будь-який скрипт елемента із назвою "СКРИПТ", байдуже, до якого елемента
він належатиме.
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.
--formats ФОРМАТ,...
Set the list of output formats, separating them with comma.
Підтримувані формати:
"docker"
Import the image to docker, running docker import. The target for the image must
be specified using --docker-target.
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.
"qcow2" (типово увімкнено)
QEMU's qcow2. This output format requires the "qemu-img" tool.
"raw"
Формат даних диска без обробки.
"squashfs"
An squashfs filesystem, compressed with XZ. This output format requires the
"squashfs" feature; see also "AVAILABILITY" in guestfs(3).
"tar"
Архів без стискання.
"tgz"
A tarball compressed with gzip.
"vhd"
"Virtual Hard Disk" disk image. This output format requires the "vhd-util" tool.
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.
--fs-type ФАЙЛОВА СИСТЕМА
Set the filesystem type to use for the root filesystem. The default is "ext4".
Див. також "guestfs_filesystem_available" in guestfs(3)
--image-cache КАТАЛОГ
Set the path in the host where cache the resources used by the elements of the
"extra-data.d" phase. The default is ~/.cache/image-create.
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".
--install-type ТИП
Specify the default installation type. Defaults to "source".
Set to "package" to use package based installations by default.
--machine-readable
This option is used to make the output more machine friendly when being parsed by
other programs. See "MACHINE READABLE OUTPUT" below.
-m МБ
--memsize МБ
Change the amount of memory allocated to the appliance. Increase this if you find that
the virt-dib execution runs out of memory.
Типові значення можна визначити за допомогою такої команди:
guestfish get-memsize
--mkfs-options "РЯДОК ПАРАМЕТРІВ"
Add the specified options to mkfs(1), to be able to fine-tune the root filesystem
creation; the options are passed to the driver of mfks(1), and not to mfks(1) itself.
Note that --fs-type is used to change the filesystem type.
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'
--network
--no-network
Увімкнути чи вимкнути доступ до мережі для гостьової системи під час встановлення.
Типово увімкнено. Скористайтеся параметром --no-network, щоб вимкнути доступ.
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.
--name НАЗВА
Set the name of the output image file. The default is "image".
According to the chosen name, there will be the following in the current directory:
$NAME.ext
For each output format, a file named after the output image with the extension
depending on the format; for example: $NAME.qcow2, $NAME.raw, etc.
Not applicable in ramdisk mode, see "RAMDISK BUILDING".
$NAME.d
A directory containing any files created by the elements, for example dib-
manifests directory (created by the "manifests" element), ramdisks and kernels in
ramdisk mode, and so on.
$NAME.ext.checksum
When --checksum is specified, there will be files for each supported checksum
type; for example: $NAME.ext.md5, $NAME.ext.sha256, etc.
Not applicable in ramdisk mode, see "RAMDISK BUILDING".
--no-delete-on-failure
Don't delete the output files on failure to build. You can use this to debug failures
to run scripts.
The default is to delete the output files if virt-dib fails (or, for example, some
script that it runs fails).
-q
--quiet
Не виводити звичайних повідомлень щодо поступу.
--qemu-img-options параметр[,параметр,...]
Pass --qemu-img-options option(s) to the qemu-img(1) command to fine-tune the output
format. Options available depend on the output format (see --formats) and the
installed version of the qemu-img program.
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 ...
--ramdisk
Встановити режим збирання диска у пам’яті.
Див. "ЗБИРАННЯ ДИСКА У ПАМ'ЯТІ".
--ramdisk-element НАЗВА
Set the name for the additional element added in ramdisk building mode. The default
is "ramdisk".
Див. "ЗБИРАННЯ ДИСКА У ПАМ'ЯТІ".
--root-label МІТКА
Встановити мітку для кореневої файлової системи у створеному образі.
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.
--size РОЗМІР
Select the size of the output disk, where the size can be specified using common names
such as "32G" (32 gigabytes) etc. The default size is "5G".
To specify size in bytes, the number must be followed by the lowercase letter b, eg:
"--size 10737418240b".
Див. також virt-resize(1) щодо зміни розмірів розділів на наявному образі диска.
--skip-base
Пропустити включення елемента "base".
--smp N
Enable N ≥ 2 virtual CPUs for scripts to use.
-u Do not compress resulting qcow2 images. The default is to compress them.
-v
--verbose
Увімкнути показ діагностичних повідомлень.
-V
--version
Показати дані щодо версії і завершити роботу.
-x Увімкнути трасування викликів програмного інтерфейсу libguestfs.
ЗМІННІ СЕРЕДОВИЩА
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 # яким би не було її значення
virt-dib ... --envvar MYVAR ...
або
virt-dib ... --envvar MYVAR=її_значення ...
ДОПОМІЖНИЙ ДИСК
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:
/home
This directory is set as "HOME" environment variable during the build. It contains
mostly the image cache (saved as /home/.cache/image-create), and whichever other
resource is cached in the home directory of the user running the various tools.
/virt-dib-*.log
These are the logs of the elements being run within the libguestfs appliance, which
means all the phases except "extra-data.d".
ЗБИРАННЯ ДИСКА У ПАМ'ЯТІ
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.
У цьому режимі:
• there is an additional ramdisk element added (see --ramdisk-element)
• no image is produced (so --formats is ignored)
• $NAME.d (see --name) will contain initrd, kernel, etc
ТИМЧАСОВИЙ КАТАЛОГ
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).
COMPARISON WITH DISKIMAGE-BUILDER
Virt-dib is intended as safe replacement for "diskimage-builder" and its
"ramdisk-image-create" mode; the user-notable differences consist in:
• the command line arguments; some of the arguments are the same as available in
"diskimage-builder", while some have different names:
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
• the location of non-image output files (like ramdisks and kernels)
• the way some of the cached resources are saved: using an helper drive, not directly on
the disk where virt-dib is run
• the need to specify a target size for the output disk, as opposed to
"diskimage-builder" calculating an optimal one
• the handling of environment variables, see "ENVIRONMENT VARIABLES".
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
• extra tools needed on some out-of-chroot phases need to be available in the appliance,
see "EXTRA DEPENDENCIES".
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:
• (немає)
MACHINE READABLE OUTPUT
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
Виводиться список можливостей, по одній на рядок, і програма завершує роботу зі станом 0.
The "output:" features refer to the output formats (--formats command line option)
supported by this binary.
ТЕСТУВАННЯ
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.
СТАН ВИХОДУ
Ця програма повертає значення 0 у разі успішного завершення і ненульове значення, якщо
сталася помилка.
ТАКОЖ ПЕРЕГЛЯНЬТЕ
guestfs(3), guestfish(1), virt-resize(1), http://libguestfs.org/.
АВТОР
Pino Toscano ("ptoscano at redhat dot com")
АВТОРСЬКІ ПРАВА
© Red Hat Inc., 2015
LICENSE
BUGS
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:
• The version of libguestfs.
• Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
• Describe the bug accurately and give a way to reproduce it.
• Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug
report.