Provided by: libguestfs0_1.24.5-1ubuntu0.1_amd64 
НАЗВА
guestfs-faq — поширені питання щодо libguestfs на відповіді на них (FAQ)
ПРО LIBGUESTFS
Для чого призначено 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.
libguestfs is a C library (hence "lib-"), and a set of tools built on this library, and
bindings for many common programming languages.
For more information about what libguestfs can do read the introduction on the home page
(http://libguestfs.org).
Для чого призначено virt tools?
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.
Чи потрібно встановлювати пакунки { libvirt / KVM / Red Hat / Fedora } для роботи з
libguestfs?
Ні!
libvirt не є обов’язковою частиною libguestfs.
libguestfs works with any disk image, including ones created in VMware, KVM, qemu,
VirtualBox, Xen, and many other hypervisors, and ones which you have created from scratch.
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 OS X. We try our best to support all Linux distros as first-class
citizens. Some virt tools have been ported to Windows.
Що дає використання libguestfs порівняно з іншими інструментами?
порівняно з kpartx
Libguestfs takes a different approach from kpartx. kpartx needs root, and mounts
filesystems on the host kernel (which can be insecure - see "SECURITY" in guestfs(3)).
Libguestfs isolates your host kernel from guests, is more flexible, scriptable,
supports LVM, 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.
порівняно з 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.
порівняно з qemu-nbd
NBD (Network Block Device) is a protocol for exporting block devices over the network.
qemu-nbd is an NBD server which can handle any disk format supported by qemu (eg. raw,
qcow2). You can use libguestfs and qemu-nbd together to access block devices over the
network, for example: "guestfish -a nbd://remote"
порівняно з монтуванням файлових систем у основній системі
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 guestmount(1).
порівняно з parted
Libguestfs supports LVM. Libguestfs uses parted and provides most parted features
through the libguestfs API.
ОТРИМАННЯ ДОВІДКОВОЇ ІНФОРМАЦІЇ ТА ЗВІТУВАННЯ ПРО ВАДИ
Як визначити версію програми, якою я користуюся?
Найпростіший спосіб:
guestfish --version
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 "LIBGUESTFS
VERSION NUMBERS" in guestfs(3).
Як допомогти проектові?
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
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
You can also talk to us on IRC channel "#libguestfs" on FreeNode. We're not always
around, so please stay in the channel after asking your question and someone will get back
to you.
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
Як повідомити про вади?
Please use the following link to enter a bug in Bugzilla:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
Include as much detail as you can and a way to reproduce the problem.
Include the full output of libguestfs-test-tool(1).
ТИПОВІ ПРОБЛЕМИ
See also "LIBGUESTFS GOTCHAS" in guestfs(3) for some "gotchas" with using the libguestfs
API.
"Could not allocate dynamic translator buffer"
This obscure error is in fact an SELinux failure. You have to enable the following
SELinux boolean:
setsebool -P virt_use_execmem=on
Докладніші відомості можна знайти за адресою
https://bugzilla.redhat.com/show_bug.cgi?id=806106.
"child process died unexpectedly"
[This error message was changed in libguestfs 1.21.18 to something more explanatory.]
This error indicates that qemu failed or the host kernel could not boot. To get further
information about the failure, you have to run:
libguestfs-test-tool
If, after using this, you still don't understand the failure, contact us (see previous
section).
libguestfs: error: cannot find any suitable libguestfs supermin, fixed or old-style appliance
on LIBGUESTFS_PATH
If you see this error on Debian/Ubuntu, you need to run the following command as root:
update-guestfs-appliance
execl: /init: Permission denied
Note: 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.
This error happens during the supermin boot phase of starting the appliance:
supermin: mounting new root on /root
supermin: chroot
execl: /init: Permission denied
supermin: debug: listing directory /
[...followed by a lot of debug output...]
This is a complicated bug related to supermin(1) appliances. The appliance is constructed
by copying files like "/bin/bash" and many libraries from the host. The file "hostfiles"
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 "/bin/bash" then you'll see the above error.
Diagnosing the problem involves studying the libraries needed by "/bin/bash", ie:
ldd /bin/bash
comparing that with "hostfiles", 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.
You should also check that files like "/init" and "/bin/bash" (in the appliance) are
executable. The debug output shows file modes.
Non-ASCII characters don't appear on VFAT filesystems.
Типові симптоми проблеми:
• 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 VFAT.
• When you list a directory from a VFAT filesystem, filenames appear as question marks.
This is a design flaw of the GNU/Linux system.
VFAT stores long filenames as UTF-16 characters. When opening or returning filenames, the
Linux kernel has to translate these to some form of 8 bit string. UTF-8 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).
Therefore you have to tell the kernel what translation you want done when you mount the
filesystem. The two methods are the "iocharset" parameter (which is not relevant to
libguestfs) and the "utf8" flag.
So to use a VFAT filesystem you must add the "utf8" flag when mounting. From guestfish,
use:
><fs> параметри_монтування utf8 /dev/sda1 /
or on the guestfish command line:
guestfish [...] -m /dev/sda1:/:utf8
або з програмного інтерфейсу:
guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
The kernel will then translate filenames to and from UTF-8 strings.
We considered adding this mount option transparently, but unfortunately there are several
problems with doing that:
• On some Linux systems, the "utf8" mount option doesn't work. We don't precisely
understand what systems or why, but this was reliably reported by one user.
• It would prevent you from using the "iocharset" parameter because it is incompatible
with "utf8". It is probably not a good idea to use this parameter, but we don't want
to prevent it.
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.
ОТРИМАННЯ, ВСТАНОВЛЕННЯ, ЗБИРАННЯ LIBGUESTFS
Де взяти найсвіжіші збірки для... ?
Fedora ≥ 11
Скористайтеся командою:
yum install '*guestf*'
Найсвіжіші збірки можна знайти тут:
http://koji.fedoraproject.org/koji/packageinfo?packageID=8391
Red Hat Enterprise Linux
RHEL 5
Версія, що постачається разом з офіційним RHEL 5 є дуже застарілою. Нею не варто
користуватися без сполучення з virt-v2v. Скористайтеся пакунками libguestfs 1.20 з
EPEL 5: https://fedoraproject.org/wiki/EPEL
RHEL 6
Є частиною типового набору для встановлення. У RHEL 6 і 7 (і лише тут) вам слід
встановити "libguestfs-winsupport", щоб мати змогу працювати з гостьовими
системами Windows.
RHEL 6.5
There is a preview repository available for people who want to see what
packages will be in RHEL 6.5. Follow the instructions here:
https://www.redhat.com/archives/libguestfs/2013-May/msg00100.html
RHEL 7
It will be part of the default install, and based on libguestfs 1.22. You will
need to install "libguestfs-winsupport" separately to get Windows guest support.
Debian і Ubuntu
After installing libguestfs you need to do:
sudo update-guestfs-appliance
On Ubuntu only:
sudo chmod 0644 /boot/vmlinuz*
You may need to add yourself to the "kvm" group:
sudo usermod -a -G kvm yourlogin
Debian Squeeze (6)
Hilko Bengen has built libguestfs in squeeze backports:
http://packages.debian.org/search?keywords=guestfs&searchon=names§ion=all&suite=squeeze-backports
Debian Wheezy та пізніші версії (7+)
Супровід libguestfs у Debian здійснює Hilko Bengen. Ви можете скористатися
офіційними пакунками Debian: http://packages.debian.org/search?keywords=libguestfs
Ubuntu
У нас немає повноцінного супровідника пакунків Ubuntu. Пакунки, що надаються
Canonical (і не контролюються нами) іноді виявляються непрацездатними.
Компанією Canonical прийнято рішення щодо зміни прав доступу до ядра таким чином,
що його читання не може виконувати жоден з користувачів, окрім root. Ми вважаємо
таке рішення повністю невиправданим, але компанія відмовляється його змінювати
(https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725). Тому користувачам
слід віддати таку команду:
sudo chmod 0644 /boot/vmlinuz*
Ubuntu 12.04
libguestfs у цій версії Ubuntu має працювати, але вам слід оновити пакунки
febootstrap та seabios до найсвіжіших версій.
Вам знадобиться пакунок febootstrap ≥ 3.14-2 з
http://packages.ubuntu.com/precise/febootstrap
Після встановлення або оновлення febootstrap виконайте повторне збирання
базової системи:
sudo update-guestfs-appliance
Вам знадобиться пакунок seabios ≥ 0.6.2-0ubuntu2.1 або ≥ 0.6.2-0ubuntu3 з
http://packages.ubuntu.com/precise-updates/seabios або
http://packages.ubuntu.com/quantal/seabios
Крім того, вам слід виконати такі дії (див. вище):
sudo chmod 0644 /boot/vmlinuz*
Gentoo
Libguestfs було додано до Gentoo 2012-07, автори — Andreis Vinogradovs (libguestfs)
та Maxim Koltsov (в основному hivex). Віддайте команду:
emerge libguestfs
SuSE
Libguestfs було додано до сховищ пакунків SuSE у 2012 році, супровідник — Olaf Hering.
ArchLinux
Libguestfs було додано до AUR у 2010 році.
Інші дистрибутиви Linux
Можна зібрати з початкових кодів (наступний розділ).
Інші дистрибутиви не-Linux
You'll have to compile from source, and port it.
How can I compile and install libguestfs from source?
If your Linux distro has a working port of supermin (that is, Fedora,
Red Hat Enterprise Linux ≥ 6.3, Debian, Ubuntu and ArchLinux) then you should just be
able to compile from source in the usual way. Download the latest tarball from
http://libguestfs.org/download, unpack it, and start by reading the README file.
If you don't have supermin, you will need to use the "fixed appliance method". See:
http://libguestfs.org/download/binaries/appliance/
Patches to port supermin to more Linux distros are welcome.
Why do I get an error when I try to rebuild from the source RPMs supplied by Red Hat / Fedora?
Note: This issue is fixed in Fedora ≥ 19 and RHEL ≥ 6.5.
Because of the complexity of building the libguestfs appliance, the source RPMs provided
cannot be rebuilt directly using "rpmbuild" or "mock".
If you use Koji (which is open source software and may be installed locally), then the
SRPMs can be rebuilt in Koji. https://fedoraproject.org/wiki/Koji
If you don't have or want to use Koji, then you have to give libguestfs access to the
network so it can download the RPMs for building the appliance. You also need to set an
RPM macro to tell libguestfs to use the network. Put the following line into a file
called "$HOME/.rpmmacros":
%libguestfs_buildnet 1
If you are using mock, do:
mock -D '%libguestfs_buildnet 1' [тощо]
How can I add support for sVirt?
Note for Fedora/RHEL users: This configuration is the default starting with Fedora 18 and
RHEL 7. If you find any problems, please let us know or file a bug.
SVirt provides a hardened appliance using SELinux, making it very hard for a rogue disk
image to "escape" 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).
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.
Once you have the requirements, do:
./configure --with-default-backend=libvirt # libguestfs >= 1.22
./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
make
Set SELinux to Enforcing mode, and sVirt should be used automatically.
All, or almost all, features of libguestfs should work under sVirt. There is one known
shortcoming: virt-rescue(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.
You can check if sVirt is being used by enabling libvirtd logging (see
"/etc/libvirt/libvirtd.log"), killing and restarting libvirtd, and checking the log files
for "Setting SELinux context on ..." messages.
In theory sVirt should support AppArmor, but we have not tried it. It will almost
certainly require patching libvirt and writing an AppArmor policy.
Чому у Libguestfs такий великий список залежностей?
Тому що вона може робити дуже багато речей.
Libguestfs -- as it is packaged for Fedora -- satisfies the following conditions:
1. The Fedora package is full featured, that is, it supports every possible feature of
libguestfs (every filesystem, every filesystem tool, etc.)
A common request is to split up libguestfs into separate feature areas so you could,
say, install XFS support and NTFS support separately. This is not possible right now.
2. The download size of the libguestfs package is relatively small (ie. not ten's of
megabytes as it would be if it included a complete, "statically linked" appliance).
3. The Fedora package automatically updates itself if there is a security update. It
doesn't include a huge static blob that has to be rebuilt and users have to re-
download if there is an update.
4. Able to be installed without needing direct network access. This is important when
using closed networks, privately mirrored repositories or RHN Satellite.
5. The Fedora package can be tested during the build.
If you want to drop any one of those conditions, then you can package libguestfs
differently and make it have fewer dependencies, fewer features or a faster start up time:
1. (повний набір можливостей)
Take "appliance/packagelist.in" in the source, and comment out any features you don't
actually care about. For example if you never anticipate editing a Windows guest,
remove all the ntfs-related packages. You can get away with fewer dependencies.
2. (download size) / 3. (updates)
Use libguestfs-make-fixed-appliance(1) to build a compressed appliance. Bundle this
with your package and set $LIBGUESTFS_PATH to point to it. Users will have to
download this large appliance, but no dependencies are needed, and supermin-helper(1)
is not used.
4. (доступ до мережі)
Reconstruct and cache the appliance once during package install. The Debian packaging
currently works like this, but requires network access during package install.
5. (тести)
Don't run any tests during the build. The build will be much faster, but also less
likely to work correctly.
Note that running the tests in "tests/qemu" is probably a good idea, since those are
sanity tests. Also you should do "make quickcheck" to ensure libguestfs is basically
working.
Errors during launch on Fedora ≥ 18, RHEL ≥ 7
In Fedora ≥ 18 and RHEL ≥ 7, libguestfs uses libvirt to manage the appliance. Previously
(and upstream) libguestfs runs qemu directly:
+----------------------------------+
| libguestfs |
+----------------+-----------------+
| direct backend | libvirt backend |
+----------------+-----------------+
| |
v v
+-------+ +----------+
| qemu | | libvirtd |
+-------+ +----------+
|
v
+-------+
| qemu |
+-------+
upstream Fedora 18+
non-Fedora RHEL 7+
non-RHEL
The libvirt backend is more sophisticated, supporting SELinux/sVirt (see above),
hotplugging and more. It is, however, more complex and so less robust.
If you have permissions problems using the libvirt backend, you can switch to the direct
backend by setting this environment variable:
export LIBGUESTFS_BACKEND=direct
before running any libguestfs program or virt tool.
How can I switch to a fixed / prebuilt appliance?
This may improve the stability and performance of libguestfs on Fedora and RHEL.
Any time after installing libguestfs, run the following commands as root:
mkdir -p /usr/local/lib/guestfs/appliance
libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
ls -l /usr/local/lib/guestfs/appliance
Now set the following environment variable before using libguestfs or any virt tool:
export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
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 NFS because of permissions problems (so
either switch to the direct backend or don't use NFS).
Як пришвидшити збирання libguestfs?
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.
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
Make sure Squid is running, and that the environment variables $http_proxy and $ftp_proxy
are pointing to it.
With Squid running and correctly configured, appliance builds should be reduced to a few
minutes.
How can I speed up libguestfs builds (Debian)?
Hilko Bengen suggests using "approx" which is a Debian archive proxy
(http://packages.debian.org/approx). This tool is documented on Debian in the approx(8)
manual page.
SPEED, DISK SPACE USED BY LIBGUESTFS
Note: Most of the information in this section has moved: guestfs-performance(1).
Вивантаження або запис дуже повільні.
In libguestfs < 1.13.16, the mount command ("guestfs_mount" in guestfs(3)) enabled option
"-o sync" implicitly. This causes very poor write performance, and was one of the main
gotchas for new libguestfs users.
For libguestfs < 1.13.16, replace mount with "mount-options", leaving the first parameter
as an empty string.
You can also do this with more recent versions of libguestfs, but if you know that you are
using libguestfs ≥ 1.13.16 then it's safe to use plain mount.
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 "preallocation=metadata" option.
Libguestfs uses too much disk space!
libguestfs caches a large-ish appliance in:
/var/tmp/.guestfs-<UID>
If the environment variable "TMPDIR" is defined, then "$TMPDIR/.guestfs-<UID>" is used
instead.
It is safe to delete this directory when you are not using libguestfs.
virt-sparsify seems to make the image grow to the full size of the virtual disk
If the input to virt-sparsify(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 "du -sh".
It can make a huge difference:
$ 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
(Compare the apparent size 100M vs the actual size 3.6M)
If all this confuses you, use a non-sparse output format by specifying the --convert
option, eg:
virt-sparsify --convert qcow2 диск.raw диск.qcow2
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.
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 LVM would be very difficult to support (because of the almost arbitrary mapping
between LV content and underlying disk blocks).
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 "qemu-img create" + "virt-resize", 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.
In summary, this is a hard problem, and what we have now mostly works so we are reluctant
to change it.
Why doesn't virt-sparsify work on the disk image in-place?
Eventually we plan to make virt-sparsify work on disk images in-place, instead of copying
the disk image. However it requires several changes to both the Linux kernel and qemu
which are slowly making their way upstream (thanks to the tireless efforts of Paolo
Bonzini). Then we will have to modify virt-sparsify to support this. Finally there will
be some integration work required to make sure all the pieces work together.
Even with this implemented there may be some limitations: For example, it requires
completely different steps (and is probably harder) to sparsify a disk image that is
stored on a SAN LUN, compared to one which is stored in a local raw image file, so you can
expect that different storage and backing formats will become supported at different
times. Some backing filesystems / formats may never support sparsification (eg. disk
images stored on VFAT, old-style non-thin LVs).
USING LIBGUESTFS IN YOUR OWN PROGRAMS
The API has hundreds of methods, where do I start?
We recommend you start by reading the API overview: "API OVERVIEW" in guestfs(3).
Although the API overview covers the C API, it is still worth reading even if you are
going to use another programming language, because the API is the same, just with simple
logical changes to the names of the calls:
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);
Once you're familiar with the API overview, you should look at this list of starting
points for other language bindings: "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES" in
guestfs(3).
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.
In the source tree the license is in the file "COPYING.LIB" (LGPLv2+ for the library and
bindings) and "COPYING" (GPLv2+ for the standalone programs).
ДІАГНОСТИКА LIBGUESTFS
Help, it's not working!
Please supply all the information in this checklist, in an email sent to "libguestfs" @
"redhat.com":
• What are you trying to achieve?
• What exact commands did you run?
• What was the precise error / output of these commands?
• Enable debugging, run the commands again, and capture the complete output. Do not
edit the output.
export LIBGUESTFS_DEBUG=1
export LIBGUESTFS_TRACE=1
• Include the version of libguestfs, the operating system version, and how you installed
libguestfs (eg. from source, "yum install", etc.)
• If no libguestfs program seems to work at all, run the program below and paste the
complete, unedited output into the email:
libguestfs-test-tool
How do I debug when using any libguestfs program or tool (eg. virt-v2v or virt-df)?
There are two "LIBGUESTFS_*" environment variables you can set in order to get more
information from libguestfs.
"LIBGUESTFS_TRACE"
Set this to 1 and libguestfs will print out each command / API call in a format which
is similar to guestfish commands.
"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.
To set these from the shell, do this before running the program:
export LIBGUESTFS_TRACE=1
export LIBGUESTFS_DEBUG=1
For csh/tcsh the equivalent commands would be:
setenv LIBGUESTFS_TRACE 1
setenv LIBGUESTFS_DEBUG 1
Докладніші дані можна знайти на сторінці "ЗМІННІ СЕРЕДОВИЩА" in guestfs(3)
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.
Докладніші дані можна знайти на сторінці guestfish(1).
How do I debug when using the API?
Call "guestfs_set_trace" in guestfs(3) to enable command traces, and/or
"guestfs_set_verbose" in guestfs(3) to enable debug messages.
For best results, call these functions as early as possible, just after creating the
guestfs handle if you can, and definitely before calling launch.
How do I capture debug output and put it into my logging system?
Use the event API. For examples, see: "SETTING CALLBACKS TO HANDLE EVENTS" in guestfs(3)
and the "examples/debug-logging.c" program in the libguestfs sources.
Digging deeper into the appliance boot process.
Enable debugging and then read this documentation on the appliance boot process:
"INTERNALS" in guestfs(3).
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 complete output of libguestfs-test-tool(1).
DESIGN/INTERNALS OF LIBGUESTFS
Why don't you do everything through the FUSE / filesystem interface?
We offer a command called guestmount(1) which lets you mount guest filesystems on the
host. This is implemented as a FUSE module. Why don't we just implement the whole of
libguestfs using this mechanism, instead of having the large and rather complicated API?
The reasons are twofold. Firstly, libguestfs offers API 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 "mkdir /fs/hda1" but then you'd have to specify some method to choose
the size of the partition (maybe "echo 100M > /fs/hda1/.size"), and the partition type,
start and end sectors etc., but once you've done that the filesystem-based API starts to
look more complicated than the call-based API we currently have.
The second reason is for efficiency. FUSE itself is reasonably efficient, but it does
make lots of small, independent calls into the FUSE 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 KB chunks is inefficient because each
chunk would turn into a single round trip. In the libguestfs API it is much more
efficient to download an entire file or directory through one of the streaming calls like
"guestfs_download" or "guestfs_tar_out".
Why don't you do everything through GVFS?
The problems are similar to the problems with FUSE.
GVFS is a better abstraction than POSIX/FUSE. There is an FTP backend for GVFS, which is
encouraging because FTP is conceptually similar to the libguestfs API. However the GVFS
FTP backend makes multiple simultaneous connections in order to keep interactivity, which
we can't easily do with libguestfs.
Why can I write to the disk, even though I added it read-only?
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 "guestfish" etc. exits).
There are two reasons for doing it this way: Firstly read-only disks aren't possible in
many cases (eg. IDE 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).
Secondly and more importantly, even if read-only disks were possible, you wouldn't want
them. Mounting any filesystem that has a journal, even "mount -o ro", 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.
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.
Note also that there is a regression test for this when building libguestfs (in
"tests/qemu"). This is one reason why it's important for packagers to run the test suite.
Does "--ro" make all disks read-only?
No! The "--ro" option only affects disks added on the command line, ie. using "-a" and
"-d" options.
In guestfish, if you use the "add" command, then disk is added read-write (unless you
specify the "readonly:true" flag explicitly with the command).
Can I use "guestfish --ro" as a way to backup my virtual machines?
Usually this is not 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
See also the next question.
Why can't I run fsck on a live filesystem using "guestfish --ro"?
This command will usually not work:
guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda
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.
What you have to do is to create a point-in-time snapshot. If it's a logical volume, use
an LVM2 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 "/sbin/fsck" directly.
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.
What's the difference between guestfish and virt-rescue?
A lot of people are confused by the two superficially similar tools we provide:
$ guestfish --ro -a guest.img
><fs> run
><fs> fsck /dev/sda1
$ virt-rescue --ro guest.img
><rescue> /sbin/fsck /dev/sda1
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 virt-rescue(1)).
guestfish(1) is a program providing structured access to the guestfs(3) API. 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 API in
general) is the ability to automate changes.
virt-rescue(1) is a free-for-all freeform way to boot the libguestfs appliance and make
arbitrary changes to your VM. It's not structured, you can't automate it, but for making
quick ad-hoc fixes to your guests, it can be quite useful.
But, libguestfs also has a "backdoor" 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:
><fs> debug sh "cmd arg1 arg2 ..."
Note that you should not rely on this. It could be removed or changed in future. If your
program needs some operation, please add it to the libguestfs API instead.
What's the deal with "guestfish -i"?
Why does virt-cat only work on a real VM image, but virt-df works on any disk image?
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.
At the guestfs(3) API level, a "disk image" is just a pile of partitions and filesystems.
In contrast, when the virtual machine boots, it mounts those filesystems into a consistent
hierarchy such as:
/ (/dev/sda2)
|
+-- /boot (/dev/sda1)
|
+-- /home (/dev/vg_external/Homes)
|
+-- /usr (/dev/vg_os/lv_usr)
|
+-- /var (/dev/vg_os/lv_var)
(або літери дисків у Windows).
The API first of all sees the disk image at the "pile of filesystems" 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: "INSPECTION" in guestfs(3).
Users expect some tools (like virt-cat(1)) to work with VM paths:
virt-cat fedora.img /var/log/messages
How does virt-cat know that "/var" is a separate partition? The trick is that virt-cat
performs inspection on the disk image, and uses that to translate the path correctly.
Some tools (including virt-cat(1), virt-edit(1), virt-ls(1)) use inspection to map VM
paths. Other tools, such as virt-df(1) and virt-filesystems(1) operate entirely at the
raw "big pile of filesystems" level of the libguestfs API, and don't use inspection.
guestfish(1) is in an interesting middle ground. If you use the -a and -m command line
options, then you have to tell guestfish exactly how to add disk images and where to mount
partitions. This is the raw API level.
If you use the -i option, libguestfs performs inspection and mounts the filesystems for
you.
The error "no root device found in this operating system image" 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.
What do these "debug*" and "internal-*" functions do?
There are some functions which are used for debugging and internal purposes which are not
part of the stable API.
The "debug*" (or "guestfs_debug*") functions, primarily "guestfs_debug" in guestfs(3) and
a handful of others, are used for debugging libguestfs. Although they are not part of the
stable API 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.
The "internal-*" (or "guestfs_internal_*") 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 API.
РОЗРОБНИКАМ
Куди слід надсилати латки?
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.
Please don't use github pull requests - they will be ignored. 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.
Як запропонувати нову можливість?
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.
If you want to suggest a useful feature but don't want to write the code, you can file a
bug (see "GETTING HELP AND REPORTING BUGS") with "RFE: " at the beginning of the Summary
line.
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:
https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html
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.
ТАКОЖ ПЕРЕГЛЯНЬТЕ
guestfish(1), guestfs(3), http://libguestfs.org/.
АВТОРИ
Richard W.M. Jones ("rjones at redhat dot com")
АВТОРСЬКІ ПРАВА
Copyright (C) 2012-2014 Red Hat Inc.
LICENSE
BUGS
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
When reporting a bug, please supply:
• The version of libguestfs.
• Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
• Describe the bug accurately and give a way to reproduce it.
• Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug
report.