guestfs-internals - онлайн у хмарі

ПРОГРАМА:

ІМ'Я

guestfs-internals - архітектура та внутрішні елементи libguestfs

ОПИС

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

АРХІТЕКТУРА

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

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

Бібліотека, пов’язана з основною програмою, створює дочірній процес і, отже, пристрій
у функції "guestfs_launch".

Всередині пристрою є ядро ​​Linux і повний набір інструментів для простору користувача (наприклад
програми LVM і ext2) і невеликий контрольний демон під назвою "guestfsd". Бібліотека
спілкується з "guestfsd" за допомогою віддалених викликів процедур (RPC). Є переважно один на один
відповідність між викликами API libguestfs і викликами RPC до демона. Нарешті диск
зображення додаються до процесу qemu, який перекладає доступ до пристрою за допомогою
ядро Linux пристрою для доступу до образу.

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

СТАН МАШИНА

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

|
guestfs_create / guestfs_create_flags
|
|
____V_____
/\
| КОНФІГУРАЦІЯ |
\__________/
^ ^ \
| \ \ guestfs_launch
| _\__V______
| / \
| | ЗАПУСК |
| \___________/
| /
| guestfs_launch
| /
__|____V
/\
| ГОТОВІ |
\________/

Звичайними переходами є (1) CONFIG (коли дескриптор створено, але немає дочірнього елемента
процес), (2) ЗАПУСК (коли дочірній процес завантажується), (3) ГОТОВ, що означає
пристрій запущено, дії можуть надаватися дочірньому процесу та виконуватися ним.

Гість може бути вбитий "guestfs_kill_subprocess" або може померти асинхронно в будь-якому
часу (наприклад, через якусь внутрішню помилку), і це змушує стан повернутися до
КОНФІГ.

Команди конфігурації для qemu, такі як "guestfs_set_path", можуть бути видані лише в
Стан CONFIG.

API пропонує один виклик, який переходить від CONFIG через LAUNCHING до READY.
"guestfs_launch" блокується, доки дочірній процес не буде ГОТОВИЙ приймати команди (або поки деякі
збій або тайм-аут). "guestfs_launch" внутрішньо переміщує стан з CONFIG до LAUNCHING
поки він працює.

Дії API, такі як "guestfs_mount", можуть виконуватися лише в стані READY. Ці API
блок викликів в очікуванні виконання команди. Неблокуючих немає
версії, і не можна одночасно видавати більше однієї команди на дескриптор.

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

ВНУТРІШНІСТЬ

ПРИЛАД BOOT ПРОЦЕС
Цей процес розвивався і продовжує розвиватися. Опис тут відповідає лише
до поточної версії libguestfs і надається лише для інформації.

Щоб виконати наведені нижче етапи, увімкніть налагодження libguestfs (встановіть
змінна середовища "LIBGUESTFS_DEBUG=1").

Створіть прилад
"supermin --build" викликається для створення ядра, невеликого initrd і пристрою.

Пристрій кешується /var/tmp/.guestfs- (або в іншому каталозі, якщо
Встановлено "LIBGUESTFS_CACHEDIR" або "TMPDIR").

Щоб отримати повний опис того, як пристрій створюється та кешується, прочитайте
супермін(1) сторінка посібника.

Запустіть qemu і завантажте ядро
qemu викликається для завантаження ядра.

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

Initrd — це архів cpio під назвою /var/tmp/.guestfs- /appliance.d/initrd.

Коли initrd запуститься, ви побачите повідомлення, що показують, що модулі ядра є
завантажується, подібно до цього:

supermin: запуск ext2 mini initrd
supermin: монтаж / sys
supermin: внутрішній insmod libcrc32c.ko
supermin: внутрішній insmod crc32c-intel.ko

Знайдіть і встановіть прилад
Пристрій являє собою розріджений файл, що містить файлову систему ext2, яка містить знайомі
(хоча зменшена в розмірі) операційна система Linux. Зазвичай це називалося б
/var/tmp/.guestfs- /appliance.d/root.

