guestfs-internals - Интернет в облаке

ПРОГРАММА:

ИМЯ

guestfs-internals - архитектура и внутреннее устройство libguestfs

ОПИСАНИЕ

Эта страница руководства предназначена для хакеров, которые хотят понять, как работает libguestfs внутри.
Это просто описание того, как сейчас работает libguestfs, и оно может измениться в любое время в
будущее.

АРХИТЕКТУРА

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

┌────────────────────┐
│ основная программа │
│ │
│ │ дочерний процесс / устройство
│ │ ┌───────────────────────────
│ │ │ кему │
├───────────────────┤ RPC │ ┌──────────────────┐ │
│ libguestfs ◀ ╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍ ▶ guestfsd │ │
│ │ │ ├──────────────────┤ │
└──────────────────── │ Ядро Linux │ │
│ └────────┬──────── │
└───────────────│───────────┘
│
│ виртуальный scsi
┌──────┴──────┐
│ Устройство или │
│ образ диска │
└─────────────

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

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

Распространенное заблуждение состоит в том, что устройство - это виртуальная машина. Хотя
образ диска, к которому вы подключены, также может использоваться какой-либо виртуальной машиной, libguestfs
не знает об этом и не заботится об этом. (Но вам будет все равно, если и процесс qemu libguestfs, и
ваша виртуальная машина одновременно пытается обновить образ диска, так как эти
обычно приводит к массовому повреждению диска).

ГОСУДАРСТВЕННЫЙ МАШИНА

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

|
Guestfs_create / Guestfs_create_flags
|
|
____В_____
/\
| КОНФИГУРАЦИЯ |
\ __________ /
^ ^ \
| \\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" внутренне перемещает состояние с КОНФИГУРАЦИИ на ЗАПУСК
пока он работает.

Действия API, такие как "guestfs_mount", могут выполняться только в состоянии ГОТОВ. Эти API
вызывает блок, ожидающий выполнения команды. Нет неблокирующих
версий, и нет возможности выполнить более одной команды для каждого дескриптора одновременно.

Наконец, дочерний процесс отправляет асинхронные сообщения обратно в основную программу, например
сообщения журнала ядра. Вы можете зарегистрировать обратный вызов для получения этих сообщений.

ВНУТРЕННИЕ

ПРИБОР BOAT ПРОЦЕСС ПРОЕКТИРОВАНИЯ
Этот процесс эволюционировал и продолжает развиваться. Описание здесь соответствует только
к текущей версии libguestfs и предоставляется только для информации.

Чтобы выполнить описанные ниже этапы, включите отладку libguestfs (установите
переменная окружения "LIBGUESTFS_DEBUG = 1").

Создайте прибор
"supermin --build" вызывается для создания ядра, небольшого initrd и устройства.

Устройство кэшируется в /var/tmp/.guestfs- (или в другом каталоге, если
"LIBGUESTFS_CACHEDIR" или "TMPDIR" установлены).

Полное описание того, как устройство создается и кэшируется, см. В
супермин(1) справочная страница.

Запустите qemu и загрузите ядро
qemu вызывается для загрузки ядра.

Запустите initrd
"supermin --build" создает небольшой initrd. Initrd - это не устройство. В
цель initrd - загрузить достаточное количество модулей ядра, чтобы устройство
сам можно смонтировать и запустить.

Initrd - это архив cpio, который называется /var/tmp/.guestfs- /appliance.d/initrd.

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

supermin: запуск ext2 mini initrd
supermin: монтаж / sys
супермин: внутренний insmod libcrc32c.ko
супермин: внутренний 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: установка нового корня на / Корень
супермин: chroot
Запуск / инициализация скрипта ...

Обратите внимание, что «Запуск / сценарий инициализации ...» указывает, что сценарий инициализации устройства
сейчас работает.

Инициализируйте прибор
Само устройство теперь инициализируется. Это предполагает запуск определенных процессов
например "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, которые используют один и тот же запрос и
ответные сообщения, но за ними также могут следовать файлы, отправленные с использованием фрагментированной кодировки.

ОБЫЧНЫЙ ФУНКЦИИ (NO ФАЙЛ / ФАЙЛ ПАРАМЕТРЫ)

