НАЗВА
guestfs-internals — архітектура і внутрішня будова libguestfs
ОПИС
Цю сторінку підручника призначено для тих, хто хоче зрозуміти, як працює libguestfs на внутрішньому рівні. Це опис лише того, як libguestfs працює у поточній версії. Принципи роботи може бути змінено у майбутніх версіях.
АРХІТЕКТУРА
На внутрішньому рівні libguestfs реалізовано шляхом запуску базової системи (спеціального типу малої віртуальної машини) за допомогою qemu(1). Qemu запускається як дочірній процес основної програми.
┌───────────────────┐
│ main program │
│ │
│ │
дочірній
процес /
базова
система
│ │
┌──────────────────────────┐
│ │ │ qemu │
├───────────────────┤
RPC │
┌─────────────────┐
│
│ libguestfs
◀╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍▶
guestfsd │ │
│ │ │
├─────────────────┤
│
└───────────────────┘
│ │ ядро Linux │
│
│
└────────┬────────┘
│
└───────────────│──────────┘
│
│ virtio-scsi
┌──────┴──────┐
│
Пристрій
або │
│ образ
диска│
└─────────────┘
Бібліотека, пов’язана із основною програмою, створює дочірній процес і, отже, базову систему у функції "guestfs_launch" in guestfs(3).
Всередині базової системи знаходиться ядро Linux і повний комплект засобів керування простором користувача (зокрема програми для керування LVM та ext2), а також невеличка фонова служба, яка називається "guestfsd". Бібліотека обмінюється даними із "guestfsd" за допомогою віддаленого виклику процедур (RPC). Між викликами програмного інтерфейсу libguestfs та викликами RPC фонової служби існує майже дзеркальна подібність. Нарешті, образи дисків долучено до процесу qemu, який транслює доступ до пристроїв за допомогою ядра Linux базової системи у доступ до образів для основної системи.
Поширеною помилкою є вважати, що базова система «є» віртуальна машина. Хоча образ диска, з яким з’єднується ваша система, може використовуватися якоюсь із систем керування віртуальними машинами, libguestfs не використовує і не бере до уваги цю можливість. (Але вам слід брати це до уваги, якщо оновлення даних на образі диска одночасно виконується процесом qemu libguestfs та вашою віртуальною машиною, оскільки це, зазвичай, призводить до значних ушкоджень даних на диску).
СКІНЧЕННИЙ АВТОМАТ
libguestfs використовує скінченний автомат для моделювання дочірнього процесу:
|
guestfs_create / guestfs_create_flags
|
|
____V___________
/ \
|
НАЛАШТУВАННЯ
|
\_________________/
^ ^ \
| \ \ guestfs_launch
| _\__V___
| / \
| | ЗАПУСК |
| \________/
| /
| guestfs_launch
| /
__|____V_____
/ \
|
ГОТОВНІСТЬ
|
\_____________/
Нормальними станами є (1) CONFIG (коли створено дескриптор, але немає дочірнього процесу), (2) LAUNCHING (коли завантажується дочірній процес), (3) READY — означає, що базова система завантажилася, можна виконувати за її допомогою дії, працездатністю системи опікується дочірній процес.
Роботу гостьової системи можна завершити за допомогою "guestfs_kill_subprocess" in guestfs(3), гостьова система також може будь-коли асинхронно припинити роботу (наприклад, через якусь внутрішню помилку). Це спричиняє повернення до стану CONFIG.
Команди налаштовування для qemu, зокрема "guestfs_set_path" in guestfs(3), можна віддавати лише у стані CONFIG.
Програмний інтерфейс пропонує один виклик, який проходить від CONFIG крізь LAUNCHING до READY. "guestfs_launch" in guestfs(3) блокує систему, аж доки дочірній процес не повідомить про стан READY для отримання команд (або не надійде повідомлення про помилку чи перевищення часу очікування). "guestfs_launch" in guestfs(3) на внутрішньому рівні переводить стан з CONFIG у LAUNCHING протягом часу своєї роботи.
Команди програмного інтерфейсу, зокрема "guestfs_mount" in guestfs(3), можуть надсилатися, лише у стані READY. Ці виклики програмного інтерфейсу блокуються до завершення виконання попередньої команди. Версій без блокування не передбачено. Крім того, не передбачено способів надсилання декількох команд одному дескриптору одночасно.
Нарешті, дочірній процес надсилає асинхронні повідомлення, зокрема повідомлення журналу ядра, до основної програми. Ви можете зареєструвати зворотний виклик для отримання цих повідомлень.
ВНУТРІШНІ ПРИНЦИПИ РОБОТИ
ПРОЦЕДУРА
ЗАВАНТАЖЕННЯ
БАЗОВОЇ
СИСТЕМИ
Цей
процес
змінювався
із
розвитком
бібліотеки
і
продовжує
змінюватися.
Наведений
тут опис
відповідає
поточній
версії libguestfs.
Його
надано із
інформаційною
метою.
Для
виконання
описаних
нижче
кроків
увімкніть
діагностику
у libguestfs
(встановіть
значення
змінної
середовища
"LIBGUESTFS_DEBUG=1").
Створення
базової
системи
"supermin --build" викликається для створення ядра, невеличкого initrd та базової системи.
Кеш базової системи зберігається у /var/tmp/.guestfs-<UID> (або іншому каталозі, якщо встановлено значення змінної середовища "LIBGUESTFS_CACHEDIR" або "TMPDIR").
Щоб ознайомитися із повним описом створення базової системи та особливостями кешування, прочитайте сторінку підручника щодо supermin(1).
Запуск qemu і завантаження ядра
qemu викликається для завантаження ядра.
Запуск initrd
"supermin --build" збирає невеличкий initrd. initrd не є базовою системою. Метою роботи initrd є завантаження достатньої кількості модулів ядра для того, щоб можна було змонтувати і запустити саму базову систему.
initrd є архівом cpio із назвою /var/tmp/.guestfs-<UID>/appliance.d/initrd.
Після запуску initrd ви побачите повідомлення щодо завантаження модулів ядра, подібні до таких:
supermin: ext2
mini initrd starting up
supermin: mounting /sys
supermin: internal insmod libcrc32c.ko
supermin: internal insmod crc32c-intel.ko
Пошук і монтування пристрою базової системи
Базовою системою є розріджений файл, що містить файлову систему ext2 зі звичайною (але зменшеною у розмірах) операційною системою Linux. За звичайних умов, цей файл називається /var/tmp/.guestfs-<UID>/appliance.d/root.
Звичайні диски, які досліджуються за допомогою libguestfs, є першими пристроями, які «бачить» qemu (eg. as /dev/vda).
Останнім диском, який додано до qemu, є сама базова система (наприклад, /dev/vdb, якщо був лише один звичайний диск).
Таким чином, останнім завданням initrd є визначення розташування диска базової системи, його монтування та перемикання кореневої файлової системи на базову систему і запуск /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 ...
Зауважте, що повідомлення "Starting /init script ..." означає, що запущено скрипт ініціалізації (init) базової системи.
Ініціалізація базової системи
Далі, базова система ініціалізується. Ця процедура включає запуск певних процесів, зокрема "udev", можливе виведення певної діагностичної інформації і, нарешті, запуск фонової служби ("guestfsd").
Фонова служба
На останньому етапі фонова служба ("guestfsd") працює у базовій системі. Якщо запуск служби виконано вдало, ви побачите таке повідомлення:
verbose daemon enabled
Фонова служба очікує виявити іменований послідовний порт virtio, відкритий qemu і з’єднаний іншим боком із бібліотекою.
Фонова служба встановлює з’єднання з цим портом (а отже і з бібліотекою) і надсилає чотирибайтове повідомлення "GUESTFS_LAUNCH_FLAG", яке ініціює протокол обміну даними (див. нижче).
ПРОТОКОЛ
ОБМІНУ
ДАНИМИ
Не
покладайтеся
на
викладені
у цьому
розділі
подробиці
протоколу
безпосередньо.
Документація
цього
розділу
стосується
поточних
принципів
його
роботи,
але вони
можуть
змінитися
у
майбутніх
версіях.
Протокол, який використовується для обміну даними між бібліотекою та фоновою службою, запущеною всередині віртуальної машини qemu, простим механізмом RPC, побудованим на основі XDR (RFC 1014, RFC 1832, RFC 4506).
Докладний формат структур описано у файлі common/protocol/guestfs_protocol.x (зауваження: цей файл створюється автоматично під час збирання бібліотеки).
Існує два широких класи: звичайні функції, які не мають параметрів "FileIn" і "FileOut" і які керуються дуже простим повідомленнями запитів і відповідей, і функції, які мають параметри "FileIn" або "FileOut" і які використовують такі самі повідомлення запитів і відповідей, але за повідомленням може слідувати файл, який надсилається у певному фрагментному кодуванні.
ЗВИЧАЙНІ ФУНКЦІЇ (БЕЗ ПАРАМЕТРІВ FILEIN/FILEOUT)
Повідомлення запиту для звичайних функцій:
загальна
довжина
(заголовок
+
аргументи,
але без
включення
самого
слова length)
struct guestfs_message_header (у
кодуванні
XDR)
struct guestfs_<щось>_args
(у
кодуванні
XDR)
Поле загальної довжини надає змогу фоновій службі отримувати фіксований буфер у пам’яті, до якого вона записуватиме решту повідомлення. Отже, загальну довжину обмежено до "GUESTFS_MESSAGE_MAX" байтів (у поточній версії, 4 МБ), що означає, що ефективний розмір будь-якого запису обмежено цим обсягом пам’яті.
Зауважте, що багато функцій не приймають жодних аргументів. Для таких функцій "guestfs_щось_args" взагалі не вказують.
У заголовку міститься номер процедури ("guestfs_proc"), за допомогою якого функція-отримувач визначає тип структури аргументів, який слід очікувати, або дізнається про те, що аргументів не буде.
Для функцій, які приймають необов’язкові аргументи, додаткові аргументи кодуються у структуру "guestfs_foo_args" у той самий спосіб, що і звичайні аргументи. Бітова маска у заголовку позначає, які додаткові аргументи мають значення. Виконується також перевірка бітової маски на вміст бітів, про які не знає фонова служба (наприклад, якщо у новішій версії бібліотеки додано додаткові аргументи). Виклики із такими бітами відкидаються.
Повідомлення відповіді для звичайних функцій:
загальна
довжина
(заголовок
+
повернуте
значення,
але без
включення
самого
слова length)
struct guestfs_message_header (у
кодуванні
XDR)
struct guestfs_<щось>_ret
(у
кодуванні
XDR)
Як і вище, структуру "guestfs_щось_ret" може бути повністю пропущено, якщо функція формально не повертає значень.
Як і вище, значення загальної довжини відповіді обмежується значенням "GUESTFS_MESSAGE_MAX".
Якщо станеться помилка, у заголовку буде встановлено прапорець, а саме повідомлення відповіді буде дещо змінено:
загальна
довжина
(заголовок
+ помилка,
але без
включення
самого
слова length)
struct guestfs_message_header (у
кодуванні
XDR)
struct
guestfs_<щось>_message_error
(у
кодуванні
XDR)
Структура "guestfs_message_error" містить повідомлення про помилку у форматі рядка.
ФУНКЦІЇ З ПАРАМЕТРАМИ FILEIN
Параметр "FileIn" позначає, що ми передаємо файл до гостьової системи. Надсилається звичайне повідомлення запиту (див. вище). Втім, за ним слідує послідовність фрагментів файла.
загальна
довжина
(заголовок
+
аргументи,
але без
включення
самого
слова 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)
Значення "data_len" останнього фрагмента дорівнює нулю. Крім того, у останньому фрагментів встановлено прапорець, який позначає успішне завершення або передчасне переривання.
На момент написання цього підручника не існувало жодної функції, яка б приймала більше одного параметра FileIn. Втім, теоретично, підтримку багатьох таких параметрів передбачено. Адже передбачено можливість надсилати послідовність фрагментів для кожного параметра FileIn один фрагмент за одним (зліва праворуч).
Передавання даних може бути скасовано як бібліотекою (відправником), так і фоновою службою (отримувачем). Бібліотека скасовує передавання надсиланням фрагмента із спеціальним прапорцем, який позначає скасовування. Коли фонова служба отримує такий фрагмент, вона скасовує увесь RPC, не надсилає жодної відповіді і повертається до читання наступного запиту.
Фонова служба також може скасувати передавання даних. Зробити це вона можна записуванням до сокета спеціального слова "GUESTFS_CANCEL_FLAG". Бібліотека очікує на цьому сокеті на дані під час передавання. Якщо буде отримано спеціальне слово, бібліотека скасує передавання (надішле фрагмент скасовування). Спеціальне слово вибрано так, щоб навіть якщо скасовування станеться безпосередньо наприкінці передавання (після того, як бібліотека завершить запис і розпочне очікувати на відповідь), «неоднозначний» прапорець скасовування не буде переплутано із повідомленням відповіді.
Цей протокол уможливлює передавання файлів довільного розміру (без обмеження у 32 біти), а також файлів, розмір яких невідомий наперед (наприклад з каналів обробки даних або сокетів). Втім, фрагменти є доволі малими ("GUESTFS_MAX_CHUNK_SIZE"), отже, ні бібліотеці, ні фоновій службі не потрібно для передавання багато оперативної пам’яті.
FФУНКЦІЇ З ПАРАМЕТРАМИ FILEOUT
Протокол для параметрів FileOut є тим самим, що і для параметрів FileIn, але у ньому фонова служба і бібліотека міняються місцями.
загальна
довжина
(заголовок
+
повернуте
значення,
але без
включення
самого
слова length,
і без
включення
фрагментів)
struct guestfs_message_header (у
кодуванні
XDR)
struct guestfs_<щось>_ret
(у
кодуванні
XDR)
послідовність
фрагментів
для
параметра
0 FileOut
послідовність
фрагментів
для
параметра
1 FileOut тощо
=head3
ПОЧАТКОВЕ
ПОВІДОМЛЕННЯ
Під час запуску фонова служба надсилає початкове слово ("GUESTFS_LAUNCH_FLAG"), яке означає, що гостьова система і фонова служба працюють. Саме на це очікує "guestfs_launch" in guestfs(3).
ПОВІДОМЛЕННЯ ЩОДО ПОСТУПУ
Фонова служба може будь-коли надсилати сповіщення щодо поступу. Ці сповіщення відрізняються від інших тим, що звичайне слово length замінюється на "GUESTFS_PROGRESS_FLAG", а за ним слідує повідомлення щодо поступу фіксованого розміру.
Бібліотека перетворює їх на зворотні виклики щодо поступу (див. "GUESTFS_EVENT_PROGRESS" in guestfs(3)), якщо зареєстровано зворотний виклик; або відкидає їх, якщо виклик не зареєстровано.
Фонова служба автоматично обмежує частоту повідомлень щодо поступу, які вона надсилає (див. "daemon/proto.c:notify_progress"). Не усі виклики створюють повідомлення щодо поступу.
ФІКСОВАНА
БАЗОВА
СИСТЕМА
Під час
роботи libguestfs
(або
інструментів
libguestfs)
виконується
пошук
базової
системи у
відповідному
каталозі.
Типовий
шлях до
цього
каталогу
вбудовано
до libguestfs, його
також
можна
змінити
за
допомогою
змінної
середовища
"LIBGUESTFS_PATH".
Зазвичай, базова система supermin зберігається саме у цьому каталозі (див. "БАЗОВА СИСТЕМА SUPERMIN" in supermin(1)). libguestfs перебудовує її у повноцінну базову систему за допомогою команди "supermin --build".
Втім, також можна скористатися простішою «фіксованою базовою системою». libguestfs визначає таку систему, виконуючи пошук каталогу, який містить такі файли:
|
• |
kernel |
|||
|
• |
initrd |
|||
|
• |
root |
|||
|
• |
README.fixed (зауважте, що він також має бути) |
Якщо буде виявлено фіксовану базову систему, libguestfs не використовуватиме supermin взагалі і запустить віртуальну машину (за допомогою qemu або поточного модуля обробки, див. "МОДУЛЬ" in guestfs(3)) із ядром, initrd та кореневим диском із фіксованої базової системи.
Отже, фіксованою базовою системою можна скористатися, якщо для платформи або дистрибутива Linux не передбачено підтримки supermin. Ви збираєте базову систему на платформі, де таку підтримку передбачено, за допомогою libguestfs-make-fixed-appliance(1), копіюєте її і використовуєте для запуску libguestfs.
ТАКОЖ ПЕРЕГЛЯНЬТЕ
guestfs(3), guestfs-hacking(1), guestfs-examples(3), libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
АВТОРИ
Richard W.M. Jones ("rjones at redhat dot com")
АВТОРСЬКІ ПРАВА
Copyright (C) 2009-2023 Red Hat Inc.
LICENSE
BUGS
To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
When reporting a bug, please supply:
|
• |
The version of libguestfs. | ||
|
• |
Where you got libguestfs (eg. which Linux distro, compiled from source, etc) | ||
|
• |
Describe the bug accurately and give a way to reproduce it. | ||
|
• |
Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report. |