.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.52.3 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "virt-builder 1"
.TH virt-builder 1 2025-02-18 guestfs-tools-1.52.3 "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\-builder \- Build virtual machine images quickly
.SH 書式
.IX Header "書式"
.Vb 3
\& virt\-builder os\-version
\&    [\-o|\-\-output DISKIMAGE] [\-\-size SIZE] [\-\-format raw|qcow2]
\&    [\-\-arch ARCHITECTURE] [\-\-attach ISOFILE]
\&
\&
\&
\& virt\-builder \-l|\-\-list [\-\-long] [\-\-list\-format short|long|json] [os\-version]
\&
\& virt\-builder \-\-notes os\-version
\&
\& virt\-builder \-\-print\-cache
\&
\& virt\-builder \-\-cache\-all\-templates
\&
\& virt\-builder \-\-delete\-cache
\&
\& virt\-builder \-\-get\-kernel DISKIMAGE
\&    [\-\-format raw|qcow2] [\-\-output OUTPUTDIR]
.Ve
.SH 説明
.IX Header "説明"
Virt\-builder is a tool for quickly building new virtual machines.  You can build a variety of VMs for local or cloud use, usually within a few minutes or less.  Virt\-builder also has many ways to customize these VMs. Everything is run from the command line and nothing requires root privileges, so automation and scripting is simple.
.PP
Note that virt\-builder does not install guests from scratch.  It takes cleanly prepared, digitally signed OS templates and customizes them.  This approach is used because it is much faster, but if you need to do fresh installs you may want to look at \fBvirt\-install\fR\|(1) and \fBoz\-install\fR\|(1).
.PP
The easiest way to get started is by looking at the examples in the next section.
.SH 例
.IX Header "例"
.SS "List the virtual machines available"
.IX Subsection "List the virtual machines available"
.Vb 1
\& virt\-builder \-\-list
.Ve
.PP
will list out the operating systems available to install.  A selection of freely redistributable OSes is available as standard.  You can add your own too (see below).
.PP
After choosing a guest from the list, you may want to see if there are any installation notes:
.PP
.Vb 1
\& virt\-builder \-\-notes fedora\-27
.Ve
.SS "Build a virtual machine"
.IX Subsection "Build a virtual machine"
.Vb 1
\& virt\-builder fedora\-27
.Ve
.PP
will build a Fedora 25 image for the same architecture as virt\-builder (so running it from an i686 installation will try to build an i686 image, if available).  This will have all default configuration (minimal size, no user accounts, random root password, only the bare minimum installed software, etc.).
.PP
You \fIdo not\fR need to run this command as root.
.PP
The first time this runs it has to download the template over the network, but this gets cached (see "CACHING").
.PP
The name of the output file is derived from the template name, so above it will be \fIfedora\-27.img\fR.  You can change the output filename using the \fI\-o\fR option:
.PP
.Vb 1
\& virt\-builder fedora\-27 \-o mydisk.img
.Ve
.PP
You can also use the \fI\-o\fR option to write to existing devices or logical volumes.
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-format qcow2
.Ve
.PP
As above, but write the output in qcow2 format to \fIfedora\-27.qcow2\fR.
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-size 20G
.Ve
.PP
As above, but the output size will be 20 GB.  The guest OS is resized as it is copied to the output (automatically, using \fBvirt\-resize\fR\|(1)).
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-arch i686
.Ve
.PP
As above, but using an i686 template, if available.
.SS "Setting the root password"
.IX Subsection "Setting the root password"
.Vb 1
\& virt\-builder fedora\-27 \-\-root\-password file:/tmp/rootpw
.Ve
.PP
Create a Fedora 25 image.  The root password is taken from the file \fI/tmp/rootpw\fR.
.PP
Note if you \fIdon’t\fR set \fI\-\-root\-password\fR then the guest is given a \fIrandom\fR root password which is printed on stdout.
.PP
You can also create user accounts.  See "USERS AND PASSWORDS" below.
.SS "Set the hostname"
.IX Subsection "Set the hostname"
.Vb 1
\& virt\-builder fedora\-27 \-\-hostname virt.example.com
.Ve
.PP
Set the hostname to \f(CW\*(C`virt.example.com\*(C'\fR.
.SS "Installing software"
.IX Subsection "Installing software"
To install packages from the ordinary (guest) software repository (eg. dnf or apt):
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-install "inkscape,@Xfce Desktop"
.Ve
.PP
(In Fedora, \f(CW\*(C`@\*(C'\fR is used to install groups of packages.  On Debian you would install a meta\-package instead.)
.PP
To update the installed packages to the latest version:
.PP
.Vb 1
\& virt\-builder debian\-7 \-\-update
.Ve
.SS "Customizing the installation"
.IX Subsection "Customizing the installation"
There are many options that let you customize the installation.  These include: \fI\-\-run\fR/\fI\-\-run\-command\fR, which run a shell script or command while the disk image is being generated and lets you add or edit files that go into the disk image.  \fI\-\-firstboot\fR/\fI\-\-firstboot\-command\fR, which let you add scripts/commands that are run the first time the guest boots. \fI\-\-edit\fR to edit files.  \fI\-\-upload\fR to upload files.
.PP
例:
.PP
.Vb 3
\& cat <<\*(AqEOF\*(Aq > /tmp/dnf\-update.sh
\& dnf \-y \-\-best update
\& EOF
\& 
\& virt\-builder fedora\-27 \-\-firstboot /tmp/dnf\-update.sh
.Ve
.PP
or simply:
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-firstboot\-command \*(Aqdnf \-y \-\-best update\*(Aq
.Ve
.PP
which makes the \fBdnf\fR\|(8) \f(CW\*(C`update\*(C'\fR command run once the first time the guest boots.
.PP
Or:
.PP
.Vb 3
\& virt\-builder fedora\-27 \e
\&   \-\-edit \*(Aq/etc/dnf/dnf.conf:
\&             s/gpgcheck=1/gpgcheck=0/\*(Aq
.Ve
.PP
which edits \fI/etc/dnf/dnf.conf\fR inside the disk image (during disk image creation, long before boot).
.PP
You can combine these options, and have multiple options of all types.
.SH オプション
.IX Header "オプション"
.IP \fB\-\-help\fR 4
.IX Item "--help"
ヘルプを表示します。
.IP "\fB\-\-arch\fR ARCHITECTURE" 4
.IX Item "--arch ARCHITECTURE"
Use the specified architecture for the output image.  This means there must be sources providing the requested template for the requested architecture.
.Sp
See also "ARCHITECTURE".
.IP "\fB\-\-attach\fR ISOFILE" 4
.IX Item "--attach ISOFILE"
During the customization phase, the given disk is attached to the libguestfs appliance.  This is used to provide extra software repositories or other data for customization.
.Sp
You probably want to ensure the volume(s) or filesystems in the attached disks are labelled (or use an ISO volume name) so that you can mount them by label in your run\-scripts:
.Sp
.Vb 2
\& mkdir /tmp/mount
\& mount LABEL=EXTRA /tmp/mount
.Ve
.Sp
You can have multiple \fI\-\-attach\fR options, and the format can be any disk format (not just an ISO).
.Sp
See also: \fI\-\-run\fR, "Installing packages at build time from a side repository", \fBgenisoimage\fR\|(1), \fBvirt\-make\-fs\fR\|(1).
.IP "\fB\-\-attach\-format\fR FORMAT" 4
.IX Item "--attach-format FORMAT"
Specify the disk format for the next \fI\-\-attach\fR option.  The \f(CW\*(C`FORMAT\*(C'\fR is usually \f(CW\*(C`raw\*(C'\fR or \f(CW\*(C`qcow2\*(C'\fR.  Use \f(CW\*(C`raw\*(C'\fR for ISOs.
.IP "\fB\-\-cache\fR DIR" 4
.IX Item "--cache DIR"
.PD 0
.IP \fB\-\-no\-cache\fR 4
.IX Item "--no-cache"
.PD
\&\fI\-\-cache\fR DIR sets the directory to use/check for cached template files. If not set, defaults to either \fR\f(CI$XDG_CACHE_HOME\fR\fI/virt\-builder/\fR or \fI\fR\f(CI$HOME\fR\fI/.cache/virt\-builder/\fR.
.Sp
\&\fI\-\-no\-cache\fR disables template caching.
.IP \fB\-\-cache\-all\-templates\fR 4
.IX Item "--cache-all-templates"
Download all templates to the cache and then exit.  See "CACHING".
.Sp
Note this doesn\*(Aqt cache everything.  More templates might be uploaded.  Also this doesn\*(Aqt cache packages (the \fI\-\-install\fR, \fI\-\-update\fR options).
.IP \fB\-\-check\-signature\fR 4
.IX Item "--check-signature"
.PD 0
.IP \fB\-\-no\-check\-signature\fR 4
.IX Item "--no-check-signature"
.PD
Check/don’t check the digital signature of the OS template.  The default is to check the signature and exit if it is not correct.  Using \fI\-\-no\-check\-signature\fR bypasses this check.
.Sp
See also \fI\-\-fingerprint\fR.
.IP \fB\-\-colors\fR 4
.IX Item "--colors"
.PD 0
.IP \fB\-\-colours\fR 4
.IX Item "--colours"
.PD
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.
.IP "\fB\-\-curl\fR CURL" 4
.IX Item "--curl CURL"
Specify an alternate \fBcurl\fR\|(1) binary.  You can also use this to add curl parameters, for example to disable https certificate checks:
.Sp
.Vb 1
\& virt\-builder \-\-curl "curl \-\-insecure" [...]
.Ve
.IP \fB\-\-delete\-cache\fR 4
.IX Item "--delete-cache"
Delete the template cache.  See "CACHING".
.IP \fB\-\-no\-delete\-on\-failure\fR 4
.IX Item "--no-delete-on-failure"
Don’t delete the output file on failure to build.  You can use this to debug failures to run scripts.  See "DEBUGGING BUILDS" for ways to debug images.
.Sp
The default is to delete the output file if virt\-builder fails (or, for example, some script that it runs fails).
.IP "\fB\-\-fingerprint\fR \*(AqAAAA BBBB ...\*(Aq" 4
.IX Item "--fingerprint 'AAAA BBBB ...'"
Check that the index and templates are signed by the key with the given fingerprint.  (The fingerprint is a long string, usually written as 10 groups of 4 hexadecimal digits).
.Sp
You can give this option multiple times.  If you have multiple source URLs, then you can have either no fingerprint, one fingerprint or multiple fingerprints.  If you have multiple, then each must correspond 1\-1 with a source URL.
.IP "\fB\-\-format\fR qcow2" 4
.IX Item "--format qcow2"
.PD 0
.IP "\fB\-\-format\fR raw" 4
.IX Item "--format raw"
.PD
For ordinary builds, this selects the output format.  The default is \fIraw\fR.
.Sp
With \fI\-\-get\-kernel\fR this specifies the input format.
.Sp
To create an old\-style qcow2 file (for compatibility with RHEL 6 or very old qemu < 1.1), after running virt\-builder, use this command:
.Sp
.Vb 1
\& qemu\-img amend \-f qcow2 \-o compat=0.10 output.qcow2
.Ve
.IP "\fB\-\-get\-kernel\fR IMAGE" 4
.IX Item "--get-kernel IMAGE"
This option extracts the kernel and initramfs from a previously built disk image called \f(CW\*(C`IMAGE\*(C'\fR (in fact it works for any VM disk image, not just ones built using virt\-builder).
.Sp
Note this method is \fBdeprecated\fR: there is a separate tool for this, \fBvirt\-get\-kernel\fR\|(1), which has more options for the file extraction.
.Sp
The kernel and initramfs are written to the current directory, unless you also specify the \fI\-\-output\fR \f(CW\*(C`outputdir\*(C'\fR \fBdirectory\fR name.
.Sp
The format of the disk image is automatically detected unless you specify it by using the \fI\-\-format\fR option.
.Sp
In the case where the guest contains multiple kernels, the one with the highest version number is chosen.  To extract arbitrary kernels from the disk image, see \fBguestfish\fR\|(1).  To extract the entire \fI/boot\fR directory of a guest, see \fBvirt\-copy\-out\fR\|(1).
.IP "\fB\-\-gpg\fR GPG" 4
.IX Item "--gpg GPG"
Specify an alternate \fBgpg\fR\|(1) (GNU Privacy Guard) binary.  By default virt\-builder looks for either \f(CW\*(C`gpg2\*(C'\fR or \f(CW\*(C`gpg\*(C'\fR in the \f(CW$PATH\fR.
.Sp
You can also use this to add gpg parameters, for example to specify an alternate home directory:
.Sp
.Vb 1
\& virt\-builder \-\-gpg "gpg \-\-homedir /tmp" [...]
.Ve
.IP "\fB\-l\fR [os\-version]" 4
.IX Item "-l [os-version]"
.PD 0
.IP "\fB\-\-list\fR [os\-version]" 4
.IX Item "--list [os-version]"
.IP "\fB\-\-list\fR \fB\-\-list\-format\fR format [os\-version]" 4
.IX Item "--list --list-format format [os-version]"
.IP "\fB\-\-list\fR \fB\-\-long\fR [os\-version]" 4
.IX Item "--list --long [os-version]"
.PD
List all the available templates if no guest is specified, or only for the specified one.
.Sp
It is possible to choose with \fI\-\-list\-format\fR the output format for the list templates:
.RS 4
.IP \fBshort\fR 4
.IX Item "short"
The default format, prints only the template identifier and, next to it, its short description.
.IP \fBlong\fR 4
.IX Item "long"
Prints a textual list with the details of the available sources, followed by the details of the available templates.
.IP \fBjson\fR 4
.IX Item "json"
Prints a JSON object with the details of the available sources and the details of the available templates.
.Sp
The \f(CW\*(C`version\*(C'\fR key in the main object represents the "compatibility version", and it is bumped every time the resulting JSON output is incompatible with the previous versions (for example the structure has changed, or non\-optional keys are no more present).
.RE
.RS 4
.Sp
\&\fI\-\-long\fR is a shorthand for the \f(CW\*(C`long\*(C'\fR format.
.Sp
See also: \fI\-\-source\fR, \fI\-\-notes\fR, "SOURCES OF TEMPLATES".
.RE
.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
このオプションは、他のプログラムにより解析されるときに、よりマシンに易しい出力を作成するために使用されます。以下の "マシン可読な出力" 参照。
.IP "\fB\-m\fR MB" 4
.IX Item "-m MB"
.PD 0
.IP "\fB\-\-memsize\fR MB" 4
.IX Item "--memsize MB"
.PD
Change the amount of memory allocated to \fI\-\-run\fR scripts.  Increase this if you find that \fI\-\-run\fR scripts or the \fI\-\-install\fR option are running out of memory.
.Sp
The default can be found with this command:
.Sp
.Vb 1
\& guestfish get\-memsize
.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 "NETWORK" in \fBvirt\-rescue\fR\|(1).
.Sp
If you use \fI\-\-no\-network\fR then certain other options such as \fI\-\-install\fR will not work.
.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\-builder.
.Sp
Generally speaking you should \fInot\fR use \fI\-\-no\-network\fR.  But here are some reasons why you might want to:
.RS 4
.IP 1. 4
Because the libguestfs backend that you are using doesn\*(Aqt support the network.  (See: "BACKEND" in \fBguestfs\fR\|(3)).
.IP 2. 4
Any software you need to install comes from an attached ISO, so you don\*(Aqt need the network.
.IP 3. 4
You don’t want untrusted guest code trying to access your host network when running virt\-builder.  This is particularly an issue when you don\*(Aqt trust the source of the operating system templates.  (See "SECURITY" below).
.IP 4. 4
You don’t have a host network (eg. in secure/restricted environments).
.RE
.RS 4
.RE
.IP \fB\-\-no\-sync\fR 4
.IX Item "--no-sync"
Do not sync the output file on exit.
.Sp
Virt\-builder \f(CW\*(C`fsync\*(C'\fRs the output file or disk image when it exits.
.Sp
The reason is that qemu/KVM’s default caching mode is \f(CW\*(C`none\*(C'\fR or \f(CW\*(C`directsync\*(C'\fR, both of which bypass the host page cache.  Therefore these would not work correctly if you immediately started the guest after running virt\-builder \- they would not see the complete output file.  (Note that you should not use these caching modes \- they are fundamentally broken for this and other reasons.)
.Sp
If you are not using these broken caching modes, you can use \fI\-\-no\-sync\fR to avoid this unnecessary sync and gain considerable extra performance.
.IP "\fB\-\-notes\fR os\-version" 4
.IX Item "--notes os-version"
List any notes associated with this guest, then exit (this does not do the install).
.IP "\fB\-o\fR filename" 4
.IX Item "-o filename"
.PD 0
.IP "\fB\-\-output\fR filename" 4
.IX Item "--output filename"
.PD
Write the output to \fIfilename\fR.  If you don’t specify this option, then the output filename is generated by taking the \f(CW\*(C`os\-version\*(C'\fR string and adding \f(CW\*(C`.img\*(C'\fR (for raw format) or \f(CW\*(C`.qcow2\*(C'\fR (for qcow2 format).
.Sp
Note that the output filename could be a device, partition or logical volume.
.Sp
When used with \fI\-\-get\-kernel\fR, this option specifies the output directory.
.IP \fB\-\-print\-cache\fR 4
.IX Item "--print-cache"
Print information about the template cache.  See "CACHING".
.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\-\-size\fR SIZE" 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.
.Sp
Virt\-builder will resize filesystems inside the disk image automatically.
.Sp
If the size is not specified, then one of two things happens.  If the output is a file, then the size is the same as the template.  If the output is a device, partition, etc then the size of that device is used.
.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.
.IP "\fB\-\-smp\fR N" 4
.IX Item "--smp N"
Enable N ≥ 2 virtual CPUs for \fI\-\-run\fR scripts to use.
.IP "\fB\-\-source\fR URL" 4
.IX Item "--source URL"
Set the source URL to look for indexes.
.Sp
You can give this option multiple times to specify multiple sources.
.Sp
See also "SOURCES OF TEMPLATES" below.
.Sp
Note that you should not point \fI\-\-source\fR to sources that you don’t trust (unless the source is signed by someone you do trust).  See also the \fI\-\-no\-network\fR option.
.IP \fB\-\-no\-warn\-if\-partition\fR 4
.IX Item "--no-warn-if-partition"
Do not emit a warning if the output device is a partition.  This warning avoids a common user error when writing to a USB key or external drive, when you should normally write to the whole device (\fI\-\-output\ /dev/sdX\fR), not to a partition on the device (\fI\-\-output\ /dev/sdX1\fR).  Use this option to \fIsuppress\fR this warning.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
Enable debug messages and/or produce verbose output.
.Sp
When reporting bugs, use this option and attach the complete output to your bug report.
.IP \fB\-V\fR 4
.IX Item "-V"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
バージョン番号を表示して、終了します。
.IP \fB\-\-wrap\fR 4
.IX Item "--wrap"
Wrap error, warning, and informative messages.  This is the default when the output is a tty.  If the output of the program is redirected to a file, wrapping is disabled unless you use this option.
.IP \fB\-x\fR 4
.IX Item "-x"
libguestfs API 呼び出しのトレースを有効にします。
.SS "Customization options"
.IX Subsection "Customization options"
.IP "\fB\-\-append\-line\fR FILE:LINE" 4
.IX Item "--append-line FILE:LINE"
Append a single line of text to the \f(CW\*(C`FILE\*(C'\fR.  If the file does not already end with a newline, then one is added before the appended line.  Also a newline is added to the end of the \f(CW\*(C`LINE\*(C'\fR string automatically.
.Sp
For example (assuming ordinary shell quoting) this command:
.Sp
.Vb 1
\& \-\-append\-line \*(Aq/etc/hosts:10.0.0.1 foo\*(Aq
.Ve
.Sp
will add either \f(CW\*(C`10.0.0.1 foo⏎\*(C'\fR or \f(CW\*(C`⏎10.0.0.1 foo⏎\*(C'\fR to the file, the latter only if the existing file does not already end with a newline.
.Sp
\&\f(CW\*(C`⏎\*(C'\fR represents a newline character, which is guessed by looking at the existing content of the file, so this command does the right thing for files using Unix or Windows line endings.  It also works for empty or non\-existent files.
.Sp
To insert several lines, use the same option several times:
.Sp
.Vb 2
\& \-\-append\-line \*(Aq/etc/hosts:10.0.0.1 foo\*(Aq
\& \-\-append\-line \*(Aq/etc/hosts:10.0.0.2 bar\*(Aq
.Ve
.Sp
To insert a blank line before the appended line, do:
.Sp
.Vb 2
\& \-\-append\-line \*(Aq/etc/hosts:\*(Aq
\& \-\-append\-line \*(Aq/etc/hosts:10.0.0.1 foo\*(Aq
.Ve
.IP "\fB\-\-chmod\fR PERMISSIONS:FILE" 4
.IX Item "--chmod PERMISSIONS:FILE"
Change the permissions of \f(CW\*(C`FILE\*(C'\fR to \f(CW\*(C`PERMISSIONS\*(C'\fR.
.Sp
\&\fINote\fR: \f(CW\*(C`PERMISSIONS\*(C'\fR by default would be decimal, unless you prefix it with \f(CW0\fR to get octal, ie. use \f(CW0700\fR not \f(CW700\fR.
.IP "\fB\-\-chown\fR UID:GID:PATH" 4
.IX Item "--chown UID:GID:PATH"
Change the owner user and group ID of a file or directory in the guest. Note:
.RS 4
.IP \(bu 4
Only numeric UIDs and GIDs will work, and these may not be the same inside the guest as on the host.
.IP \(bu 4
This will not work with Windows guests.
.RE
.RS 4
.Sp
例:
.Sp
.Vb 1
\& virt\-customize \-\-chown \*(Aq0:0:/var/log/audit.log\*(Aq
.Ve
.Sp
See also: \fI\-\-upload\fR.
.RE
.IP "\fB\-\-commands\-from\-file\fR FILENAME" 4
.IX Item "--commands-from-file FILENAME"
Read the customize commands from a file, one (and its arguments)  each line.
.Sp
Each line contains a single customization command and its arguments, for example:
.Sp
.Vb 3
\& delete /some/file
\& install some\-package
\& password some\-user:password:its\-new\-password
.Ve
.Sp
Empty lines are ignored, and lines starting with \f(CW\*(C`#\*(C'\fR are comments and are ignored as well.  Furthermore, arguments can be spread across multiple lines, by adding a \f(CW\*(C`\e\*(C'\fR (continuation character) at the of a line, for example
.Sp
.Vb 2
\& edit /some/file:\e
\&   s/^OPT=.*/OPT=ok/
.Ve
.Sp
The commands are handled in the same order as they are in the file, as if they were specified as \fI\-\-delete /some/file\fR on the command line.
.IP "\fB\-\-copy\fR SOURCE:DEST" 4
.IX Item "--copy SOURCE:DEST"
Copy files or directories recursively inside the guest.
.Sp
Wildcards cannot be used.
.IP "\fB\-\-copy\-in\fR LOCALPATH:REMOTEDIR" 4
.IX Item "--copy-in LOCALPATH:REMOTEDIR"
Copy local files or directories recursively into the disk image, placing them in the directory \f(CW\*(C`REMOTEDIR\*(C'\fR (which must exist).
.Sp
Wildcards cannot be used.
.IP "\fB\-\-delete\fR PATH" 4
.IX Item "--delete PATH"
Delete a file from the guest.  Or delete a directory (and all its contents, recursively).
.Sp
You can use shell glob characters in the specified path.  Be careful to escape glob characters from the host shell, if that is required.  For example:
.Sp
.Vb 1
\& virt\-customize \-\-delete \*(Aq/var/log/*.log\*(Aq.
.Ve
.Sp
See also: \fI\-\-upload\fR, \fI\-\-scrub\fR.
.IP "\fB\-\-edit\fR FILE:EXPR" 4
.IX Item "--edit FILE:EXPR"
Edit \f(CW\*(C`FILE\*(C'\fR using the Perl expression \f(CW\*(C`EXPR\*(C'\fR.
.Sp
表現がシェルにより変更されるのを防ぐために、適切に引用符でくくるよう注意してください。
.Sp
このオプションは Perl 5 がインストールされているときのみ利用可能であることに注意してください。
.Sp
See "NON\-INTERACTIVE EDITING" in \fBvirt\-edit\fR\|(1).
.IP "\fB\-\-firstboot\fR SCRIPT" 4
.IX Item "--firstboot SCRIPT"
Install \f(CW\*(C`SCRIPT\*(C'\fR inside the guest, so that when the guest first boots up, the script runs (as root, late in the boot process).
.Sp
The script is automatically chmod +x after installation in the guest.
.Sp
The alternative version \fI\-\-firstboot\-command\fR is the same, but it conveniently wraps the command up in a single line script for you.
.Sp
You can have multiple \fI\-\-firstboot\fR options.  They run in the same order that they appear on the command line.
.Sp
Please take a look at "FIRST BOOT SCRIPTS" for more information and caveats about the first boot scripts.
.Sp
See also \fI\-\-run\fR.
.IP "\fB\-\-firstboot\-command\fR \*(AqCMD+ARGS\*(Aq" 4
.IX Item "--firstboot-command 'CMD+ARGS'"
Run command (and arguments) inside the guest when the guest first boots up (as root, late in the boot process).
.Sp
You can have multiple \fI\-\-firstboot\fR options.  They run in the same order that they appear on the command line.
.Sp
Please take a look at "FIRST BOOT SCRIPTS" for more information and caveats about the first boot scripts.
.Sp
See also \fI\-\-run\fR.
.IP "\fB\-\-firstboot\-install\fR PKG,PKG.." 4
.IX Item "--firstboot-install PKG,PKG.."
Install the named packages (a comma\-separated list).  These are installed when the guest first boots using the guest’s package manager (eg. apt, yum, etc.) and the guest’s network connection.
.Sp
For an overview on the different ways to install packages, see "INSTALLING PACKAGES".
.IP "\fB\-\-hostname\fR HOSTNAME" 4
.IX Item "--hostname HOSTNAME"
Set the hostname of the guest to \f(CW\*(C`HOSTNAME\*(C'\fR.  You can use a dotted hostname.domainname (FQDN) if you want.
.IP "\fB\-\-inject\-qemu\-ga\fR METHOD" 4
.IX Item "--inject-qemu-ga METHOD"
Inject the QEMU Guest Agent into a Windows guest.  The guest agent communicates with qemu through a socket in order to provide enhanced features (see \fBqemu\-ga\fR\|(8)).  This operation also injects a firstboot script so that the Guest Agent is installed when the guest boots.
.Sp
The parameter is the same as used by the \fI\-\-inject\-virtio\-win\fR operation.
.Sp
Note that to do a full conversion of a Windows guest from a foreign hypervisor like VMware (which involves many other operations)  you should use the \fBvirt\-v2v\fR\|(1) tool instead of this.
.IP "\fB\-\-inject\-virtio\-win\fR METHOD" 4
.IX Item "--inject-virtio-win METHOD"
Inject virtio\-win drivers into a Windows guest.  These drivers add virtio accelerated drivers suitable when running on top of a hypervisor that supports virtio (such as qemu/KVM).  The operation also adjusts the Windows Registry so that the drivers are installed when the guest boots.
.Sp
The parameter can be one of:
.RS 4
.IP ISO 4
.IX Item "ISO"
The path to the ISO image containing the virtio\-win drivers (eg. \fI/usr/share/virtio\-win/virtio\-win.iso\fR).
.IP DIR 4
.IX Item "DIR"
The directory containing the unpacked virtio\-win drivers (eg. \fI/usr/share/virtio\-win\fR).
.IP "\fB""osinfo""\fR" 4
.IX Item """osinfo"""
The literal string \f(CW"osinfo"\fR means to use the libosinfo database to locate the drivers.  (See \fBosinfo\-query\fR\|(1).
.RE
.RS 4
.Sp
Note that to do a full conversion of a Windows guest from a foreign hypervisor like VMware (which involves many other operations)  you should use the \fBvirt\-v2v\fR\|(1) tool instead of this.
.RE
.IP "\fB\-\-install\fR PKG,PKG.." 4
.IX Item "--install PKG,PKG.."
Install the named packages (a comma\-separated list).  These are installed during the image build using the guest’s package manager (eg. apt, yum, etc.) and the host’s network connection.
.Sp
For an overview on the different ways to install packages, see "INSTALLING PACKAGES".
.Sp
See also \fI\-\-update\fR, \fI\-\-uninstall\fR.
.IP "\fB\-\-link\fR TARGET:LINK[:LINK..]" 4
.IX Item "--link TARGET:LINK[:LINK..]"
Create symbolic link(s) in the guest, starting at \f(CW\*(C`LINK\*(C'\fR and pointing at \f(CW\*(C`TARGET\*(C'\fR.
.IP "\fB\-\-mkdir\fR DIR" 4
.IX Item "--mkdir DIR"
Create a directory in the guest.
.Sp
This uses \f(CW\*(C`mkdir\ \-p\*(C'\fR so any intermediate directories are created, and it also works if the directory already exists.
.IP "\fB\-\-move\fR SOURCE:DEST" 4
.IX Item "--move SOURCE:DEST"
Move files or directories inside the guest.
.Sp
Wildcards cannot be used.
.IP \fB\-\-no\-logfile\fR 4
.IX Item "--no-logfile"
Scrub \f(CW\*(C`builder.log\*(C'\fR (log file from build commands) from the image after building is complete.  If you don\*(Aqt want to reveal precisely how the image was built, use this option.
.Sp
See also: "LOG FILE".
.IP \fB\-\-no\-selinux\-relabel\fR 4
.IX Item "--no-selinux-relabel"
Do not attempt to correct the SELinux labels of files in the guest.
.Sp
In such guests that support SELinux, customization automatically relabels files so that they have the correct SELinux label.  (The relabeling is performed immediately, but if the operation fails, customization will instead touch \fI/.autorelabel\fR on the image to schedule a relabel operation for the next time the image boots.)  This option disables the automatic relabeling.
.Sp
The option is a no\-op for guests that do not support SELinux.
.IP "\fB\-\-password\fR USER:SELECTOR" 4
.IX Item "--password USER:SELECTOR"
Set the password for \f(CW\*(C`USER\*(C'\fR.  (Note this option does \fInot\fR create the user account).
.Sp
See "USERS AND PASSWORDS" for the format of the \f(CW\*(C`SELECTOR\*(C'\fR field, and also how to set up user accounts.
.IP "\fB\-\-password\-crypto\fR md5|sha256|sha512" 4
.IX Item "--password-crypto md5|sha256|sha512"
When the virt tools change or set a password in the guest, this option sets the password encryption of that password to \f(CW\*(C`md5\*(C'\fR, \f(CW\*(C`sha256\*(C'\fR or \f(CW\*(C`sha512\*(C'\fR.
.Sp
\&\f(CW\*(C`sha256\*(C'\fR and \f(CW\*(C`sha512\*(C'\fR require glibc ≥ 2.7 (check \fBcrypt\fR\|(3) inside the guest).
.Sp
\&\f(CW\*(C`md5\*(C'\fR will work with relatively old Linux guests (eg. RHEL 3), but is not secure against modern attacks.
.Sp
The default is \f(CW\*(C`sha512\*(C'\fR unless libguestfs detects an old guest that didn\*(Aqt have support for SHA\-512, in which case it will use \f(CW\*(C`md5\*(C'\fR.  You can override libguestfs by specifying this option.
.Sp
Note this does not change the default password encryption used by the guest when you create new user accounts inside the guest.  If you want to do that, then you should use the \fI\-\-edit\fR option to modify \f(CW\*(C`/etc/sysconfig/authconfig\*(C'\fR (Fedora, RHEL) or \f(CW\*(C`/etc/pam.d/common\-password\*(C'\fR (Debian, Ubuntu).
.IP "\fB\-\-root\-password\fR SELECTOR" 4
.IX Item "--root-password SELECTOR"
Set the root password.
.Sp
See "USERS AND PASSWORDS" for the format of the \f(CW\*(C`SELECTOR\*(C'\fR field, and also how to set up user accounts.
.Sp
Note: In virt\-builder, if you \fIdon\*(Aqt\fR set \fI\-\-root\-password\fR then the guest is given a \fIrandom\fR root password.
.IP "\fB\-\-run\fR SCRIPT" 4
.IX Item "--run SCRIPT"
Run the shell script (or any program) called \f(CW\*(C`SCRIPT\*(C'\fR on the disk image. The script runs virtualized inside a small appliance, chrooted into the guest filesystem.
.Sp
The script is automatically chmod +x.
.Sp
If libguestfs supports it then a limited network connection is available but it only allows outgoing network connections.  You can also attach data disks (eg. ISO files) as another way to provide data (eg. software packages) to the script without needing a network connection (\fI\-\-attach\fR).  You can also upload data files (\fI\-\-upload\fR).
.Sp
You can have multiple \fI\-\-run\fR options.  They run in the same order that they appear on the command line.
.Sp
See also: \fI\-\-firstboot\fR, \fI\-\-attach\fR, \fI\-\-upload\fR.
.IP "\fB\-\-run\-command\fR \*(AqCMD+ARGS\*(Aq" 4
.IX Item "--run-command 'CMD+ARGS'"
Run the command and arguments on the disk image.  The command runs virtualized inside a small appliance, chrooted into the guest filesystem.
.Sp
If libguestfs supports it then a limited network connection is available but it only allows outgoing network connections.  You can also attach data disks (eg. ISO files) as another way to provide data (eg. software packages) to the script without needing a network connection (\fI\-\-attach\fR).  You can also upload data files (\fI\-\-upload\fR).
.Sp
You can have multiple \fI\-\-run\-command\fR options.  They run in the same order that they appear on the command line.
.Sp
See also: \fI\-\-firstboot\fR, \fI\-\-attach\fR, \fI\-\-upload\fR.
.IP "\fB\-\-scrub\fR FILE" 4
.IX Item "--scrub FILE"
Scrub a file from the guest.  This is like \fI\-\-delete\fR except that:
.RS 4
.IP \(bu 4
It scrubs the data so a guest could not recover it.
.IP \(bu 4
It cannot delete directories, only regular files.
.RE
.RS 4
.RE
.IP \fB\-\-selinux\-relabel\fR 4
.IX Item "--selinux-relabel"
This is a compatibility option that does nothing.
.IP "\fB\-\-sm\-attach\fR SELECTOR" 4
.IX Item "--sm-attach SELECTOR"
Attach to a pool using \f(CW\*(C`subscription\-manager\*(C'\fR.
.Sp
See "SUBSCRIPTION\-MANAGER" for the format of the \f(CW\*(C`SELECTOR\*(C'\fR field.
.IP "\fB\-\-sm\-credentials\fR SELECTOR" 4
.IX Item "--sm-credentials SELECTOR"
Set the credentials for \f(CW\*(C`subscription\-manager\*(C'\fR.
.Sp
See "SUBSCRIPTION\-MANAGER" for the format of the \f(CW\*(C`SELECTOR\*(C'\fR field.
.IP \fB\-\-sm\-register\fR 4
.IX Item "--sm-register"
Register the guest using \f(CW\*(C`subscription\-manager\*(C'\fR.
.Sp
This requires credentials being set using \fI\-\-sm\-credentials\fR.
.IP \fB\-\-sm\-remove\fR 4
.IX Item "--sm-remove"
Remove all the subscriptions from the guest using \f(CW\*(C`subscription\-manager\*(C'\fR.
.IP \fB\-\-sm\-unregister\fR 4
.IX Item "--sm-unregister"
Unregister the guest using \f(CW\*(C`subscription\-manager\*(C'\fR.
.IP "\fB\-\-ssh\-inject\fR USER[:SELECTOR]" 4
.IX Item "--ssh-inject USER[:SELECTOR]"
Inject an ssh key so the given \f(CW\*(C`USER\*(C'\fR will be able to log in over ssh without supplying a password.  The \f(CW\*(C`USER\*(C'\fR must exist already in the guest.
.Sp
See "SSH KEYS" for the format of the \f(CW\*(C`SELECTOR\*(C'\fR field.
.Sp
You can have multiple \fI\-\-ssh\-inject\fR options, for different users and also for more keys for each user.
.IP "\fB\-\-tar\-in\fR TARFILE:REMOTEDIR" 4
.IX Item "--tar-in TARFILE:REMOTEDIR"
Copy local files or directories from a local tar file called \f(CW\*(C`TARFILE\*(C'\fR into the disk image, placing them in the directory \f(CW\*(C`REMOTEDIR\*(C'\fR (which must exist).  Note that the tar file must be uncompressed (\fI.tar.gz\fR files will not work here)
.IP "\fB\-\-timezone\fR TIMEZONE" 4
.IX Item "--timezone TIMEZONE"
Set the default timezone of the guest to \f(CW\*(C`TIMEZONE\*(C'\fR.  Use a location string like \f(CW\*(C`Europe/London\*(C'\fR
.IP "\fB\-\-touch\fR FILE" 4
.IX Item "--touch FILE"
This command performs a \fBtouch\fR\|(1)\-like operation on \f(CW\*(C`FILE\*(C'\fR.
.IP "\fB\-\-truncate\fR FILE" 4
.IX Item "--truncate FILE"
This command truncates \f(CW\*(C`FILE\*(C'\fR to a zero\-length file. The file must exist already.
.IP "\fB\-\-truncate\-recursive\fR PATH" 4
.IX Item "--truncate-recursive PATH"
This command recursively truncates all files under \f(CW\*(C`PATH\*(C'\fR to zero\-length.
.IP "\fB\-\-uninstall\fR PKG,PKG.." 4
.IX Item "--uninstall PKG,PKG.."
Uninstall the named packages (a comma\-separated list).  These are removed during the image build using the guest’s package manager (eg. apt, yum, etc.).  Dependent packages may also need to be uninstalled to satisfy the request.
.Sp
See also \fI\-\-install\fR, \fI\-\-update\fR.
.IP \fB\-\-update\fR 4
.IX Item "--update"
Do the equivalent of \f(CW\*(C`yum update\*(C'\fR, \f(CW\*(C`apt\-get upgrade\*(C'\fR, or whatever command is required to update the packages already installed in the template to their latest versions.
.Sp
See also \fI\-\-install\fR, \fI\-\-uninstall\fR.
.IP "\fB\-\-upload\fR FILE:DEST" 4
.IX Item "--upload FILE:DEST"
Upload local file \f(CW\*(C`FILE\*(C'\fR to destination \f(CW\*(C`DEST\*(C'\fR in the disk image.  File owner and permissions from the original are preserved, so you should set them to what you want them to be in the disk image.
.Sp
\&\f(CW\*(C`DEST\*(C'\fR could be the final filename.  This can be used to rename the file on upload.
.Sp
If \f(CW\*(C`DEST\*(C'\fR is a directory name (which must already exist in the guest)  then the file is uploaded into that directory, and it keeps the same name as on the local filesystem.
.Sp
See also: \fI\-\-mkdir\fR, \fI\-\-delete\fR, \fI\-\-scrub\fR.
.IP "\fB\-\-write\fR FILE:CONTENT" 4
.IX Item "--write FILE:CONTENT"
Write \f(CW\*(C`CONTENT\*(C'\fR to \f(CW\*(C`FILE\*(C'\fR.
.SH REFERENCE
.IX Header "REFERENCE"
.SS "INSTALLING PACKAGES"
.IX Subsection "INSTALLING PACKAGES"
There are several approaches to installing packages or applications in the guest which have different trade\-offs.
.PP
\fIInstalling packages at build time\fR
.IX Subsection "Installing packages at build time"
.PP
If the guest OS you are installing is similar to the host OS (eg.  both are Linux), and if libguestfs supports network connections, then you can use \fI\-\-install\fR to install packages like this:
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-install inkscape
.Ve
.PP
This uses the guest’s package manager and the host’s network connection.
.PP
\fIUpdating packages at build time\fR
.IX Subsection "Updating packages at build time"
.PP
To update the installed packages in the template at build time:
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-update
.Ve
.PP
Most of the templates that ship with virt\-builder come with a very minimal selection of packages (known as a "JEOS" or "Just Enough Operating System"), which are up to date at the time the template is created, but could be out of date by the time you come to install an OS from the template.  This option updates those template packages.
.PP
\fIInstalling packages at first boot\fR
.IX Subsection "Installing packages at first boot"
.PP
Another option is to install the packages when the guest first boots:
.PP
.Vb 1
\& virt\-builder fedora\-27 \-\-firstboot\-install inkscape
.Ve
.PP
This uses the guest’s package manager and the guest’s network connection.
.PP
The downsides are that it will take the guest a lot longer to boot first time, and there’s nothing much you can do if package installation fails (eg. if a network problem means the guest can\*(Aqt reach the package repositories).
.PP
\fIInstalling packages at build time from a side repository\fR
.IX Subsection "Installing packages at build time from a side repository"
.PP
If the software you want to install is not available in the main package repository of the guest, then you can add a side repository.  Usually this is presented as an ISO (CD disk image) file containing extra packages.
.PP
You can create the disk image using either \fBgenisoimage\fR\|(1) or \fBvirt\-make\-fs\fR\|(1).  For genisoimage, use a command like this:
.PP
.Vb 1
\& genisoimage \-o extra\-packages.iso \-R \-J \-V EXTRA cdcontents/
.Ve
.PP
Create a script that mounts the ISO and sets up the repository.  For dnf, create /tmp/install.sh containing:
.PP
.Vb 2
\& mkdir /tmp/mount
\& mount LABEL=EXTRA /tmp/mount
\& 
\& cat <<\*(AqEOF\*(Aq > /etc/yum.repos.d/extra.repo
\& [extra]
\& name=extra
\& baseurl=file:///tmp/mount
\& enabled=1
\& EOF
\& 
\& dnf \-y install famousdatabase
.Ve
.PP
For apt, create /tmp/install.sh containing:
.PP
.Vb 2
\& mkdir /tmp/mount
\& mount LABEL=EXTRA /tmp/mount
\& 
\& apt\-cdrom \-d=/tmp/mount add
\& apt\-get \-y install famousdatabase
.Ve
.PP
Use the \fI\-\-attach\fR option to attach the CD / disk image and the \fI\-\-run\fR option to run the script:
.PP
.Vb 3
\& virt\-builder fedora\-27 \e
\&   \-\-attach extra\-packages.iso \e
\&   \-\-run /tmp/install.sh
.Ve
.SS "USERS AND PASSWORDS"
.IX Subsection "USERS AND PASSWORDS"
The \fI\-\-root\-password\fR option is used to change the root password (otherwise a random password is used).  This option takes a password \f(CW\*(C`SELECTOR\*(C'\fR in one of the following formats:
.IP "\fB\-\-root\-password\fR file:FILENAME" 4
.IX Item "--root-password file:FILENAME"
Read the root password from \f(CW\*(C`FILENAME\*(C'\fR.  The whole first line of this file is the replacement password.  Any other lines are ignored.  You should create the file with mode 0600 to ensure no one else can read it.
.IP "\fB\-\-root\-password\fR password:PASSWORD" 4
.IX Item "--root-password password:PASSWORD"
Set the root password to the literal string \f(CW\*(C`PASSWORD\*(C'\fR.
.Sp
\&\fBNote: this is not secure\fR since any user on the same machine can see the cleartext password using \fBps\fR\|(1).
.IP "\fB\-\-root\-password\fR random" 4
.IX Item "--root-password random"
Choose a random password, which is printed on stdout.  The password has approximately 120 bits of randomness.
.Sp
これがデフォルトです。
.IP "\fB\-\-root\-password\fR disabled" 4
.IX Item "--root-password disabled"
The root account password is disabled.  This is like putting \f(CW\*(C`*\*(C'\fR in the password field.
.IP "\fB\-\-root\-password\fR locked:file:FILENAME" 4
.IX Item "--root-password locked:file:FILENAME"
.PD 0
.IP "\fB\-\-root\-password\fR locked:password:PASSWORD" 4
.IX Item "--root-password locked:password:PASSWORD"
.IP "\fB\-\-root\-password\fR locked:random" 4
.IX Item "--root-password locked:random"
.PD
The root account is locked, but a password is placed on the account.  If first unlocked (using \f(CW\*(C`passwd \-u\*(C'\fR) then logins will use the given password.
.IP "\fB\-\-root\-password\fR locked" 4
.IX Item "--root-password locked"
.PD 0
.IP "\fB\-\-root\-password\fR locked:disabled" 4
.IX Item "--root-password locked:disabled"
.PD
The root account is locked \fIand\fR password is disabled.
.PP
\fICreating user accounts\fR
.IX Subsection "Creating user accounts"
.PP
To create user accounts, use the \fBuseradd\fR\|(8) command with \-\-firstboot\-command like this:
.PP
.Vb 2
\& virt\-builder \-\-firstboot\-command \e
\&    \*(Aquseradd \-m \-p "" rjones ; chage \-d 0 rjones\*(Aq
.Ve
.PP
The above command will create an \f(CW\*(C`rjones\*(C'\fR account with no password, and force the user to set a password when they first log in.  There are other ways to manage passwords, see \fBuseradd\fR\|(8) for details.
.SS "KEYBOARD LAYOUT"
.IX Subsection "KEYBOARD LAYOUT"
Because there are so many different ways to set the keyboard layout in Linux distributions, virt\-builder does not yet attempt to have a simple command line option.  This section describes how to set the keyboard for some common Linux distributions.
.PP
\fIKeyboard layout with systemd\fR
.IX Subsection "Keyboard layout with systemd"
.PP
For distros that use systemd \f(CW\*(C`localectl\*(C'\fR, use a command like this:
.PP
.Vb 2
\& virt\-builder fedora\-27 \e
\&   \-\-firstboot\-command \*(Aqlocalectl set\-keymap uk\*(Aq
.Ve
.PP
See \fBlocalectl\fR\|(1) and https://www.happyassassin.net/2013/11/23/keyboard\-layouts\-in\-fedora\-20\-and\-previously/ for more details.
.PP
\fIKeyboard layout using /etc/sysconfig/keyboard\fR
.IX Subsection "Keyboard layout using /etc/sysconfig/keyboard"
.PP
For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard configuration file using the \fI\-\-upload\fR, \fI\-\-write\fR or \fI\-\-edit\fR options. For example:
.PP
.Vb 2
\& virt\-builder centos\-6 \e
\&   \-\-edit \*(Aq/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/\*(Aq
.Ve
.PP
The format of this file can be found documented in many places online.
.PP
\fIKeyboard layout with Debian\-derived distros\fR
.IX Subsection "Keyboard layout with Debian-derived distros"
.PP
For Debian\-derived distros using \fI/etc/default/keyboard\fR, upload or modify the keyboard file using the \fI\-\-upload\fR, \fI\-\-write\fR or \fI\-\-edit\fR options. For example:
.PP
.Vb 2
\& virt\-builder debian\-8 \e
\&   \-\-edit \*(Aq/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/\*(Aq
.Ve
.PP
See https://wiki.debian.org/Keyboard.
.SS LANGUAGE
.IX Subsection "LANGUAGE"
Most Linux distributions support multiple locale settings so that you can have guest messages printed in another language such as Russian.
.PP
However there is no single setting which controls this, since extra packages may need to be installed to support console and X fonts, and keyboard input methods.  The packages required, and their configuration is highly distro\-specific, and it is outside the scope of virt\-builder to do this.
.PP
This section contains examples for some common Linux distributions.
.PP
\fISetting Japanese in Fedora 25\fR
.IX Subsection "Setting Japanese in Fedora 25"
.PP
.Vb 10
\& virt\-builder fedora\-27 \e
\&   \-\-size 20G \e
\&   \-\-update \e
\&   \-\-install @japanese\-support \e
\&   \-\-install @xfce \e
\&   \-\-install xorg\-x11\-server\-Xorg,xorg\-x11\-drivers,rsyslog \e
\&   \-\-link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \e
\&   \-\-firstboot\-command \*(Aqlocalectl set\-locale LANG=ja_JP.utf8\*(Aq \e
\&   \-\-firstboot\-command \*(Aqlocalectl set\-keymap jp\*(Aq \e
\&   \-\-firstboot\-command \*(Aqsystemctl isolate graphical.target\*(Aq
.Ve
.PP
\fISetting Japanese in Debian 8 (Jessie)\fR
.IX Subsection "Setting Japanese in Debian 8 (Jessie)"
.PP
Note that although this enables Japanese in the text console too, it is unlikely that you will see properly rendered Japanese there.  However Japanese is properly rendered in X applications and terminals.
.PP
.Vb 6
\& pkgs=locales,xfce4,\e
\& ibus,ibus\-anthy,\e
\& fonts\-ipafont\-gothic,fonts\-ipafont\-mincho,\e
\& fonts\-takao\-mincho,\e
\& xfonts\-intl\-japanese,xfonts\-intl\-japanese\-big,\e
\& iceweasel\-l10n\-ja,manpages\-ja
\& 
\& virt\-builder debian\-8 \e
\&   \-\-size 20G \e
\&   \-\-install $pkgs \e
\&   \-\-edit \*(Aq/etc/locale.gen: s,^#\es*ja,ja,\*(Aq \e
\&   \-\-write \*(Aq/etc/default/locale:LANG="ja_JP.UTF\-8"\*(Aq \e
\&   \-\-run\-command "locale\-gen"
.Ve
.SS "LOG FILE"
.IX Subsection "LOG FILE"
Scripts and package installation that runs at build time (\fI\-\-run\fR, \fI\-\-run\-command\fR, \fI\-\-install\fR, \fI\-\-update\fR, but \fInot\fR firstboot) is logged in one of the following locations:
.IP \fI/tmp/builder.log\fR 4
.IX Item "/tmp/builder.log"
On Linux, BSD, and other non\-Windows guests.
.IP \fIC:\eTemp\ebuilder.log\fR 4
.IX Item "C:Tempbuilder.log"
On Windows, DOS guests.
.IP \fI/builder.log\fR 4
.IX Item "/builder.log"
If \fI/tmp\fR or \fIC:\eTemp\fR is missing.
.PP
If you don’t want the log file to appear in the final image, then use the \fI\-\-no\-logfile\fR command line option.
.SS "SSH KEYS"
.IX Subsection "SSH KEYS"
The \fI\-\-ssh\-inject\fR option is used to inject ssh keys for users in the guest, so they can login without supplying a password.
.PP
The \f(CW\*(C`SELECTOR\*(C'\fR part of the option value is optional; in this case, \fI\-\-ssh\-inject\fR \f(CW\*(C`USER\*(C'\fR means that we look in the \fIcurrent\fR user’s \fI~/.ssh\fR directory to find the default public ID file.  That key is uploaded.  "default public ID" is the \fIdefault_ID_file\fR file described in \fBssh\-copy\-id\fR\|(1).
.PP
If specified, the \f(CW\*(C`SELECTOR\*(C'\fR can be in one of the following formats:
.IP "\fB\-\-ssh\-inject\fR USER:file:FILENAME" 4
.IX Item "--ssh-inject USER:file:FILENAME"
Read the ssh key from \fIFILENAME\fR.  \fIFILENAME\fR is usually a \fI.pub\fR file.
.IP "\fB\-\-ssh\-inject\fR USER:string:KEY_STRING" 4
.IX Item "--ssh-inject USER:string:KEY_STRING"
Use the specified \f(CW\*(C`KEY_STRING\*(C'\fR.  \f(CW\*(C`KEY_STRING\*(C'\fR is usually a public string like \fIssh\-rsa AAAA.... user@localhost\fR.
.PP
In any case, the \fI~USER/.ssh\fR directory and the \fI~USER/.ssh/authorized_keys\fR file will be created if not existing already.
.SS "FIRST BOOT SCRIPTS"
.IX Subsection "FIRST BOOT SCRIPTS"
The \fI\-\-firstboot\fR and \fI\-\-firstboot\-command\fR options allow you to execute commands at the first boot of the guest.  To do so, an init script for the guest init system is installed, which takes care of running all the added scripts and commands.
.PP
Supported operating systems are:
.IP Linux 4
.IX Item "Linux"
Init systems supported are: systemd, System\-V init (known also as sysvinit), and Upstart (using the System\-V scripts).
.Sp
Note that usually init scripts run as root, but with a more limited environment than what could be available from a normal shell: for example, \f(CW$HOME\fR may be unset or empty.
.Sp
The output of the first boot scripts is available in the guest as \fI~root/virt\-sysprep\-firstboot.log\fR.
.IP Windows 4
.IX Item "Windows"
\&\fIrhsrvany.exe\fR, available from sources at https://github.com/rwmjones/rhsrvany, or \fIpvvxsvc.exe\fR, available with SUSE VMDP is installed to run the first boot scripts.  It is required, and the setup of first boot scripts will fail if it is not present.
.Sp
\&\fIrhsrvany.exe\fR or \fIpvvxsvc.exe\fR is copied from the location pointed to by the \f(CW\*(C`VIRT_TOOLS_DATA_DIR\*(C'\fR environment variable; if not set, a compiled\-in default will be used (something like \fI/usr/share/virt\-tools\fR).
.Sp
The output of the first boot scripts is available in the guest as \fIC:\eProgram Files\eGuestfs\eFirstboot\elog.txt\fR.
.SS SUBSCRIPTION\-MANAGER
.IX Subsection "SUBSCRIPTION-MANAGER"
It is possible to automate the registration and attaching of the system using \f(CW\*(C`subscription\-manager\*(C'\fR.  This is typical on Red Hat Enterprise Linux guests.  There are few options which ease this process, avoid executing commands manually and exposing passwords on command line.
.PP
\&\fI\-\-sm\-register\fR starts the registration process, and requires \fI\-\-sm\-credentials\fR to be specified; the format of the \f(CW\*(C`SELECTOR\*(C'\fR of \fI\-\-sm\-credentials\fR is one of the following formats:
.IP "\fB\-\-sm\-credentials\fR USER:file:FILENAME" 4
.IX Item "--sm-credentials USER:file:FILENAME"
Read the password for the specified \f(CW\*(C`USER\*(C'\fR from \fIFILENAME\fR.
.IP "\fB\-\-sm\-credentials\fR USER:password:PASSWORD" 4
.IX Item "--sm-credentials USER:password:PASSWORD"
Use the literal string \f(CW\*(C`PASSWORD\*(C'\fR for the specified \f(CW\*(C`USER\*(C'\fR.
.PP
\&\fI\-\-sm\-attach\fR attaches the system to subscriptions; the format of its \f(CW\*(C`SELECTOR\*(C'\fR is one of the following:
.IP "\fB\-\-sm\-attach\fR auto" 4
.IX Item "--sm-attach auto"
\&\f(CW\*(C`subscription\-manager\*(C'\fR attaches to the best\-fitting subscriptions for the system.
.IP "\fB\-\-sm\-attach\fR file:FILENAME" 4
.IX Item "--sm-attach file:FILENAME"
Read the pool ID from \fIFILENAME\fR.
.IP "\fB\-\-sm\-attach\fR pool:POOL" 4
.IX Item "--sm-attach pool:POOL"
Use the literal string \f(CW\*(C`POOL\*(C'\fR as pool ID.
.PP
\&\fI\-\-sm\-remove\fR removes all the subscriptions from the guest, while \fI\-\-sm\-unregister\fR completely unregister the system.
.SS "INSTALLATION PROCESS"
.IX Subsection "INSTALLATION PROCESS"
When you invoke virt\-builder, installation proceeds as follows:
.IP \(bu 4
The template image is downloaded.
.Sp
If the template image is present in the cache, the cached version is used instead.  (See "CACHING").
.IP \(bu 4
The template signature is checked.
.IP \(bu 4
The template is uncompressed to a tmp file.
.IP \(bu 4
The template image is resized into the destination, using \fBvirt\-resize\fR\|(1).
.IP \(bu 4
Extra disks are attached (\fI\-\-attach\fR).
.IP \(bu 4
A new random seed is generated for the guest.
.IP \(bu 4
Guest customization is performed, in the order specified on the command line.
.IP \(bu 4
SELinux relabelling is done unless disabled with \fI\-\-no\-selinux\-relabel\fR.
.SS "IMPORTING THE DISK IMAGE"
.IX Subsection "IMPORTING THE DISK IMAGE"
\fIImporting into libvirt\fR
.IX Subsection "Importing into libvirt"
.PP
Import the disk image into libvirt using \fBvirt\-install\fR\|(1) \fI\-\-import\fR option.
.PP
.Vb 3
\& virt\-install \-\-import \e
\&   \-\-name guest \-\-ram 2048 \e
\&   \-\-disk path=disk.img,format=raw \-\-os\-variant fedora27
.Ve
.PP
注:
.IP 1. 4
You \fImust\fR specify the correct format.  The format is \f(CW\*(C`raw\*(C'\fR unless you used virt\-builder’s \fI\-\-format\fR option.
.IP 2. 4
\&\fI\-\-os\-variant\fR is highly recommended, because it will present optimum devices to enable the guest to run most efficiently.  To get a list of all variants, do:
.Sp
.Vb 1
\& osinfo\-query os
.Ve
.Sp
The above tool is provided by libosinfo package.
.IP 3. 4
You can run virt\-install as root or non\-root.  Each works slightly differently because libvirt manages a different set of virtual machines for each user.  In particular virt\-manager normally shows the root\-owned VMs, whereas Boxes shows the user\-owned VMs, and other tools probably work differently as well.
.PP
\fIImporting into OpenStack\fR
.IX Subsection "Importing into OpenStack"
.PP
Import the image into Glance (the OpenStack image store) by doing:
.PP
.Vb 3
\& glance image\-create \-\-name fedora\-27\-image \-\-file fedora\-27.img \e
\&   \-\-disk\-format raw \-\-container\-format bare \e
\&   \-\-is\-public True
.Ve
.PP
The \fI\-\-file\fR parameter is the virt\-builder\-generated disk image.  It should match virt\-builder’s \fI\-\-output\fR option.  The \fI\-\-disk\-format\fR parameter should match virt\-builder’s \fI\-\-format\fR option (or \f(CW\*(C`raw\*(C'\fR if you didn\*(Aqt use that option).  The \fI\-\-container\-format\fR should always be \f(CW\*(C`bare\*(C'\fR since virt\-builder doesn\*(Aqt put images into containers.
.PP
You can use the \f(CW\*(C`glance\ image\-show\ \fR\f(CIfedora\-27\-image\fR\f(CW\*(C'\fR command to display the properties of the image.
.PP
To boot up an instance of your image on a Nova compute node, do:
.PP
.Vb 2
\& nova boot fedora\-27\-server \-\-image fedora\-27\-image \e
\&   \-\-flavor m1.medium
.Ve
.PP
Use \f(CW\*(C`nova\ flavor\-list\*(C'\fR to list possible machine flavors.  Use \f(CW\*(C`nova\ list\*(C'\fR to list running instances.
.PP
\fIBooting directly using qemu or KVM\fR
.IX Subsection "Booting directly using qemu or KVM"
.PP
The qemu command line is not very stable or easy to use, hence libvirt should be used if possible.  However a command line similar to the following could be used to boot the virtual machine:
.PP
.Vb 5
\& qemu\-system\-x86_64 \e
\&   \-machine accel=kvm:tcg \e
\&   \-cpu host \e
\&   \-m 2048 \e
\&   \-drive file=disk.img,format=raw,if=virtio
.Ve
.PP
As with libvirt, it is very important that the correct format is chosen.  It will be \f(CW\*(C`raw\*(C'\fR unless the \fI\-\-format\fR option was used.
.SS "CONFIGURATION MANAGEMENT"
.IX Subsection "CONFIGURATION MANAGEMENT"
\fIPuppet\fR
.IX Subsection "Puppet"
.PP
To enable the Puppet agent in a guest, install the package, point the configuration at your Puppetmaster, and ensure the agent runs at boot.
.PP
A typical virt\-builder command would be:
.PP
.Vb 7
\& virt\-builder fedora\-27 \e
\&   \-\-hostname client.example.com \e
\&   \-\-update \e
\&   \-\-install puppet \e
\&   \-\-append\-line \*(Aq/etc/puppet/puppet.conf:[agent]\*(Aq \e
\&   \-\-append\-line \*(Aq/etc/puppet/puppet.conf:server = puppetmaster.example.com/\*(Aq \e
\&   \-\-run\-command \*(Aqsystemctl enable puppet\*(Aq
.Ve
.PP
The precise instructions vary according to the Linux distro.  For further information see: https://docs.puppet.com/puppet/latest/install_pre.html
.SS "DEBUGGING BUILDS"
.IX Subsection "DEBUGGING BUILDS"
If virt\-builder itself fails, then enable debugging (\fI\-v\fR) and report a bug (see "BUGS" below).
.PP
If virt\-builder fails because some script or package it is installing fails, try using \fI\-\-no\-delete\-on\-failure\fR to preserve the output file, and continue reading this section.
.PP
If virt\-builder is successful but the image doesn\*(Aqt work, here are some things to try:
.IP "Use virt\-rescue" 4
.IX Item "Use virt-rescue"
Run \fBvirt\-rescue\fR\|(1) on the disk image:
.Sp
.Vb 1
\& virt\-rescue \-a disk.img
.Ve
.Sp
This gives you a rescue shell.  You can mount the filesystems from the disk image on \fI/sysroot\fR and examine them using ordinary Linux commands.  You can also chroot into the guest to reinstall the bootloader.  The virt\-rescue man page has a lot more information and examples.
.IP "Use guestfish" 4
.IX Item "Use guestfish"
Run \fBguestfish\fR\|(1) on the disk image:
.Sp
.Vb 1
\& guestfish \-a disk.img \-i
.Ve
.Sp
Use guestfish commands like \f(CW\*(C`ll /directory\*(C'\fR and \f(CW\*(C`cat /file\*(C'\fR to examine directories and files.
.IP "Use guestmount" 4
.IX Item "Use guestmount"
Mount the disk image safely on the host using FUSE and \fBguestmount\fR\|(1):
.Sp
.Vb 3
\& mkdir /tmp/mp
\& guestmount \-a disk.img \-i /tmp/mp
\& cd /tmp/mp
.Ve
.Sp
To unmount the disk image do:
.Sp
.Vb 1
\& fusermount \-u /tmp/mp
.Ve
.IP "Add a serial console" 4
.IX Item "Add a serial console"
If the guest hangs during boot, it can be helpful to add a serial console to the guest, and direct kernel messages to the serial console.  Adding the serial console will involve looking at the documentation for your hypervisor.  To direct kernel messages to the serial console, add the following on the kernel command line:
.Sp
.Vb 1
\& console=tty0 console=ttyS0,115200
.Ve
.SS "SOURCES OF TEMPLATES"
.IX Subsection "SOURCES OF TEMPLATES"
virt\-builder reads the available sources from configuration files, with the \fI.conf\fR extension and located in the following paths:
.IP \(bu 4
\&\f(CW$XDG_CONFIG_HOME\fR/virt\-builder/repos.d/ (\f(CW$XDG_CONFIG_HOME\fR is \fR\f(CI$HOME\fR\fI/.config\fR if not set).
.IP \(bu 4
\&\f(CW$VIRT_BUILDER_DIRS\fR/virt\-builder/repos.d/ (where \f(CW$VIRT_BUILDER_DIRS\fR means any of the directories in that environment variable, or just \fI/etc\fR if not set).
.PP
Each \fI.conf\fR file in those paths has a simple text format like the following:
.PP
.Vb 3
\& [libguestfs.org]
\& uri=http://libguestfs.org/download/builder/index.asc
\& gpgkey=file:///etc/xdg/virt\-builder/repos.d/libguestfs.gpg
.Ve
.PP
The part in square brackets is the repository identifier, which is used as unique identifier.
.PP
The following fields can appear:
.ie n .IP """uri=URI""" 4
.el .IP \f(CWuri=URI\fR 4
.IX Item "uri=URI"
The URI of the index file which this repository refers to.
.Sp
This field is required.
.ie n .IP """gpgkey=URI""" 4
.el .IP \f(CWgpgkey=URI\fR 4
.IX Item "gpgkey=URI"
This optional field represents the URI (although only \fIfile://\fR URIs are accepted) of the key used to sign the index file.  If not present, the index file referred by \fIuri=..\fR is not signed.
.ie n .IP """proxy=MODE""" 4
.el .IP \f(CWproxy=MODE\fR 4
.IX Item "proxy=MODE"
This optional field specifies the proxy mode, to be used when downloading the index file of this repository.  The possible values are:
.RS 4
.IP "\fBno\fR, \fBoff\fR" 4
.IX Item "no, off"
No proxy is being used at all, even overriding the system configuration.
.IP \fBsystem\fR 4
.IX Item "system"
The proxy used is the system one.
.IP "\fIanything else\fR" 4
.IX Item "anything else"
Specifies the actual proxy configuration to be used, overriding the system configuration.
.RE
.RS 4
.Sp
If not present, the assumed value is to respect the proxy settings of the system (i.e. as if \fBsystem\fR would be specified).
.RE
.ie n .IP """format=FORMAT""" 4
.el .IP \f(CWformat=FORMAT\fR 4
.IX Item "format=FORMAT"
This optional field specifies the format of the repository.  The possible values are:
.RS 4
.IP \fBnative\fR 4
.IX Item "native"
The native format of the \f(CW\*(C`virt\-builder\*(C'\fR repository.  See also "Creating and signing the index file" below.
.IP \fBsimplestreams\fR 4
.IX Item "simplestreams"
The URI represents the root of a Simple Streams v1.0 tree of metadata.
.Sp
For more information about Simple Streams, see also https://launchpad.net/simplestreams.
.RE
.RS 4
.Sp
If not present, the assumed value is \f(CW\*(C`native\*(C'\fR.
.RE
.PP
For serious virt\-builder use, you may want to create your own repository of templates.
.PP
\fILibguestfs.org repository\fR
.IX Subsection "Libguestfs.org repository"
.PP
Out of the box, virt\-builder downloads the file http://libguestfs.org/download/builder/index.asc which is an index of available templates plus some information about each one, wrapped up in a digital signature.  The command \f(CW\*(C`virt\-builder \-\-list\*(C'\fR lists out the information in this index file.
.PP
The templates hosted on libguestfs.org were created using shell scripts, kickstart files and preseed files which can be found in the libguestfs source tree, in \f(CW\*(C`builder/templates\*(C'\fR.
.PP
\fISetting up the repository\fR
.IX Subsection "Setting up the repository"
.PP
You can set up your own site containing an index file and some templates, and then point virt\-builder at the site by creating a \fI.conf\fR file pointing to it.
.PP
Note that if your index is signed, you will need to properly fill \fIgpgkey=..\fR in your \fI.conf\fR file, making sure to deploy also the GPG key file.
.PP
.Vb 3
\& virt\-builder \-\-source https://example.com/builder/index.asc \e
\&    \-\-fingerprint \*(AqAAAA BBBB ...\*(Aq \e
\&    \-\-list
.Ve
.PP
You can host this on any web or FTP server, or a local or network filesystem.
.PP
\fISetting up a GPG key\fR
.IX Subsection "Setting up a GPG key"
.PP
If you don’t have a GnuPG key, you will need to set one up.  (Strictly speaking this is optional, but if your index and template files are not signed then virt\-builder users will have to use the \fI\-\-no\-check\-signature\fR flag every time they use virt\-builder.)
.PP
To create a key, see the GPG manual http://www.gnupg.org/gph/en/manual.html.
.PP
Export your GPG public key:
.PP
.Vb 1
\& gpg \-\-export \-a "you@example.com" > pubkey
.Ve
.PP
\fICreate the templates\fR
.IX Subsection "Create the templates"
.PP
There are many ways to create the templates.  For example you could clone existing guests (see \fBvirt\-sysprep\fR\|(1)), or you could install a guest by hand (\fBvirt\-install\fR\|(1)).  To see how the templates were created for virt\-builder, look at the scripts in \f(CW\*(C`builder/templates\*(C'\fR
.PP
Virt\-builder supports any image format (e.g. raw, qcow2, etc) as template, both as\-is, and compressed as XZ.  This way, existing images (e.g. cleaned using \fBvirt\-sysprep\fR\|(1)) can be used as templates.
.PP
For best results when compressing the templates, use the following xz options (see \fBnbdkit\-xz\-plugin\fR\|(1) for further explanation):
.PP
.Vb 1
\& xz \-\-best \-\-block\-size=16777216 disk
.Ve
.PP
\fICreating and signing the index file\fR
.IX Subsection "Creating and signing the index file"
.PP
The index file has a simple text format (shown here without the digital signature):
.PP
.Vb 10
\& [fedora\-18]
\& name=Fedora® 18
\& osinfo=fedora18
\& arch=x86_64
\& file=fedora\-18.xz
\& checksum[sha512]=...
\& format=raw
\& size=6442450944
\& compressed_size=148947524
\& expand=/dev/sda3
\& 
\& [fedora\-19]
\& name=Fedora® 19
\& osinfo=fedora19
\& arch=x86_64
\& file=fedora\-19.xz
\& checksum[sha512]=...
\& revision=3
\& format=raw
\& size=4294967296
\& compressed_size=172190964
\& expand=/dev/sda3
.Ve
.PP
The part in square brackets is the \f(CW\*(C`os\-version\*(C'\fR, which is the same string that is used on the virt\-builder command line to build that OS.
.PP
The index file creation and signature can be eased with the \fBvirt\-builder\-repository\fR\|(1) tool.
.PP
After preparing the \f(CW\*(C`index\*(C'\fR file in the correct format, clearsign it using the following command:
.PP
.Vb 1
\& gpg \-\-clearsign \-\-armor index
.Ve
.PP
This will create the final file called \fIindex.asc\fR which can be uploaded to the server (and is the \fIuri=..\fR URL).  As noted above, signing the index file is optional, but recommended.
.PP
The following fields can appear:
.ie n .IP """name=NAME""" 4
.el .IP \f(CWname=NAME\fR 4
.IX Item "name=NAME"
The user\-friendly name of this template.  This is displayed in the \fI\-\-list\fR output but is otherwise not significant.
.ie n .IP """osinfo=ID""" 4
.el .IP \f(CWosinfo=ID\fR 4
.IX Item "osinfo=ID"
This optional field maps the operating system to the associated libosinfo ID.  Virt\-builder does not use it (yet).
.ie n .IP """arch=ARCH""" 4
.el .IP \f(CWarch=ARCH\fR 4
.IX Item "arch=ARCH"
The architecture of the operating system installed within the template. This field is required.
.ie n .IP """file=PATH""" 4
.el .IP \f(CWfile=PATH\fR 4
.IX Item "file=PATH"
The path (relative to the index) of the xz\-compressed template.
.Sp
Note that absolute paths or URIs are \fBnot\fR permitted here.  This is because virt\-builder has a "same origin" policy for templates so they cannot come from other servers.
.ie n .IP """sig=PATH""" 4
.el .IP \f(CWsig=PATH\fR 4
.IX Item "sig=PATH"
\&\fBThis option is deprecated\fR.  Use the checksum field instead.
.Sp
The path (relative to the index) of the GPG detached signature of the xz file.
.Sp
Note that absolute paths or URIs are \fBnot\fR permitted here.  This is because virt\-builder has a "same origin" policy for templates so they cannot come from other servers.
.Sp
The file can be created as follows:
.Sp
.Vb 1
\& gpg \-\-detach\-sign \-\-armor \-o disk.xz.sig disk.xz
.Ve
.ie n .IP """checksum[sha512]=7b882fe9b82eb0fef...""" 4
.el .IP \f(CWchecksum[sha512]=7b882fe9b82eb0fef...\fR 4
.IX Item "checksum[sha512]=7b882fe9b82eb0fef..."
The SHA\-512 checksum of the file specified in \fIfile=..\fR is checked after it is downloaded.  To work out the signature, do:
.Sp
.Vb 1
\& sha512sum disk.xz
.Ve
.Sp
Note if you use this, you don’t need to sign the file, ie. don’t use \f(CW\*(C`sig\*(C'\fR.  This option overrides \f(CW\*(C`sig\*(C'\fR.
.ie n .IP """checksum=7b882fe9b82eb0fef...""" 4
.el .IP \f(CWchecksum=7b882fe9b82eb0fef...\fR 4
.IX Item "checksum=7b882fe9b82eb0fef..."
\&\f(CW\*(C`checksum\*(C'\fR is an alias for \f(CW\*(C`checksum[sha512]\*(C'\fR.
.Sp
If you need to interoperate with virt\-builder = 1.24.0 then you have to use \f(CW\*(C`checksum\*(C'\fR because that version would give a parse error with square brackets and numbers in the key of a field.  This is fixed in virt\-builder ≥ 1.24.1.
.ie n .IP """revision=N""" 4
.el .IP \f(CWrevision=N\fR 4
.IX Item "revision=N"
The revision is an integer which is used to control the template cache. Increasing the revision number causes clients to download the template again even if they have a copy in the cache.
.Sp
The revision number is optional.  If omitted it defaults to \f(CW1\fR.
.ie n .IP """format=raw""" 4
.el .IP \f(CWformat=raw\fR 4
.IX Item "format=raw"
.PD 0
.ie n .IP """format=qcow2""" 4
.el .IP \f(CWformat=qcow2\fR 4
.IX Item "format=qcow2"
.PD
Specify the format of the disk image; in case it is compressed, that is the format before the compression.  If not given, the format is autodetected, but generally it is better to be explicit about the intended format.
.Sp
Note this is the source format, which is different from the \fI\-\-format\fR option (requested output format).  Virt\-builder does on\-the\-fly conversion from the source format to the requested output format.
.ie n .IP """size=NNN""" 4
.el .IP \f(CWsize=NNN\fR 4
.IX Item "size=NNN"
The virtual size of the image in bytes.  This is the size of the image when uncompressed.  If using a non\-raw format such as qcow2 then it means the virtual disk size, not the size of the qcow2 file.
.Sp
This field is required.
.Sp
Virt\-builder also uses this as the minimum size that users can request via the \fI\-\-size\fR option, or as the default size if there is no \fI\-\-size\fR option.
.ie n .IP """compressed_size=NNN""" 4
.el .IP \f(CWcompressed_size=NNN\fR 4
.IX Item "compressed_size=NNN"
The actual size of the disk image in bytes, i.e. what was specified in \fIfile=..\fR.  This is just used for information (when using \f(CW\*(C`long\*(C'\fR, and \f(CW\*(C`json\*(C'\fR formats of \fI\-\-list\fR).
.ie n .IP """expand=/dev/sdaX""" 4
.el .IP \f(CWexpand=/dev/sdaX\fR 4
.IX Item "expand=/dev/sdaX"
When expanding the image to its final size, instruct \fBvirt\-resize\fR\|(1) to expand the named partition in the guest image to fill up all available space.  This works like the virt\-resize \fI\-\-expand\fR option.
.Sp
You should usually put the device name of the guest’s root filesystem here.
.Sp
It’s a good idea to use this, but not required.  If the field is omitted then virt\-resize will create an extra partition at the end of the disk to cover the free space, which is much less user\-friendly.
.ie n .IP """lvexpand=/dev/VolGroup/LogVol""" 4
.el .IP \f(CWlvexpand=/dev/VolGroup/LogVol\fR 4
.IX Item "lvexpand=/dev/VolGroup/LogVol"
When expanding the image to its final size, instruct \fBvirt\-resize\fR\|(1) to expand the named logical volume in the guest image to fill up all available space.  This works like the virt\-resize \fI\-\-lv\-expand\fR option.
.Sp
If the guest uses LVM2 you should usually put the LV of the guest’s root filesystem here.  If the guest does not use LVM2 or its root filesystem is not on an LV, don\*(Aqt use this option.
.ie n .IP """notes=NOTES""" 4
.el .IP \f(CWnotes=NOTES\fR 4
.IX Item "notes=NOTES"
Any notes that go with this image, especially notes describing what packages are in the image, how the image was prepared, and licensing information.
.Sp
This information is shown in the \fI\-\-notes\fR and \fI\-\-list\fR \fI\-\-long\fR modes.
.Sp
You can use multi\-line notes here by indenting each new line with at least one character of whitespace (even on blank lines):
.Sp
.Vb 5
\& notes=This image was prepared using
\&  the following kickstart script:
\&                                <\-\- one space at beginning of line
\&  part /boot \-\-fstype ext3
\&  ...
.Ve
.ie n .IP """hidden=true""" 4
.el .IP \f(CWhidden=true\fR 4
.IX Item "hidden=true"
Using the hidden flag prevents the template from being listed by the \fI\-\-list\fR option (but it is still installable).  This is used for test images.
.ie n .IP """aliases=ALIAS1 ALIAS2 ...""" 4
.el .IP "\f(CWaliases=ALIAS1 ALIAS2 ...\fR" 4
.IX Item "aliases=ALIAS1 ALIAS2 ..."
This optional field specifies a list of aliases, separated by spaces, for the image.  For example, an alias could be used to always point to the latest version of a certain image, leaving the old versions available in the index instead of updating the same image (see the \f(CW\*(C`revision\*(C'\fR field).
.PP
\fIRunning virt\-builder against multiple sources\fR
.IX Subsection "Running virt-builder against multiple sources"
.PP
It is possible to use multiple sources with virt\-builder.  The recommended way is to deploy \fI.conf\fR files pointing to the index files. Another way is to specify the sources using multiple \fI\-\-source\fR and/or \fI\-\-fingerprint\fR options:
.PP
.Vb 3
\& virt\-builder \e
\&   \-\-source http://example.com/s1/index.asc \e
\&   \-\-source http://example.com/s2/index.asc
.Ve
.PP
You can provide N or 1 fingerprints.  In the case where you provide N fingerprints, N = number of sources and there is a 1\-1 correspondence between each source and each fingerprint:
.PP
.Vb 3
\& virt\-builder \e
\&   \-\-source http://example.com/s1/index.asc \-\-fingerprint \*(Aq0123 ...\*(Aq \e
\&   \-\-source http://example.com/s2/index.asc \-\-fingerprint \*(Aq9876 ...\*(Aq
.Ve
.PP
In the case where you provide 1 fingerprint, the same fingerprint is used for all sources.
.PP
You \f(CW\*(C`must\*(C'\fR provide at least 1 fingerprint.
.PP
\fILicensing of templates\fR
.IX Subsection "Licensing of templates"
.PP
You should be aware of the licensing of images that you distribute.  For open source guests, provide a link to the source code in the \f(CW\*(C`notes\*(C'\fR field and comply with other requirements (eg. around trademarks).
.PP
\fIFormal specification of the index file\fR
.IX Subsection "Formal specification of the index file"
.PP
The index file format has a formal specification defined by the flex scanner and bison parser used to parse the file.  This can be found in the following files in the libguestfs source tree:
.PP
.Vb 2
\& builder/index\-scan.l
\& builder/index\-parse.y
.Ve
.PP
A tool called \fBvirt\-index\-validate\fR\|(1) is available to validate the index file to ensure it is correct.
.PP
Note that the parser and tool can work on either the signed or unsigned index file (ie. \fIindex\fR or \fIindex.asc\fR).
.PP
The index is always encoded in UTF\-8.
.SS CACHING
.IX Subsection "CACHING"
\fICaching templates\fR
.IX Subsection "Caching templates"
.PP
Since the templates are usually very large, downloaded templates are cached in the user’s home directory.
.PP
The location of the cache is \fR\f(CI$XDG_CACHE_HOME\fR\fI/virt\-builder/\fR or \fI\fR\f(CI$HOME\fR\fI/.cache/virt\-builder\fR.
.PP
You can print out information about the cache directory, including which guests are currently cached, by doing:
.PP
.Vb 1
\& virt\-builder \-\-print\-cache
.Ve
.PP
The cache can be deleted if you want to save space by doing:
.PP
.Vb 1
\& virt\-builder \-\-delete\-cache
.Ve
.PP
You can download all (current) templates to the local cache by doing:
.PP
.Vb 1
\& virt\-builder \-\-cache\-all\-templates
.Ve
.PP
To disable the template cache, use \fI\-\-no\-cache\fR.
.PP
Only templates are cached.  The index and detached digital signatures are not cached.
.PP
\fICaching packages\fR
.IX Subsection "Caching packages"
.PP
Virt\-builder uses \fBcurl\fR\|(1) to download files and it also uses the current \f(CW\*(C`http_proxy\*(C'\fR (etc) settings when installing packages (\fI\-\-install\fR, \fI\-\-update\fR).
.PP
You may therefore want to set those environment variables in order to maximize the amount of local caching that happens.  See "ENVIRONMENT VARIABLES" and \fBcurl\fR\|(1).
.PP
\fILocal mirrors\fR
.IX Subsection "Local mirrors"
.PP
To increase both speed and reliability of installing packages, you can set up a local mirror of the target distribution, and point the guest package manager at that.
.PP
Using a local mirror with Fedora
.IX Subsection "Using a local mirror with Fedora"
.PP
To install a Fedora guest using a local mirror:
.PP
.Vb 11
\& virt\-builder fedora\-27 \e
\&   \-\-edit \*(Aq/etc/yum.repos.d/fedora.repo:
\&       s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
\&       s{.*metalink=.*}{};
\&   \*(Aq \e
\&   \-\-edit \*(Aq/etc/yum.repos.d/fedora\-updates.repo:
\&       s{.*baseurl=.*}{baseurl=http://example.com/mirror\-updates/};
\&       s{.*metalink=.*}{};
\&   \*(Aq \e
\&   \-\-run\-command \*(Aqdnf \-y update\*(Aq \e
\&   \-\-install \*(Aqpkg1,pkg2,...\*(Aq
.Ve
.PP
Using a local mirror with Debian
.IX Subsection "Using a local mirror with Debian"
.PP
Assuming that you are using \f(CW\*(C`apt\-proxy\*(C'\fR to mirror the repository, you should create a new \fIsources.list\fR file to point to your proxy (see https://help.ubuntu.com/community/AptProxy) and then do:
.PP
.Vb 4
\& virt\-builder debian\-8 \e
\&   \-\-upload sources.list:/etc/apt/sources.list \e
\&   \-\-run\-command \*(Aqapt\-get \-y update\*(Aq \e
\&   \-\-install \*(Aqpkg1,pkg2,...\*(Aq
.Ve
.SS "DIGITAL SIGNATURES"
.IX Subsection "DIGITAL SIGNATURES"
Virt\-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the index and templates have not been tampered with.
.PP
The source points to an index file, which is optionally signed.
.PP
Virt\-builder downloads the index and checks that the signature is valid and the signer’s fingerprint matches the specified fingerprint (ie. the one specified in \fIgpgkey=..\fR in the \fI.conf\fR, or with \fI\-\-fingerprint\fR, in that order).
.PP
For checking against the built\-in public key/fingerprint, this requires importing the public key into the user’s local gpg keyring (that’s just the way that gpg works).
.PP
When a template is downloaded, its signature is checked in the same way.
.PP
Although the signatures are optional, if you don’t have them then virt\-builder users will have to use \fI\-\-no\-check\-signature\fR on the command line.  This prevents an attacker from replacing the signed index file with an unsigned index file and having virt\-builder silently work without checking the signature.  In any case it is highly recommended that you always create signed index and templates.
.SS アーキテクチャー
.IX Subsection "アーキテクチャー"
Virt\-builder can build a guest for any architecture no matter what the host architecture is.  For example an x86\-64 guest on an ARM host.
.PP
However certain options may not work, specifically options that require running commands in the guest during the build process: \fI\-\-install\fR, \fI\-\-update\fR, \fI\-\-run\fR, \fI\-\-run\-command\fR.  You may need to replace these with their firstboot\-equivalents.
.PP
An x86\-64 host building 32 bit i686 guests should work without any special steps.
.SS セキュリティ
.IX Subsection "セキュリティ"
Virt\-builder does not need to run as root (in fact, should not be run as root), and doesn\*(Aqt use setuid, \f(CW\*(C`sudo\*(C'\fR or any similar mechanism.
.PP
\&\fI\-\-install\fR, \fI\-\-update\fR, \fI\-\-run\fR and \fI\-\-run\-command\fR are implemented using an appliance (a small virtual machine) so these commands do not run on the host.  If you are using the libguestfs libvirt backend and have SELinux enabled then the virtual machine is additionally encapsulated in an SELinux container (sVirt).
.PP
However these options will have access to the host’s network and since the template may contain untrusted code, the code might try to access host network resources which it should not.  You can use \fI\-\-no\-network\fR to prevent this.
.PP
Firstboot commands run in the context of the guest when it is booted, and so the security of your hypervisor / cloud should be considered.
.PP
Virt\-builder injects a random seed into every guest which it builds.  This helps to ensure that TCP sequence numbers, UUIDs, ssh host keys etc are truly random when the guest boots.
.PP
You should check digital signatures and not ignore any signing errors.
.SS CLONES
.IX Subsection "CLONES"
If you wish to create many new guests of the same type, it is tempting to run virt\-builder once and then copy the output file.  You should \fBnot\fR do this.  You should run virt\-builder once for each new guest you need.
.PP
The reason is that each clone needs to have (at least) a separate random seed, and possibly other unique features (such as filesystem UUIDs) in future versions of virt\-builder.
.PP
Another thing you should \fInot\fR do is to boot the guest, then clone the booted disk image.  The reason is that some guests create unique machine IDs, SSH host keys and so on at first boot, and you would not want clones to have duplicate identities.
.PP
See also: \fBvirt\-sysprep\fR\|(1).
.SS PERFORMANCE
.IX Subsection "PERFORMANCE"
The most important aspect of getting good performance is caching.  Templates gets downloaded into the cache the first time they are used, or if you use the \fI\-\-cache\-all\-templates\fR option.  See "CACHING" above for further information.
.PP
Packages required for the \fI\-\-install\fR and \fI\-\-update\fR options are downloaded using the host network connection.  Setting the \f(CW\*(C`http_proxy\*(C'\fR, \f(CW\*(C`https_proxy\*(C'\fR and \f(CW\*(C`ftp_proxy\*(C'\fR environment variables to point to a local web cache may ensure they only need to be downloaded once.  You can also try using a local package repository, although this can be complex to set up and varies according to which Linux distro you are trying to install.
.PP
\fIUsing \-\-no\-sync\fR
.IX Subsection "Using --no-sync"
.PP
Use \fI\-\-no\-sync\fR.  However read the caveats in the "OPTIONS" section above, since this can cause disk corruption if not used correctly.
.PP
\fISkipping virt\-resize\fR
.IX Subsection "Skipping virt-resize"
.PP
Virt\-builder can skip the virt\-resize step under certain conditions.  This makes virt\-builder much faster.  The conditions are:
.IP \(bu 4
the output must be a regular file (not a block device), \fBand\fR
.IP \(bu 4
the user did \fBnot\fR use the \fI\-\-size\fR option, \fBand\fR
.IP \(bu 4
the output format is the same as the template format (usually raw).
.PP
\fIpxzcat\fR
.IX Subsection "pxzcat"
.PP
Virt\-builder uses an internal implementation of pxzcat (parallel xzcat) if liblzma was found at build time.  If liblzma was not found at build time, regular \f(CW\*(C`xzcat\*(C'\fR is used which is single\-threaded.
.SS SELinux
.IX Subsection "SELinux"
Guests which use SELinux (such as Fedora and Red Hat Enterprise Linux) require that each file has a correct SELinux label.
.PP
Virt\-builder does not know how to give new files a label, so there are two possible strategies it can use to ensure correct labelling:
.IP "Automatic relabeling" 4
.IX Item "Automatic relabeling"
This runs \fBsetfiles\fR\|(8) just before finalizing the guest, which sets SELinux labels correctly in the disk image.
.Sp
This is the recommended method.
.IP "Using \fI\-\-no\-selinux\-relabel\fR \fI\-\-touch\fR \fI/.autorelabel\fR" 4
.IX Item "Using --no-selinux-relabel --touch /.autorelabel"
Guest templates may already contain a file called \fI/.autorelabel\fR or you may touch it.
.Sp
For guests that use SELinux, this causes \fBrestorecon\fR\|(8) to run at first boot.  Guests will reboot themselves once the first time you use them, which is normal and harmless.
.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\-builder from other programs, GUIs etc.
.PP
Use the option on its own to query the capabilities of the virt\-builder binary.  Typical output looks like this:
.PP
.Vb 7
\& $ virt\-builder \-\-machine\-readable
\& virt\-builder
\& arch
\& config\-file
\& customize
\& json\-list
\& pxzcat
.Ve
.PP
A list of features is printed, one per line, and the program exits with status 0.
.PP
It is possible to specify a format string for controlling the output; see "ADVANCED MACHINE READABLE OUTPUT" in \fBguestfs\fR\|(3).
.SH 環境変数
.IX Header "環境変数"
For other environment variables which affect all libguestfs programs, see "ENVIRONMENT VARIABLES" in \fBguestfs\fR\|(3).
.ie n .IP """http_proxy""" 4
.el .IP \f(CWhttp_proxy\fR 4
.IX Item "http_proxy"
.PD 0
.ie n .IP """https_proxy""" 4
.el .IP \f(CWhttps_proxy\fR 4
.IX Item "https_proxy"
.ie n .IP """no_proxy""" 4
.el .IP \f(CWno_proxy\fR 4
.IX Item "no_proxy"
.PD
Set the proxy for downloads.  These environment variables (and more)  are actually interpreted by \fBcurl\fR\|(1), not virt\-builder.
.ie n .IP """HOME""" 4
.el .IP \f(CWHOME\fR 4
.IX Item "HOME"
Used to determine the location of the template cache, and the location of the user\*(Aq sources.  See "CACHING" and "SOURCES OF TEMPLATES".
.ie n .IP """VIRT_TOOLS_DATA_DIR""" 4
.el .IP \f(CWVIRT_TOOLS_DATA_DIR\fR 4
.IX Item "VIRT_TOOLS_DATA_DIR"
This can point to the directory containing data files used for Windows firstboot installation.
.Sp
Normally you do not need to set this.  If not set, a compiled\-in default will be used (something like \fI/usr/share/virt\-tools\fR).
.Sp
This directory may contain the following files:
.RS 4
.IP \fIrhsrvany.exe\fR 4
.IX Item "rhsrvany.exe"
This is the RHSrvAny Windows binary, used to install a "firstboot" script in Windows guests.  It is required if you intend to use the \fI\-\-firstboot\fR or \fI\-\-firstboot\-command\fR options with Windows guests.
.Sp
See also: \f(CW\*(C`https://github.com/rwmjones/rhsrvany\*(C'\fR
.IP \fIpvvxsvc.exe\fR 4
.IX Item "pvvxsvc.exe"
This is a Windows binary shipped with SUSE VMDP, used to install a "firstboot" script in Windows guests.  It is required if you intend to use the \fI\-\-firstboot\fR or \fI\-\-firstboot\-command\fR options with Windows guests.
.RE
.RS 4
.RE
.ie n .IP """XDG_CACHE_HOME""" 4
.el .IP \f(CWXDG_CACHE_HOME\fR 4
.IX Item "XDG_CACHE_HOME"
Used to determine the location of the template cache.  See "CACHING".
.ie n .IP """XDG_CONFIG_HOME""" 4
.el .IP \f(CWXDG_CONFIG_HOME\fR 4
.IX Item "XDG_CONFIG_HOME"
Used to determine the location of the user\*(Aq sources.  See "SOURCES OF TEMPLATES".
.ie n .IP """VIRT_BUILDER_DIRS""" 4
.el .IP \f(CWVIRT_BUILDER_DIRS\fR 4
.IX Item "VIRT_BUILDER_DIRS"
Used to determine the location of the system sources.  See "SOURCES OF TEMPLATES".
.SH 終了ステータス
.IX Header "終了ステータス"
このプログラムは、成功すると 0 を、エラーがあると 0 以外を返します。
.SH 関連項目
.IX Header "関連項目"
\&\fBguestfs\fR\|(3), \fBguestfish\fR\|(1), \fBguestmount\fR\|(1), \fBvirt\-builder\-repository\fR\|(1), \fBvirt\-copy\-out\fR\|(1), \fBvirt\-customize\fR\|(1), \fBvirt\-get\-kernel\fR\|(1), \fBvirt\-install\fR\|(1), \fBvirt\-rescue\fR\|(1), \fBvirt\-resize\fR\|(1), \fBvirt\-sysprep\fR\|(1), \fBoz\-install\fR\|(1), \fBgpg\fR\|(1), \fBgpg2\fR\|(1), \fBcurl\fR\|(1), \fBvirt\-make\-fs\fR\|(1), \fBgenisoimage\fR\|(1), http://libguestfs.org/.
.SH 著者
.IX Header "著者"
Richard W.M. Jones http://people.redhat.com/~rjones/
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2013 Red Hat Inc.
.SH LICENSE
.IX Header "LICENSE"
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.
.PP
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.
.PP
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.
.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.