Звичайні диски, що перевіряються libguestfs, є першими пристроями, які відкриває qemu
(наприклад, як /dev/vda).

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

Таким чином, останнє завдання initrd — знайти диск пристрою, змонтувати його та перемкнути
вкоріньте пристрій і запустіть /у цьому від приладу.

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

supermin: обрано /sys/block/vdb/dev як кореневий пристрій
supermin: створення /dev/root як спеціальний блок 252:16
supermin: встановлення нового root / корінь
супермін: chroot
Запуск сценарію /init...

Зауважте, що «Запуск сценарію /init...» означає, що сценарій ініціалізації пристрою є
зараз працює.

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

Демон
Нарешті, демон ("guestfsd") запускається всередині пристрою. Якщо він працює, ви повинні побачити:

детальний демон увімкнено

Демон очікує побачити названий послідовний порт virtio, відкритий qemu та підключений
інший кінець до бібліотеки.

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

ЗВ'ЯЗОК ПРОТОКОЛ
Не покладайтеся на пряме використання цього протоколу. У цьому розділі описано, як це відбувається зараз
працює, але може змінитися в будь-який час.

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

Детальний формат конструкцій в src/guestfs_protocol.x (Примітка: цей файл є
автоматично генерується).

Є два широкі випадки, звичайні функції, які не мають «FileIn» і «FileOut»
параметри, які обробляються за допомогою дуже простих повідомлень запиту/відповіді. Тоді є
функції, які мають будь-які параметри "FileIn" або "FileOut", які використовують той самий запит і
повідомлення-відповіді, але за ними також можуть супроводжуватися файли, надіслані за допомогою фрагментованого кодування.

Звичайні ФУНКЦІЇ (НІ FILEIN/FILEOUT ПАРАМИ)

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

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

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

Зауважте також, що багато функцій не приймають жодних аргументів, і в цьому випадку
"guestfs_foo_args" повністю пропущено.

Заголовок містить номер процедури ("guestfs_proc"), який знає одержувач
якого типу структури аргументів очікувати, або взагалі немає.

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

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

загальна довжина (заголовок + ret,
але не включаючи саме слово довжини)
struct guestfs_message_header (закодований як XDR)
структура guestfs_ _ret (закодовано як XDR)

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

Як зазначено вище, загальна тривалість відповіді обмежена "GUESTFS_MESSAGE_MAX".

У разі помилки в заголовку встановлюється прапорець, а повідомлення-відповідь злегка
змінено:

загальна довжина (заголовок + помилка,
але не включаючи саме слово довжини)
struct guestfs_message_header (закодований як XDR)
struct guestfs_message_error (закодовано як XDR)

Структура "guestfs_message_error" містить повідомлення про помилку у вигляді рядка.

ФУНКЦІЇ ЩО МИЛИ FILEIN ПАРАМЕТРИ

Параметр «FileIn» вказує, що ми передаємо файл в гостя. Нормальний запит
повідомлення надіслано (див. вище). Однак за цим слідує послідовність фрагментів файлів.

загальна довжина (заголовок + аргументи,
але не включаючи саме слово довжини,
і не включаючи шматки)
struct guestfs_message_header (закодований як XDR)
структура guestfs_ _args (закодовано як XDR)
послідовність фрагментів для параметра FileIn №0
послідовність фрагментів для параметра FileIn №1 тощо.

"Послідовність фрагментів" така:

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

Останній фрагмент має нульове значення для поля "data_len". Додатково встановлюється прапор
Останній фрагмент, який вказує на успішне завершення або дострокове скасування.

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

Обидві бібліотеки (відправник) та демон (одержувач) може скасувати передачу. Бібліотека
робить це, надсилаючи фрагмент зі спеціальним прапорцем, що вказує на скасування. Коли
демон бачить це, він скасовує весь RPC, робить НЕ надіслати будь-яку відповідь і повернутися до
читання наступного запиту.

