guestfs-faq

НАЗВА

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

ПРО LIBGUESTFS

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

libguestfs — засіб створення образів диска, доступу до образів диску та внесення змін до образів диска. За її допомогою ви зможете бачити вміст образів диска, вносити зміни до файлів, які у ньому містяться, створювати образи, змінювати їхні розміри тощо. Це особливо корисно для керування образами зі скриптів та програм, а також командного рядка. libguestfs є бібліотекою мовою C (звідси «lib-») і набором інструментів, побудованих на основі цієї бібліотеки, а також прив'язок до багатьох типових мов програмування. Докладніший опис призначення і можливостей libguestfs наведено у вступній частині домашньої сторінки (http://libguestfs.org).

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

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

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

Ні! libvirt не є обов’язковою частиною libguestfs. libguestfs працює із будь-яким образом диска, зокрема образами, створеним за допомогою VMware, KVM, qemu, VirtualBox, Xen та багатьох інших гіпервізорів, а також тими образами, які ви створили «з нуля». Red Hat спонсорує (тобто оплачує) розробку libguestfs та величезної кількості інших проєктів із відкритим кодом. Втім, ви можете працювати із libguestfs та засобами віртуалізації на багатьох інших дистрибутивах Linux та у Mac OS X. Ми намагаємося якнайкраще підтримувати передусім усі дистрибутиви Linux. Деякі із засобів віртуалізації портовано на Windows.

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

порівняно з kpartx

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

порівняно з vdfuse

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

порівняно з qemu-nbd

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

порівняно з монтуванням файлових систем у основній системі

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

порівняно з parted

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

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

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

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

 guestfish --version

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

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

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

Якщо ви є клієнтом Red Hat, який користується Red Hat Enterprise Linux, будь ласка, зв'яжіться із Службою підтримки Red Hat: http://redhat.com/support Передбачено список листування, здебільшого, для тем, пов'язаних із розробкою, але користувачі також можуть задавати питання щодо libguestfs та засобів віртуалізації у цьому списку: https://www.redhat.com/mailman/listinfo/libguestfs You can also talk to us on IRC channel "#guestfs" on Libera Chat. We're not always around, so please stay in the channel after asking your question and someone will get back to you. Щодо інших засобів віртуалізації (не тих, які є частиною libguestfs) існує загальний список листування щодо засобів віртуалізації: https://www.redhat.com/mailman/listinfo/virt-tools-list

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

Будь ласка, скористайтеся цим посиланням для створення записів звітів щодо вад у Bugzilla: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools Надайте якнайдокладніший опис і поради щодо способу відтворення проблеми. Включіть до звіту усі дані, які було виведено libguestfs-test-tool(1).

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

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

"Could not allocate dynamic translator buffer"

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

 setsebool -P virt_use_execmem=on

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

"child process died unexpectedly"

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

 libguestfs-test-tool

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

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

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

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

[Цю ваду було остаточно виправлено у libguestfs ≥ 1.26.] Якщо ви бачите ці повідомлення про помилки у Debian/Ubuntu, вам слід віддати таку команду:

 sudo update-guestfs-appliance

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

Ви отримуєте повідомлення щодо заборони доступу під час відкриття образу диска, незважаючи на те, що запускали libguestfs від імені адміністратора системи (root). Причиною є робота libvirt, отже, це трапляється лише при використанні модуля обробки libvirt. Під час роботи від імені користувача root libvirt запускає базову систему qemu від імені користувача "qemu.qemu". На жаль, зазвичай, це означає, що qemu не зможе відкривати образи дисків, особливо якщо власником цих образів диска є користувач root або ці образи зберігаються у каталогах, доступ до яких має лише користувач root. Для виправлення цього відкрито звіт про ваду у libvirt: https://bugzilla.redhat.com/show_bug.cgi?id=1045069 Обійти проблему можна у один з таких способів:

•

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

 export LIBGUESTFS_BACKEND=direct
    

•

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

•

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

•

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

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

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

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

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

 ldd /bin/bash

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

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

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