Для обычных функций сообщение запроса:

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

Поле общей длины позволяет демону выделить буфер фиксированного размера, в котором он
проглатывает остальную часть сообщения. В результате общая длина ограничена
«GUESTFS_MESSAGE_MAX» байтов (в настоящее время 4 МБ), что означает эффективный размер любого запроса.
ограничен где-то ниже этого размера.

Также обратите внимание, что многие функции не принимают никаких аргументов, и в этом случае
"guestfs_foo_args " полностью опущено.

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

Для функций, которые принимают необязательные аргументы, необязательные аргументы кодируются в
"guestfs_foo_args " структура так же, как и обычные аргументы. Битовая маска в
заголовок указывает, какие необязательные аргументы имеют смысл. Битовая маска также проверяется на
посмотрите, содержит ли он набор битов, о котором демон не знает (например, если более необязательный
аргументы были добавлены в более поздней версии библиотеки), и это приводит к тому, что вызов
отвергнуто.

Ответное сообщение для обычных функций:

общая длина (заголовок + ret,
но не включая само слово длины)
struct guestfs_message_header (в кодировке XDR)
struct guestfs_ _ret (в кодировке XDR)

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

Как и выше, общая длина ответа ограничена «GUESTFS_MESSAGE_MAX».

В случае ошибки в заголовке ставится флаг, а ответное сообщение немного
изменена:

общая длина (заголовок + ошибка,
но не включая само слово длины)
struct guestfs_message_header (в кодировке XDR)
struct guestfs_message_error (в кодировке XDR)

Структура "guestfs_message_error" содержит сообщение об ошибке в виде строки.

ФУНКЦИИ ЧТО ИМЕТЬ ФАЙЛЕЙН ПАРАМЕТРЫ

Параметр "FileIn" указывает, что мы передаем файл в Гость. Обычный запрос
сообщение отправлено (см. выше). Однако за этим следует последовательность фрагментов файла.

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

«Последовательность фрагментов»:

длина блока (не включая слово длины)
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"), так что ни библиотека, ни
демону нужно много хранить в памяти.

ФУНКЦИИ ЧТО ИМЕТЬ ВЫПОЛНИТЬ ПАРАМЕТРЫ

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

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

ИСХОДНЫЙ СООБЩЕНИЕ

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

ПРОГРЕСС ИЗВЕЩЕНИЕ СООБЩЕНИЯ

Демон может отправлять сообщения с уведомлением о ходе выполнения в любое время. Они выделяются
слово нормальной длины заменяется на "GUESTFS_PROGRESS_FLAG", за которым следует фиксированный
сообщение о прогрессе размера.

Библиотека превращает их в обратные вызовы выполнения (см. «GUESTFS_EVENT_PROGRESS»), если есть
обратный вызов зарегистрирован, или отбрасывает их, если нет.

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

FIXED ПРИБОР
Когда libguestfs (или инструменты libguestfs) запущены, они ищут путь в поисках
прибор. Путь встроен в libguestfs или может быть установлен с помощью "LIBGUESTFS_PATH"
переменная среды.

Обычно на этом пути располагается сверхминиатюрное устройство (см. «СУПЕРМИН-ПРИБОР» в
супермин(1)). libguestfs преобразует это в полноценное устройство, запустив "supermin
--строить".

Однако можно использовать и более простой «фиксированный прибор». libguestfs обнаруживает это, глядя
для каталога на пути, содержащего все следующие файлы:

· ядро

· Initrd

· корень

· README.исправлено (обратите внимание, что это обязательно тоже присутствовать)

Если фиксированное устройство найдено, libguestfs полностью пропускает супермин и просто запускает
виртуальная машина (используя qemu или текущий бэкэнд, см. «НАЗАД») с ядром, initrd
и корневой диск от фиксированного устройства.

Таким образом, фиксированное устройство можно использовать, когда платформа или дистрибутив Linux не
поддержка супермин. Вы строите фиксированное устройство на платформе, которая поддерживает supermin
через libguestfs-make-фиксированное устройство(1), скопируйте его и используйте для запуска libguestfs.

Используйте guestfs-internals онлайн с помощью сервисов onworks.net