Демон також може скасувати. Це робиться шляхом написання спеціального слова "GUESTFS_CANCEL_FLAG"
до розетки. Бібліотека прослуховує це під час передачі, і якщо отримує, то
скасує передачу (відправляє фрагмент скасування). Спеціальне слово підібрано так, що
навіть якщо скасування відбувається відразу в кінці передачі (після того, як бібліотека зробить
закінчив писати і почав слухати відповідь), з’явиться прапорець "підробного" скасування
не плутайте з повідомленням-відповіддю.

Цей протокол дозволяє передавати файли довільного розміру (без обмеження 32 біт), а також
файли, розмір яких не відомий заздалегідь (наприклад, з труб або розеток). Однак
фрагменти досить малі ("GUESTFS_MAX_CHUNK_SIZE"), тому ні бібліотека, ні
демону потрібно багато зберігати в пам'яті.

ФУНКЦІЇ ЩО МИЛИ FILEOUT ПАРАМЕТРИ

Протокол для параметрів FileOut точно такий же, як і для параметрів FileIn, але з
ролі демона і бібліотеки помінялися.

загальна довжина (заголовок + ret,
але не включаючи саме слово довжини,
і не включаючи шматки)
struct guestfs_message_header (закодований як XDR)
структура guestfs_ _ret (закодовано як XDR)
послідовність фрагментів для параметра FileOut №0
послідовність фрагментів для параметра FileOut №1 тощо.

ПОЧАТКОВИЙ З

Коли демон запускається, він надсилає початкове слово ("GUESTFS_LAUNCH_FLAG"), яке вказує
що гість і демон живі. Це те, на що чекає "guestfs_launch".

ПРОГРЕС ПОВІДОМЛЕННЯ ПОВІДОМЛЕННЯ

Демон може надсилати повідомлення про прогрес у будь-який час. Ці виділяються
слово звичайної довжини замінюється на "GUESTFS_PROGRESS_FLAG", за яким слідує фіксована
повідомлення про прогрес розміру.

Бібліотека перетворює їх у зворотні виклики прогресу (див. "GUESTFS_EVENT_PROGRESS"), якщо є
зареєстровано зворотний виклик або відкидає їх, якщо ні.

Демон самостійно обмежує частоту надсилання повідомлень про прогрес (див
"daemon/proto.c:notify_progress"). Не всі дзвінки генерують повідомлення про перебіг.

ФІКСОВАНО ПРИЛАД
Коли запускаються libguestfs (або інструменти libguestfs), вони шукають шлях у пошуках
прилад. Шлях вбудований у libguestfs або може бути встановлений за допомогою "LIBGUESTFS_PATH"
змінна оточення

Зазвичай на цьому шляху знаходиться пристрій Supermin (див. «SUPERMIN APPLIANCE» в
супермін(1)). libguestfs відновлює це в повноцінний пристрій, запускаючи «supermin
--будувати».

Однак можна використовувати і простіший «фіксований прилад». libguestfs виявляє це, дивлячись
для каталогу на шляху, що містить усі наступні файли:

· ядро

· initrd

· корінь

· README.виправлено (зверніть увагу, що це повинен також бути присутнім)

Якщо фіксований пристрій знайдено, libguestfs повністю пропускає supermin і просто запускає
віртуальна машина (використовуючи qemu або поточний бекенд, див. «БЕКЕНД») з ядром, initrd
і кореневий диск зі стаціонарного пристрою.

Таким чином, фіксований пристрій можна використовувати, коли платформа або дистрибутив Linux цього не роблять
підтримка супермін. Ви створюєте фіксований пристрій на платформі, яка підтримує Supermin
використання libguestfs-make-fixed-appliance(1), скопіюйте його та використовуйте для запуску libguestfs.

Використовуйте guestfs-internals онлайн за допомогою служб onworks.net