Fedora ≥ 11

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

 yum install '*guestf*'
    

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

Red Hat Enterprise Linux

Debian і Ubuntu

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

 sudo update-guestfs-appliance
    

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

 sudo chmod 0644 /boot/vmlinuz*
    

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

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

Gentoo

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

 emerge libguestfs
    

Mageia

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

 urpmi libguestfs
    

SuSE

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

ArchLinux

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

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

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

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

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

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

Ви можете зібрати libguestfs з git або архіву tar із початковим кодом. Перш ніж почнете це робити, ознайомтеся із вмістом файла README. Git: https://github.com/libguestfs/libguestfs Архіви з кодом: http://libguestfs.org/download Не використовуйте команду "make install"! Замість неї слід користуватися скриптом "./run" (див. README).

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

Для роботи libguestfs потрібен supermin 5. Якщо supermin 5 не портовано на ваш дистрибутив, ознайомтеся із наведеною нижче відповіддю на наступне питання. Спочатку зберіть qemu, supermin і/або ядро із початкового коду. Вам не слід віддавати команду "make install" для встановлення. У каталозі із початковим кодом libguestfs створіть два файли. Файл "localconfigure" має містити такий текст:

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

Зробіть "localconfigure" виконуваним. "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

Розкоментуйте і скоригуйте рядки так, щоб вони відповідали зібраним вами альтернативним варіантам програм. Скористайтеся "./localconfigure" замість "./configure" додавши до скрипту звичайні аргументи для збирання libguestfs. Не використовуйте команду "make install"! Замість неї слід користуватися скриптом "./run" (див. README).

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

Якщо у supermin 5 передбачено підтримку вашого дистрибутива, але якось так вийшло, що у вашій системі не встановлено достатньо нової версії supermin, скористайтеся настановами із відповіді на попереднє питання. If supermin 5 doesn't support your distro at all, you will need to use the "fixed appliance method" where you use a pre-compiled binary appliance. To build libguestfs without supermin, you need to pass "--disable-appliance --disable-daemon" to either ./configure or ./configure (depending whether you are building respectively from git or from tarballs). Then, when using libguestfs, you must set the "LIBGUESTFS_PATH" environment variable to the directory of a pre-compiled appliance, as also described in "FIXED APPLIANCE" in guestfs-internals(1). Крім того, попередньо зібрані базові системи можна знайти тут: http://libguestfs.org/download/binaries/appliance/. Ми будемо раді надісланим вами латкам для портування supermin на інші дистрибутиви Linux.

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

Зауваження для користувачів Fedora/RHEL: ця конфігурація є типовою, починаючи з Fedora 18 та RHEL 7. Якщо вами буде виявлено якісь проблеми, будь ласка, повідомте розробникам або створіть звіт про ваду у бібліотеці. SVirt створює захищену базову систему із використанням SELinux, роблячи дуже складною для створеного зловмисниками образу диска «втечу» з контейнера libguestfs і ускладнюючи спроби нашкодити основній системі (слід сказати, що навіть у стандартній libguestfs зробити це складно, але sVirt створює додатковий шар захисту для основної системи і, що важливіше, захищає віртуальні машини на одній основній системі одна від одної). У поточній версії для вмикання sVirt вам знадобиться libvirt ≥ 0.10.2 (бажано 1.0 або новіша версія), libguestfs ≥ 1.20, та правила SELinux зі свіжої версії Fedora. Якщо ви працюєте не з 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. Втім, є один відомий недолік: virt-rescue(1) не використовуватиме libvirt (а отже, і sVirt), а повернеться до безпосереднього запуску qemu. Тому, ви не зможете скористатися перевагами захисту sVirt, якщо користуватиметеся virt-rescue. Перевірити, чи працює sVirt можна вмиканням журналу libvirtd (див. /etc/libvirt/libvirtd.log). Далі слід завершити роботу libvirtd і перезапустити цю службу, а потім пошукати у файлах журналу повідомлення "Setting SELinux context on ..." (Встановлюємо контекст SELinux...»). Теоретично, у sVirt має бути передбачено підтримку AppArmor, але ми цього не перевіряли. Майже напевне, використання sVirt потребуватиме латання libvirt і написання правил AppArmor.

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

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

