=head1 НАЗВА

guestfs-internals — архітектура і внутрішня будова libguestfs

=head1 ОПИС

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

=head1 АРХІТЕКТУРА

На внутрішньому рівні libguestfs реалізовано шляхом запуску базової системи
(спеціального типу малої віртуальної машини) за допомогою L<qemu(1)>. Qemu
запускається як дочірній процес основної програми.

 ┌───────────────────┐
 │ main program      │
 │                   │
 │                   │           дочірній процес / базова система
 │                   │          ┌──────────────────────────┐
 │                   │          │ qemu                     │
 ├───────────────────┤   RPC    │      ┌─────────────────┐ │
 │ libguestfs  ◀╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶ guestfsd        │ │
 │                   │          │      ├─────────────────┤ │
 └───────────────────┘          │      │   ядро Linux    │ │
                                │      └────────┬────────┘ │
                                └───────────────│──────────┘
                                                │
                                                │ virtio-scsi
                                         ┌──────┴──────┐
                                         │  Пристрій або │
                                         │  образ диска│
                                         └─────────────┘

Бібліотека, пов'язана із основною програмою, створює дочірній процес і,
отже, базову систему у функції L<guestfs(3)/guestfs_launch>.

Всередині базової системи знаходиться ядро Linux і повний комплект засобів
керування простором користувача (зокрема програми для керування LVM та
ext2), а також невеличка фонова служба, яка називається
L</guestfsd>. Бібліотека обмінюється даними із L</guestfsd> за допомогою
віддаленого виклику процедур (RPC). Між викликами програмного інтерфейсу
libguestfs та викликами RPC фонової служби існує майже дзеркальна
подібність. Нарешті, образи дисків долучено до процесу qemu, який транслює
доступ до пристроїв за допомогою ядра Linux базової системи у доступ до
образів для основної системи.

Поширеною помилкою є вважати, що базова система «є» віртуальна машина. Хоча
образ диска, з яким з'єднується ваша система, може використовуватися якоюсь
із систем керування віртуальними машинами, libguestfs не використовує і не
бере до уваги цю можливість. (Але вам слід брати це до уваги, якщо оновлення
даних на образі диска одночасно виконується процесом qemu libguestfs та
вашою віртуальною машиною, оскільки це, зазвичай, призводить до значних
ушкоджень даних на диску).

=head1 СКІНЧЕННИЙ АВТОМАТ

libguestfs використовує скінченний автомат для моделювання дочірнього
процесу:

                         |
          guestfs_create / guestfs_create_flags
                         |
                         |
                     ____V___________
                    /          \
                    |  НАЛАШТУВАННЯ  |
                    \_________________/
                       ^   ^  \
                       |    \  \ guestfs_launch
                       |    _\__V___
                       |   /           \
                       |   | ЗАПУСК |
                       |   \________/
                       |       /
                       |  guestfs_launch
                       |     /
                     __|____V_____
                    /        \
                    | ГОТОВНІСТЬ  |
                    \_____________/

Нормальними станами є (1) CONFIG (коли створено дескриптор, але немає
дочірнього процесу), (2) LAUNCHING (коли завантажується дочірній процес),
(3) READY — означає, що базова система завантажилася, можна виконувати за її
допомогою дії, працездатністю системи опікується дочірній процес.

Роботу гостьової системи можна завершити за допомогою
L<guestfs(3)/guestfs_kill_subprocess>, гостьова система також може будь-коли
асинхронно припинити роботу (наприклад, через якусь внутрішню помилку). Це
спричиняє повернення до стану CONFIG.

Команди налаштовування для qemu, зокрема L<guestfs(3)/guestfs_set_path>,
можна віддавати лише у стані CONFIG.

Програмний інтерфейс пропонує один виклик, який проходить від CONFIG крізь
LAUNCHING до READY.  L<guestfs(3)/guestfs_launch> блокує систему, аж доки
дочірній процес не повідомить про стан READY для отримання команд (або не
надійде повідомлення про помилку чи перевищення часу
очікування). L<guestfs(3)/guestfs_launch> на внутрішньому рівні переводить
стан з CONFIG у LAUNCHING протягом часу своєї роботи.

