.\" Automatically generated by Podwrapper::Man 1.40.2 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "virt-dib 1"
.TH virt-dib 1 "2019-02-07" "libguestfs-1.40.2" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "名前"
.IX Header "名前"
virt-dib \- Run diskimage-builder elements
.SH "書式"
.IX Header "書式"
.Vb 1
\& virt\-dib \-B DIB\-LIB [options] elements...
.Ve
.SH "説明"
.IX Header "説明"
Virt-dib is a tool for using the elements of \f(CW\*(C`diskimage\-builder\*(C'\fR to build a
new disk image, generate new ramdisks, etc.
.PP
Virt-dib is intended as safe replacement for \f(CW\*(C`diskimage\-builder\*(C'\fR and its
\&\f(CW\*(C`ramdisk\-image\-create\*(C'\fR mode, see \*(L"\s-1COMPARISON WITH\s0 DISKIMAGE-BUILDER\*(R" for
a quick comparison with usage of \f(CW\*(C`diskimage\-builder\*(C'\fR.
.PP
\&\f(CW\*(C`diskimage\-builder\*(C'\fR is part of the TripleO OpenStack project:
https://wiki.openstack.org/wiki/TripleO.
.SH "例"
.IX Header "例"
.SS "Build simple images of distributions"
.IX Subsection "Build simple images of distributions"
.Vb 6
\& virt\-dib \e
\&   \-B /path/to/diskimage\-builder/lib \e
\&   \-p /path/to/diskimage\-builder/elements \e
\&   \-\-envvar DIB_RELEASE=jessie \e
\&   \-\-name debian\-jessie \e
\&   debian vm
.Ve
.PP
This builds a Debian Jessie (8.x) disk image, suitable for running as
virtual machine, saved as \fIdebian\-jessie.qcow2\fR.
.SS "Build ramdisks"
.IX Subsection "Build ramdisks"
.Vb 6
\& virt\-dib \e
\&   \-B /path/to/diskimage\-builder/lib \e
\&   \-p /path/to/diskimage\-builder/elements \e
\&   \-\-ramdisk \e
\&   \-\-name ramdisk \e
\&   ubuntu deploy\-ironic
.Ve
.PP
This builds a ramdisk for the Ironic OpenStack component based on the Ubuntu
distribution.
.SH "オプション"
.IX Header "オプション"
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
ヘルプを表示します。
.IP "\fB\-B\fR \s-1PATH\s0" 4
.IX Item "-B PATH"
Set the path to the library directory of \f(CW\*(C`diskimage\-builder\*(C'\fR. This is
usually the \fIlib\fR subdirectory in the sources and when installed, and
\&\fI/usr/share/diskimage\-builder/lib\fR when installed in \fI/usr\fR.
.Sp
This parameter is \fBmandatory\fR, 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.
.IP "\fB\-\-arch\fR \s-1ARCHITECTURE\s0" 4
.IX Item "--arch ARCHITECTURE"
Use the specified architecture for the output image.  The default value is
the same as the host running virt-dib.
.Sp
Right now this option does nothing more than setting the \f(CW\*(C`ARCH\*(C'\fR environment
variable for the elements, and it’s up to them to produce an image for the
requested architecture.
.IP "\fB\-\-checksum\fR" 4
.IX Item "--checksum"
Generate checksum files for the generated image.  The supported checksums
are \s-1MD5,\s0 and \s-1SHA256.\s0
.IP "\fB\-\-colors\fR" 4
.IX Item "--colors"
.PD 0
.IP "\fB\-\-colours\fR" 4
.IX Item "--colours"
.PD
Use \s-1ANSI\s0 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,
\&\s-1ANSI\s0 colour sequences are disabled unless you use this option.
.IP "\fB\-\-debug\fR \s-1LEVEL\s0" 4
.IX Item "--debug LEVEL"
Set the debug level to \f(CW\*(C`LEVEL\*(C'\fR, which is a non-negative integer number.
The default is \f(CW0\fR.
.Sp
This debug level is different than what \fI\-x\fR and \fI\-v\fR set, and it
increases the debugging information printed out.  Specifically, this sets
the \f(CW\*(C`DIB_DEBUG_TRACE\*(C'\fR, and any value > \f(CW0\fR enables tracing in the
scripts executed.
.IP "\fB\-\-docker\-target\fR \s-1TARGET\s0" 4
.IX Item "--docker-target TARGET"
Set the repository and tag for docker.
.Sp
This is used only when the formats include \f(CW\*(C`docker\*(C'\fR, and it is required in
that case.
.IP "\fB\-\-drive\fR \s-1DISK\s0" 4
.IX Item "--drive DISK"
Add the specified disk to be used as helper drive where to cache files of
the elements, like disk images, distribution packages, etc.
.Sp
See \*(L"\s-1HELPER DRIVE\*(R"\s0.
.IP "\fB\-\-drive\-format\fR raw" 4
.IX Item "--drive-format raw"
.PD 0
.IP "\fB\-\-drive\-format\fR qcow2" 4
.IX Item "--drive-format qcow2"
.PD
Specify the format of the helper drive.  If this flag is not given then it
is auto-detected from the drive itself.
.Sp
If working with untrusted raw-format guest disk images, you should ensure
the format is always specified.
.Sp
This option is used only if \fI\-\-drive\fR is specified.
.Sp
See \*(L"\s-1HELPER DRIVE\*(R"\s0.
.IP "\fB\-p\fR \s-1PATH\s0" 4
.IX Item "-p PATH"
.PD 0
.IP "\fB\-\-element\-path\fR \s-1PATH\s0" 4
.IX Item "--element-path PATH"
.PD
Add a new path with elements.  Paths are used in the same order as the \fI\-p\fR
parameters appear, so a path specified first is looked first, and so on.
.Sp
Obviously, it is recommended to add the path to the own elements of
\&\f(CW\*(C`diskimage\-builder\*(C'\fR, as most of the other elements will rely on them.
.IP "\fB\-\-extra\-packages\fR \s-1PACKAGE,...\s0" 4
.IX Item "--extra-packages PACKAGE,..."
Install additional packages in the image being built.
.Sp
This relies on the \f(CW\*(C`install\-packages\*(C'\fR binary provided by the package
management elements.
.Sp
This option can be specified multiple times, each time with multiple
packages separated by comma.
.IP "\fB\-\-envvar\fR \s-1VARIABLE\s0" 4
.IX Item "--envvar VARIABLE"
.PD 0
.IP "\fB\-\-envvar\fR VARIABLE=VALUE" 4
.IX Item "--envvar VARIABLE=VALUE"
.PD
Carry or set an environment variable for the elements.
.Sp
See \*(L"\s-1ENVIRONMENT VARIABLES\*(R"\s0 below for more information on the interaction
and usage of environment variables.
.Sp
This option can be used in two ways:
.RS 4
.IP "\fB\-\-envvar\fR \s-1VARIABLE\s0" 4
.IX Item "--envvar VARIABLE"
Carry the environment variable \f(CW\*(C`VARIABLE\*(C'\fR. If it is not set, nothing is
exported to the elements.
.IP "\fB\-\-envvar\fR VARIABLE=VALUE" 4
.IX Item "--envvar VARIABLE=VALUE"
Set the environment variable \f(CW\*(C`VARIABLE\*(C'\fR with value \f(CW\*(C`VALUE\*(C'\fR for the
elements, regardless whether an environment variable with the same name
exists.
.Sp
This can be useful to pass environment variable without exporting them in
the environment where virt-dib runs.
.RE
.RS 4
.RE
.IP "\fB\-\-exclude\-element\fR \s-1ELEMENT\s0" 4
.IX Item "--exclude-element ELEMENT"
Ignore the specified element.
.IP "\fB\-\-exclude\-script\fR \s-1SCRIPT\s0" 4
.IX Item "--exclude-script SCRIPT"
Ignore any element script named \f(CW\*(C`SCRIPT\*(C'\fR, whichever element it is in.
.Sp
This can be useful in case some script does not run well with virt-dib, for
example when they really need \f(CW\*(C`diskimage\-builder\*(C'\fR's environment.
.IP "\fB\-\-formats\fR \s-1FORMAT,...\s0" 4
.IX Item "--formats FORMAT,..."
Set the list of output formats, separating them with comma.
.Sp
Supported formats are:
.RS 4
.ie n .IP """docker""" 4
.el .IP "\f(CWdocker\fR" 4
.IX Item "docker"
Import the image to docker, running \fBdocker import\fR.  The target for the
image \fBmust\fR be specified using \fI\-\-docker\-target\fR.
.Sp
Please note this operation usually requires the docker service to be
enabled, otherwise it will fail.  Furthermore, \fBdocker\fR is run using
\&\fBsudo\fR\|(8), so make sure the user has the permissions to run at least
\&\fBdocker\fR.
.ie n .IP """qcow2"" (enabled by default)" 4
.el .IP "\f(CWqcow2\fR (enabled by default)" 4
.IX Item "qcow2 (enabled by default)"
QEMU’s qcow2.  This output format requires the \f(CW\*(C`qemu\-img\*(C'\fR tool.
.ie n .IP """raw""" 4
.el .IP "\f(CWraw\fR" 4
.IX Item "raw"
Raw disk format.
.ie n .IP """squashfs""" 4
.el .IP "\f(CWsquashfs\fR" 4
.IX Item "squashfs"
An squashfs filesystem, compressed with \s-1XZ.\s0  This output format requires the
\&\f(CW\*(C`squashfs\*(C'\fR feature; see also \*(L"\s-1AVAILABILITY\*(R"\s0 in \fBguestfs\fR\|(3).
.ie n .IP """tar""" 4
.el .IP "\f(CWtar\fR" 4
.IX Item "tar"
An uncompressed tarball.
.ie n .IP """tgz""" 4
.el .IP "\f(CWtgz\fR" 4
.IX Item "tgz"
A tarball compressed with gzip.
.ie n .IP """vhd""" 4
.el .IP "\f(CWvhd\fR" 4
.IX Item "vhd"
\&\f(CW\*(C`Virtual Hard Disk\*(C'\fR disk image.  This output format requires the
\&\f(CW\*(C`vhd\-util\*(C'\fR tool.
.Sp
Please note that the version of \f(CW\*(C`vhd\-util\*(C'\fR tool needs to be patched to
support the \f(CW\*(C`convert\*(C'\fR subcommand, and to be bootable.  The patch is
available here:
https://github.com/emonty/vhd\-util/blob/master/debian/patches/citrix.
.RE
.RS 4
.RE
.IP "\fB\-\-fs\-type\fR \s-1FILESYSTEM\s0" 4
.IX Item "--fs-type FILESYSTEM"
Set the filesystem type to use for the root filesystem.  The default is
\&\f(CW\*(C`ext4\*(C'\fR.
.Sp
See also \*(L"guestfs_filesystem_available\*(R" in \fBguestfs\fR\|(3).
.IP "\fB\-\-image\-cache\fR \s-1DIRECTORY\s0" 4
.IX Item "--image-cache DIRECTORY"
Set the path in the host where cache the resources used by the elements of
the \f(CW\*(C`extra\-data.d\*(C'\fR phase.  The default is \fI~/.cache/image\-create\fR.
.Sp
Please note that most of the resources fetched in phases other than
\&\f(CW\*(C`extra\-data.d\*(C'\fR will be cached in the helper drive specified with
\&\fI\-\-drive\fR; see also \*(L"\s-1HELPER DRIVE\*(R"\s0.
.IP "\fB\-\-install\-type\fR \s-1TYPE\s0" 4
.IX Item "--install-type TYPE"
Specify the default installation type.  Defaults to \f(CW\*(C`source\*(C'\fR.
.Sp
Set to \f(CW\*(C`package\*(C'\fR to use package based installations by default.
.IP "\fB\-\-machine\-readable\fR" 4
.IX Item "--machine-readable"
.PD 0
.IP "\fB\-\-machine\-readable\fR=format" 4
.IX Item "--machine-readable=format"
.PD
このオプションは、他のプログラムにより解析されるときに、よりマシンに易しい出力を作成するために使用されます。以下の \*(L"マシン可読な出力\*(R" 参照。
.IP "\fB\-m\fR \s-1MB\s0" 4
.IX Item "-m MB"
.PD 0
.IP "\fB\-\-memsize\fR \s-1MB\s0" 4
.IX Item "--memsize MB"
.PD
Change the amount of memory allocated to the appliance. Increase this if you
find that the virt-dib execution runs out of memory.
.Sp
The default can be found with this command:
.Sp
.Vb 1
\& guestfish get\-memsize
.Ve
.ie n .IP "\fB\-\-mkfs\-options\fR ""OPTION STRING""" 4
.el .IP "\fB\-\-mkfs\-options\fR \f(CWOPTION STRING\fR" 4
.IX Item "--mkfs-options OPTION STRING"
Add the specified options to \fBmkfs\fR\|(1), to be able to fine-tune the root
filesystem creation; the options are passed to the driver of \fBmfks\fR\|(1), and
not to \fBmfks\fR\|(1) itself.  Note that \fI\-\-fs\-type\fR is used to change the
filesystem type.
.Sp
You should use \fI\-\-mkfs\-options\fR at most once.  To pass multiple options,
separate them with space, eg:
.Sp
.Vb 1
\& virt\-dib ... \-\-mkfs\-options \*(Aq\-O someopt \-I foo\*(Aq
.Ve
.IP "\fB\-\-network\fR" 4
.IX Item "--network"
.PD 0
.IP "\fB\-\-no\-network\fR" 4
.IX Item "--no-network"
.PD
Enable or disable network access from the guest during the installation.
.Sp
Enabled is the default.  Use \fI\-\-no\-network\fR to disable access.
.Sp
The network only allows outgoing connections and has other minor
limitations.  See \*(L"\s-1NETWORK\*(R"\s0 in \fBvirt\-rescue\fR\|(1).
.Sp
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.
.Sp
If you use \fI\-\-no\-network\fR, then the environment variable \f(CW\*(C`DIB_OFFLINE\*(C'\fR is
set to \f(CW1\fR, signaling the elements that they should use only cached
resources when available.  Note also that, unlike with \f(CW\*(C`diskimage\-builder\*(C'\fR
where elements may still be able to access to the network even with
\&\f(CW\*(C`DIB_OFFLINE=\*(C'\fR, under virt-dib network will not be accessible at all.
.IP "\fB\-\-name\fR \s-1NAME\s0" 4
.IX Item "--name NAME"
Set the name of the output image file.  The default is \f(CW\*(C`image\*(C'\fR.
.Sp
According to the chosen name, there will be the following in the current
directory:
.RS 4
.IP "\fI\f(CI$NAME\fI.ext\fR" 4
.IX Item "$NAME.ext"
For each output format, a file named after the output image with the
extension depending on the format; for example: \fI\f(CI$NAME\fI.qcow2\fR,
\&\fI\f(CI$NAME\fI.raw\fR, etc.
.Sp
Not applicable in ramdisk mode, see \*(L"\s-1RAMDISK BUILDING\*(R"\s0.
.IP "\fI\f(CI$NAME\fI.d\fR" 4
.IX Item "$NAME.d"
A directory containing any files created by the elements, for example
\&\fIdib-manifests\fR directory (created by the \f(CW\*(C`manifests\*(C'\fR element), ramdisks
and kernels in ramdisk mode, and so on.
.IP "\fI\f(CI$NAME\fI.ext.checksum\fR" 4
.IX Item "$NAME.ext.checksum"
When \fI\-\-checksum\fR is specified, there will be files for each supported
checksum type; for example: \fI\f(CI$NAME\fI.ext.md5\fR, \fI\f(CI$NAME\fI.ext.sha256\fR, etc.
.Sp
Not applicable in ramdisk mode, see \*(L"\s-1RAMDISK BUILDING\*(R"\s0.
.RE
.RS 4
.RE
.IP "\fB\-\-no\-delete\-on\-failure\fR" 4
.IX Item "--no-delete-on-failure"
Don’t delete the output files on failure to build.  You can use this to
debug failures to run scripts.
.Sp
The default is to delete the output files if virt-dib fails (or, for
example, some script that it runs fails).
.IP "\fB\-\-python\fR \s-1PYTHON\s0" 4
.IX Item "--python PYTHON"
Specify a different Python interpreter to use.  Parts of
\&\f(CW\*(C`diskimage\-builder\*(C'\fR are implemented in Python, and thus an interpreter is
needed.
.Sp
\&\f(CW\*(C`PYTHON\*(C'\fR can either be an executable filename (e.g. \fIpython2\fR, which is
then searched in \f(CW$PATH\fR), or a full path (e.g.  \fI/usr/bin/python2\fR).  If
not specified, the default value is \fIpython\fR.
.IP "\fB\-q\fR" 4
.IX Item "-q"
.PD 0
.IP "\fB\-\-quiet\fR" 4
.IX Item "--quiet"
.PD
Don’t print ordinary progress messages.
.IP "\fB\-\-qemu\-img\-options\fR option[,option,...]" 4
.IX Item "--qemu-img-options option[,option,...]"
Pass \fI\-\-qemu\-img\-options\fR option(s) to the \fBqemu\-img\fR\|(1) command to
fine-tune the output format.  Options available depend on the output format
(see \fI\-\-formats\fR) and the installed version of the qemu-img program.
.Sp
You should use \fI\-\-qemu\-img\-options\fR at most once.  To pass multiple
options, separate them with commas, eg:
.Sp
.Vb 1
\& virt\-dib ... \-\-qemu\-img\-options cluster_size=512,preallocation=metadata ...
.Ve
.IP "\fB\-\-ramdisk\fR" 4
.IX Item "--ramdisk"
Set the ramdisk building mode.
.Sp
See \*(L"\s-1RAMDISK BUILDING\*(R"\s0.
.IP "\fB\-\-ramdisk\-element\fR \s-1NAME\s0" 4
.IX Item "--ramdisk-element NAME"
Set the name for the additional element added in ramdisk building mode.  The
default is \f(CW\*(C`ramdisk\*(C'\fR.
.Sp
See \*(L"\s-1RAMDISK BUILDING\*(R"\s0.
.IP "\fB\-\-root\-label\fR \s-1LABEL\s0" 4
.IX Item "--root-label LABEL"
Set the label for the root filesystem in the created image.
.Sp
Please note that some filesystems have different restrictions on the length
of their labels; for example, on \f(CW\*(C`ext2/3/4\*(C'\fR filesystems labels cannot be
longer than 16 characters, while on \f(CW\*(C`xfs\*(C'\fR they have at most 12 characters.
.Sp
The default depends on the actual filesystem for the root partition (see
\&\fI\-\-fs\-type\fR): on \f(CW\*(C`xfs\*(C'\fR is \f(CW\*(C`img\-rootfs\*(C'\fR, while \f(CW\*(C`cloudimg\-rootfs\*(C'\fR on any
other filesystem.
.IP "\fB\-\-size\fR \s-1SIZE\s0" 4
.IX Item "--size SIZE"
Select the size of the output disk, where the size can be specified using
common names such as \f(CW\*(C`32G\*(C'\fR (32 gigabytes) etc.  The default size is \f(CW\*(C`5G\*(C'\fR.
.Sp
To specify size in bytes, the number must be followed by the lowercase
letter \fIb\fR, eg: \f(CW\*(C`\-\-size 10737418240b\*(C'\fR.
.Sp
See also \fBvirt\-resize\fR\|(1) for resizing partitions of an existing disk
image.
.IP "\fB\-\-skip\-base\fR" 4
.IX Item "--skip-base"
Skip the inclusion of the \f(CW\*(C`base\*(C'\fR element.
.IP "\fB\-\-smp\fR N" 4
.IX Item "--smp N"
Enable N ≥ 2 virtual CPUs for scripts to use.
.IP "\fB\-u\fR" 4
.IX Item "-u"
Do not compress resulting qcow2 images.  The default is to compress them.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
デバッグメッセージを有効にします。
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
バージョン番号を表示して、終了します。
.IP "\fB\-x\fR" 4
.IX Item "-x"
libguestfs \s-1API\s0 呼び出しのトレースを有効にします。
.SH "環境変数"
.IX Header "環境変数"
Unlike with \f(CW\*(C`diskimage\-builder\*(C'\fR, the environment of the host is \fBnot\fR
inherited in the appliance when running most of the elements (i.e. all
except the ones in the \f(CW\*(C`extra\-data.d\*(C'\fR phase).
.PP
To set environment for the elements being run, it is necessary to tell
virt-dib to use them, with the option \fI\-\-envvar\fR.  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.
.PP
To recap: if you want the environment variable \f(CW\*(C`MYVAR\*(C'\fR (and its content) to
be available to the elements, you can do either
.PP
.Vb 2
\& export MYVAR   # whichever is its value
\& virt\-dib ... \-\-envvar MYVAR ...
.Ve
.PP
または
.PP
.Vb 1
\& virt\-dib ... \-\-envvar MYVAR=value_of_it ...
.Ve
.SH "HELPER DRIVE"
.IX Header "HELPER DRIVE"
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.
.PP
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.
.PP
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 \fBguestfish\fR\|(1) like the following:
.PP
.Vb 1
\& guestfish \-N filename.img=fs:ext4:10G exit
.Ve
.PP
The above will create a disk image called \fIfilename.img\fR, 10G big, with a
single partition of type ext4; see \*(L"\s-1PREPARED DISK IMAGES\*(R"\s0 in \fBguestfish\fR\|(1).
.PP
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 \fBvirt\-resize\fR\|(1) if more space in
it is needed.
.PP
The drive can be accessed like any other disk image, for example using other
tools of libguestfs such as \fBguestfish\fR\|(1):
.PP
.Vb 1
\& guestfish \-a filename.img \-m /dev/sda1
.Ve
.PP
If no helper drive is specified with \fI\-\-drive\fR, all the resources cached
during a virt-dib run will be discarded.
.SS "\s-1RESOURCES INSIDE THE DRIVE\s0"
.IX Subsection "RESOURCES INSIDE THE DRIVE"
Inside the helper drive, it is possible to find the following resources:
.IP "\fI/home\fR" 4
.IX Item "/home"
This directory is set as \f(CW\*(C`HOME\*(C'\fR environment variable during the build.  It
contains mostly the image cache (saved as \fI/home/.cache/image\-create\fR), and
whichever other resource is cached in the home directory of the user running
the various tools.
.IP "\fI/virt\-dib\-*.log\fR" 4
.IX Item "/virt-dib-*.log"
These are the logs of the elements being run within the libguestfs
appliance, which means all the phases except \f(CW\*(C`extra\-data.d\*(C'\fR.
.SH "RAMDISK BUILDING"
.IX Header "RAMDISK BUILDING"
Virt-dib can emulate also \f(CW\*(C`ramdisk\-image\-create\*(C'\fR, which is a secondary
operation mode of \f(CW\*(C`diskimage\-builder\*(C'\fR.  Instead of being a different tool
name, virt-dib provides easy access to this mode using the \fI\-\-ramdisk\fR
switch.
.PP
In this mode:
.IP "\(bu" 4
there is an additional ramdisk element added (see \fI\-\-ramdisk\-element\fR)
.IP "\(bu" 4
no image is produced (so \fI\-\-formats\fR is ignored)
.IP "\(bu" 4
\&\fI\f(CI$NAME\fI.d\fR (see \fI\-\-name\fR) will contain initrd, kernel, etc
.SH "TEMPORARY DIRECTORY"
.IX Header "TEMPORARY DIRECTORY"
Virt-dib uses the standard temporary directory used by libguestfs, see
\&\*(L"\s-1ENVIRONMENT VARIABLES\*(R"\s0 in \fBguestfs\fR\|(3).
.PP
By default this location is \fI/tmp\fR (default value for \f(CW\*(C`TMPDIR\*(C'\fR), which on
some systems may be on a tmpfs filesystem, and thus defaulting to a maximum
size of \fIhalf\fR of physical \s-1RAM.\s0  If virt-dib exceeds this, it may hang or
exit early with an error.  The solution is to point \f(CW\*(C`TMPDIR\*(C'\fR to a permanent
location used as temporary location, for example:
.PP
.Vb 3
\& mkdir local\-tmp
\& env TMPDIR=$PWD/local\-tmp virt\-dib ...
\& rm \-rf local\-tmp
.Ve
.SH "EXTRA DEPENDENCIES"
.IX Header "EXTRA DEPENDENCIES"
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
\&\f(CW\*(C`root.d\*(C'\fR, \f(CW\*(C`block\-device.d\*(C'\fR, and \f(CW\*(C`cleanup.d\*(C'\fR)  need to be present in the
appliance as well.  In case they are not, scripts will fail typically with a
\&\f(CW\*(C`command not found\*(C'\fR error.
.PP
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:
.PP
.Vb 1
\& # echo wget > /usr/lib64/guestfs/supermin.d/dib\-my\-extra
.Ve
.PP
The actual path to the \fIsupermin.d\fR directory depends on the distribution;
additional files can list more packages, each in its own line.  For more
details, see \fBsupermin\fR\|(1).
.SH "COMPARISON WITH DISKIMAGE-BUILDER"
.IX Header "COMPARISON WITH DISKIMAGE-BUILDER"
Virt-dib is intended as safe replacement for \f(CW\*(C`diskimage\-builder\*(C'\fR and its
\&\f(CW\*(C`ramdisk\-image\-create\*(C'\fR mode; the user-notable differences consist in:
.IP "\(bu" 4
the command line arguments; some of the arguments are the same as available
in \f(CW\*(C`diskimage\-builder\*(C'\fR, while some have different names:
.Sp
.Vb 12
\& 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
.Ve
.IP "\(bu" 4
the location of non-image output files (like ramdisks and kernels)
.IP "\(bu" 4
the way some of the cached resources are saved: using an helper drive, not
directly on the disk where virt-dib is run
.IP "\(bu" 4
the need to specify a target size for the output disk, as opposed to
\&\f(CW\*(C`diskimage\-builder\*(C'\fR calculating an optimal one
.IP "\(bu" 4
the handling of environment variables, see \*(L"\s-1ENVIRONMENT VARIABLES\*(R"\s0.
.Sp
Furthermore, other than the libguestfs own environment variables (see
\&\*(L"\s-1ENVIRONMENT VARIABLES\*(R"\s0 in \fBguestfs\fR\|(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
.IP "\(bu" 4
extra tools needed on some out-of-chroot phases need to be available in the
appliance, see \*(L"\s-1EXTRA DEPENDENCIES\*(R"\s0.
.PP
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.
.PP
Known issues at the moment:
.IP "\(bu" 4
(none)
.SH "マシン可読な出力"
.IX Header "マシン可読な出力"
The \fI\-\-machine\-readable\fR option can be used to make the output more machine
friendly, which is useful when calling virt-dib from other programs, GUIs
etc.
.PP
Use the option on its own to query the capabilities of the virt-dib binary.
Typical output looks like this:
.PP
.Vb 6
\& $ virt\-dib \-\-machine\-readable
\& virt\-dib
\& output:qcow2
\& output:tar
\& output:raw
\& output:vhd
.Ve
.PP
A list of features is printed, one per line, and the program exits with
status 0.
.PP
The \f(CW\*(C`output:\*(C'\fR features refer to the output formats (\fI\-\-formats\fR command
line option) supported by this binary.
.PP
It is possible to specify a format string for controlling the output; see
\&\*(L"\s-1ADVANCED MACHINE READABLE OUTPUT\*(R"\s0 in \fBguestfs\fR\|(3).
.SH "TESTING"
.IX Header "TESTING"
Virt-dib has been tested with \f(CW\*(C`diskimage\-builder\*(C'\fR (and its elements)  ≥
0.1.43; from time to time also with \f(CW\*(C`tripleo\-image\-elements\*(C'\fR and
\&\f(CW\*(C`sahara\-image\-elements\*(C'\fR.
.PP
Previous versions may work, but it is not guaranteed.
.SH "終了ステータス"
.IX Header "終了ステータス"
このプログラムは、成功すると 0 を、エラーがあると 0 以外を返します。
.SH "関連項目"
.IX Header "関連項目"
\&\fBguestfs\fR\|(3), \fBguestfish\fR\|(1), \fBvirt\-resize\fR\|(1),
http://libguestfs.org/.
.SH "著者"
.IX Header "著者"
Pino Toscano (\f(CW\*(C`ptoscano at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2015 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
.SH "BUGS"
.IX Header "BUGS"
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
When reporting a bug, please supply:
.IP "\(bu" 4
The version of libguestfs.
.IP "\(bu" 4
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
.IP "\(bu" 4
Describe the bug accurately and give a way to reproduce it.
.IP "\(bu" 4
Run \fBlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR
output into the bug report.