1.

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

2.

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

3.

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

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

Помилки під час запуску на Fedora ≥ 18, RHEL ≥ 7

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

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

The libvirt backend is more sophisticated, supporting SELinux/sVirt (see above) and more. It is, however, more complex and so less robust. Якщо виникають проблеми із правами доступу під час використання модуля libvirt, ви можете перейти на модуль безпосереднього керування встановленням такої змінної середовища:

 export LIBGUESTFS_BACKEND=direct

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

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

Це може поліпшити стабільність та швидкодію 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).

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

Найважливішим у пришвидшенні роботи може стати встановлення і належне налаштовування Squid. Зауважте, що типові налаштування, з якими встановлюється Squid не дадуть бажаних результатів, тому налаштовування у цьому випадку є обов'язковим. Чудові початкові поради щодо налаштовування Squid можна знайти тут: https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads Переконайтеся, що Squid працює, і що змінні середовища $http_proxy та $ftp_proxy вказують на нього. Якщо Squid запущено і належним чином налаштовано, збирання базової системи має стати справою декількох хвилин. Як пришвидшити збирання libguestfs (Debian)? Hilko Bengen запропоновано використовувати «approx», архівний проксі-сервер Debian (http://packages.debian.org/approx). Документацію до цієї програми можна знайти на сторінці підручника щодо approx(8).

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

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

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

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

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

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

 /var/tmp/.guestfs-<UID>

Якщо визначено змінну середовища "TMPDIR", буде використано $TMPDIR/.guestfs-<UID>. Коли ви не використовуєте libguestfs, цей каталог можна безпечно вилучити.

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

Якщо результатом virt-sparsify(1) є образ raw, буде виведено розріджені дані raw. Отже, вимірювати виведені дані слід за допомогою інструмента, який обробляє розріджені дані, наприклад "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

(Порівняйте видимий розмір у 100 МБ зі справжнім розміром у 3,6 МБ) Якщо такі відмінності бентежать вас, скористайтеся форматом виведення без розрідження, вказавши параметр --convert. Приклад:

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

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