Команди програмного інтерфейсу, зокрема L<guestfs(3)/guestfs_mount>, можуть
надсилатися, лише у стані READY. Ці виклики програмного інтерфейсу
блокуються до завершення виконання попередньої команди. Версій без
блокування не передбачено. Крім того, не передбачено способів надсилання
декількох команд одному дескриптору одночасно.

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

=head1 ВНУТРІШНІ ПРИНЦИПИ РОБОТИ

=head2 ПРОЦЕДУРА ЗАВАНТАЖЕННЯ БАЗОВОЇ СИСТЕМИ

Цей процес змінювався із розвитком бібліотеки і продовжує
змінюватися. Наведений тут опис відповідає поточній версії libguestfs. Його
надано із інформаційною метою.

Для виконання описаних нижче кроків увімкніть діагностику у libguestfs
(встановіть значення змінної середовища C<LIBGUESTFS_DEBUG=1>).

=over 4

=item Створення базової системи

C<supermin --build> викликається для створення ядра, невеличкого initrd та
базової системи.

Кеш базової системи зберігається у F</var/tmp/.guestfs-E<lt>UIDE<gt>> (або
іншому каталозі, якщо встановлено значення змінної середовища
C<LIBGUESTFS_CACHEDIR> або C<TMPDIR>).

Щоб ознайомитися із повним описом створення базової системи та особливостями
кешування, прочитайте сторінку підручника щодо L<supermin(1)>.

=item Запуск qemu і завантаження ядра

qemu викликається для завантаження ядра.

=item Запуск initrd

C<supermin --build> збирає невеличкий initrd. initrd не є базовою
системою. Метою роботи initrd є завантаження достатньої кількості модулів
ядра для того, щоб можна було змонтувати і запустити саму базову систему.

initrd є архівом cpio із назвою
F</var/tmp/.guestfs-E<lt>UIDE<gt>/appliance.d/initrd>.

Після запуску initrd ви побачите повідомлення щодо завантаження модулів
ядра, подібні до таких:

 supermin: ext2 mini initrd starting up
 supermin: mounting /sys
 supermin: internal insmod libcrc32c.ko
 supermin: internal insmod crc32c-intel.ko

=item Пошук і монтування пристрою базової системи

Базовою системою є розріджений файл, що містить файлову систему ext2 зі
звичайною (але зменшеною у розмірах) операційною системою Linux. За
звичайних умов, цей файл називається
F</var/tmp/.guestfs-E<lt>UIDE<gt>/appliance.d/root>.

Звичайні диски, які досліджуються за допомогою libguestfs, є першими
пристроями, які «бачить» qemu (eg. as F</dev/vda>).

Останнім диском, який додано до qemu, є сама базова система (наприклад,
F</dev/vdb>, якщо був лише один звичайний диск).

Таким чином, останнім завданням initrd є визначення розташування диска
базової системи, його монтування та перемикання кореневої файлової системи
на базову систему і запуск F</init> з базової системи.

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

 supermin: picked /sys/block/vdb/dev as root device
 supermin: creating /dev/root as block special 252:16
 supermin: mounting new root on /root
 supermin: chroot
 Starting /init script ...

Зауважте, що повідомлення C<Starting /init script ...> означає, що запущено
скрипт ініціалізації (init) базової системи.

=item Ініціалізація базової системи

Далі, базова система ініціалізується. Ця процедура включає запуск певних
процесів, зокрема C<udev>, можливе виведення певної діагностичної інформації
і, нарешті, запуск фонової служби (C<guestfsd>).

=item Фонова служба

На останньому етапі фонова служба (C<guestfsd>) працює у базовій
системі. Якщо запуск служби виконано вдало, ви побачите таке повідомлення:

 verbose daemon enabled

Фонова служба очікує виявити іменований послідовний порт virtio, відкритий
qemu і з'єднаний іншим боком із бібліотекою.

Фонова служба встановлює з'єднання з цим портом (а отже і з бібліотекою) і
надсилає чотирибайтове повідомлення C<GUESTFS_LAUNCH_FLAG>, яке ініціює
протокол обміну даними (див. нижче).

=back

=head2 ПРОТОКОЛ ОБМІНУ ДАНИМИ

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

Протокол, який використовується для обміну даними між бібліотекою та фоновою
службою, запущеною всередині віртуальної машини qemu, простим механізмом
RPC, побудованим на основі XDR (RFC 1014, RFC 1832, RFC 4506).

