=head1 НАЗВА

guestfs-faq — поширені питання щодо libguestfs на відповіді на них (FAQ)

=head1 ПРО LIBGUESTFS

=head2 Для чого призначено libguestfs?

libguestfs — засіб створення образів диска, доступу до образів диску та
внесення змін до образів диска. За її допомогою ви зможете бачити вміст
образів диска, вносити зміни до файлів, які у ньому містяться, створювати
образи, змінювати їхні розміри тощо. Це особливо корисно для керування
образами зі скриптів та програм, а також командного рядка.

libguestfs є бібліотекою мовою C (звідси «lib-») і набором інструментів,
побудованих на основі цієї бібліотеки, а також прив'язок до багатьох типових
мов програмування.

Докладніший опис призначення і можливостей libguestfs наведено у вступній
частині домашньої сторінки (L<http://libguestfs.org>).

=head2 Для чого призначено virt tools?

Засоби віртуалізації (сайт: L<http://virt-tools.org>) — загальний набір
засобів для керування віртуалізацією, призначений для системних
адміністраторів. Деякі із засобів походять із libguestfs, деякі — з libvirt,
а багато інших — із інших проєктів із відкритим кодом. Отже, засоби
віртуалізації — надбудова над libguestfs. Втім, багато важливих інструментів
є частиною саме libguestfs. Із повним списком можна ознайомитися тут:
L<http://libguestfs.org>.

=head2 Чи потрібно встановлювати пакунки { libvirt / KVM / Red Hat / Fedora } для
роботи з libguestfs?

Ні!

libvirt не є обов’язковою частиною libguestfs.

libguestfs працює із будь-яким образом диска, зокрема образами, створеним за
допомогою VMware, KVM, qemu, VirtualBox, Xen та багатьох інших гіпервізорів,
а також тими образами, які ви створили «з нуля».

S<Red Hat> спонсорує (тобто оплачує) розробку libguestfs та величезної
кількості інших проєктів із відкритим кодом. Втім, ви можете працювати із
libguestfs та засобами віртуалізації на багатьох інших дистрибутивах Linux
та у Mac OS X. Ми намагаємося якнайкраще підтримувати передусім усі
дистрибутиви Linux. Деякі із засобів віртуалізації портовано на Windows.

=head2 Що дає використання libguestfs порівняно з іншими інструментами?

=over 4

=item I<порівняно з kpartx>

У libguestfs використано інший підхід, порівняно із kpartx. Для роботи
kpartx потрібні права доступу адміністратора (root) та монтування файлових
систем на рівні ядра основної системи (що може бути небезпечним,
див. L<guestfs-security(1)>).  Libguestfs ізолює ядро основної системи від
гостьових систем, є гнучкішою, придатнішою для керування ззовні, підтримує
LVM, не потребує прав доступу root, ізольована від інших процесів та чистить
систему після себе. Libguestfs — це не лише доступ до файлів, оскільки
бібліотека здатна сама створювати образи «з нуля».

=item I<порівняно з vdfuse>

vdfuse подібна до kpartx, але призначена для образів VirtualBox. Відповідно,
порівняння подібне до наведеного вище порівняння для kpartx. Ви можете
скористатися libguestfs для роботи із файлами розділів крізь vdfuse, але у
цьому немає потреби, оскільки libguestfs може отримувати доступ до образів
VirtualBox безпосередньо.

=item I<порівняно з qemu-nbd>

NBD (Network Block Device) — протокол для експортування блокових пристроїв
мережею. qemu-nbd — сервер NBD, який може працювати із дисками будь-якого
формату, якщо підтримку цього формату передбачено у qemu (зокрема з raw,
qcow2). Ви можете скористатися libguestfs у поєднанні із qemu-nbd або nbdkit
together для доступу до блокових пристроїв мережею. Приклад: C<guestfish -a
nbd://віддалена_система>

=item I<порівняно з монтуванням файлових систем у основній системі>

Монтування файлових систем гостьової системи до основної системи не є
безпечним. Його слід завжди уникати для ненадійних гостьових
систем. Скористайтеся libguestfs для створення шару захисту від вразливостей
у засобах обробки файлових систем. Див. також L<guestmount(1)>.

=item I<порівняно з parted>

У libguestfs передбачено підтримку LVM. У libguestfs використовується
parted, бібліотека надає доступ до більшості можливостей parted за допомогою
програмного інтерфейсу libguestfs.

=back

=head1 ОТРИМАННЯ ДОВІДКОВОЇ ІНФОРМАЦІЇ ТА ЗВІТУВАННЯ ПРО ВАДИ

=head2 Як визначити версію програми, якою я користуюся?

Найпростіший спосіб:

 guestfish --version

Розробка libguestfs відбувається у нестабільній гілці. Ми також періодично
створюємо стабільні гілки, до яких портуємо латки із виправленнями вад. Щоб
дізнатися більше, ознайомтеся із розділом L<guestfs(3)/НУМЕРАЦІЯ ВЕРСІЙ
LIBGUESTFS>.

=head2 Як допомогти проєктові?

=head2 Якими списками листування або кімнатами спілкування можна скористатися?

Якщо ви є клієнтом S<Red Hat>, який користується Red Hat Enterprise Linux,
будь ласка, зв'яжіться із S<Службою підтримки Red Hat>:
L<http://redhat.com/support>

Передбачено список листування, здебільшого, для тем, пов'язаних із
розробкою, але користувачі також можуть задавати питання щодо libguestfs та
засобів віртуалізації у цьому списку:
L<https://www.redhat.com/mailman/listinfo/libguestfs>

Крім того, ви можете поспілкуватися із нами на каналі IRC C<#libguestfs>
сервера FreeNode. Не всі розробники можуть увесь час перебувати на зв'язку,
отому, будь ласка, задавши питання на каналі, зачекайте хоч трохи, і хтось
обов'язково на нього відповість.

Щодо інших засобів віртуалізації (не тих, які є частиною libguestfs) існує
загальний список листування щодо засобів віртуалізації:
L<https://www.redhat.com/mailman/listinfo/virt-tools-list>

=head2 Як повідомити про вади?

Будь ласка, скористайтеся цим посиланням для створення записів звітів щодо
вад у Bugzilla:

L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>

Надайте якнайдокладніший опис і поради щодо способу відтворення проблеми.

Включіть до звіту усі дані, які було виведено L<libguestfs-test-tool(1)>.

=head1 ТИПОВІ ПРОБЛЕМИ

Приклади помилкового використання програмного інтерфейсу libguestfs також
наведено у розділі L<guestfs(3)/ПРОБЛЕМНІ МІСЦЯ LIBGUESTFS>.

=head2 "Could not allocate dynamic translator buffer"

Фактично, причиною цієї важковідстежуваної помилки є проблеми із
SELinux. Вам слід увімкнути такий булевий перемикач SELinux:

 setsebool -P virt_use_execmem=on

Докладніші відомості можна знайти за адресою
L<https://bugzilla.redhat.com/show_bug.cgi?id=806106>.

=head2 "child process died unexpectedly"

[Це повідомлення у libguestfs 1.21.18 було замінено на змістовніше.]

Це повідомлення про помилку вказує на помилку у роботі qemu або неможливість
завантаження ядра основної системи. Для отримання подальшої інформації щодо
помилки вам слід віддати таку команду:

 libguestfs-test-tool

Якщо навіть після використання цієї команди ви не зрозуміли причини помилки,
зверніться до розробників бібліотеки (див. попередній розділ).

=head2 libguestfs: помилка: не вдалося знайти відповідного supermin libguestfs,
фіксованого розгортання або розгортання у застарілому стилі за адресою
LIBGUESTFS_PATH

=head2 febootstrap-supermin-helper: ext2: не знайдено батьківського каталогу

=head2 supermin-helper: ext2: не знайдено батьківського каталогу

[Цю ваду було остаточно виправлено у libguestfs E<ge> 1.26.]

Якщо ви бачите ці повідомлення про помилки у Debian/Ubuntu, вам слід віддати
таку команду:

 sudo update-guestfs-appliance

=head2 «Заборонено доступ» («Permission denied») під час виконання libguestfs від
імені root

Ви отримуєте повідомлення щодо заборони доступу під час відкриття образу
диска, незважаючи на те, що запускали libguestfs від імені адміністратора
системи (root).

Причиною є робота libvirt, отже, це трапляється лише при використанні модуля
обробки libvirt. Під час роботи від імені користувача root libvirt запускає
базову систему qemu від імені користувача C<qemu.qemu>. На жаль, зазвичай,
це означає, що qemu не зможе відкривати образи дисків, особливо якщо
власником цих образів диска є користувач root або ці образи зберігаються у
каталогах, доступ до яких має лише користувач root.

Для виправлення цього відкрито звіт про ваду у libvirt:
L<https://bugzilla.redhat.com/show_bug.cgi?id=1045069>

Обійти проблему можна у один з таких способів:

=over 4

=item *

Перемкнутися на безпосередній модуль:

 export LIBGUESTFS_BACKEND=direct

=item *

Не запускати libguestfs від імені адміністратора (root).

=item *

Змініть режим доступу до образу диска та усіх каталогів, з яких складається
шлях до нього, таким чином, щоб користувач qemu мав до них доступ.

=item *

(Небезпечний спосіб) Відкрийте для редагування F</etc/libvirt/qemu.conf> і
змініть значення параметра C<user>.

=back

=head2 execl: /init: відмовлено у доступі

B<Зауваження:> якщо ви бачите це повідомлення про помилку під час роботи із
дистрибутивним пакунком libguestfs (наприклад, пакунком Fedora, Debian),
повідомте про ваду розробникам дистрибутива. Звичайний користувач
дистрибутивного пакунка, приготованого належним чином, ніколи не повинен
бачити цього повідомлення про помилку.

Це повідомлення про помилку виникає під час стадії завантаження запуску
базової системи у supermin:

 supermin: mounting new root on /root
 supermin: chroot
 execl: /init: Permission denied
 supermin: debug: listing directory /
 [...далі багато інших діагностичних повідомлень...]

Це складна вада, пов'язана із базовими системами L<supermin(1)>. Базова
система будується шляхом копіювання файлів, подібних до F</bin/bash>, та
багатьох бібліотек із основної системи. Список файлів, які має бути
скопійовано з основної системи до базової, зберігається у файлі
C<hostfiles>. Якщо якихось файлів немає у основній системі, їх буде
пропущено, але якщо такі файли потрібні (наприклад) для запуску
F</bin/bash>, ви побачите згодом саме таке повідомлення про помилку.

Виявити причину помилки можна вивчивши список бібліотек, потрібних для
роботи F</bin/bash>. Тобто, слід віддати таку команду:

 ldd /bin/bash

і порівняти отриманий список зі списком із C<hostfiles>, списком файлів, які
є у файловій системі основної системи та діагностичними повідомленнями із
повідомлення про помилку. Щойно буде виявлено файл, якого не вистачає, його
слід встановити за допомогою програми для керування пакунками, а потім
повторити спробу.

Також слід перевірити, чи є файли, подібні до F</init> та F</bin/bash> (у
базовій системі) виконуваними. У діагностичних даних мають бути відомості
щодо режимів файлів.

=head1 ОТРИМАННЯ, ВСТАНОВЛЕННЯ, ЗБИРАННЯ LIBGUESTFS

=begin html

<!-- old anchor for the next section --> <a name="binaries"/>

=end html

=head2 Де взяти найсвіжіші збірки для... ?

=over 4

=item Fedora E<ge> 11

Скористайтеся командою:

 yum install '*guestf*'

Найсвіжіші збірки можна знайти тут:
L<http://koji.fedoraproject.org/koji/packageinfo?packageID=8391>

=item Red Hat Enterprise Linux

=over 4

=item RHEL 6

=item RHEL 7

Є частиною типового набору для встановлення. У RHEL 6 і 7 (і лише тут) вам
слід встановити C<libguestfs-winsupport>, щоб мати змогу працювати з
гостьовими системами Windows.

=back

=item Debian і Ubuntu

У libguestfs E<lt> 1.26 після встановлення libguestfs вам слід віддати такі
команди:

 sudo update-guestfs-appliance

(Цей скрипт було вилучено у Debian/Ubuntu  у версіях libguestfs E<ge> 1.26,
де замість цього базова система збирається на вимогу.)

Лише в Ubuntu:

 sudo chmod 0644 /boot/vmlinuz*

Вам, ймовірно, варто додати вашого користувача до групи C<kvm>:

 sudo usermod -a -G kvm ваш_обліковий_запис

=over 4

=item Debian Squeeze (6)

Hilko Bengen зібрано libguestfs для сховища пакунків зворотного портування
squeeze:
L<http://packages.debian.org/search?keywords=guestfs&searchon=names&section=all&suite=squeeze-backports>

=item Debian Wheezy та пізніші версії (7+)

Супровід libguestfs у Debian здійснює Hilko Bengen. Ви можете скористатися
офіційними пакунками Debian:
L<http://packages.debian.org/search?keywords=libguestfs>

=item Ubuntu

У нас немає повноцінного супровідника пакунків Ubuntu. Пакунки, що надаються
Canonical (і не контролюються нами) іноді виявляються непрацездатними.

Компанією Canonical прийнято рішення щодо зміни прав доступу до ядра таким
чином, що його читання не може виконувати жоден з користувачів, окрім
root. Ми вважаємо таке рішення повністю невиправданим, але компанія
відмовляється його змінювати
(L<https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725>). Тому
користувачам слід віддати таку команду:

 sudo chmod 0644 /boot/vmlinuz*

=over 4

=item Ubuntu 12.04

libguestfs у цій версії Ubuntu має працювати, але вам слід оновити пакунки
febootstrap та seabios до найсвіжіших версій.

Вам знадобиться пакунок febootstrap E<ge> 3.14-2 з
L<http://packages.ubuntu.com/precise/febootstrap>

Після встановлення або оновлення febootstrap виконайте повторне збирання
базової системи:

 sudo update-guestfs-appliance

Вам знадобиться пакунок seabios E<ge> 0.6.2-0ubuntu2.1 або E<ge>
0.6.2-0ubuntu3 з L<http://packages.ubuntu.com/precise-updates/seabios> або
L<http://packages.ubuntu.com/quantal/seabios>

Крім того, вам слід виконати такі дії (див. вище):

 sudo chmod 0644 /boot/vmlinuz*

=back

=back

=item Gentoo

Libguestfs було додано до Gentoo 2012-07, автори —  Andreis Vinogradovs
(libguestfs) та Maxim Koltsov (в основному hivex). Віддайте команду:

 emerge libguestfs

=item Mageia

Libguestfs was added to Mageia in 2013-08. Do:

 urpmi libguestfs

=item SuSE

Libguestfs було додано до сховищ пакунків SuSE у 2012 році, супровідник —
Olaf Hering.

=item ArchLinux

Libguestfs було додано до AUR у 2010 році.

=item Інші дистрибутиви Linux

Можна зібрати з початкових кодів (наступний розділ).

=item Інші дистрибутиви не-Linux

Вам слід зібрати бібліотеку з початкових кодів і портувати її.

=back

=head2 Як зібрати і встановити libguestfs з початкових кодів?

Ви можете зібрати libguestfs з git або архіву tar із початковим кодом. Перш
ніж почнете це робити, ознайомтеся із вмістом файла README.

Git: L<https://github.com/libguestfs/libguestfs> Архіви з кодом:
L<http://libguestfs.org/download>

Не використовуйте команду C<make install>! Замість неї слід користуватися
скриптом C<./run> (див. README).

=head2 Як зібрати і встановити libguestfs, якщо у дистрибутиві немає достатньо
нового qemu, supermin або ядра?

Для роботи libguestfs потрібен supermin 5. Якщо supermin 5 не портовано на
ваш дистрибутив, ознайомтеся із наведеною нижче відповіддю на наступне
питання.

Спочатку зберіть qemu, supermin і/або ядро із початкового коду. Вам I<не
слід> віддавати команду C<make install> для встановлення.

У каталозі із початковим кодом libguestfs створіть два файли. Файл
C<localconfigure> має містити такий текст:

 source localenv
 #export PATH=/tmp/qemu/x86_64-softmmu:$PATH
 ./autogen.sh --prefix /usr "$@"

Зробіть C<localconfigure> виконуваним.

C<localenv> має містити таке:

 #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

Розкоментуйте і скоригуйте рядки так, щоб вони відповідали зібраним вами
альтернативним варіантам програм.

Скористайтеся C<./localconfigure> замість C<./configure> додавши до скрипту
звичайні аргументи для збирання libguestfs.

Не використовуйте команду C<make install>! Замість неї слід користуватися
скриптом C<./run> (див. README).

=head2 Як зібрати і встановити libguestfs без supermin?

Якщо у supermin 5 передбачено підтримку вашого дистрибутива, але якось так
вийшло, що у вашій системі не встановлено достатньо нової версії supermin,
скористайтеся настановами із відповіді на попереднє питання.

Якщо у supermin 5 взагалі не передбачено підтримки вашого дистрибутива, вам
доведеться скористатися «методом фіксованої базової системи», згідно з яким
вам слід скористатися наперед зібраним двійковим образом базової
системи. Щоб зібрати libguestfs без підтримки supermin, вам слід передати
параметри C<--disable-appliance --disable-daemon> F<./autogen.sh> або
F<./configure> (залежно від того, що ви збираєте, код з git або код з архіву
tar). Далі, під час використання libguestfs вам B<слід> встановити для
змінної середовища C<LIBGUESTFS_PATH> значення, яке збігається із адресою
каталогу, де зберігається попередньо зібрана базова система, як це описано у
розділі L<guestfs-internals(1)/ФІКСОВАНА БАЗОВА СИСТЕМА>.

Крім того, попередньо зібрані базові системи можна знайти тут:
L<http://libguestfs.org/download/binaries/appliance/>.

Ми будемо раді надісланим вами латкам для портування supermin на інші
дистрибутиви Linux.

=head2 Як додати підтримку для sVirt?

B<Зауваження для користувачів Fedora/RHEL:> ця конфігурація є типовою,
починаючи з S<Fedora 18> та S<RHEL 7>.  Якщо вами буде виявлено якісь
проблеми, будь ласка, повідомте розробникам або створіть звіт про ваду у
бібліотеці.

L<SVirt|http://selinuxproject.org/page/SVirt> створює захищену базову
систему із використанням SELinux, роблячи дуже складною для створеного
зловмисниками образу диска «втечу» з контейнера libguestfs і ускладнюючи
спроби нашкодити основній системі (слід сказати, що навіть у стандартній
libguestfs зробити це складно, але sVirt створює додатковий шар захисту для
основної системи і, що важливіше, захищає віртуальні машини на одній
основній системі одна від одної).

У поточній версії для вмикання sVirt вам знадобиться libvirt E<ge> 0.10.2
(бажано 1.0 або новіша версія), libguestfs E<ge> 1.20, та правила SELinux зі
свіжої версії Fedora. Якщо ви працюєте не з S<Fedora 18+>, вам доведеться
внести зміни до ваших правил SELinux — якщо потрібен конкретний список,
зв'яжіться із нами за допомогою списку листування.

Щойно усі вимоги буде задоволено, зробіть наступне:

 ./configure --with-default-backend=libvirt       # libguestfs >= 1.22
 ./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
 make

Встановіть SELinux у примусовий (Enforcing) режим, і sVirt буде використано
автоматично.

З sVirt мають працювати усі або майже усі можливості libguestfs. Втім, є
один відомий недолік: L<virt-rescue(1)> не використовуватиме libvirt (а
отже, і sVirt), а повернеться до безпосереднього запуску qemu. Тому, ви не
зможете скористатися перевагами захисту sVirt, якщо користуватиметеся
virt-rescue.

Перевірити, чи працює sVirt можна вмиканням журналу libvirtd
(див. F</etc/libvirt/libvirtd.log>). Далі слід завершити роботу libvirtd і
перезапустити цю службу, а потім пошукати у файлах журналу повідомлення
S<"Setting SELinux context on ..."> (Встановлюємо контекст SELinux...»).

Теоретично, у sVirt має бути передбачено підтримку AppArmor, але ми цього не
перевіряли. Майже напевне, використання sVirt потребуватиме латання libvirt
і написання правил AppArmor.

=head2 Чому у Libguestfs такий великий список залежностей?

Основа бібліотеки має доволі мало залежностей, але існує три причини, через
які список залежностей є доволі довгим:

=over 4

=item 1.

Libguestfs повинна мати змогу читати і редагувати дані у багатьох різних
форматах дисків. Наприклад, підтримка XFS потребує використання інструментів
для роботи з XFS.

=item 2.

До складу бібліотеки включено прив'язки до багатьох мов програмування, і для
усіх цих мов потрібні власні інструменти для розробки. Усі прив'язки до мов
(окрім C) є необов'язковими.

=item 3.

До складу бібліотеки включено декілька додаткових можливостей, які можна
вимкнути.

=back

Починаючи з libguestfs E<ge> 1.26, можна відділити залежності базової
системи (пункт 1 у наведеному вище списку), створивши, наприклад, окремий
підпакунок C<libguestfs-xfs> для обробки образів дисків XFS. Ми радимо
пакувальникам для дистрибутивів почати ділити базовий пакунок libguestfs на
менші підпакунки.

=head2 Помилки під час запуску на Fedora E<ge> 18, RHEL E<ge> 7

У Fedora E<ge> 18 та RHEL E<ge> 7 libguestfs використовує libvirt для
керування базовою системою. Раніше (і у основній гілці розробки) libguestfs
запускає qemu безпосередньо:

 ┌──────────────────────────────────┐
 │ libguestfs                       │
 ├────────────────┬─────────────────┤
 │ безп. модуль │ модуль libvirt │
 └────────────────┴─────────────────┘
        ↓                  ↓
    ┌───────┐         ┌──────────┐
    │ qemu  │         │ libvirtd │
    └───────┘         └──────────┘
                           ↓
                       ┌───────┐
                       │ qemu  │
                       └───────┘
 
    upstream          Fedora 18+
    не-Fedora         RHEL 7+
    не-RHEL

Модуль libvirt є складнішим, підтримує SELinux/sVirt (див. вище), «гаряче»
з'єднання образів тощо. Втім, через складність він є менш стійким.

Якщо виникають проблеми із правами доступу під час використання модуля
libvirt, ви можете перейти на модуль безпосереднього керування встановленням
такої змінної середовища:

 export LIBGUESTFS_BACKEND=direct

до запуску будь-яких інструментів libguestfs або virt.

=head2 Як перемкнути бібліотеку на фіксовану або попередньо зібрану базову систему?

Це може поліпшити стабільність та швидкодію libguestfs у Fedora і RHEL.

Будь-коли після встановлення libguestfs віддайте такі команди від імені
root:

 mkdir -p /usr/local/lib/guestfs/appliance
 libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
 ls -l /usr/local/lib/guestfs/appliance

Далі, встановіть значення для такої змінної середовища до використання
libguest або будь-якого іншого засобу віртуалізації:

 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance

Звичайно ж, ви можете змінити шлях на адресу будь-якого каталогу. Ви можете
спільно використовувати базову систему на різних машинах із однаковою
архітектурою (наприклад, усіх машинах x86-64), але слід пам'ятати, що
libvirt не дасть вам спільно використовувати базову систему за допомогою NFS
через проблеми із правами доступу (отже, слід або перемкнутися на модуль
безпосередньої роботи, або не використовувати NFS).

=head2 Як пришвидшити збирання libguestfs?

Найважливішим у пришвидшенні роботи може стати встановлення і належне
налаштовування Squid. Зауважте, що типові налаштування, з якими
встановлюється Squid не дадуть бажаних результатів, тому налаштовування у
цьому випадку є обов'язковим.

Чудові початкові поради щодо налаштовування Squid можна знайти тут:
L<https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads>

Переконайтеся, що Squid працює, і що змінні середовища C<$http_proxy> та
C<$ftp_proxy> вказують на нього.

Якщо Squid запущено і належним чином налаштовано, збирання базової системи
має стати справою декількох хвилин.

=head3 Як пришвидшити збирання libguestfs (Debian)?

Hilko Bengen запропоновано використовувати «approx», архівний проксі-сервер
Debian (L<http://packages.debian.org/approx>).   Документацію до цієї
програми можна знайти на сторінці підручника щодо approx(8).

=head1 ШВИДКІСТЬ, МІСЦЕ НА ДИСКУ, ЯКЕ ЗАЙНЯТО LIBGUESTFS

B<Зауваження:> більшу частину відомостей з цього розділу перенесено до
розділу L<guestfs-performance(1)>.

=head2 Вивантаження або запис дуже повільні.

Якщо базовий диск не повністю розподілено (наприклад, маєте справу із
розрідженим raw або qcow2), запис може бути повільним через те, що основна
операційна система має виконувати ресурсомісткі операції із отримання місця
на диску під час запису. Усунути проблему можна використанням формату із
повним розподілом, тобто raw без розрідження або qcow2 з параметром
C<preallocation=metadata>.

=head2 Libguestfs займає надто багато місця на диску!

libguestfs кешує найбільшу базову систему сюди:

 /var/tmp/.guestfs-<UID>

Якщо визначено змінну середовища C<TMPDIR>, буде використано
F<$TMPDIR/.guestfs-E<lt>UIDE<gt>>.

Коли ви не використовуєте libguestfs, цей каталог можна безпечно вилучити.

=head2 Здається, virt-sparsify робить так, що розмір образу збільшується до повного
розміру віртуального диска

Якщо результатом L<virt-sparsify(1)> є образ raw, буде виведено розріджені
дані raw. Отже, вимірювати виведені дані слід за допомогою інструмента, який
обробляє розріджені дані, наприклад C<du -sh>. Використання такого
інструмента є дуже важливим:

 $ 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

(Порівняйте видимий розмір у B<100 МБ> зі справжнім розміром у B<3,6 МБ>)

Якщо такі відмінності бентежать вас, скористайтеся форматом виведення без
розрідження, вказавши параметр I<--convert>. Приклад:

 virt-sparsify --convert qcow2 диск.raw диск.qcow2

=head2 Чому virt-resize не працює із образами дисків «на місці»?

Зміна розміру образу диска є доволі непростою дією — особливо, з урахуванням
того, що слід зберегти усі дані і не пошкодити завантажувач. У поточній
версії, насправді, створюється новий образ диска, до якого копіюються дані і
завантажувач зі старого образу. Якщо щось піде не так, ви завжди можете
повернутися до початкового варіанта.

Якби нами було реалізовано роботу virt-resize «на місці», нам довелося б
також ввести декілька обмежень: наприклад, було б заборонено пересування
наявних розділів (оскільки пересування даних у межах одного диска,
найімовірніше, призвело б до пошкодження даних при раптовому вимиканні
живлення або аварійному завершенні роботи програми), а підтримка LVM стала б
дуже складною справою (через майже випадковий зв'язок між вмістом логічного
тому і підлеглих йому блоків на диску).

Ми розглядали і інший спосіб, який полягав у тому, щоб створювати
різницю-знімок щодо початкового образу диска так, щоб початкові дані
лишалися незмінними, а до знімка записувалася лише різниця. Зробити це у
поточній версії можна за допомогою комбінації C<qemu-img create> +
C<virt-resize>. Втім, qemu у поточній версії недостатньо кмітлива, щоб
розпізнати ситуацію, коли блок, який записується до знімка вже існує у
резервній копію диска, отже, зрозуміло, цей спосіб не заощадить вам ні місця
на диску, ні часу.

Підсумовуючи, це складна проблема, у поточній версії усе працює майже як
слід, тому ми не дуже хочемо щось міняти.

=head2 Чому virt-sparcify не працює із образами дисків «на місці»?

У libguestfs E<ge> 1.26 virt-sparsify може працювати над образами диска на
місці. Скористайтеся такою командою:

 virt-sparsify --in-place disk.img

Але спочатку вам слід ознайомитися із розділом
L<virt-sparsify(1)/РОЗРІДЖЕННЯ НА МІСЦІ>.

=head1 ПРОБЛЕМИ З ВІДКРИТТЯМ ОБРАЗІВ ДИСКІВ

=head2 Неможливо відкрити віддалені гостьові системи libvirt.

Підтримки відкриття віддалених гостьових систем libvirt у поточній версії не
передбачено. Наприклад, така команда не працюватиме:

 guestfish -c qemu://remote/system -d Guest

Щоб відкрити віддалені диски, вам слід спочатку якось їх експортувати, а
потім з'єднатися із експортованими даними. Наприклад, якщо ви вирішили
скористатися NBD:

 remote$ qemu-nbd -t -p 10809 guest.img
  local$ guestfish -a nbd://remote:10809 -i

Серед інших можливостей є використання ssh (якщо ви користуєтеся досить
свіжою версією qemu), NFS або iSCSI. Див. L<guestfs(3)/ВІДДАЛЕНЕ СХОВИЩЕ>.

=head2 Як відкрити якесь дивне дискове джерело?

Нехай у вас є образ диска, розташований у іншій системі, доступ до якої
потребує бібліотеки, HTTP, REST або пропрієтарного програмного інтерфейсу,
або такий образ, який стиснено або архівовано у певний спосіб. (Одним із
прикладів є віддалений доступ до образів glance OpenStack без початкового
отримання усіх даних таких образів.)

Ми створили дочірній проєкт із назвою nbdkit
(L<https://github.com/libguestfs/nbdkit>). Цей проєкт надає вам змогу
перетворити будь-яке дискове джерело у сервер NBD. Libguestfs може отримати
доступ до серверів NBD безпосередньо, приклад:

 guestfish -a nbd://remote

Умови ліцензування nbdkit є доволі ліберальними, тому ви можете компонувати
або включати цей програмний код до пропрієтарних бібліотек та програм. Крім
того, передбачено простий і стабільний програмний інтерфейс для
додатків. Отже, ви зможете без проблем писати додатки з цим програмним
інтерфейсом, які працюватимуть і з майбутніми версіями.

=head2 Повідомлення про помилку під час відкриття дисків VMDK: «uses a vmdk feature
which is not supported by this qemu version: VMDK version 3»

У qemu (а отже і у libguestfs) передбачено підтримку лише деяких образів
дисків VMDK. Інші не працюватимуть — буде показано лише це або подібне
повідомлення про помилку.

Було б чудово, якби хтось виправив qemu так, щоб було реалізовано найновіші
можливості VMDK, але, доки цього не сталося, у вас три варіанти дій:

=over 4

=item 1.

Якщо гостьова система працює на «живому», доступному сервері ESX, знайдіть і
отримайте образ диска із назвою
F<I<назва_гостьової_системи>-flat.vmdk>. Незважаючи на назву, це образ диска
raw, який можна відкрити будь-якою відповідною програмою.

Якщо ви працюєте з доволі свіжою версією qemu і libguestfs, ви, ймовірно,
зможете отримати доступ до цього образу диска віддалено за допомогою HTTPS
або ssh. Див. L<guestfs(3)/ВІДДАЛЕНЕ СХОВИЩЕ>.

=item 2.

Скористайтеся пропрієтарним інструментом VMware vdiskmanager для
перетворення образу у формат raw.

=item 3.

Скористайтеся nbdkit із пропрієтарним додатком VDDK для експортування
«вживу» образу диска як джерела NBD. Це дасть вам змогу прочитати дані файла
VMDK і записати до нього дані.

=back

=head2 Не передбачено можливості відкриття дисків UFS (у форматі, що
використовується BSD).

У файлової системи UFS багато варіантів. Визначити варіант непросто. Ядру
Linux має бути повідомлено варіант UFS, який слід використати, а libguestfs
не зможе це зробити самостійно.

Під час монтування цих файлових систем слід передати правильне значення
параметра монтування C<ufstype>.

Див. L<https://www.kernel.org/doc/Documentation/filesystems/ufs.txt>

=head2 Windows ReFS

Windows ReFS є копією ZFS/Btrfs від Microsoft. Принципи роботи цієї файлової
системи ще не визначено шляхами зворотної інженерії і не реалізовано у ядрі
Linux, тому у libguestfs не передбачено її підтримки. На сьогодні, зустріти
цю файлову систему «наживо» доволі важко.

=head2 У файлових системах VFAT не видно символів поза ASCII.

Типові симптоми проблеми:

=over 4

=item *

Ви бачите повідомлення про помилку під час створення файла із назвою, яка
містить символи поза ASCII, зокрема не-8-бітові символи з азійських мов
(китайської, японської тощо). Файловою системою є VFAT.

=item *

У каталогах файлової системи VFAT назви файлів показано знаками питання.

=back

Це конструктивна проблема системи GNU/Linux.

VFAT зберігає довгі назви файлів у форматі набору символів UTF-16. Коли
операційна система відкриває або повертає назви файлів, ядро Linux має
перетворити такий набір символів у певну форму рядка із 8-бітових
символів. Очевидним вибором про цьому є UTF-8, окрім тих випадків, коли
користувачі Linux примусово визначають локалі, відмінні від UTF-8 (локаль
користувача не є відомою ядру, оскільки її роботу забезпечує не ядро, а
libc).

Через це вам слід повідомити ядру, яке саме перетворення слід виконати під
час монтування файлової системи. Зробити це можна або за допомогою параметра
C<iocharset> (у випадку із libguestfs цей спосіб не спрацює), або за
допомогою прапорця C<utf8>.

Отже, щоб скористатися файловою системою VFAT, вам слід додати прапорець
C<utf8> під час монтування. У guestfish скористайтеся таким кодом:

 ><fs> параметри_монтування utf8 /dev/sda1 /

або у командному рядку guestfish:

 guestfish [...] -m /dev/sda1:/:utf8

або з програмного інтерфейсу:

 guestfs_mount_options (g, "utf8", "/dev/sda1", "/");

Після цього ядро зможе належним чином перетворювати назви файлів у рядки
UTF-8, і навпаки.

У нас були наміри додати цей параметр монтування у прозорий спосіб, але, на
жаль, з цим виникли певні проблеми:

=over 4

=item *

У деяких системах Linux параметр монтування C<utf8> не працює. Нам не відомі
точні критерії визначення таких систем та причини непрацездатності
параметра, але щодо цього є гідні довіри звіти від одного з наших
користувачів.

=item *

Це не дасть вам змоги скористатися параметром C<iocharset>, оскільки він є
несумісним із C<utf8>. Ймовірно, цим параметром не варто користуватися, але
ми не хочемо і забороняти його використання.

=back

=head2 У файлових системах ISO9660 символи, які не належать до символів ASCII,
показуються як підкреслювання (_).

Файлову систему не було належним чином приготовано за допомогою mkisofs або
genisoimage. Переконайтеся, що файлову систему було створено за допомогою
розширень Joliet і/або Rock Ridge. libguestfs не потрібні ніяких спеціальні
параметри монтування для роботи з файловою системою.

=head2 Не вдається відкрити гостьові системи Windows, у яких використовується NTFS.

Ви бачите такі повідомлення про помилки:

 mount: unknown filesystem type 'ntfs'

У Red Hat Enterprise Linux або CentOS E<lt> 7.2 вам слід встановити пакунок
L<libguestfs-winsupport|https://people.redhat.com/~rjones/libguestfs-winsupport/>.
У RHEL E<ge> 7.2, C<libguestfs-winsupport> є частиною базового дистрибутива
RHEL, але є аспекти, описані у наступному питанні.

=head2 «mount: unsupported filesystem type» для NTFS у RHEL E<ge> 7.2

У RHEL 7.2 нам вдалося додати C<libguestfs-winsupport> до базового
дистрибутива RHEL, але довелося вимкнути можливість використовувати програму
для відкриття та редагування файлових систем. Підтримку цих дій передбачено
лише у поєднанні із L<virt-v2v(1)>. Якщо ви спробуєте скористатися
L<guestfish(1)>,  L<guestmount(1)> або деякими іншими програмами для
файлової системи NTFS, ви побачите таке повідомлення про помилку:

 mount: unsupported filesystem type

Підтримки цієї конфігурації не передбачено, отже ніхто не працюватиме над
тим, щоб це запрацювало у RHEL. Вам не варто створювати повідомлень про
ваду, оскільки їх одразу буде закрито за критерієм C<CLOSED -E<gt> WONTFIX>.

Ви можете L<зібрати власну версію libguestfs без цього
обмеження|https://www.redhat.com/archives/libguestfs/2016-February/msg00145.html>,
але не очікуйте на схвалення або підтримку з боку Red Hat.

=head2 Не вдається відкрити або вивчити гостьові системи RHEL 7.

=head2 Не вдається відкрити гостьові системи Linux, де використовується XFS.

Гостьові системи RHEL 7 та будь-які інші гостьові системи, де
використовується XFS, можна відкрити у libguestfs, але вам слід встановити
пакунок C<libguestfs-xfs>.

=head1 ВИКОРИСТАННЯ LIBGUESTFS У ВАШИХ ВЛАСНИХ ПРОГРАМАХ

=head2 У програмному інтерфейсі сотні методів, з чого почати?

Рекомендуємо вам розпочати з читання огляду програмного інтерфейсу:
L<guestfs(3)/ОГЛЯД ПРОГРАМНОГО ІНТЕРФЕЙСУ>.

Хоча огляд програмного інтерфейсу стосується програмного інтерфейсу мовою C,
все ж варто його прочитати, навіть якщо ви будете користуватися іншою мовою
програмування, оскільки програмний інтерфейс є тим самим, лише з простими
логічними змінами у назвах викликів:

                  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);

Після ознайомлення із оглядом програмного інтерфейсу, вам слід вивчити ці
початкові настанови щодо прив'язки до інших мов програмування:
L<guestfs(3)/ВИКОРИСТАННЯ LIBGUESTFS ЗА ДОПОМОГОЮ ІНШИХ МОВ ПРОГРАМУВАННЯ>.

=head2 Чи можна використовувати libguestfs у пропрієтарній програмі, програмі із
закритим кодом або комерційній програмі?

Загалом, так. Втім, ця порада не є порадою юриста. Ознайомтеся із умовами
ліцензування, які постачаються разом із libguestfs, і якщо у вас виникнуть
специфічні питання, зв'яжіться із правником.

У ієрархії початкового коду умови ліцензування викладено у файлах
C<COPYING.LIB> (LGPLv2+ для бібліотеки і прив'язок) та C<COPYING> (GPLv2+
для окремих програм).

=begin html

<!-- old anchor for the next section --> <a name="debug"/>

=end html

=head1 ДІАГНОСТИКА LIBGUESTFS

=head2 Допоможіть, не працює!

Якщо не працює жодна із програм libguestfs, віддайте вказану нижче команду і
вставте виведений текст B<повністю, без змін> до повідомлення на адресу
C<libguestfs> @ C<redhat.com>:

 libguestfs-test-tool

Якщо не вдається виконати певну дію, надайте усі дані із наведеного нижче
списку у повідомлення на адресу C<libguestfs> @ C<redhat.com>:

=over 4

=item 1.

Що саме ви намагаєтеся зробити?

=item 2.

Які саме команди було віддано вами?

=item 3.

Як саме виглядало повідомлення про помилку або результат виконання ваших
команд?

=item 4.

Увімкніть діагностику, віддайте команду ще раз і скопіюйте B<усі> виведені
дані. B<Не редагуйте виведені дані.>

 export LIBGUESTFS_DEBUG=1
 export LIBGUESTFS_TRACE=1

=item 5.

Вкажіть версію libguestfs, версію операційної системи та спосіб встановлення
libguestfs (наприклад, з початкового коду (from source), C<yum install>
тощо)

=back

=head2 How do I debug when using any libguestfs program or tool (eg. virt-customize
or virt-df)?

Передбачено дві змінні середовища C<LIBGUESTFS_*>, якими ви можете
скористатися для отримання додаткових відомостей від libguestfs.

=over 4

=item C<LIBGUESTFS_TRACE>

Встановіть для цієї змінної значення 1, і libguestfs виводитиме кожну
команду і виклик програмного інтерфейсу у форматі, який подібний до команд
guestfish.

=item C<LIBGUESTFS_DEBUG>

Встановіть для цієї змінної значення 1, щоб увімкнути значний масив
діагностичних повідомлень. Якщо ви вважаєте, що причина проблеми ховається у
базовій системі libguestfs, вам слід скористатися цим варіантом.

=back

Щоб встановити ці змінні із командної оболонки, віддайте такі команди до
запуску програми:

 export LIBGUESTFS_TRACE=1
 export LIBGUESTFS_DEBUG=1

Для csh/tcsh еквівалентними командами будуть такі:

 setenv LIBGUESTFS_TRACE 1
 setenv LIBGUESTFS_DEBUG 1

Докладніші дані можна знайти на сторінці L<guestfs(3)/ЗМІННІ СЕРЕДОВИЩА>

=head2 Як виконувати діагностику за допомогою guestfish?

Можна скористатися описаними вище змінними середовища. Крім того, ви можете
скористатися параметрами guestfish -x (для трасування команд) та -v (для
отримання повної діагностичної інформації).

Докладніші дані можна знайти на сторінці L<guestfish(1)>.

=head2 Як виконувати діагностику за допомогою програмного інтерфейсу?

Викличте L<guestfs(3)/guestfs_set_trace>, щоб увімкнути трасування команд
і/або L<guestfs(3)/guestfs_set_verbose>, щоб увімкнути діагностичні
повідомлення.

Щоб отримати якнайкращі результати, викликайте ці функції якомога раніше,
одразу після створення дескриптора guestfs, точно до виклику launch.

=head2 Як перехопити діагностичні повідомлення і спрямувати їх до системи ведення
журналу?

Скористайтеся програмним інтерфейсом подій. Приклади можна знайти у розділі
L<guestfs(3)/ВСТАНОВЛЕННЯ ЗВОРОТНИХ ВИКЛИКІВ ДЛЯ ОБРОБКИ ПОДІЙ> та програмі
F<examples/debug-logging.c> у початковому коді libguestfs.

=head2 Занурення глибше до процесу завантаження базової системи.

Увімкніть діагностику, а потім ознайомтеся із цією документацією щодо
процесу завантаження базової системи: L<guestfs-internals(1)>.

=head2 libguestfs повисає або повідомляє про помилку під час запуску.

Увімкніть діагностику і ознайомтеся із повними виведеними даними. Якщо вам
не вдається визначити причину, повідомте про ваду, додавши виведені
L<libguestfs-test-tool(1)> дані I<повністю>.

=head2 Діагностування libvirt

Якщо ви користуєтеся модулем libvirt, а libvirt не працює, ви можете
увімкнути діагностику редагуванням F</etc/libvirt/libvirtd.conf>.

Якщо ви запускаєте програму не від імені користувача root, вам слід внести
зміни до іншого файла. Створіть F<~/.config/libvirt/libvirtd.conf> з таким
вмістом:

 log_level=1
 log_outputs="1:file:/tmp/libvirtd.log"

Припиніть роботу усіх libvirtd (запущених не від імені root) у сеансі, і під
час наступного виконання команди libguestfs ви маєте побачити багато
корисних діагностичних відомостей від libvirtd у F</tmp/libvirtd.log>

=head2 Помилки у ядрі або як спробувати інше ядро.

Ви можете вибрати інше ядро для базової системи встановленням певних
L<змінних середовища supermin|supermin(8)/ЗМІННІ СЕРЕДОВИЩА>:

 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

=head2 Помилки у qemu або як спробувати іншу qemu.

Ви можете вибрати іншу qemu встановленням L<змінної
середовища|guestfs(3)/ЗМІННІ СЕРЕДОВИЩА> гіпервізору:

 export LIBGUESTFS_HV=/шлях/до/qemu-system-x86_64
 libguestfs-test-tool

=head1 ДИЗАЙН/ВНУТРІШНЯ БУДОВА LIBGUESTFS

Див. також L<guestfs-internals(1)>.

=head2 Чому б не виконувати усі дії за допомогою інтерфейсу FUSE або файлової
системи?

Нами створено програму із назвою L<guestmount(1)>, за допомогою якої ви
можете монтувати файлові системи гостьових систем у основній
системі. Програму реалізовано як модуль FUSE. Чому ж ми не реалізували усю
libguestfs з використанням цього механізму, замість створення великого і
доволі складного програмного інтерфейсу?

Причини дві. По-перше, libguestfs надає змогу виконувати запити до
програмного інтерфейсу з метою створення та вилучення розділів і логічних
томів, що не вкладається у просту модель файлової системи. Звичайно ж, можна
уявити це і як роботу із файловою системою. Наприклад, створення розділу
можна пов'язати із C<mkdir /fs/hda1>, але тоді доведеться вказувати метод
вибору розміру розділу (наприклад, C<echo 100M E<gt> /fs/hda1/.size>), типу
розділу, початкового і кінцевого секторів тощо. Але якщо усе це реалізувати
програмний інтерфейс на основі файлової системи стає складнішим за
програмний інтерфейс на основі викликів, який зараз має бібліотека.

Другою причиною є ефективність. Сама FUSE є доволі ефективною, але вона
виконує багато незначних незалежних викликів модуля FUSE. У guestmount ці
виклики доводиться переводити у повідомлення для базової системи libguestfs
і втрачати на цьому багато часу (у сенсі навантаження на систему і циклів
обробки). Наприклад, читання 64-кілобайтових фрагментів файла є
неефективним, оскільки кожен фрагмент дає власний цикл обробки.  У
програмному інтерфейсі libguestfs набагато ефективнішим є отримання усього
файла або каталогу за допомогою одного з потокових викликів, подібних до
C<guestfs_download> або C<guestfs_tar_out>.

=head2 Чому б не виконувати усі дії за допомогою GVFS?

Проблеми такого варіанта подібні до проблем із FUSE.

GVFS є кращою абстракцією за POSIX/FUSE. Існує модуль FTP для GVFS, що має
надихати, оскільки FTP концептуально подібна до програмного інтерфейсу
libguestfs. Втім, модуль FTP GVFS для підтримання інтерактивності встановлює
одразу декілька одночасних з'єднань, що непросто реалізувати у libguestfs.

=begin html

<!-- old anchor for the next section --> <a name="backup"/>

=end html

=head2 Чому у мене лишається можливість запису на диск, навіть якщо його позначено
як придатний лише для читання?

=head2 Чому використання C<--ro> не дає бажаних наслідків?

Коли ви додаєте диск як придатний лише для читання, libguestfs розташовує на
основі підлеглого диска придатну для запису накладку. Записувані дані
потрапляють до цієї накладки і відкидаються, коли закривається дескриптор
(або завершує роботу програма C<guestfish> або подібна).

Причин у такому стилі роботи є дві: по-перше, у багатьох випадках створення
дисків, які придатні лише для читання, неможливе (наприклад, у IDE взагалі
не передбачено підтримки таких дисків, отже, ви не можете створити придатний
лише для читання диск із емуляцією IDE, хоча створення таких дисків і не є
типовим у встановлених екземплярах libguestfs).

По-друге, і важливіше, навіть якщо створення придатних лише для читання
дисків можливе, вам вони просто не знадобляться. Монтування будь-якої
файлової системи із журналом, навіть за допомогою команди C<mount -o ro>,
призводить до запису до файлової системи, оскільки має бути відтворено
журнал і оновлено метадані. Якщо б диск був насправді захищеним від запису,
ви б не змогли змонтувати файлову систему у стані незавершеного запису.

Щоб такими файловими системами можна було користуватися, ми створили
накладку, як місце для запису даних, які згодом буде відкинуто. Це
забезпечує недоторканність підлеглого диска.

Слід зауважити, що для цього передбачено особливий тест на регресії під час
збирання libguestfs (у C<tests/qemu>). Це одна з причин, з яких ми
рекомендуємо пакувальникам вмикати комплекс перевірок під час збирання
пакунків.

=head2 Чи робить C<--ro> усі диски придатними лише для читання?

I<Ні!> Параметр C<--ro> стосується лише дисків, які додано за допомогою
командного рядка, тобто за допомогою параметрів C<-a> та C<-d>.

У guestfish, якщо ви використовуєте команду C<add>, диск додається у режимі
читання і запису (якщо ви не вкажете прапорець C<readonly:true> явним чином
у команді).

=head2 Чи можна скористатися C<guestfish --ro> для резервного копіювання моїх
віртуальних машин?

Зазвичай, I<не варто> цього роботи. Докладнішу відповідь на це питання можна
знайти у цьому повідомленні зі списку листування:
L<https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html>

Див. також наступне питання.

=head2 Чому не можна запускати fsck для робочої файлової системи, де використано
C<guestfish --ro>?

Така команда, зазвичай, I<не працює>:

 guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda

Причиною є те, що qemu створює знімок початкової файлової системи, але не
створює цей знімок із точною прив'язкою до часу. Блоки даних підлеглої
файлової системи читаються qemu у різні моменти часу під час обробки
файлової системи за допомогою fsck, а основна система у цей час може
записувати дані. У результаті fsck виявить значні пошкодження (уявні, не
справжні!) у файловій системі і завершить роботу із повідомленням про
помилку.

Щоб досягти бажаного результату, вам слід створити прив'язаний до часу
знімок. Якщо маєте справу із логічним томом, скористайтеся знімком
LVM2. Якщо файлову систему розташовано у чомусь подібному до файла
btrfs/ZFS, скористайтеся знімком btrfs/ZFS, а потім запустіть fsck для
перевірки знімка. На практиці, для виконання цього завдання libguestfs не
потрібна — просто скористайтеся F</sbin/fsck> безпосередньо.

Створення прив'язаних до часу знімків пристроїв і файлів основної системи не
виконується засобами libguestfs, хоча libguestfs може працювати із такими
знімками, коли їх буде створено.

=head2 Чим відрізняються guestfish і virt-rescue?

Для багато кого є незрозумілим включення нами двох з першого погляду
подібних інструментів до бібліотеки:

 $ guestfish --ro -a guest.img
 ><fs> run
 ><fs> fsck /dev/sda1

 $ virt-rescue --ro guest.img
 ><rescue> /sbin/fsck /dev/sda1

А ще одним пов'язаним питанням, яке тоді виникає, є питання того, чому у
guestfish не можна вводити команди оболонки повністю з усіма параметрами з
мінусами (але це можна робити у L<virt-rescue(1)>).

L<guestfish(1)> — програма, яка надає структурований доступ до програмного
інтерфейсу L<guestfs(3)>. Також це непогана інтерактивна командна оболонка,
але основним її призначенням є структурований доступ до скриптів командної
оболонки. Її можна вважати скоріше прив'язкою до мов програмування, зокрема
Python, та інших прив'язок, але для оболонки. Ключовим фактором
диференціювання guestfish (і програмного інтерфейсу libguestfs загалом) є
можливість автоматизації змін.

L<virt-rescue(1)> — гнучкий спосіб завантажити базову систему libguestfs і
внести довільні зміни до вашої віртуальної машини. Його не структуровано, ви
не можете автоматизувати його використання, але для швидкого ситуаційного
внесення виправлень до ваших гостьових систем ця програма може бути дуже
зручною.

Але у libguestfs також є і «чорний вхід» до базової системи, який надає вам
змогу надсилати довільні команди до командної оболонки. Він не є настільки
гнучким як virt-rescue, оскільки ви не можете взаємодіяти із командами
оболонки. Втім, ось він:

 ><fs> debug sh "команда аргумент1 аргумент2 ..."

Зауважте, що на цей спосіб B<не слід> покладатися. Відповідні засоби може
бути вилучено або змінено у майбутньому. Якщо у вашій програмі потрібна
певна операція, будь ласка, додайте її до програмного інтерфейсу libguestfs.

=head2 Для чого призначено C<guestfish -i>?

=head2 Чому virt-cat працює лише для справжнього образу віртуальної машини, а
virt-df працює для будь-якого образу диска?

=head2 Що означає повідомлення «у цьому образі операційної системи не знайдено
кореневого пристрою»?

Усі ці питання пов'язано на базовому рівні, хоча це спочатку здається
неочевидним.

На рівні програмного інтерфейсу L<guestfs(3)> «образ диска» це просто купа
розділів і файлових систем.

У протилежність, коли завантажується віртуальна машина, вона монтує файлові
системи у послідовну ієрархію, ось так:

 /          (/dev/sda2)
 │
 ├── /boot  (/dev/sda1)
 │
 ├── /home  (/dev/vg_external/Homes)
 │
 ├── /usr   (/dev/vg_os/lv_usr)
 │
 └── /var   (/dev/vg_os/lv_var)

(або літери дисків у Windows).

Перш за все, програмний інтерфейс бачить образ диска на рівні «купи файлових
систем». Але у програмному інтерфейсі також передбачено способи
інспектування образу диска для визначення, чи міститься на ньому операційна
система, та того, як монтуються диски, коли завантажується операційна
система: L<guestfs(3)/ІНСПЕКЦІЯ>.

Користувачі очікують працездатності деяких інструментів (зокрема
L<virt-cat(1)>) для шляхів у ВМ:

 virt-cat fedora.img /var/log/messages

Як virt-cat дізнається про те, що F</var> є окремим розділом? Справа полягає
у тому, що virt-cat виконує інспекцію образу диска і використовує отримані
дані для правильної трансляції шляху.

Деякі з інструментів (зокрема L<virt-cat(1)>, L<virt-edit(1)>,
L<virt-ls(1)>) використовують інспекцію для визначення шляхів у віртуальній
машині. Інші інструменти, зокрема L<virt-df(1)> і L<virt-filesystems(1)>,
працюють лише на рівні необробленої «великої купи файлових систем»
програмного інтерфейсу libguestfs і не використовують інспекцію.

L<guestfish(1)> є цікавим проміжним варіантом. Якщо ви використовуєте
параметри командного рядка I<-a> та I<-m>, вам доведеться повідомити
guestfish точно, як додавати образи дисків і куди слід монтувати розділи. Це
рівень програмного інтерфейсу без додаткової обробки.

Якщо ви використовуєте параметр I<-i>, libguestfs виконує інспектування та
монтує файлові системи.

Повідомлення про помилку C<у цьому образі операційної системи не знайдено
кореневого пристрою> пов'язано із цим. Воно означає, що під час інспекції не
удалося виявити операційну систему на вказаному образі диска. Ви можете
побачити таке повідомлення від програм, подібних до virt-cat, якщо ви
скористаєтеся ними для дослідження образу диска, який не є образом диска
віртуальної машини.

=head2 Яке завдання виконують функції C<debug*> і C<internal-*>?

У бібліотеці існує декілька функцій, які використовуються для діагностування
та внутрішньої обробки даних. Ці функції I<не> є частиною стабільного
програмного інтерфейсу.

Функції C<debug*> (або C<guestfs_debug*>), головним чином
L<guestfs(3)/guestfs_debug> та декілька інших, використовуються для
діагностики помилок у libguestfs. Хоча вони і не є частиною стабільного
програмного інтерфейсу, а отже, їх може бути будь-коли вилучено, їх можна
використовувати у програмах, доки певні можливості буде додано до
libguestfs.

Функції C<internal-*> (або C<guestfs_internal_*>) призначено для
використання лише у libguestfs. Немає сенсу викликати ці функції з програм,
їх також не слід використовувати у програмах. Зрідка, використання цих
функцій може призвести до небажаних наслідків, окрім того, вони не є
частиною документованого стабільного програмного інтерфейсу.

=head1 РОЗРОБНИКАМ

=head2 Куди слід надсилати латки?

Будь ласка, надсилайте латки до списку листування libguestfs,
L<https://www.redhat.com/mailman/listinfo/libguestfs>. Підписуватися на
список не обов'язково, але для непідписаних користувачів розповсюдження
відбувається лише після підтвердження повідомлення вручну кимось із
адміністраторів.

B<Будь ласка, не використовуйте запити щодо об'єднання на github — ці запити
буде проігноровано>. Причинами цього є: (а) ми хочемо обговорювати і
розбирати латки у списку листування, і (б) запити щодо об'єднання github
перетворюються у внески із об'єднанням, а ми хочемо зберігати у сховищі
лінійну історію.

=head2 Як запропонувати нову можливість?

Значні нові можливості, розробку яких ви маєте намір здійснити, має бути
спочатку обговорено у списку листування
(L<https://www.redhat.com/mailman/listinfo/libguestfs>). Так ви можете
уникнути прикростей і заощадити час, якщо раптом виявиться, що інші
розробники вважають можливість такою, яка не відповідає меті проєкту
libguestfs.

Якщо ви хочете запропонувати корисну можливість, але не хочете писати код
для її реалізації, ви можете створити повідомлення про ваду
(див. L</ОТРИМАННЯ ДОВІДКОВОЇ ІНФОРМАЦІЇ ТА ЗВІТУВАННЯ ПРО ВАДИ>) із
додаванням C<"RFE: "> на початку рядка резюме (Summary).

=head2 Хто має право записувати внески до git libguestfs?

Доступ на запис до сховища на github має близько 5 осіб. Латки має бути
спочатку надіслано до списку листування і схвалено учасниками. Правила
схвалення та запису латок окреслено нижче:

L<https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html>

=head2 Можна мені створити відгалуження libguestfs?

Звичайно ж, ви можете. Git спрощує створення відгалужень libguestfs. Github
робить цю процедуру ще простішою. Було б добре також оголосити про
відгалуження у списку листування та повідомити про причини його створення.

=head1 ІНШІ ПИТАННЯ

=head2 Чи можна інтерактивно стежити за роботою диска у віртуальній машині за
допомогою libguestfs?

Типовим запитом є реалізація у libguestfs можливості інтерактивного стеження
за діями з диском у гостьовій системі, наприклад, отримання сповіщення
кожного разу, коли у гостьовій системі створюється файл. Libguestfs I<не
працює> так, як дехто собі уявляє. Це можна бачити на наведеній нижче
діаграмі:

            ┌─────────────────────────────────────┐
            │ програма для спостереження за допомогою libguestfs │
            └─────────────────────────────────────┘
                             ↓
 ┌───────────┐    ┌──────────────────────┐
 │ жива ВМ   │    │ базова система libguestfs │
 ├───────────┤    ├──────────────────────┤
 │ ядро (1)│    │ ядро базової системи (2) │
 └───────────┘    └──────────────────────┘
      ↓                      ↓ (з'єднання для читання)
      ┌──────────────────────┐
      |      образ диска      |
      └──────────────────────┘

Цей сценарій є безпечним (якщо під час додавання диска було встановлено
прапорець C<лише читання>). Втім, тоді ядро базової системи libguestfs (2)
не бачитиме усі зміни, які відбулися у образі диска, з двох причин:

=over 4

=item i.

Ядро віртуальної машини (1) може кешувати дані у пам'яті, щоб кеш не
записувався на образ диска.

=item ii.

Ядро базової системи libguestfs (2) не очікує на зміни у образі диска, тому
його власний кеш не буде магічним чином оновлено, навіть коли ядро
віртуальної машини (1) оновлює образ диска.

=back

Єдиним підтримуваним рішенням є перезапуск усієї базової системи libguestfs
кожного разу, коли вам потрібно переглянути зміни у образі диска. На рівні
програмного інтерфейсу це відповідає виклику C<guestfs_shutdown> з наступним
викликом C<guestfs_launch>, що є доволі вартісною операцією (див. також
L<guestfs-performance(3)>).

Існує декілька «брудних» прийомів, якими ви можете скористатися, якщо
перезапуск базової системи є дійсно дуже вартісною справою:

=over 4

=item *

Виклик C<guestfs_drop_caches (g, 3)>. Такий виклик призводить до того, що
усі кешовані дані ядра базової системи libguestfs (2) буде відкинуто, отже
йому доведеться користуватися образом диска.

Втім, лише цього недостатньо, оскільки qemu також кешує деякі дані. Вам
також доведеться латати libguestfs, щоб увімкнути режим
C<cache=none>.
Див.
L<https://rwmj.wordpress.com/2013/09/02/new-in-libguestfs-allow-cache-mode-to-be-selected/>

=item *

Замість цього, вам варто скористатися інструментами, подібними до
L<virt-bmap|http://git.annexia.org/?p=virt-bmap.git>.

=item *

Запуск агента у гостьовій системі.

=back

Нічого не поможе, якщо у гостьовій системі виконуються фундаментальніші
зміни (наприклад, вилучаються файлові системи). Для фіксації таких змін вам
доведеться перезапускати базову систему.

(Зауважте, що існує і третя проблема: вам доведеться користуватися
послідовними знімками для справжнього вивчення образів дисків, але це
загальна проблема використання libguestfs для роботи з будь-яким «живим»
образом диска.)

=head1 ТАКОЖ ПЕРЕГЛЯНЬТЕ

L<guestfish(1)>, L<guestfs(3)>, L<http://libguestfs.org/>.

=head1 АВТОРИ

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 АВТОРСЬКІ ПРАВА

Copyright (C) 2012-2020 Red Hat Inc.