Зміна розміру образу диска є доволі непростою дією — особливо, з урахуванням того, що слід зберегти усі дані і не пошкодити завантажувач. У поточній версії, насправді, створюється новий образ диска, до якого копіюються дані і завантажувач зі старого образу. Якщо щось піде не так, ви завжди можете повернутися до початкового варіанта. Якби нами було реалізовано роботу virt-resize «на місці», нам довелося б також ввести декілька обмежень: наприклад, було б заборонено пересування наявних розділів (оскільки пересування даних у межах одного диска, найімовірніше, призвело б до пошкодження даних при раптовому вимиканні живлення або аварійному завершенні роботи програми), а підтримка LVM стала б дуже складною справою (через майже випадковий зв'язок між вмістом логічного тому і підлеглих йому блоків на диску). Ми розглядали і інший спосіб, який полягав у тому, щоб створювати різницю-знімок щодо початкового образу диска так, щоб початкові дані лишалися незмінними, а до знімка записувалася лише різниця. Зробити це у поточній версії можна за допомогою комбінації "qemu-img create" + "virt-resize". Втім, qemu у поточній версії недостатньо кмітлива, щоб розпізнати ситуацію, коли блок, який записується до знімка вже існує у резервній копію диска, отже, зрозуміло, цей спосіб не заощадить вам ні місця на диску, ні часу. Підсумовуючи, це складна проблема, у поточній версії усе працює майже як слід, тому ми не дуже хочемо щось міняти.

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

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

 virt-sparsify --in-place disk.img

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

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

Неможливо відкрити віддалені гостьові системи 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. Див. "ВІДДАЛЕНЕ СХОВИЩЕ" in guestfs(3).

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

Нехай у вас є образ диска, розташований у іншій системі, доступ до якої потребує бібліотеки, HTTP, REST або пропрієтарного програмного інтерфейсу, або такий образ, який стиснено або архівовано у певний спосіб. (Одним із прикладів є віддалений доступ до образів glance OpenStack без початкового отримання усіх даних таких образів.) Ми створили дочірній проєкт із назвою nbdkit (https://github.com/libguestfs/nbdkit). Цей проєкт надає вам змогу перетворити будь-яке дискове джерело у сервер NBD. Libguestfs може отримати доступ до серверів NBD безпосередньо, приклад:

 guestfish -a nbd://remote

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

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

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

1.

Якщо гостьова система працює на «живому», доступному сервері ESX, знайдіть і отримайте образ диска із назвою назва_гостьової_системи -flat.vmdk. Незважаючи на назву, це образ диска raw, який можна відкрити будь-якою відповідною програмою. Якщо ви працюєте з доволі свіжою версією qemu і libguestfs, ви, ймовірно, зможете отримати доступ до цього образу диска віддалено за допомогою HTTPS або ssh. Див. "ВІДДАЛЕНЕ СХОВИЩЕ" in guestfs(3).

2.

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

3.

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

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

У файлової системи UFS багато варіантів. Визначити варіант непросто. Ядру Linux має бути повідомлено варіант UFS, який слід використати, а libguestfs не зможе це зробити самостійно. Під час монтування цих файлових систем слід передати правильне значення параметра монтування "ufstype". Див. https://www.kernel.org/doc/Documentation/filesystems/ufs.txt

Windows ReFS

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

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

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

•

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

•

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

Це конструктивна проблема системи GNU/Linux. VFAT зберігає довгі назви файлів у форматі набору символів UTF-16. Коли операційна система відкриває або повертає назви файлів, ядро Linux має перетворити такий набір символів у певну форму рядка із 8-бітових символів. Очевидним вибором про цьому є UTF-8, окрім тих випадків, коли користувачі Linux примусово визначають локалі, відмінні від UTF-8 (локаль користувача не є відомою ядру, оскільки її роботу забезпечує не ядро, а libc). Через це вам слід повідомити ядру, яке саме перетворення слід виконати під час монтування файлової системи. Зробити це можна або за допомогою параметра "iocharset" (у випадку із libguestfs цей спосіб не спрацює), або за допомогою прапорця "utf8". Отже, щоб скористатися файловою системою VFAT, вам слід додати прапорець "utf8" під час монтування. У guestfish скористайтеся таким кодом:

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

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

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

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

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

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

•

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

•

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

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

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

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

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

 mount: unknown filesystem type 'ntfs'

У Red Hat Enterprise Linux або CentOS < 7.2 вам слід встановити пакунок libguestfs-winsupport. У RHEL ≥ 7.2, "libguestfs-winsupport" є частиною базового дистрибутива RHEL, але є аспекти, описані у наступному питанні.

«mount: unsupported filesystem type» для NTFS у RHEL ≥ 7.2

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

 mount: unsupported filesystem type

Підтримки цієї конфігурації не передбачено, отже ніхто не працюватиме над тим, щоб це запрацювало у RHEL. Вам не варто створювати повідомлень про ваду, оскільки їх одразу буде закрито за критерієм "CLOSED -> WONTFIX". Ви можете зібрати власну версію libguestfs без цього обмеження, але не очікуйте на схвалення або підтримку з боку Red Hat.

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

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

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

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

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

Рекомендуємо вам розпочати з читання огляду програмного інтерфейсу: "ОГЛЯД ПРОГРАМНОГО ІНТЕРФЕЙСУ" in 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);

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

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

Загалом, так. Втім, ця порада не є порадою юриста. Ознайомтеся із умовами ліцензування, які постачаються разом із libguestfs, і якщо у вас виникнуть специфічні питання, зв'яжіться із правником. У ієрархії початкового коду умови ліцензування викладено у файлах "COPYING.LIB" (LGPLv2+ для бібліотеки і прив'язок) та "COPYING" (GPLv2+ для окремих програм).

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

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

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

 libguestfs-test-tool

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