Докладний формат структур описано у файлі
F<common/protocol/guestfs_protocol.x> (зауваження: цей файл створюється
автоматично під час збирання бібліотеки).

Існує два широких класи: звичайні функції, які не мають параметрів C<FileIn>
і C<FileOut> і які керуються дуже простим повідомленнями запитів і
відповідей, і функції, які мають параметри C<FileIn> або C<FileOut> і які
використовують такі самі повідомлення запитів і відповідей, але за
повідомленням може слідувати файл, який надсилається у певному фрагментному
кодуванні.

=head3 ЗВИЧАЙНІ ФУНКЦІЇ (БЕЗ ПАРАМЕТРІВ FILEIN/FILEOUT)

Повідомлення запиту для звичайних функцій:

 загальна довжина (заголовок + аргументи,
      але без включення самого слова length)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_args (у кодуванні XDR)

Поле загальної довжини надає змогу фоновій службі отримувати фіксований
буфер у пам'яті, до якого вона записуватиме решту повідомлення. Отже,
загальну довжину обмежено до C<GUESTFS_MESSAGE_MAX> байтів (у поточній
версії, 4 МБ), що означає, що ефективний розмір будь-якого запису обмежено
цим обсягом пам'яті.

Зауважте, що багато функцій не приймають жодних аргументів. Для таких
функцій C<guestfs_I<щось>_args> взагалі не вказують.

У заголовку міститься номер процедури (C<guestfs_proc>), за допомогою якого
функція-отримувач визначає тип структури аргументів, який слід очікувати,
або дізнається про те, що аргументів не буде.

Для функцій, які приймають необов'язкові аргументи, додаткові аргументи
кодуються у структуру C<guestfs_I<foo>_args> у той самий спосіб, що і
звичайні аргументи. Бітова маска у заголовку позначає, які додаткові
аргументи мають значення. Виконується також перевірка бітової маски на вміст
бітів, про які не знає фонова служба (наприклад, якщо у новішій версії
бібліотеки додано додаткові аргументи). Виклики із такими бітами
відкидаються.

Повідомлення відповіді для звичайних функцій:

 загальна довжина (заголовок + повернуте значення,
      але без включення самого слова length)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_ret (у кодуванні XDR)

Як і вище, структуру C<guestfs_I<щось>_ret> може бути повністю пропущено,
якщо функція формально не повертає значень.

Як і вище, значення загальної довжини відповіді обмежується значенням
C<GUESTFS_MESSAGE_MAX>.

Якщо станеться помилка, у заголовку буде встановлено прапорець, а саме
повідомлення відповіді буде дещо змінено:

 загальна довжина (заголовок + помилка,
      але без включення самого слова length)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_message_error (у кодуванні XDR)

Структура C<guestfs_message_error> містить повідомлення про помилку у
форматі рядка.

=head3 ФУНКЦІЇ З ПАРАМЕТРАМИ FILEIN

Параметр C<FileIn> позначає, що ми передаємо файл I<до> гостьової
системи. Надсилається звичайне повідомлення запиту (див. вище). Втім, за ним
слідує послідовність фрагментів файла.

 загальна довжина (заголовок + аргументи,
      але без включення самого слова length,
      і без включення фрагментів)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_args (у кодуванні XDR)
 послідовність фрагментів для параметра 0 FileIn
 послідовність фрагментів для параметра 1 FileIn тощо
«Послідовність фрагментів» це:

 довжина фрагмента (без самого слова length)
 struct guestfs_chunk (у кодуванні XDR)
довжина фрагмента
 struct guestfs_chunk (у кодуванні XDR)
   ...
довжина фрагмента
 struct guestfs_chunk (із data.data_len == 0)

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

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

Передавання даних може бути скасовано як бібліотекою (відправником), I<так
і> фоновою службою (отримувачем). Бібліотека скасовує передавання
надсиланням фрагмента із спеціальним прапорцем, який позначає
скасовування. Коли фонова служба отримує такий фрагмент, вона скасовує увесь
RPC, I<не> надсилає жодної відповіді і повертається до читання наступного
запиту.

