.\" 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 "guestfs-faq 1"
.TH guestfs-faq 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 "名前"
guestfs-faq \- libguestfs のよくある質問 (\s-1FAQ\s0)
.SH "libguestfs について"
.IX Header "libguestfs について"
.SS "libguestfs とは?"
.IX Subsection "libguestfs とは?"
libguestfs is a way to create, access and modify disk images.  You can look
inside disk images, modify the files they contain, create them from scratch,
resize them, and much more.  It’s especially useful from scripts and
programs and from the command line.
.PP
libguestfs is a C library (hence \*(L"lib\-\*(R"), and a set of tools built on this
library, and bindings for many common programming languages.
.PP
libguestfs が実行できることの詳細はホームページ (http://libguestfs.org) にある紹介を参照できます。
.SS "virt ツールとは何か?"
.IX Subsection "virt ツールとは何か?"
Virt tools (website: http://virt\-tools.org) are a whole set of
virtualization management tools aimed at system administrators.  Some of
them come from libguestfs, some from libvirt and many others from other open
source projects.  So virt tools is a superset of libguestfs.  However
libguestfs comes with many important tools.  See http://libguestfs.org
for a full list.
.SS "libguestfs は { libvirt / \s-1KVM /\s0 Red Hat / Fedora } が必要ですか?"
.IX Subsection "libguestfs は { libvirt / KVM / Red Hat / Fedora } が必要ですか?"
いいえ！
.PP
libvirt は libguestfs に必須ではありません。
.PP
libguestfs works with any disk image, including ones created in VMware, \s-1KVM,\s0
qemu, VirtualBox, Xen, and many other hypervisors, and ones which you have
created from scratch.
.PP
Red Hat sponsors (ie. pays for) development of libguestfs and a huge
number of other open source projects.  But you can run libguestfs and the
virt tools on many different Linux distros and Mac \s-1OS X.\s0  We try our best to
support all Linux distros as first-class citizens.  Some virt tools have
been ported to Windows.
.SS "How does libguestfs compare to other tools?"
.IX Subsection "How does libguestfs compare to other tools?"
.IP "\fIvs. kpartx\fR" 4
.IX Item "vs. kpartx"
Libguestfs takes a different approach from kpartx.  kpartx needs root, and
mounts filesystems on the host kernel (which can be insecure \- see
\&\fBguestfs\-security\fR\|(1)).  Libguestfs isolates your host kernel from guests,
is more flexible, scriptable, supports \s-1LVM,\s0 doesn't require root, is
isolated from other processes, and cleans up after itself.  Libguestfs is
more than just file access because you can use it to create images from
scratch.
.IP "\fIvs. vdfuse\fR" 4
.IX Item "vs. vdfuse"
vdfuse is like kpartx but for VirtualBox images.  See the kpartx comparison
above.  You can use libguestfs on the partition files exposed by vdfuse,
although it’s not necessary since libguestfs can access VirtualBox images
directly.
.IP "\fIvs. qemu-nbd\fR" 4
.IX Item "vs. qemu-nbd"
\&\s-1NBD\s0 (Network Block Device) is a protocol for exporting block devices over
the network.  qemu-nbd is an \s-1NBD\s0 server which can handle any disk format
supported by qemu (eg. raw, qcow2).  You can use libguestfs and qemu-nbd or
nbdkit together to access block devices over the network, for example:
\&\f(CW\*(C`guestfish \-a nbd://remote\*(C'\fR
.IP "\fIvs. mounting filesystems in the host\fR" 4
.IX Item "vs. mounting filesystems in the host"
Mounting guest filesystems in the host is insecure and should be avoided
completely for untrusted guests.  Use libguestfs to provide a layer of
protection against filesystem exploits.  See also \fBguestmount\fR\|(1).
.IP "\fIvs. parted\fR" 4
.IX Item "vs. parted"
Libguestfs supports \s-1LVM.\s0  Libguestfs uses parted and provides most parted
features through the libguestfs \s-1API.\s0
.SH "GETTING HELP AND REPORTING BUGS"
.IX Header "GETTING HELP AND REPORTING BUGS"
.SS "How do I know what version I'm using?"
.IX Subsection "How do I know what version I'm using?"
最も簡単な方法は次のとおりです:
.PP
.Vb 1
\& guestfish \-\-version
.Ve
.PP
Libguestfs development happens along an unstable branch and we periodically
create a stable branch which we backport stable patches to.  To find out
more, read \*(L"\s-1LIBGUESTFS VERSION NUMBERS\*(R"\s0 in \fBguestfs\fR\|(3).
.SS "How can I get help?"
.IX Subsection "How can I get help?"
.SS "What mailing lists or chat rooms are available?"
.IX Subsection "What mailing lists or chat rooms are available?"
If you are a Red Hat customer using Red Hat Enterprise Linux, please
contact Red Hat Support: http://redhat.com/support
.PP
There is a mailing list, mainly for development, but users are also welcome
to ask questions about libguestfs and the virt tools:
https://www.redhat.com/mailman/listinfo/libguestfs
.PP
You can also talk to us on \s-1IRC\s0 channel \f(CW\*(C`#libguestfs\*(C'\fR on FreeNode.  We're
not always around, so please stay in the channel after asking your question
and someone will get back to you.
.PP
For other virt tools (not ones supplied with libguestfs) there is a general
virt tools mailing list:
https://www.redhat.com/mailman/listinfo/virt\-tools\-list
.SS "どのようにバグを報告しますか?"
.IX Subsection "どのようにバグを報告しますか?"
Bugzilla にバグを入力するには、以下のリンクを使用してください:
.PP
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
Include as much detail as you can and a way to reproduce the problem.
.PP
Include the full output of \fBlibguestfs\-test\-tool\fR\|(1).
.SH "一般的な問題"
.IX Header "一般的な問題"
See also \*(L"\s-1LIBGUESTFS GOTCHAS\*(R"\s0 in \fBguestfs\fR\|(3) for some \*(L"gotchas\*(R" with using the
libguestfs \s-1API.\s0
.ie n .SS """Could not allocate dynamic translator buffer"""
.el .SS "``Could not allocate dynamic translator buffer''"
.IX Subsection "Could not allocate dynamic translator buffer"
This obscure error is in fact an SELinux failure.  You have to enable the
following SELinux boolean:
.PP
.Vb 1
\& setsebool \-P virt_use_execmem=on
.Ve
.PP
詳細は https://bugzilla.redhat.com/show_bug.cgi?id=806106 を参照してください。
.ie n .SS """child process died unexpectedly"""
.el .SS "``child process died unexpectedly''"
.IX Subsection "child process died unexpectedly"
[This error message was changed in libguestfs 1.21.18 to something more
explanatory.]
.PP
This error indicates that qemu failed or the host kernel could not boot.  To
get further information about the failure, you have to run:
.PP
.Vb 1
\& libguestfs\-test\-tool
.Ve
.PP
If, after using this, you still don’t understand the failure, contact us
(see previous section).
.SS "libguestfs: error: cannot find any suitable libguestfs supermin, fixed or old-style appliance on \s-1LIBGUESTFS_PATH\s0"
.IX Subsection "libguestfs: error: cannot find any suitable libguestfs supermin, fixed or old-style appliance on LIBGUESTFS_PATH"
.SS "febootstrap-supermin-helper: ext2: parent directory not found"
.IX Subsection "febootstrap-supermin-helper: ext2: parent directory not found"
.SS "supermin-helper: ext2: parent directory not found"
.IX Subsection "supermin-helper: ext2: parent directory not found"
[This issue is fixed permanently in libguestfs ≥ 1.26.]
.PP
If you see any of these errors on Debian/Ubuntu, you need to run the
following command:
.PP
.Vb 1
\& sudo update\-guestfs\-appliance
.Ve
.ie n .SS """Permission denied"" when running libguestfs as root"
.el .SS "``Permission denied'' when running libguestfs as root"
.IX Subsection "Permission denied when running libguestfs as root"
You get a permission denied error when opening a disk image, even though you
are running libguestfs as root.
.PP
This is caused by libvirt, and so only happens when using the libvirt
backend.  When run as root, libvirt decides to run the qemu appliance as
user \f(CW\*(C`qemu.qemu\*(C'\fR.  Unfortunately this usually means that qemu cannot open
disk images, especially if those disk images are owned by root, or are
present in directories which require root access.
.PP
There is a bug open against libvirt to fix this:
https://bugzilla.redhat.com/show_bug.cgi?id=1045069
.PP
You can work around this by one of the following methods:
.IP "\(bu" 4
Switch to the direct backend:
.Sp
.Vb 1
\& export LIBGUESTFS_BACKEND=direct
.Ve
.IP "\(bu" 4
Don’t run libguestfs as root.
.IP "\(bu" 4
Chmod the disk image and any parent directories so that the qemu user can
access them.
.IP "\(bu" 4
(Nasty) Edit \fI/etc/libvirt/qemu.conf\fR and change the \f(CW\*(C`user\*(C'\fR setting.
.SS "execl: /init: Permission denied"
.IX Subsection "execl: /init: Permission denied"
\&\fBNote:\fR If this error happens when you are using a distro package of
libguestfs (eg. from Fedora, Debian, etc) then file a bug against the
distro.  This is not an error which normal users should ever see if the
distro package has been prepared correctly.
.PP
This error happens during the supermin boot phase of starting the appliance:
.PP
.Vb 5
\& supermin: mounting new root on /root
\& supermin: chroot
\& execl: /init: Permission denied
\& supermin: debug: listing directory /
\& [...followed by a lot of debug output...]
.Ve
.PP
This is a complicated bug related to \fBsupermin\fR\|(1) appliances.  The
appliance is constructed by copying files like \fI/bin/bash\fR and many
libraries from the host.  The file \f(CW\*(C`hostfiles\*(C'\fR lists the files that should
be copied from the host into the appliance.  If some files don't exist on
the host then they are missed out, but if these files are needed in order to
(eg) run \fI/bin/bash\fR then you'll see the above error.
.PP
Diagnosing the problem involves studying the libraries needed by
\&\fI/bin/bash\fR, ie:
.PP
.Vb 1
\& ldd /bin/bash
.Ve
.PP
comparing that with \f(CW\*(C`hostfiles\*(C'\fR, with the files actually available in the
host filesystem, and with the debug output printed in the error message.
Once you've worked out which file is missing, install that file using your
package manager and try again.
.PP
You should also check that files like \fI/init\fR and \fI/bin/bash\fR (in the
appliance) are executable.  The debug output shows file modes.
.SH "DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS"
.IX Header "DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS"
.SS "どこから最新のバイナリーを入手できますか ...?"
.IX Subsection "どこから最新のバイナリーを入手できますか ...?"
.IP "Fedora ≥ 11" 4
.IX Item "Fedora ≥ 11"
こうします:
.Sp
.Vb 1
\& yum install \*(Aq*guestf*\*(Aq
.Ve
.Sp
最新版は次を参照してください:
http://koji.fedoraproject.org/koji/packageinfo?packageID=8391
.IP "Red Hat Enterprise Linux" 4
.IX Item "Red Hat Enterprise Linux"
.RS 4
.PD 0
.IP "\s-1RHEL 5\s0" 4
.IX Item "RHEL 5"
.PD
The version shipped in official \s-1RHEL 5\s0 is very old and should not be used
except in conjunction with virt\-v2v.  Use the up-to-date libguestfs 1.20
package in \s-1EPEL 5:\s0 https://fedoraproject.org/wiki/EPEL
.IP "\s-1RHEL 6\s0" 4
.IX Item "RHEL 6"
.PD 0
.IP "\s-1RHEL 7\s0" 4
.IX Item "RHEL 7"
.PD
It is part of the default install.  On \s-1RHEL 6\s0 and 7 (only) you have to
install \f(CW\*(C`libguestfs\-winsupport\*(C'\fR to get Windows guest support.
.RE
.RS 4
.RE
.IP "Debian および Ubuntu" 4
.IX Item "Debian および Ubuntu"
For libguestfs < 1.26, after installing libguestfs you need to do:
.Sp
.Vb 1
\& sudo update\-guestfs\-appliance
.Ve
.Sp
(This script has been removed on Debian/Ubuntu with libguestfs ≥ 1.26
and instead the appliance is built on demand.)
.Sp
On Ubuntu only:
.Sp
.Vb 1
\& sudo chmod 0644 /boot/vmlinuz*
.Ve
.Sp
You may need to add yourself to the \f(CW\*(C`kvm\*(C'\fR group:
.Sp
.Vb 1
\& sudo usermod \-a \-G kvm yourlogin
.Ve
.RS 4
.IP "Debian Squeeze (6)" 4
.IX Item "Debian Squeeze (6)"
Hilko Bengen has built libguestfs in squeeze backports:
http://packages.debian.org/search?keywords=guestfs&searchon=names&section=all&suite=squeeze\-backports
.IP "Debian Wheezy およびそれ以降 (7+)" 4
.IX Item "Debian Wheezy およびそれ以降 (7+)"
Hilko Bengen supports libguestfs on Debian.  Official Debian packages are
available: http://packages.debian.org/search?keywords=libguestfs
.IP "Ubuntu" 4
.IX Item "Ubuntu"
We don’t have a full time Ubuntu maintainer, and the packages supplied by
Canonical (which are outside our control) are sometimes broken.
.Sp
Canonical はカーネルにおけるパーミッションを変更することを決定したため、これは root
により読み込めません。これは完全におかしいですが、変更しようとはしません
(https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725)。そのため、すべてのユーザーはこうする必要があります:
.Sp
.Vb 1
\& sudo chmod 0644 /boot/vmlinuz*
.Ve
.RS 4
.IP "Ubuntu 12.04" 4
.IX Item "Ubuntu 12.04"
このバージョンの Ubuntu にある libguestfs が動作しますが、febootstrap および seabios
を最新バージョンに更新する必要があります。
.Sp
次のところにある febootstrap ≥ 3.14\-2 が必要です:
http://packages.ubuntu.com/precise/febootstrap
.Sp
febootstrap のインストールまたは更新後、アプライアンスを再構築します:
.Sp
.Vb 1
\& sudo update\-guestfs\-appliance
.Ve
.Sp
次のところにある seabios ≥ 0.6.2\-0ubuntu2.1 または ≥ 0.6.2\-0ubuntu3 が必要です:
http://packages.ubuntu.com/precise\-updates/seabios または
http://packages.ubuntu.com/quantal/seabios
.Sp
次のことも実行する必要があります (上述、参照):
.Sp
.Vb 1
\& sudo chmod 0644 /boot/vmlinuz*
.Ve
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "Gentoo" 4
.IX Item "Gentoo"
libguestfs が Andreis Vinogradovs (libguestfs) および Maxim Koltsov (おもに hivex)
により 2012\-07 に Gentoo に追加されました。次のとおり実行します:
.Sp
.Vb 1
\& emerge libguestfs
.Ve
.IP "SuSE" 4
.IX Item "SuSE"
libguestfs が Olaf Hering により 2012 年に SuSE に追加されました。
.IP "ArchLinux" 4
.IX Item "ArchLinux"
libguestfs が 2010 年に \s-1AUR\s0 に追加されました。
.IP "他の Linux ディストリビューション" 4
.IX Item "他の Linux ディストリビューション"
ソースからコンパイルします (次のセクション)。
.IP "他の非 Linux ディストリビューション" 4
.IX Item "他の非 Linux ディストリビューション"
ソースからコンパイルして、取り込む必要があります。
.SS "How can I compile and install libguestfs from source?"
.IX Subsection "How can I compile and install libguestfs from source?"
You can compile libguestfs from git or a source tarball.  Read the \s-1README\s0
file before starting.
.PP
Git: https://github.com/libguestfs/libguestfs Source tarballs:
http://libguestfs.org/download
.PP
Don’t run \f(CW\*(C`make install\*(C'\fR! Use the \f(CW\*(C`./run\*(C'\fR script instead (see \s-1README\s0).
.SS "How can I compile and install libguestfs if my distro doesn't have new enough qemu/supermin/kernel?"
.IX Subsection "How can I compile and install libguestfs if my distro doesn't have new enough qemu/supermin/kernel?"
Libguestfs needs supermin 5.  If supermin 5 hasn't been ported to your
distro, then see the question below.
.PP
First compile qemu, supermin and/or the kernel from source.  You do \fInot\fR
need to \f(CW\*(C`make install\*(C'\fR them.
.PP
In the libguestfs source directory, create two files.  \f(CW\*(C`localconfigure\*(C'\fR
should contain:
.PP
.Vb 3
\& source localenv
\& #export PATH=/tmp/qemu/x86_64\-softmmu:$PATH
\& ./autogen.sh \-\-prefix /usr "$@"
.Ve
.PP
Make \f(CW\*(C`localconfigure\*(C'\fR executable.
.PP
\&\f(CW\*(C`localenv\*(C'\fR should contain:
.PP
.Vb 5
\& #export SUPERMIN=/tmp/supermin/src/supermin
\& #export LIBGUESTFS_HV=/tmp/qemu/x86_64\-softmmu/qemu\-system\-x86_64
\& #export SUPERMIN_KERNEL=/tmp/linux/arch/x86/boot/bzImage
\& #export SUPERMIN_KERNEL_VERSION=4.XX.0
\& #export SUPERMIN_MODULES=/tmp/lib/modules/4.XX.0
.Ve
.PP
Uncomment and adjust these lines as required to use the alternate programs
you have compiled.
.PP
Use \f(CW\*(C`./localconfigure\*(C'\fR instead of \f(CW\*(C`./configure\*(C'\fR, but otherwise you compile
libguestfs as usual.
.PP
Don’t run \f(CW\*(C`make install\*(C'\fR! Use the \f(CW\*(C`./run\*(C'\fR script instead (see \s-1README\s0).
.SS "How can I compile and install libguestfs without supermin?"
.IX Subsection "How can I compile and install libguestfs without supermin?"
If supermin 5 supports your distro, but you don’t happen to have a new
enough supermin installed, then see the previous question.
.PP
If supermin 5 doesn't support your distro at all, you will need to use the
\&\*(L"fixed appliance method\*(R" where you use a pre-compiled binary appliance.  To
build libguestfs without supermin, you need to pass \f(CW\*(C`\-\-disable\-appliance
\&\-\-disable\-daemon\*(C'\fR to either \fI./autogen.sh\fR or \fI./configure\fR (depending
whether you are building respectively from git or from tarballs).  Then,
when using libguestfs, you \fBmust\fR set the \f(CW\*(C`LIBGUESTFS_PATH\*(C'\fR environment
variable to the directory of a pre-compiled appliance, as also described in
\&\*(L"\s-1FIXED APPLIANCE\*(R"\s0 in \fBguestfs\-internals\fR\|(1).
.PP
For pre-compiled appliances, see also:
http://libguestfs.org/download/binaries/appliance/.
.PP
Patches to port supermin to more Linux distros are welcome.
.SS "どのように sVirt をサポートしますか?"
.IX Subsection "どのように sVirt をサポートしますか?"
\&\fBNote for Fedora/RHEL users:\fR This configuration is the default starting
with Fedora 18 and \s-1RHEL 7.\s0  If you find any problems, please let us
know or file a bug.
.PP
SVirt provides a hardened appliance
using SELinux, making it very hard for a rogue disk image to \*(L"escape\*(R" from
the confinement of libguestfs and damage the host (it's fair to say that
even in standard libguestfs this would be hard, but sVirt provides an extra
layer of protection for the host and more importantly protects virtual
machines on the same host from each other).
.PP
Currently to enable sVirt you will need libvirt ≥ 0.10.2 (1.0 or later
preferred), libguestfs ≥ 1.20, and the SELinux policies from recent
Fedora.  If you are not running Fedora 18+, you will need to make changes
to your SELinux policy \- contact us on the mailing list.
.PP
Once you have the requirements, do:
.PP
.Vb 3
\& ./configure \-\-with\-default\-backend=libvirt       # libguestfs >= 1.22
\& ./configure \-\-with\-default\-attach\-method=libvirt # libguestfs <= 1.20
\& make
.Ve
.PP
Set SELinux to Enforcing mode, and sVirt should be used automatically.
.PP
All, or almost all, features of libguestfs should work under sVirt.  There
is one known shortcoming: \fBvirt\-rescue\fR\|(1) will not use libvirt (hence
sVirt), but falls back to direct launch of qemu.  So you won't currently get
the benefit of sVirt protection when using virt-rescue.
.PP
You can check if sVirt is being used by enabling libvirtd logging (see
\&\fI/etc/libvirt/libvirtd.log\fR), killing and restarting libvirtd, and checking
the log files for \*(L"Setting SELinux context on ...\*(R" messages.
.PP
In theory sVirt should support AppArmor, but we have not tried it.  It will
almost certainly require patching libvirt and writing an AppArmor policy.
.SS "Libguestfs has a really long list of dependencies!"
.IX Subsection "Libguestfs has a really long list of dependencies!"
The base library doesn't depend on very much, but there are three causes of
the long list of other dependencies:
.IP "1." 4
Libguestfs has to be able to read and edit many different disk formats.  For
example, \s-1XFS\s0 support requires \s-1XFS\s0 tools.
.IP "2." 4
There are language bindings for many different languages, all requiring
their own development tools.  All language bindings (except C) are optional.
.IP "3." 4
There are some optional library features which can be disabled.
.PP
Since libguestfs ≥ 1.26 it is possible to split up the appliance
dependencies (item 1 in the list above) and thus have (eg)
\&\f(CW\*(C`libguestfs\-xfs\*(C'\fR as a separate subpackage for processing \s-1XFS\s0 disk images.
We encourage downstream packagers to start splitting the base libguestfs
package into smaller subpackages.
.SS "Errors during launch on Fedora ≥ 18, \s-1RHEL\s0 ≥ 7"
.IX Subsection "Errors during launch on Fedora ≥ 18, RHEL ≥ 7"
In Fedora ≥ 18 and \s-1RHEL\s0 ≥ 7, libguestfs uses libvirt to manage the
appliance.  Previously (and upstream) libguestfs runs qemu directly:
.PP
.Vb 10
\& ┌──────────────────────────────────┐
\& │ libguestfs                       │
\& ├────────────────┬─────────────────┤
\& │ direct backend │ libvirt backend │
\& └────────────────┴─────────────────┘
\&        ↓                  ↓
\&    ┌───────┐         ┌──────────┐
\&    │ qemu  │         │ libvirtd │
\&    └───────┘         └──────────┘
\&                           ↓
\&                       ┌───────┐
\&                       │ qemu  │
\&                       └───────┘
\& 
\&    upstream          Fedora 18+
\&    non\-Fedora         RHEL 7+
\&    non\-RHEL
.Ve
.PP
The libvirt backend is more sophisticated, supporting SELinux/sVirt (see
above), hotplugging and more.  It is, however, more complex and so less
robust.
.PP
If you have permissions problems using the libvirt backend, you can switch
to the direct backend by setting this environment variable:
.PP
.Vb 1
\& export LIBGUESTFS_BACKEND=direct
.Ve
.PP
before running any libguestfs program or virt tool.
.SS "How can I switch to a fixed / prebuilt appliance?"
.IX Subsection "How can I switch to a fixed / prebuilt appliance?"
This may improve the stability and performance of libguestfs on Fedora and
\&\s-1RHEL.\s0
.PP
Any time after installing libguestfs, run the following commands as root:
.PP
.Vb 3
\& mkdir \-p /usr/local/lib/guestfs/appliance
\& libguestfs\-make\-fixed\-appliance /usr/local/lib/guestfs/appliance
\& ls \-l /usr/local/lib/guestfs/appliance
.Ve
.PP
Now set the following environment variable before using libguestfs or any
virt tool:
.PP
.Vb 1
\& export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
.Ve
.PP
Of course you can change the path to any directory you want.  You can share
the appliance across machines that have the same architecture (eg. all
x86\-64), but note that libvirt will prevent you from sharing the appliance
across \s-1NFS\s0 because of permissions problems (so either switch to the direct
backend or don't use \s-1NFS\s0).
.SS "How can I speed up libguestfs builds?"
.IX Subsection "How can I speed up libguestfs builds?"
By far the most important thing you can do is to install and properly
configure Squid.  Note that the default configuration that ships with Squid
is rubbish, so configuring it is not optional.
.PP
A very good place to start with Squid configuration is here:
https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads
.PP
Make sure Squid is running, and that the environment variables
\&\f(CW$http_proxy\fR and \f(CW$ftp_proxy\fR are pointing to it.
.PP
With Squid running and correctly configured, appliance builds should be
reduced to a few minutes.
.PP
\fIHow can I speed up libguestfs builds (Debian)?\fR
.IX Subsection "How can I speed up libguestfs builds (Debian)?"
.PP
Hilko Bengen suggests using \*(L"approx\*(R" which is a Debian archive proxy
(http://packages.debian.org/approx).  This tool is documented on Debian
in the \fBapprox\fR\|(8) manual page.
.SH "SPEED, DISK SPACE USED BY LIBGUESTFS"
.IX Header "SPEED, DISK SPACE USED BY LIBGUESTFS"
\&\fBNote:\fR Most of the information in this section has moved:
\&\fBguestfs\-performance\fR\|(1).
.SS "Upload or write seem very slow."
.IX Subsection "Upload or write seem very slow."
If the underlying disk is not fully allocated (eg. sparse raw or qcow2) then
writes can be slow because the host operating system has to do costly disk
allocations while you are writing. The solution is to use a fully allocated
format instead, ie. non-sparse raw, or qcow2 with the
\&\f(CW\*(C`preallocation=metadata\*(C'\fR option.
.SS "Libguestfs uses too much disk space!"
.IX Subsection "Libguestfs uses too much disk space!"
libguestfs caches a large-ish appliance in:
.PP
.Vb 1
\& /var/tmp/.guestfs\-<UID>
.Ve
.PP
If the environment variable \f(CW\*(C`TMPDIR\*(C'\fR is defined, then
\&\fI\f(CI$TMPDIR\fI/.guestfs\-<\s-1UID\s0>\fR is used instead.
.PP
libguestfs を使用していないとき、このディレクトリーを安全に削除できます。
.SS "virt-sparsify は仮想ディスクの全容量までイメージを拡大します。"
.IX Subsection "virt-sparsify は仮想ディスクの全容量までイメージを拡大します。"
If the input to \fBvirt\-sparsify\fR\|(1) is raw, then the output will be raw
sparse.  Make sure you are measuring the output with a tool which
understands sparseness such as \f(CW\*(C`du \-sh\*(C'\fR.  It can make a huge difference:
.PP
.Vb 4
\& $ ls \-lh test1.img
\& \-rw\-rw\-r\-\-. 1 rjones rjones 100M Aug  8 08:08 test1.img
\& $ du \-sh test1.img
\& 3.6M   test1.img
.Ve
.PP
(見た目の容量 \fB100M\fR と実際の容量 \fB3.6M\fR を比較します)
.PP
If all this confuses you, use a non-sparse output format by specifying the
\&\fI\-\-convert\fR option, eg:
.PP
.Vb 1
\& virt\-sparsify \-\-convert qcow2 disk.raw disk.qcow2
.Ve
.SS "Why doesn't virt-resize work on the disk image in-place?"
.IX Subsection "Why doesn't virt-resize work on the disk image in-place?"
Resizing a disk image is very tricky \*(-- especially making sure that you
don't lose data or break the bootloader.  The current method effectively
creates a new disk image and copies the data plus bootloader from the old
one.  If something goes wrong, you can always go back to the original.
.PP
If we were to make virt-resize work in-place then there would have to be
limitations: for example, you wouldn't be allowed to move existing
partitions (because moving data across the same disk is most likely to
corrupt data in the event of a power failure or crash), and \s-1LVM\s0 would be
very difficult to support (because of the almost arbitrary mapping between
\&\s-1LV\s0 content and underlying disk blocks).
.PP
Another method we have considered is to place a snapshot over the original
disk image, so that the original data is untouched and only differences are
recorded in the snapshot.  You can do this today using \f(CW\*(C`qemu\-img create\*(C'\fR +
\&\f(CW\*(C`virt\-resize\*(C'\fR, but qemu currently isn't smart enough to recognize when the
same block is written back to the snapshot as already exists in the backing
disk, so you will find that this doesn't save you any space or time.
.PP
In summary, this is a hard problem, and what we have now mostly works so we
are reluctant to change it.
.SS "Why doesn't virt-sparsify work on the disk image in-place?"
.IX Subsection "Why doesn't virt-sparsify work on the disk image in-place?"
In libguestfs ≥ 1.26, virt-sparsify can now work on disk images in
place.  Use:
.PP
.Vb 1
\& virt\-sparsify \-\-in\-place disk.img
.Ve
.PP
But first you should read \*(L"IN-PLACE \s-1SPARSIFICATION\*(R"\s0 in \fBvirt\-sparsify\fR\|(1).
.SH "PROBLEMS OPENING DISK IMAGES"
.IX Header "PROBLEMS OPENING DISK IMAGES"
.SS "Remote libvirt guests cannot be opened."
.IX Subsection "Remote libvirt guests cannot be opened."
Opening remote libvirt guests is not supported at this time.  For example
this won't work:
.PP
.Vb 1
\& guestfish \-c qemu://remote/system \-d Guest
.Ve
.PP
To open remote disks you have to export them somehow, then connect to the
export.  For example if you decided to use \s-1NBD:\s0
.PP
.Vb 2
\& remote$ qemu\-nbd \-t \-p 10809 guest.img
\&  local$ guestfish \-a nbd://remote:10809 \-i
.Ve
.PP
Other possibilities include ssh (if qemu is recent enough), \s-1NFS\s0 or iSCSI.
See \*(L"\s-1REMOTE STORAGE\*(R"\s0 in \fBguestfs\fR\|(3).
.SS "How can I open this strange disk source?"
.IX Subsection "How can I open this strange disk source?"
You have a disk image located inside another system that requires access via
a library / \s-1HTTP / REST /\s0 proprietary \s-1API,\s0 or is compressed or archived in
some way.  (One example would be remote access to OpenStack glance images
without actually downloading them.)
.PP
We have a sister project called nbdkit
(https://github.com/libguestfs/nbdkit).  This project lets you turn any
disk source into an \s-1NBD\s0 server.  Libguestfs can access \s-1NBD\s0 servers directly,
eg:
.PP
.Vb 1
\& guestfish \-a nbd://remote
.Ve
.PP
nbdkit is liberally licensed, so you can link it to or include it in
proprietary libraries and code.  It also has a simple, stable plugin \s-1API\s0 so
you can easily write plugins against the \s-1API\s0 which will continue to work in
future.
.ie n .SS "Error opening \s-1VMDK\s0 disks: ""uses a vmdk feature which is not supported by this qemu version: \s-1VMDK\s0 version 3"""
.el .SS "Error opening \s-1VMDK\s0 disks: ``uses a vmdk feature which is not supported by this qemu version: \s-1VMDK\s0 version 3''"
.IX Subsection "Error opening VMDK disks: uses a vmdk feature which is not supported by this qemu version: VMDK version 3"
Qemu (and hence libguestfs) only supports certain \s-1VMDK\s0 disk images.  Others
won't work, giving this or similar errors.
.PP
Ideally someone would fix qemu to support the latest \s-1VMDK\s0 features, but in
the meantime you have three options:
.IP "1." 4
If the guest is hosted on a live, reachable \s-1ESX\s0 server, then locate and
download the disk image called \fI\fIsomename\fI\-flat.vmdk\fR.  Despite the name,
this is a raw disk image, and can be opened by anything.
.Sp
If you have a recent enough version of qemu and libguestfs, then you may be
able to access this disk image remotely using either \s-1HTTPS\s0 or ssh.  See
\&\*(L"\s-1REMOTE STORAGE\*(R"\s0 in \fBguestfs\fR\|(3).
.IP "2." 4
Use VMware’s proprietary vdiskmanager tool to convert the image to raw
format.
.IP "3." 4
Use nbdkit with the proprietary \s-1VDDK\s0 plugin to live export the disk image as
an \s-1NBD\s0 source.  This should allow you to read and write the \s-1VMDK\s0 file.
.SS "\s-1UFS\s0 disks (as used by \s-1BSD\s0) cannot be opened."
.IX Subsection "UFS disks (as used by BSD) cannot be opened."
The \s-1UFS\s0 filesystem format has many variants, and these are not
self-identifying.  The Linux kernel has to be told which variant of \s-1UFS\s0 it
has to use, which libguestfs cannot know.
.PP
You have to pass the right \f(CW\*(C`ufstype\*(C'\fR mount option when mounting these
filesystems.
.PP
See https://www.kernel.org/doc/Documentation/filesystems/ufs.txt
.SS "Windows ReFS"
.IX Subsection "Windows ReFS"
Windows ReFS is Microsoft’s ZFS/Btrfs copy.  This filesystem has not yet
been reverse engineered and implemented in the Linux kernel, and therefore
libguestfs doesn't support it.  At the moment it seems to be very rare \*(L"in
the wild\*(R".
.SS "Non-ASCII characters don’t appear on \s-1VFAT\s0 filesystems."
.IX Subsection "Non-ASCII characters don’t appear on VFAT filesystems."
Typical symptoms of this problem:
.IP "\(bu" 4
You get an error when you create a file where the filename contains
non-ASCII characters, particularly non 8\-bit characters from Asian languages
(Chinese, Japanese, etc).  The filesystem is \s-1VFAT.\s0
.IP "\(bu" 4
When you list a directory from a \s-1VFAT\s0 filesystem, filenames appear as
question marks.
.PP
This is a design flaw of the GNU/Linux system.
.PP
\&\s-1VFAT\s0 stores long filenames as \s-1UTF\-16\s0 characters.  When opening or returning
filenames, the Linux kernel has to translate these to some form of 8 bit
string.  \s-1UTF\-8\s0 would be the obvious choice, except for Linux users who
persist in using non\-UTF\-8 locales (the user’s locale is not known to the
kernel because it’s a function of libc).
.PP
Therefore you have to tell the kernel what translation you want done when
you mount the filesystem.  The two methods are the \f(CW\*(C`iocharset\*(C'\fR parameter
(which is not relevant to libguestfs) and the \f(CW\*(C`utf8\*(C'\fR flag.
.PP
そのため、VFAT ファイルシステムを使用するには、マウント時に \f(CW\*(C`utf8\*(C'\fR フラグを追加する必要があります。guestfish
から、次のように使用します:
.PP
.Vb 1
\& ><fs> mount\-options utf8 /dev/sda1 /
.Ve
.PP
または guestfish コマンドラインにおいて:
.PP
.Vb 1
\& guestfish [...] \-m /dev/sda1:/:utf8
.Ve
.PP
または \s-1API\s0 から:
.PP
.Vb 1
\& guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
.Ve
.PP
The kernel will then translate filenames to and from \s-1UTF\-8\s0 strings.
.PP
We considered adding this mount option transparently, but unfortunately
there are several problems with doing that:
.IP "\(bu" 4
On some Linux systems, the \f(CW\*(C`utf8\*(C'\fR mount option doesn't work.  We don't
precisely understand what systems or why, but this was reliably reported by
one user.
.IP "\(bu" 4
It would prevent you from using the \f(CW\*(C`iocharset\*(C'\fR parameter because it is
incompatible with \f(CW\*(C`utf8\*(C'\fR.  It is probably not a good idea to use this
parameter, but we don't want to prevent it.
.SS "Non-ASCII characters appear as underscore (_) on \s-1ISO9660\s0 filesystems."
.IX Subsection "Non-ASCII characters appear as underscore (_) on ISO9660 filesystems."
The filesystem was not prepared correctly with mkisofs or genisoimage.  Make
sure the filesystem was created using Joliet and/or Rock Ridge extensions.
libguestfs does not require any special mount options to handle the
filesystem.
.SS "Cannot open Windows guests which use \s-1NTFS.\s0"
.IX Subsection "Cannot open Windows guests which use NTFS."
You see errors like:
.PP
.Vb 1
\& mount: unknown filesystem type \*(Aqntfs\*(Aq
.Ve
.PP
On Red Hat Enterprise Linux or CentOS < 7.2, you have to install the
libguestfs-winsupport
package.  In \s-1RHEL\s0 ≥ 7.2, \f(CW\*(C`libguestfs\-winsupport\*(C'\fR is part of the base
\&\s-1RHEL\s0 distribution, but see the next question.
.ie n .SS """mount: unsupported filesystem type"" with \s-1NTFS\s0 in \s-1RHEL\s0 ≥ 7.2"
.el .SS "``mount: unsupported filesystem type'' with \s-1NTFS\s0 in \s-1RHEL\s0 ≥ 7.2"
.IX Subsection "mount: unsupported filesystem type with NTFS in RHEL ≥ 7.2"
In \s-1RHEL 7.2\s0 we were able to add \f(CW\*(C`libguestfs\-winsupport\*(C'\fR to the base \s-1RHEL\s0
distribution, but we had to disable the ability to use it for opening and
editing filesystems.  It is only supported when used with \fBvirt\-v2v\fR\|(1).
If you try to use \fBguestfish\fR\|(1) or \fBguestmount\fR\|(1) or some other programs
on an \s-1NTFS\s0 filesystem, you will see the error:
.PP
.Vb 1
\& mount: unsupported filesystem type
.Ve
.PP
This is not a supported configuration, and it will not be made to work in
\&\s-1RHEL.\s0  Don't bother to open a bug about it, as it will be immediately
\&\f(CW\*(C`CLOSED \-> WONTFIX\*(C'\fR.
.PP
You may compile your own libguestfs removing this
restriction,
but that won't be endorsed or supported by Red Hat.
.SS "Cannot open or inspect \s-1RHEL 7\s0 guests."
.IX Subsection "Cannot open or inspect RHEL 7 guests."
.SS "Cannot open Linux guests which use \s-1XFS.\s0"
.IX Subsection "Cannot open Linux guests which use XFS."
\&\s-1RHEL 7\s0 guests, and any other guests that use \s-1XFS,\s0 can be opened by
libguestfs, but you have to install the \f(CW\*(C`libguestfs\-xfs\*(C'\fR package.
.SH "USING LIBGUESTFS IN YOUR OWN PROGRAMS"
.IX Header "USING LIBGUESTFS IN YOUR OWN PROGRAMS"
.SS "The \s-1API\s0 has hundreds of methods, where do I start?"
.IX Subsection "The API has hundreds of methods, where do I start?"
We recommend you start by reading the \s-1API\s0 overview: \*(L"\s-1API
OVERVIEW\*(R"\s0 in \fBguestfs\fR\|(3).
.PP
Although the \s-1API\s0 overview covers the C \s-1API,\s0 it is still worth reading even
if you are going to use another programming language, because the \s-1API\s0 is the
same, just with simple logical changes to the names of the calls:
.PP
.Vb 6
\&                  C  guestfs_ln_sf (g, target, linkname);
\&             Python  g.ln_sf (target, linkname);
\&              OCaml  g#ln_sf target linkname;
\&               Perl  $g\->ln_sf (target, linkname);
\&  Shell (guestfish)  ln\-sf target linkname
\&                PHP  guestfs_ln_sf ($g, $target, $linkname);
.Ve
.PP
Once you're familiar with the \s-1API\s0 overview, you should look at this list of
starting points for other language bindings: \*(L"\s-1USING LIBGUESTFS
WITH OTHER PROGRAMMING LANGUAGES\*(R"\s0 in \fBguestfs\fR\|(3).
.SS "Can I use libguestfs in my proprietary / closed source / commercial program?"
.IX Subsection "Can I use libguestfs in my proprietary / closed source / commercial program?"
In general, yes.  However this is not legal advice \- read the license that
comes with libguestfs, and if you have specific questions contact a lawyer.
.PP
In the source tree the license is in the file \f(CW\*(C`COPYING.LIB\*(C'\fR (LGPLv2+ for
the library and bindings) and \f(CW\*(C`COPYING\*(C'\fR (GPLv2+ for the standalone
programs).
.SH "libguestfs のデバッグ"
.IX Header "libguestfs のデバッグ"
.SS "Help, it’s not working!"
.IX Subsection "Help, it’s not working!"
If no libguestfs program seems to work at all, run the program below and
paste the \fBcomplete, unedited\fR output into an email to \f(CW\*(C`libguestfs\*(C'\fR @
\&\f(CW\*(C`redhat.com\*(C'\fR:
.PP
.Vb 1
\& libguestfs\-test\-tool
.Ve
.PP
If a particular operation fails, supply all the information in this
checklist, in an email to \f(CW\*(C`libguestfs\*(C'\fR @ \f(CW\*(C`redhat.com\*(C'\fR:
.IP "1." 4
What are you trying to do?
.IP "2." 4
What exact command(s) did you run?
.IP "3." 4
What was the precise error or output of these commands?
.IP "4." 4
Enable debugging, run the commands again, and capture the \fBcomplete\fR
output.  \fBDo not edit the output.\fR
.Sp
.Vb 2
\& export LIBGUESTFS_DEBUG=1
\& export LIBGUESTFS_TRACE=1
.Ve
.IP "5." 4
Include the version of libguestfs, the operating system version, and how you
installed libguestfs (eg. from source, \f(CW\*(C`yum install\*(C'\fR, etc.)
.SS "How do I debug when using any libguestfs program or tool (eg. virt\-v2v or virt-df)?"
.IX Subsection "How do I debug when using any libguestfs program or tool (eg. virt-v2v or virt-df)?"
There are two \f(CW\*(C`LIBGUESTFS_*\*(C'\fR environment variables you can set in order to
get more information from libguestfs.
.ie n .IP """LIBGUESTFS_TRACE""" 4
.el .IP "\f(CWLIBGUESTFS_TRACE\fR" 4
.IX Item "LIBGUESTFS_TRACE"
Set this to 1 and libguestfs will print out each command / \s-1API\s0 call in a
format which is similar to guestfish commands.
.ie n .IP """LIBGUESTFS_DEBUG""" 4
.el .IP "\f(CWLIBGUESTFS_DEBUG\fR" 4
.IX Item "LIBGUESTFS_DEBUG"
Set this to 1 in order to enable massive amounts of debug messages.  If you
think there is some problem inside the libguestfs appliance, then you should
use this option.
.PP
To set these from the shell, do this before running the program:
.PP
.Vb 2
\& export LIBGUESTFS_TRACE=1
\& export LIBGUESTFS_DEBUG=1
.Ve
.PP
For csh/tcsh the equivalent commands would be:
.PP
.Vb 2
\& setenv LIBGUESTFS_TRACE 1
\& setenv LIBGUESTFS_DEBUG 1
.Ve
.PP
詳細は \*(L"\s-1ENVIRONMENT VARIABLES\*(R"\s0 in \fBguestfs\fR\|(3) 参照。
.SS "How do I debug when using guestfish?"
.IX Subsection "How do I debug when using guestfish?"
You can use the same environment variables above.  Alternatively use the
guestfish options \-x (to trace commands) or \-v (to get the full debug
output), or both.
.PP
詳細は \fBguestfish\fR\|(1) を参照してください。
.SS "\s-1API\s0 を使用するとき、どのようにデバッグしますか?"
.IX Subsection "API を使用するとき、どのようにデバッグしますか?"
Call \*(L"guestfs_set_trace\*(R" in \fBguestfs\fR\|(3) to enable command traces, and/or
\&\*(L"guestfs_set_verbose\*(R" in \fBguestfs\fR\|(3) to enable debug messages.
.PP
For best results, call these functions as early as possible, just after
creating the guestfs handle if you can, and definitely before calling
launch.
.SS "How do I capture debug output and put it into my logging system?"
.IX Subsection "How do I capture debug output and put it into my logging system?"
Use the event \s-1API.\s0  For examples, see: \*(L"\s-1SETTING CALLBACKS TO
HANDLE EVENTS\*(R"\s0 in \fBguestfs\fR\|(3) and the \fIexamples/debug\-logging.c\fR program in the libguestfs
sources.
.SS "Digging deeper into the appliance boot process."
.IX Subsection "Digging deeper into the appliance boot process."
Enable debugging and then read this documentation on the appliance boot
process: \fBguestfs\-internals\fR\|(1).
.SS "libguestfs hangs or fails during run/launch."
.IX Subsection "libguestfs hangs or fails during run/launch."
Enable debugging and look at the full output.  If you cannot work out what
is going on, file a bug report, including the \fIcomplete\fR output of
\&\fBlibguestfs\-test\-tool\fR\|(1).
.SS "Debugging libvirt"
.IX Subsection "Debugging libvirt"
If you are using the libvirt backend, and libvirt is failing, then you can
enable debugging by editing \fI/etc/libvirt/libvirtd.conf\fR.
.PP
If you are running as non-root, then you have to edit a different file.
Create \fI~/.config/libvirt/libvirtd.conf\fR containing:
.PP
.Vb 2
\& log_level=1
\& log_outputs="1:file:/tmp/libvirtd.log"
.Ve
.PP
Kill any session (non-root) libvirtd that is running, and next time you run
the libguestfs command, you should see a large amount of useful debugging
information from libvirtd in \fI/tmp/libvirtd.log\fR
.SS "Broken kernel, or trying a different kernel."
.IX Subsection "Broken kernel, or trying a different kernel."
You can choose a different kernel for the appliance by setting some
supermin environment variables:
.PP
.Vb 5
\& export SUPERMIN_KERNEL_VERSION=4.8.0\-1.fc25.x86_64
\& export SUPERMIN_KERNEL=/boot/vmlinuz\-$SUPERMIN_KERNEL_VERSION
\& export SUPERMIN_MODULES=/lib/modules/$SUPERMIN_KERNEL_VERSION
\& rm \-rf /var/tmp/.guestfs\-*
\& libguestfs\-test\-tool
.Ve
.SS "Broken qemu, or trying a different qemu."
.IX Subsection "Broken qemu, or trying a different qemu."
You can choose a different qemu by setting the hypervisor environment
variable:
.PP
.Vb 2
\& export LIBGUESTFS_HV=/path/to/qemu\-system\-x86_64
\& libguestfs\-test\-tool
.Ve
.SH "DESIGN/INTERNALS OF LIBGUESTFS"
.IX Header "DESIGN/INTERNALS OF LIBGUESTFS"
See also \fBguestfs\-internals\fR\|(1).
.SS "Why don’t you do everything through the \s-1FUSE /\s0 filesystem interface?"
.IX Subsection "Why don’t you do everything through the FUSE / filesystem interface?"
We offer a command called \fBguestmount\fR\|(1) which lets you mount guest
filesystems on the host.  This is implemented as a \s-1FUSE\s0 module.  Why don't
we just implement the whole of libguestfs using this mechanism, instead of
having the large and rather complicated \s-1API\s0?
.PP
The reasons are twofold.  Firstly, libguestfs offers \s-1API\s0 calls for doing
things like creating and deleting partitions and logical volumes, which
don't fit into a filesystem model very easily.  Or rather, you could fit
them in: for example, creating a partition could be mapped to \f(CW\*(C`mkdir
/fs/hda1\*(C'\fR but then you'd have to specify some method to choose the size of
the partition (maybe \f(CW\*(C`echo 100M > /fs/hda1/.size\*(C'\fR), and the partition
type, start and end sectors etc., but once you've done that the
filesystem-based \s-1API\s0 starts to look more complicated than the call-based \s-1API\s0
we currently have.
.PP
The second reason is for efficiency.  \s-1FUSE\s0 itself is reasonably efficient,
but it does make lots of small, independent calls into the \s-1FUSE\s0 module.  In
guestmount these have to be translated into messages to the libguestfs
appliance which has a big overhead (in time and round trips).  For example,
reading a file in 64 \s-1KB\s0 chunks is inefficient because each chunk would turn
into a single round trip.  In the libguestfs \s-1API\s0 it is much more efficient
to download an entire file or directory through one of the streaming calls
like \f(CW\*(C`guestfs_download\*(C'\fR or \f(CW\*(C`guestfs_tar_out\*(C'\fR.
.SS "Why don’t you do everything through \s-1GVFS\s0?"
.IX Subsection "Why don’t you do everything through GVFS?"
The problems are similar to the problems with \s-1FUSE.\s0
.PP
\&\s-1GVFS\s0 is a better abstraction than \s-1POSIX/FUSE.\s0  There is an \s-1FTP\s0 backend for
\&\s-1GVFS,\s0 which is encouraging because \s-1FTP\s0 is conceptually similar to the
libguestfs \s-1API.\s0  However the \s-1GVFS FTP\s0 backend makes multiple simultaneous
connections in order to keep interactivity, which we can't easily do with
libguestfs.
.SS "Why can I write to the disk, even though I added it read-only?"
.IX Subsection "Why can I write to the disk, even though I added it read-only?"
.ie n .SS "Why does ""\-\-ro"" appear to have no effect?"
.el .SS "Why does \f(CW\-\-ro\fP appear to have no effect?"
.IX Subsection "Why does --ro appear to have no effect?"
When you add a disk read-only, libguestfs places a writable overlay on top
of the underlying disk.  Writes go into this overlay, and are discarded when
the handle is closed (or \f(CW\*(C`guestfish\*(C'\fR etc. exits).
.PP
There are two reasons for doing it this way: Firstly read-only disks aren't
possible in many cases (eg. \s-1IDE\s0 simply doesn't support them, so you couldn't
have an IDE-emulated read-only disk, although this is not common in real
libguestfs installations).
.PP
Secondly and more importantly, even if read-only disks were possible, you
wouldn't want them.  Mounting any filesystem that has a journal, even
\&\f(CW\*(C`mount \-o ro\*(C'\fR, causes writes to the filesystem because the journal has to
be replayed and metadata updated.  If the disk was truly read-only, you
wouldn't be able to mount a dirty filesystem.
.PP
To make it usable, we create the overlay as a place to temporarily store
these writes, and then we discard it afterwards.  This ensures that the
underlying disk is always untouched.
.PP
Note also that there is a regression test for this when building libguestfs
(in \f(CW\*(C`tests/qemu\*(C'\fR).  This is one reason why it’s important for packagers to
run the test suite.
.ie n .SS """\-\-ro"" はすべてのディスクを読み込み専用にしますか?"
.el .SS "\f(CW\-\-ro\fP はすべてのディスクを読み込み専用にしますか?"
.IX Subsection "--ro はすべてのディスクを読み込み専用にしますか?"
\&\fIいいえ!\fR \f(CW\*(C`\-\-ro\*(C'\fR オプションはコマンドラインにおいて、つまり \f(CW\*(C`\-a\*(C'\fR および \f(CW\*(C`\-d\*(C'\fR
オプションを使用して追加されたディスクのみに影響します。
.PP
In guestfish, if you use the \f(CW\*(C`add\*(C'\fR command, then disk is added read-write
(unless you specify the \f(CW\*(C`readonly:true\*(C'\fR flag explicitly with the command).
.ie n .SS "Can I use ""guestfish \-\-ro"" as a way to backup my virtual machines?"
.el .SS "Can I use \f(CWguestfish \-\-ro\fP as a way to backup my virtual machines?"
.IX Subsection "Can I use guestfish --ro as a way to backup my virtual machines?"
Usually this is \fInot\fR a good idea.  The question is answered in more detail
in this mailing list posting:
https://www.redhat.com/archives/libguestfs/2010\-August/msg00024.html
.PP
See also the next question.
.ie n .SS "Why can’t I run fsck on a live filesystem using ""guestfish \-\-ro""?"
.el .SS "Why can’t I run fsck on a live filesystem using \f(CWguestfish \-\-ro\fP?"
.IX Subsection "Why can’t I run fsck on a live filesystem using guestfish --ro?"
This command will usually \fInot\fR work:
.PP
.Vb 1
\& guestfish \-\-ro \-a /dev/vg/my_root_fs run : fsck /dev/sda
.Ve
.PP
The reason for this is that qemu creates a snapshot over the original
filesystem, but it doesn't create a strict point-in-time snapshot.  Blocks
of data on the underlying filesystem are read by qemu at different times as
the fsck operation progresses, with host writes in between.  The result is
that fsck sees massive corruption (imaginary, not real!) and fails.
.PP
What you have to do is to create a point-in-time snapshot.  If it’s a
logical volume, use an \s-1LVM2\s0 snapshot.  If the filesystem is located inside
something like a btrfs/ZFS file, use a btrfs/ZFS snapshot, and then run the
fsck on the snapshot.  In practice you don't need to use libguestfs for this
\&\*(-- just run \fI/sbin/fsck\fR directly.
.PP
Creating point-in-time snapshots of host devices and files is outside the
scope of libguestfs, although libguestfs can operate on them once they are
created.
.SS "What’s the difference between guestfish and virt-rescue?"
.IX Subsection "What’s the difference between guestfish and virt-rescue?"
多くの人々が私たちの提供している 2 つの似たツールにより混乱しています:
.PP
.Vb 3
\& $ guestfish \-\-ro \-a guest.img
\& ><fs> run
\& ><fs> fsck /dev/sda1
\&
\& $ virt\-rescue \-\-ro guest.img
\& ><rescue> /sbin/fsck /dev/sda1
.Ve
.PP
And the related question which then arises is why you can’t type in full
shell commands with all the \-\-options in guestfish (but you can in
\&\fBvirt\-rescue\fR\|(1)).
.PP
\&\fBguestfish\fR\|(1) is a program providing structured access to the
\&\fBguestfs\fR\|(3) \s-1API.\s0  It happens to be a nice interactive shell too, but its
primary purpose is structured access from shell scripts.  Think of it more
like a language binding, like Python and other bindings, but for shell.  The
key differentiating factor of guestfish (and the libguestfs \s-1API\s0 in general)
is the ability to automate changes.
.PP
\&\fBvirt\-rescue\fR\|(1) is a free-for-all freeform way to boot the libguestfs
appliance and make arbitrary changes to your \s-1VM.\s0 It’s not structured, you
can't automate it, but for making quick ad-hoc fixes to your guests, it can
be quite useful.
.PP
But, libguestfs also has a \*(L"backdoor\*(R" into the appliance allowing you to
send arbitrary shell commands.  It’s not as flexible as virt-rescue, because
you can't interact with the shell commands, but here it is anyway:
.PP
.Vb 1
\& ><fs> debug sh "cmd arg1 arg2 ..."
.Ve
.PP
Note that you should \fBnot\fR rely on this.  It could be removed or changed in
future. If your program needs some operation, please add it to the
libguestfs \s-1API\s0 instead.
.ie n .SS "What’s the deal with ""guestfish \-i""?"
.el .SS "What’s the deal with \f(CWguestfish \-i\fP?"
.IX Subsection "What’s the deal with guestfish -i?"
.SS "Why does virt-cat only work on a real \s-1VM\s0 image, but virt-df works on any disk image?"
.IX Subsection "Why does virt-cat only work on a real VM image, but virt-df works on any disk image?"
.ie n .SS "What does ""no root device found in this operating system image"" mean?"
.el .SS "What does ``no root device found in this operating system image'' mean?"
.IX Subsection "What does no root device found in this operating system image mean?"
These questions are all related at a fundamental level which may not be
immediately obvious.
.PP
At the \fBguestfs\fR\|(3) \s-1API\s0 level, a \*(L"disk image\*(R" is just a pile of partitions
and filesystems.
.PP
In contrast, when the virtual machine boots, it mounts those filesystems
into a consistent hierarchy such as:
.PP
.Vb 9
\& /          (/dev/sda2)
\& │
\& ├── /boot  (/dev/sda1)
\& │
\& ├── /home  (/dev/vg_external/Homes)
\& │
\& ├── /usr   (/dev/vg_os/lv_usr)
\& │
\& └── /var   (/dev/vg_os/lv_var)
.Ve
.PP
(または Windows におけるドライブレター)。
.PP
The \s-1API\s0 first of all sees the disk image at the \*(L"pile of filesystems\*(R"
level.  But it also has a way to inspect the disk image to see if it
contains an operating system, and how the disks are mounted when the
operating system boots: \*(L"\s-1INSPECTION\*(R"\s0 in \fBguestfs\fR\|(3).
.PP
Users expect some tools (like \fBvirt\-cat\fR\|(1)) to work with \s-1VM\s0 paths:
.PP
.Vb 1
\& virt\-cat fedora.img /var/log/messages
.Ve
.PP
How does virt-cat know that \fI/var\fR is a separate partition? The trick is
that virt-cat performs inspection on the disk image, and uses that to
translate the path correctly.
.PP
Some tools (including \fBvirt\-cat\fR\|(1), \fBvirt\-edit\fR\|(1), \fBvirt\-ls\fR\|(1))  use
inspection to map \s-1VM\s0 paths.  Other tools, such as \fBvirt\-df\fR\|(1) and
\&\fBvirt\-filesystems\fR\|(1) operate entirely at the raw \*(L"big pile of filesystems\*(R"
level of the libguestfs \s-1API,\s0 and don't use inspection.
.PP
\&\fBguestfish\fR\|(1) is in an interesting middle ground.  If you use the \fI\-a\fR
and \fI\-m\fR command line options, then you have to tell guestfish exactly how
to add disk images and where to mount partitions. This is the raw \s-1API\s0 level.
.PP
If you use the \fI\-i\fR option, libguestfs performs inspection and mounts the
filesystems for you.
.PP
The error \f(CW\*(C`no root device found in this operating system image\*(C'\fR is related
to this.  It means inspection was unable to locate an operating system
within the disk image you gave it.  You might see this from programs like
virt-cat if you try to run them on something which is just a disk image, not
a virtual machine disk image.
.ie n .SS "What do these ""debug*"" and ""internal\-*"" functions do?"
.el .SS "What do these \f(CWdebug*\fP and \f(CWinternal\-*\fP functions do?"
.IX Subsection "What do these debug* and internal-* functions do?"
There are some functions which are used for debugging and internal purposes
which are \fInot\fR part of the stable \s-1API.\s0
.PP
The \f(CW\*(C`debug*\*(C'\fR (or \f(CW\*(C`guestfs_debug*\*(C'\fR) functions, primarily
\&\*(L"guestfs_debug\*(R" in \fBguestfs\fR\|(3) and a handful of others, are used for debugging
libguestfs.  Although they are not part of the stable \s-1API\s0 and thus may
change or be removed at any time, some programs may want to call these while
waiting for features to be added to libguestfs.
.PP
The \f(CW\*(C`internal\-*\*(C'\fR (or \f(CW\*(C`guestfs_internal_*\*(C'\fR) functions are purely to be used
by libguestfs itself.  There is no reason for programs to call them, and
programs should not try to use them.  Using them will often cause bad things
to happen, as well as not being part of the documented stable \s-1API.\s0
.SH "DEVELOPERS"
.IX Header "DEVELOPERS"
.SS "Where do I send patches?"
.IX Subsection "Where do I send patches?"
Please send patches to the libguestfs mailing list
https://www.redhat.com/mailman/listinfo/libguestfs.  You don't have to be
subscribed, but there will be a delay until your posting is manually
approved.
.PP
\&\fBPlease don’t use github pull requests \- they will be ignored\fR.  The
reasons are (a) we want to discuss and dissect patches on the mailing list,
and (b) github pull requests turn into merge commits but we prefer to have a
linear history.
.SS "How do I propose a feature?"
.IX Subsection "How do I propose a feature?"
Large new features that you intend to contribute should be discussed on the
mailing list first (https://www.redhat.com/mailman/listinfo/libguestfs).
This avoids disappointment and wasted work if we don't think the feature
would fit into the libguestfs project.
.PP
If you want to suggest a useful feature but don’t want to write the code,
you can file a bug (see \*(L"\s-1GETTING HELP AND REPORTING BUGS\*(R"\s0)  with \f(CW"RFE:
"\fR at the beginning of the Summary line.
.SS "Who can commit to libguestfs git?"
.IX Subsection "Who can commit to libguestfs git?"
About 5 people have commit access to github.  Patches should be posted on
the list first and ACKed.  The policy for ACKing and pushing patches is
outlined here:
.PP
https://www.redhat.com/archives/libguestfs/2012\-January/msg00023.html
.SS "Can I fork libguestfs?"
.IX Subsection "Can I fork libguestfs?"
Of course you can.  Git makes it easy to fork libguestfs.  Github makes it
even easier.  It’s nice if you tell us on the mailing list about forks and
the reasons for them.
.SH "MISCELLANEOUS QUESTIONS"
.IX Header "MISCELLANEOUS QUESTIONS"
.SS "Can I monitor the live disk activity of a virtual machine using libguestfs?"
.IX Subsection "Can I monitor the live disk activity of a virtual machine using libguestfs?"
A common request is to be able to use libguestfs to monitor the live disk
activity of a guest, for example, to get notified every time a guest creates
a new file.  Libguestfs does \fInot\fR work in the way some people imagine, as
you can see from this diagram:
.PP
.Vb 10
\&            ┌─────────────────────────────────────┐
\&            │ monitoring program using libguestfs │
\&            └─────────────────────────────────────┘
\&                             ↓
\& ┌───────────┐    ┌──────────────────────┐
\& │ live VM   │    │ libguestfs appliance │
\& ├───────────┤    ├──────────────────────┤
\& │ kernel (1)│    │ appliance kernel (2) │
\& └───────────┘    └──────────────────────┘
\&      ↓                      ↓ (r/o connection)
\&      ┌──────────────────────┐
\&      |      disk image      |
\&      └──────────────────────┘
.Ve
.PP
This scenario is safe (as long as you set the \f(CW\*(C`readonly\*(C'\fR flag when adding
the drive).  However the libguestfs appliance kernel (2) does not see all
the changes made to the disk image, for two reasons:
.IP "i." 4
.IX Item "i."
The \s-1VM\s0 kernel (1) can cache data in memory, so it doesn't appear in the disk
image.
.IP "ii." 4
.IX Item "ii."
The libguestfs appliance kernel (2) doesn't expect that the disk image is
changing underneath it, so its own cache is not magically updated even when
the \s-1VM\s0 kernel (1) does update the disk image.
.PP
The only supported solution is to restart the entire libguestfs appliance
whenever you want to look at changes in the disk image.  At the \s-1API\s0 level
that corresponds to calling \f(CW\*(C`guestfs_shutdown\*(C'\fR followed by
\&\f(CW\*(C`guestfs_launch\*(C'\fR, which is a heavyweight operation (see also
\&\fBguestfs\-performance\fR\|(3)).
.PP
There are some unsupported hacks you can try if relaunching the appliance is
really too costly:
.IP "\(bu" 4
Call \f(CW\*(C`guestfs_drop_caches (g, 3)\*(C'\fR.  This causes all cached data help by the
libguestfs appliance kernel (2) to be discarded, so it goes back to the disk
image.
.Sp
However this on its own is not sufficient, because qemu also caches some
data.  You will also need to patch libguestfs to (re\-)enable the
\&\f(CW\*(C`cache=none\*(C'\fR mode.  See:
https://rwmj.wordpress.com/2013/09/02/new\-in\-libguestfs\-allow\-cache\-mode\-to\-be\-selected/
.IP "\(bu" 4
Use a tool like virt-bmap
instead.
.IP "\(bu" 4
Run an agent inside the guest.
.PP
Nothing helps if the guest is making more fundamental changes (eg.  deleting
filesystems).  For those kinds of things you must relaunch the appliance.
.PP
(Note there is a third problem that you need to use consistent snapshots to
really examine live disk images, but that’s a general problem with using
libguestfs against any live disk image.)
.SH "関連項目"
.IX Header "関連項目"
\&\fBguestfish\fR\|(1), \fBguestfs\fR\|(3), http://libguestfs.org/.
.SH "著者"
.IX Header "著者"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2012\-2019 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.