1.

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

2.

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

3.

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

4.

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

 export LIBGUESTFS_DEBUG=1
 export LIBGUESTFS_TRACE=1
    

5.

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

Як виконати діагностику роботи програми або інструмента libguestfs (наприклад virt-customize або virt-df)?

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

"LIBGUESTFS_TRACE"

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

"LIBGUESTFS_DEBUG"

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

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

 export LIBGUESTFS_TRACE=1
 export LIBGUESTFS_DEBUG=1

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

 setenv LIBGUESTFS_TRACE 1
 setenv LIBGUESTFS_DEBUG 1

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

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

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

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

Викличте "guestfs_set_trace" in guestfs(3), щоб увімкнути трасування команд і/або "guestfs_set_verbose" in guestfs(3), щоб увімкнути діагностичні повідомлення. Щоб отримати якнайкращі результати, викликайте ці функції якомога раніше, одразу після створення дескриптора guestfs, точно до виклику launch.

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

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

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

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

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

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

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

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

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

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

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

Ви можете вибрати інше ядро для базової системи встановленням певних змінних середовища supermin:

 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

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

Ви можете вибрати іншу qemu встановленням змінної середовища гіпервізору:

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

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

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

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

Нами створено програму із назвою guestmount(1), за допомогою якої ви можете монтувати файлові системи гостьових систем у основній системі. Програму реалізовано як модуль FUSE. Чому ж ми не реалізували усю libguestfs з використанням цього механізму, замість створення великого і доволі складного програмного інтерфейсу? Причини дві. По-перше, libguestfs надає змогу виконувати запити до програмного інтерфейсу з метою створення та вилучення розділів і логічних томів, що не вкладається у просту модель файлової системи. Звичайно ж, можна уявити це і як роботу із файловою системою. Наприклад, створення розділу можна пов'язати із "mkdir /fs/hda1", але тоді доведеться вказувати метод вибору розміру розділу (наприклад, "echo 100M > /fs/hda1/.size"), типу розділу, початкового і кінцевого секторів тощо. Але якщо усе це реалізувати програмний інтерфейс на основі файлової системи стає складнішим за програмний інтерфейс на основі викликів, який зараз має бібліотека. Другою причиною є ефективність. Сама FUSE є доволі ефективною, але вона виконує багато незначних незалежних викликів модуля FUSE. У guestmount ці виклики доводиться переводити у повідомлення для базової системи libguestfs і втрачати на цьому багато часу (у сенсі навантаження на систему і циклів обробки). Наприклад, читання 64-кілобайтових фрагментів файла є неефективним, оскільки кожен фрагмент дає власний цикл обробки. У програмному інтерфейсі libguestfs набагато ефективнішим є отримання усього файла або каталогу за допомогою одного з потокових викликів, подібних до "guestfs_download" або "guestfs_tar_out".

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

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

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

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

Коли ви додаєте диск як придатний лише для читання, libguestfs розташовує на основі підлеглого диска придатну для запису накладку. Записувані дані потрапляють до цієї накладки і відкидаються, коли закривається дескриптор (або завершує роботу програма "guestfish" або подібна). Причин у такому стилі роботи є дві: по-перше, у багатьох випадках створення дисків, які придатні лише для читання, неможливе (наприклад, у IDE взагалі не передбачено підтримки таких дисків, отже, ви не можете створити придатний лише для читання диск із емуляцією IDE, хоча створення таких дисків і не є типовим у встановлених екземплярах libguestfs). По-друге, і важливіше, навіть якщо створення придатних лише для читання дисків можливе, вам вони просто не знадобляться. Монтування будь-якої файлової системи із журналом, навіть за допомогою команди "mount -o ro", призводить до запису до файлової системи, оскільки має бути відтворено журнал і оновлено метадані. Якщо б диск був насправді захищеним від запису, ви б не змогли змонтувати файлову систему у стані незавершеного запису. Щоб такими файловими системами можна було користуватися, ми створили накладку, як місце для запису даних, які згодом буде відкинуто. Це забезпечує недоторканність підлеглого диска. Слід зауважити, що для цього передбачено особливий тест на регресії під час збирання libguestfs (у "tests/qemu"). Це одна з причин, з яких ми рекомендуємо пакувальникам вмикати комплекс перевірок під час збирання пакунків.

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