Фонова служба також може скасувати передавання даних. Зробити це вона можна
записуванням до сокета спеціального слова C<GUESTFS_CANCEL_FLAG>. Бібліотека
очікує на цьому сокеті на дані під час передавання. Якщо буде отримано
спеціальне слово, бібліотека скасує передавання (надішле фрагмент
скасовування). Спеціальне слово вибрано так, щоб навіть якщо скасовування
станеться безпосередньо наприкінці передавання (після того, як бібліотека
завершить запис і розпочне очікувати на відповідь), «неоднозначний»
прапорець скасовування не буде переплутано із повідомленням відповіді.

Цей протокол уможливлює передавання файлів довільного розміру (без обмеження
у 32 біти), а також файлів, розмір яких невідомий наперед (наприклад з
каналів обробки даних або сокетів). Втім, фрагменти є доволі малими
(C<GUESTFS_MAX_CHUNK_SIZE>), отже, ні бібліотеці, ні фоновій службі не
потрібно для передавання багато оперативної пам'яті.

=head3 FФУНКЦІЇ З ПАРАМЕТРАМИ FILEOUT

Протокол для параметрів FileOut є тим самим, що і для параметрів FileIn, але
у ньому фонова служба і бібліотека міняються місцями.

 загальна довжина (заголовок + повернуте значення,
      але без включення самого слова length,
      і без включення фрагментів)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_ret (у кодуванні XDR)
 послідовність фрагментів для параметра 0 FileOut
 послідовність фрагментів для параметра 1 FileOut тощо
=head3 ПОЧАТКОВЕ ПОВІДОМЛЕННЯ

Під час запуску фонова служба надсилає початкове слово
(C<GUESTFS_LAUNCH_FLAG>), яке означає, що гостьова система і фонова служба
працюють. Саме на це очікує L<guestfs(3)/guestfs_launch>.

=head3 ПОВІДОМЛЕННЯ ЩОДО ПОСТУПУ

Фонова служба може будь-коли надсилати сповіщення щодо поступу. Ці
сповіщення відрізняються від інших тим, що звичайне слово length замінюється
на C<GUESTFS_PROGRESS_FLAG>, а за ним слідує повідомлення щодо поступу
фіксованого розміру.

Бібліотека перетворює їх на зворотні виклики щодо поступу
(див. L<guestfs(3)/GUESTFS_EVENT_PROGRESS>), якщо зареєстровано зворотний
виклик; або відкидає їх, якщо виклик не зареєстровано.

Фонова служба автоматично обмежує частоту повідомлень щодо поступу, які вона
надсилає (див. C<daemon/proto.c:notify_progress>). Не усі виклики створюють
повідомлення щодо поступу.

=head2 ФІКСОВАНА БАЗОВА СИСТЕМА

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

Зазвичай, базова система supermin зберігається саме у цьому каталозі
(див. L<supermin(1)/БАЗОВА СИСТЕМА SUPERMIN>).  libguestfs перебудовує її у
повноцінну базову систему за допомогою команди C<supermin --build>.

Втім, також можна скористатися простішою «фіксованою базовою
системою». libguestfs визначає таку систему, виконуючи пошук каталогу, який
містить такі файли:

=over 4

=item * F<kernel>

=item * F<initrd>

=item * F<root>

=item * F<README.fixed> (зауважте, що він також B<має> бути)

=back

Якщо буде виявлено фіксовану базову систему, libguestfs не використовуватиме
supermin взагалі і запустить віртуальну машину (за допомогою qemu або
поточного модуля обробки, див. L<guestfs(3)/МОДУЛЬ>) із ядром, initrd та
кореневим диском із фіксованої базової системи.

Отже, фіксованою базовою системою можна скористатися, якщо для платформи або
дистрибутива Linux не передбачено підтримки supermin. Ви збираєте базову
систему на платформі, де таку підтримку передбачено, за допомогою
L<libguestfs-make-fixed-appliance(1)>, копіюєте її і використовуєте для
запуску libguestfs.

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

L<guestfs(3)>, L<guestfs-hacking(1)>, L<guestfs-examples(3)>,
L<libguestfs-test-tool(1)>, L<libguestfs-make-fixed-appliance(1)>,
L<http://libguestfs.org/>.

=head1 АВТОРИ

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

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

Copyright (C) 2009-2020 Red Hat Inc.