Ні! Параметр "--ro" стосується лише дисків, які додано за допомогою командного рядка, тобто за допомогою параметрів "-a" та "-d". У guestfish, якщо ви використовуєте команду "add", диск додається у режимі читання і запису (якщо ви не вкажете прапорець "readonly:true" явним чином у команді).

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

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

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

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

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

Причиною є те, що qemu створює знімок початкової файлової системи, але не створює цей знімок із точною прив'язкою до часу. Блоки даних підлеглої файлової системи читаються qemu у різні моменти часу під час обробки файлової системи за допомогою fsck, а основна система у цей час може записувати дані. У результаті fsck виявить значні пошкодження (уявні, не справжні!) у файловій системі і завершить роботу із повідомленням про помилку. Щоб досягти бажаного результату, вам слід створити прив'язаний до часу знімок. Якщо маєте справу із логічним томом, скористайтеся знімком LVM2. Якщо файлову систему розташовано у чомусь подібному до файла btrfs/ZFS, скористайтеся знімком btrfs/ZFS, а потім запустіть fsck для перевірки знімка. На практиці, для виконання цього завдання libguestfs не потрібна — просто скористайтеся /sbin/fsck безпосередньо. Створення прив'язаних до часу знімків пристроїв і файлів основної системи не виконується засобами libguestfs, хоча libguestfs може працювати із такими знімками, коли їх буде створено.

Чим відрізняються 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 не можна вводити команди оболонки повністю з усіма параметрами з мінусами (але це можна робити у virt-rescue(1)). guestfish(1) — програма, яка надає структурований доступ до програмного інтерфейсу guestfs(3). Також це непогана інтерактивна командна оболонка, але основним її призначенням є структурований доступ до скриптів командної оболонки. Її можна вважати скоріше прив'язкою до мов програмування, зокрема Python, та інших прив'язок, але для оболонки. Ключовим фактором диференціювання guestfish (і програмного інтерфейсу libguestfs загалом) є можливість автоматизації змін. virt-rescue(1) — гнучкий спосіб завантажити базову систему libguestfs і внести довільні зміни до вашої віртуальної машини. Його не структуровано, ви не можете автоматизувати його використання, але для швидкого ситуаційного внесення виправлень до ваших гостьових систем ця програма може бути дуже зручною. Але у libguestfs також є і «чорний вхід» до базової системи, який надає вам змогу надсилати довільні команди до командної оболонки. Він не є настільки гнучким як virt-rescue, оскільки ви не можете взаємодіяти із командами оболонки. Втім, ось він:

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

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

Для чого призначено "guestfish -i"?

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

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

Усі ці питання пов'язано на базовому рівні, хоча це спочатку здається неочевидним. На рівні програмного інтерфейсу 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). Перш за все, програмний інтерфейс бачить образ диска на рівні «купи файлових систем». Але у програмному інтерфейсі також передбачено способи інспектування образу диска для визначення, чи міститься на ньому операційна система, та того, як монтуються диски, коли завантажується операційна система: "ІНСПЕКЦІЯ" in guestfs(3). Користувачі очікують працездатності деяких інструментів (зокрема virt-cat(1)) для шляхів у ВМ:

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

Як virt-cat дізнається про те, що /var є окремим розділом? Справа полягає у тому, що virt-cat виконує інспекцію образу диска і використовує отримані дані для правильної трансляції шляху. Деякі з інструментів (зокрема virt-cat(1), virt-edit(1), virt-ls(1)) використовують інспекцію для визначення шляхів у віртуальній машині. Інші інструменти, зокрема virt-df(1) і virt-filesystems(1), працюють лише на рівні необробленої «великої купи файлових систем» програмного інтерфейсу libguestfs і не використовують інспекцію. guestfish(1) є цікавим проміжним варіантом. Якщо ви використовуєте параметри командного рядка -a та -m, вам доведеться повідомити guestfish точно, як додавати образи дисків і куди слід монтувати розділи. Це рівень програмного інтерфейсу без додаткової обробки. Якщо ви використовуєте параметр -i, libguestfs виконує інспектування та монтує файлові системи. Повідомлення про помилку "у цьому образі операційної системи не знайдено кореневого пристрою" пов'язано із цим. Воно означає, що під час інспекції не удалося виявити операційну систему на вказаному образі диска. Ви можете побачити таке повідомлення від програм, подібних до virt-cat, якщо ви скористаєтеся ними для дослідження образу диска, який не є образом диска віртуальної машини.

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

У бібліотеці існує декілька функцій, які використовуються для діагностування та внутрішньої обробки даних. Ці функції не є частиною стабільного програмного інтерфейсу. Функції "debug*" (або "guestfs_debug*"), головним чином "guestfs_debug" in guestfs(3) та декілька інших, використовуються для діагностики помилок у libguestfs. Хоча вони і не є частиною стабільного програмного інтерфейсу, а отже, їх може бути будь-коли вилучено, їх можна використовувати у програмах, доки певні можливості буде додано до libguestfs. Функції "internal-*" (або "guestfs_internal_*") призначено для використання лише у libguestfs. Немає сенсу викликати ці функції з програм, їх також не слід використовувати у програмах. Зрідка, використання цих функцій може призвести до небажаних наслідків, окрім того, вони не є частиною документованого стабільного програмного інтерфейсу.

РОЗРОБНИКАМ

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

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

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

Значні нові можливості, розробку яких ви маєте намір здійснити, має бути спочатку обговорено у списку листування (https://www.redhat.com/mailman/listinfo/libguestfs). Так ви можете уникнути прикростей і заощадити час, якщо раптом виявиться, що інші розробники вважають можливість такою, яка не відповідає меті проєкту libguestfs. Якщо ви хочете запропонувати корисну можливість, але не хочете писати код для її реалізації, ви можете створити повідомлення про ваду (див. "ОТРИМАННЯ ДОВІДКОВОЇ ІНФОРМАЦІЇ ТА ЗВІТУВАННЯ ПРО ВАДИ") із додаванням "RFE: " на початку рядка резюме (Summary).

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

Доступ на запис до сховища на github має близько 5 осіб. Латки має бути спочатку надіслано до списку листування і схвалено учасниками. Правила схвалення та запису латок окреслено нижче: https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html

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

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

ІНШІ ПИТАННЯ

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

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

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

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

i.

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

ii.

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

Єдиним підтримуваним рішенням є перезапуск усієї базової системи libguestfs кожного разу, коли вам потрібно переглянути зміни у образі диска. На рівні програмного інтерфейсу це відповідає виклику "guestfs_shutdown" з наступним викликом "guestfs_launch", що є доволі вартісною операцією (див. також guestfs-performance(3)). Існує декілька «брудних» прийомів, якими ви можете скористатися, якщо перезапуск базової системи є дійсно дуже вартісною справою:

•

Виклик "guestfs_drop_caches (g, 3)". Такий виклик призводить до того, що усі кешовані дані ядра базової системи libguestfs (2) буде відкинуто, отже йому доведеться користуватися образом диска. Втім, лише цього недостатньо, оскільки qemu також кешує деякі дані. Вам також доведеться латати libguestfs, щоб увімкнути режим "cache=none". Див. https://rwmj.wordpress.com/2013/09/02/new-in-libguestfs-allow-cache-mode-to-be-selected/

•

Замість цього, вам варто скористатися інструментами, подібними до virt-bmap.

•

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

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

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

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

АВТОРИ

Richard W.M. Jones ("rjones at redhat dot com")

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

© Red Hat Inc., 2012–2020

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.