=begin html

<img src="virt-builder.svg" width="250"
  style="float: right; clear: right;" />

=end html

=head1 НАЗВА

virt-builder — засіб швидкої побудови образів для віртуальної машини

=head1 КОРОТКИЙ ОПИС

 virt-builder версія-ОС
    [-o|--output ОБРАЗ ДИСКА] [--size РОЗМІР] [--format raw|qcow2]
    [--arch АРХІТЕКТУРА] [--attach ФАЙЛ ISO]
__CUSTOMIZE_SYNOPSIS__

 virt-builder -l|--list [--long] [--list-format short|long|json]

 virt-builder --notes версія-ОС

 virt-builder --print-cache

 virt-builder --cache-all-templates

 virt-builder --delete-cache

 virt-builder --get-kernel ОБРАЗДИСКА
    [--format raw|qcow2] [--output КАТАЛОГВИВЕДЕННЯ]

=head1 ОПИС

Virt-builder — інструмент для швидкого збирання нових віртуальних машин. За його допомогою ви зможете зібрати цілий спектр віртуальних машин для локального використання або використання у «хмарі». Зазвичай, для цього достатньо декількох хвилин.  Крім того, у virt-builder передбачено багато способів налаштовування зібраних віртуальних машин. Усі команди віддаються за допомогою командного рядка. Для роботи програми не потрібні права доступу адміністратора системи, тому збирання нових віртуальних машин просто автоматизувати або керувати ним за допомогою скриптів.

Зауважте, що virt-builder не встановлює гостьові системи «з нуля». Програма використовує ретельного приготовані, підписані цифровими підписами шаблони операційних систем і налаштовує їх. Такий підхід використано, оскільки він є набагато швидшим за інші. Втім, якщо потрібно встановити систему «з нуля», ви можете скористатися L<virt-install(1)> та L<oz-install(1)>.

Найпростіше буде розпочати з прикладів з наступного розділу.

=head1 ПРИКЛАДИ

=head2 Показ списку доступних віртуальних машин

 virt-builder --list

покаже список доступних до встановлення операційних систем. Типово, доступний набір операційних систем із вільним поширенням. Ви також можете додати свою операційну систему (див. нижче).

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

 virt-builder --notes fedora-27

=head2 Побудова віртуальної машини

 virt-builder fedora-27

збере образ Fedora 25 для тієї самої архітектури, що і virt-builder (отже виконання команди у системі архітектури i686 призведе до спроби збирання образу i686, якщо це можливо). Образ матиме типові налаштування (мінімальний розмір, без облікових записів користувачів, випадковий пароль root, лише базовий мінімальний набір встановлених програм тощо).

Потреби у запуску цієї програми від імені root I<немає>.

Першого разу доведеться отримати шаблон мережею, а наступні операції може бути кешовано (див. L</КЕШУВАННЯ>).

Назву файла результатів буде визначено на основі назви шаблона, отже для наведеного вище прикладу буде F<fedora-27.img>.  Змінити назву файла результатів можна за допомогою параметра I<-o>:

 virt-builder fedora-27 -o mydisk.img

Ви також можете скористатися параметром I<-o> для запису на наявні пристрої або логічні томи.

 virt-builder fedora-27 --format qcow2

Те саме, що і вище, але виведені дані буде записано у форматі qcow2 до F<fedora-27.qcow2>.

 virt-builder fedora-27 --size 20G

Як і вище, але обсяг виведених даних дорівнюватиме 20 ГБ. Розмір гостьової операційної системи буде змінено так, наче її скопійовано до виведених даних (автоматично, за допомогою L<virt-resize(1)>).

 virt-builder fedora-27 --arch i686

Те саме, що і вище, але з використанням шаблона i686, якщо він доступний.

=head2 Встановлення пароля root

 virt-builder fedora-27 --root-password file:/tmp/rootpw

Створити образ Fedora 25. Пароль користувача root буде запозичено з файла F</tmp/rootpw>.

Зауважте, що якщо ви I<не встановите> I<--root-password>, гостьовій системі буде надано I<випадковий> пароль адміністратора root, який буде виведено до стандартного виведення.

Крім того, ви можете створювати облікові записи користувачів. Див. L</КОРИСТУВАЧІ І ПАРОЛІ> нижче.

=head2 Встановити назву вузла

 virt-builder fedora-27 --hostname virt.example.com

Встановити назву вузла C<virt.example.com>.

=head2 Встановлення програмного забезпечення

Встановлення пакунків зі звичайного (гостьового) сховища (наприклад, за допомогою dnf або apt):

 virt-builder fedora-27 --install "inkscape,@Xfce Desktop"

(У Fedora C<@> використовується для встановлення груп пакунків. У Debian вам доведеться встановлювати відповідний метапакунок.)

Для оновлення встановлених пакунків до останньої версії виконайте такі дії:

 virt-builder debian-7 --update

=head2 Налаштовування встановленої системи

Передбачено багато параметрів, за допомогою яких ви можете налаштувати встановлення. Це зокрема параметр I<--run>/I<--run-command>, за допомогою якого можна виконати скрипт оболонки або команду під час створення образу диска і додати або змінити файли, які буде включено до образу диска. За допомогою параметра I<--firstboot>/I<--firstboot-command> можна додати скрипти або команди, які буде виконано під час першого завантаження гостьової системи. За допомогою параметра I<--edit> можна редагувати файли, а параметра I<--upload> — вивантажувати файли до образу.

Приклад:

 cat <<'EOF' > /tmp/dnf-update.sh
 dnf -y --best update
 EOF
 
 virt-builder fedora-27 --firstboot /tmp/dnf-update.sh

або просто:

 virt-builder fedora-27 --firstboot-command 'dnf -y --best update'

у результаті команду L<dnf(8)> C<update> буде один раз виконано під час першого завантаження гостьової системи.

або

 virt-builder fedora-27 \
   --edit '/etc/dnf/dnf.conf:
             s/gpgcheck=1/gpgcheck=0/'

буде змінено F</etc/dnf/dnf.conf> у образі диска (під час створення образу диска, задовго до завантаження).

Ви можете поєднувати ці параметри і додавати декілька параметрів усіх типів.

=head1 ПАРАМЕТРИ

=over 4

=item B<--help>

Показати довідкове повідомлення.

=item B<--arch> АРХІТЕКТУРА

Використовувати для образу-результату вказану архітектуру. Це означає, що мають бути початкові коди шаблона для вказаної архітектури.

Див. також L</АРХІТЕКТУРА>.

=item B<--attach> ФАЙЛ_ISO

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

Ймовірно, вам варто додати мітки для долучених дисків (або скористатися назвою тому ISO), щоб надалі монтувати диски за міткою у ваших скриптах запуску:

 mkdir /tmp/mount
 mount LABEL=EXTRA /tmp/mount

Параметр I<--attach> можна вказати декілька разів, а форматом може бути будь-який формат образу (не лише ISO).

Див. також I<--run>, L</Встановлення пакунків зі стороннього сховища під час збирання>, L<genisoimage(1)>, L<virt-make-fs(1)>.

=item B<--attach-format> ФОРМАТ

Вказати формат диска для наступного параметра I<--attach>. Значенням аргументу C<ФОРМАТ> зазвичай є C<raw> або C<qcow2>.  Для образів ISO скористайтеся варіантом C<raw>.

=item B<--cache> КАТАЛОГ

=item B<--no-cache>

I<--cache> КАТАЛОГ встановлює каталог зберігання і пошуку файлів кешованих шаблонів. Якщо значення не встановлено, типовим значенням буде F<$XDG_CACHE_HOME/virt-builder/> або F<$HOME/.cache/virt-builder/>.

I<--no-cache> вимикає кешування шаблонів.

=item B<--cache-all-templates>

Отримати усі шаблони до кешу і завершити роботу. Див. L</КЕШУВАННЯ>.

Зауважте, що кешуються не усі дані. Можна вивантажити додаткові шаблони. Крім того, не кешуються пакунки (параметри I<--install>, I<--update>).

=item B<--check-signature>

=item B<--no-check-signature>

Перевіряти чи не перевіряти цифровий підпис шаблону операційної системи. Типово, програма перевіряє підпис і завершує роботу, якщо підпис не збігається із еталонним. Обійти цю перевірку можна за допомогою параметра I<--no-check-signature>.

Див. також I<--fingerprint>.

=item B<--colors>

=item B<--colours>

Використовувати послідовності символів ANSI для розфарбовування повідомлень. Ці послідовності типово використовуються, якщо дані виводяться на термінал tty.  Якщо дані, виведені програмою, спрямовуються до файла, послідовності визначення кольорів ANSI буде вимкнено, якщо ви не додасте до команди цей параметр.

=item B<--curl> CURL

Вказати альтернативний виконуваний файл L<curl(1)>. Ви також можете скористатися цим параметром для додавання параметрів curl, наприклад, щоб вимкнути перевірку сертифікатів https:

 virt-builder --curl "curl --insecure" [...]

=item B<--delete-cache>

Вилучити кеш шаблонів. Див. L</КЕШУВАННЯ>.

=item B<--no-delete-on-failure>

Не вилучати файл виведених даних, якщо під час збирання станеться помилка. Даними з цього файла можна скористатися для діагностування причин помилки. Див. L</ДІАГНОСТИЧНІ ЗБІРКИ>, щоб дізнатися більше про діагностику образів.

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

=item B<--fingerprint> 'AAAA BBBB ...'

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

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

=item B<--format> qcow2

=item B<--format> raw

Для звичайних процедур збирання визначає формат виведення даних. Типовим значенням є I<raw>.

З I<--get-kernel> визначає формат вхідних даних.

Для створення файла qcow2 у застарілому стилі (для сумісності з RHEL 6 або дуже старим qemu E<lt> 1.1) після виконання програми virt-builder скористайтеся такою командою:

 qemu-img amend -f qcow2 -o compat=0.10 output.qcow2

=item B<--get-kernel> ОБРАЗ

За допомогою цього параметра можна видобути ядро і initramfs з раніше зібраного образу диска із назвою C<ОБРАЗ> (фактично, це працює для будь-якого образу диска віртуальної машини, не лише для образів, які зібрано за допомогою virt-builder).

Зауважте, що цей метод є B<застарілим>: для виконання цього завдання є окрема програма, L<virt-get-kernel(1)>, у якій передбачено більше варіантів видобування файлів.

Ядро і initramfs буде записано до поточного каталогу, якщо ви не вкажете додатково назву каталогу результатів за допомогою параметра I<--output> C<каталог результатівr>.

Формат образу диска буде визначено автоматично, якщо ви не вкажете його за допомогою параметра I<--format>.

Якщо у гостьовій системі декілька ядер, буде вибрано ядро із найбільшим номером. Щоб видобути із образу диска ядро з певним номером версії, скористайтеся L<guestfish(1)>. Щоб видобути із гостьової системи увесь вміст каталогу F</boot>, скористайтеся L<virt-copy-out(1)>.

=item B<--gpg> GPG

Вказати альтернативний виконуваний файл L<gpg(1)> (GNU Privacy Guard). Типово, virt-builder шукає C<gpg2> або C<gpg> у каталогах, вказаних за допомогою змінної C<$PATH>.

Ви можете скористатися цим параметром для додавання параметрів до основної програми gpg, наприклад, для визначення альтернативного домашнього каталогу:

 virt-builder --gpg "gpg --homedir /tmp" [...]

=item B<-l> [версія-ОС]

=item B<--list> [версія-ОС]

=item B<--list> B<--list-format> формат [версія ОС]

=item B<--list> B<--long> [версія ОС]

Вивести усі доступні шаблони, якщо не вказано гостьової системи, або вивести шаблони лише для вказаної гостьової системи.

Ви можете вибрати формат виведення за допомогою параметра I<--list-format> для шаблонів списку:

=over 4

=item B<short>

Типовий формат: виводиться лише ідентифікатор шаблона і, поряд з ним, його короткий опис.

=item B<long>

Виводить тестовий список із даними щодо доступних джерел і список даних щодо доступних шаблонів після нього.

=item B<json>

Вивести об’єкт JSON із подробицями щодо доступних джерел та подробиці щодо доступних шаблонів.

Ключ C<version> у основному об'єкті визначає «версію сумісності», його значення слід збільшувати кожного разу, коли результат використання JSON ставатиме несумісним із попередніми версіями (наприклад, через зміну структури або прибирання основних ключів).

=back

I<--long> — скорочення для формату C<long>.

Див також: I<--source>, I<--notes>, L</ДЖЕРЕЛА ШАБЛОНІВ>.

=item B<--machine-readable>

=item B<--machine-readable>=формат

За допомогою цього параметра можна зробити виведені дані придатнішими для обробки комп'ютером, якщо для цієї обробки використовуються інші програми. Див. L</ПРИДАТНЕ ДО ЧИТАННЯ КОМП'ЮТЕРОМ ВИВЕДЕННЯ> нижче.

=item B<-m> МБ

=item B<--memsize> МБ

Зміна обсягу пам'яті, наданого скриптам I<--run>. Збільште це значення, якщо виявиться, що для використання скриптів I<--run> або параметра I<--install> не вистачає пам'яті.

Типові значення можна визначити за допомогою такої команди:

 guestfish get-memsize

=item B<--network>

=item B<--no-network>

Увімкнути чи вимкнути доступ до мережі для гостьової системи під час встановлення.

Типово увімкнено. Скористайтеся параметром I<--no-network>, щоб вимкнути доступ.

У мережі працюватимуть лише вихідні з'єднання, а також буде декілька інших незначних обмежень. Див. L<virt-rescue(1)/МЕРЕЖА>.

Якщо ви скористаєтеся параметром I<--no-network>, тоді інші параметри, зокрема I<--install>, не працюватимуть.

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

Загалом кажучи, вам I<не варто> використовувати I<--no-network>. Але ось декілька випадків, коли у вас може виникнути потреба у використанні цього параметра:

=over 4

=item 1.

У модулі обробки libguestfs, яким ви користуєтеся, не передбачено підтримки мережі.  (Див. L<guestfs(3)/МОДУЛЬ>).

=item 2.

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

=item 3.

Ви не хочете, щоб ненадійний код із гостьової системи намагався отримати доступ до мережевого з'єднання вашої основної системи під час роботи virt-builder. Таке, зокрема, може трапитися, якщо ви не довіряєте джерелу шаблонів операційних систем.  (Див. L</БЕЗПЕКА> нижче).

=item 4.

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

=back

=item B<--no-sync>

Не синхронізувати файл виведення під час завершення роботи.

Virt-builder виконує синхронізацію C<fsync> файла результатів або образу диска, якщо такий існує.

Причина полягає у тому, що типовим режимом кешування у qemu та KVM є C<none> або C<directsync>, і у обох цих режимах не використовується кеш сторінок основної системи. Тому ці режими не працюватимуть належним чином, якщо ви негайно запустите гостьову систему після запуску virt-builder — гостьова система просто не побачить файл результатів повністю . (Зауважте, що вам не варто користуватися обома цими режимами кешування — вони непрацездатні на базовому рівні з цієї та інших причин.)

Якщо ви не використовуєте ці помилкові режими кешування, ви можете скористатися параметром I<--no-sync>, щоб усунути непотрібну синхронізацію і значно пришвидшити роботу програми.

=item B<--notes> версія-ОС

Показує список нотаток, пов’язаних із гостьовою системою, потім завершує роботу (встановлення не виконується).

=item B<-o> назва_файла

=item B<--output> назва_файла

Записати виведені дані до файла F<назва_файла>. Якщо цей параметр не буде вказано, назву файла для виведення даних буде створено на основі рядка C<версія-ос> із додаванням суфікса C<.img> (для формату без обробки) або C<.qcow2> (для формату qcow2).

Зауважте, що назвою файла виведення результатів може бути пристрій, розділ або логічний том.

Якщо використовується з I<--get-kernel>, цей параметр задає каталог виведення даних.

=item B<--print-cache>

Вивести інформацію щодо кешу шаблонів. Див. L</КЕШУВАННЯ>.

=item B<-q>

=item B<--quiet>

Не виводити звичайних повідомлень щодо поступу.

=item B<--size> РОЗМІР

Вибір розміру диска-результату, де розмір можна вказати за допомогою типових записів, зокрема C<32G> (32 гігабайти) тощо.

Virt-builder змінить розміри файлових систем у образі диска автоматично.

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

Щоб вказати розмір у байтах, додайте до числа малу літеру I<b>, наприклад S<C<--size 10737418240b>>.

=item B<--smp> N

Увімкнути N E<ge> 2 віртуальних процесорів для використання у скриптах I<--run>.

=item B<--source> АДРЕСА

Встановити адресу початкових даних для пошуку покажчиків.

Цей параметр можна вказати декілька разів, щоб визначити декілька джерел.

Див. також L</ДЖЕРЕЛА ШАБЛОНІВ> нижче.

Зауважте, що не варто вказувати для I<--source> джерела, яким ви не довіряєте (якщо їх не підписано кимось, кому ви довіряєте). Див. також параметр I<--no-network>.

=item B<--no-warn-if-partition>

Не видавати попередження, якщо пристроєм виведення даних є розділ. Це попередження надає змогу уникнути типової помилки користувача під час записування на флеш-накопичувач USB або зовнішній диск — запису на розділ, коли слід виконувати перезапис усього пристрою (S<I<--output /dev/sdX>>), а не розділу на ньому (S<I<--output /dev/sdX1>>). Скористайтеся цим параметром, щоб I<придушити> відповідне попередження.

=item B<-v>

=item B<--verbose>

Увімкнути діагностичні повідомлення і/або режим докладних повідомлень.

Коли повідомлятимете про вади, скористайтеся цим параметром і долучіть усі виведені дані до звіту щодо вади.

=item B<-V>

=item B<--version>

Показати дані щодо версії і завершити роботу.

=item B<--wrap>

Wrap error, warning, and informative messages.  This is the default when the output is a tty.  If the output of the program is redirected to a file, wrapping is disabled unless you use this option.

=item B<-x>

Увімкнути трасування викликів програмного інтерфейсу libguestfs.

=back

=head2 Параметри налаштовування

__CUSTOMIZE_OPTIONS__

=head1 ДОВІДНИК

=head2 ВСТАНОВЛЕННЯ ПАКУНКІВ

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

=head3 Встановлення пакунків під час збирання

Якщо гостьова операційна система є подібною до основної операційної системи (наприклад, обидві є операційними системами Linux), і у libguestfs передбачено підтримку з'єднань мережею, ви можете скористатися параметром I<--install> для встановлення пакунків у такий спосіб:

 virt-builder fedora-27 --install inkscape

Тут використано засіб керування пакунками гостьової системи і з'єднання із мережею основної системи.

=head3 Оновлення пакунків під час збирання

Щоб оновити встановлений набір пакунків у шаблоні під час збирання, віддайте таку команду:

 virt-builder fedora-27 --update

У більшості шаблонів, які постачаються разом із virt-builder, передбачено дуже вузький набір пакунків (відомий як «JEOS» або «Just Enough Operating System» («Достатньо для того, щоб бути операційною системою»), які є актуальними на час створення шаблону, але можу виявитися застарілими на час, коли ви встановлюватимете операційну систему з шаблона. За допомогою цього параметра можна оновити пакунки з шаблона.

=head3 Встановлення пакунків під час першого завантаження

Іншим варіантом є встановлення пакунків під час першого завантаження гостьової системи:

 virt-builder fedora-27 --firstboot-install inkscape

Тут використано засіб керування пакунками гостьової системи і з'єднання із мережею гостьової системи.

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

=head3 Встановлення пакунків зі стороннього сховища під час збирання

Якщо програмного забезпечення, яке ви хочете встановити, немає у основному сховищі пакунків гостьової системи, ви можете додати стороннє сховище. Зазвичай, таке сховище є файлом образу ISO (образом компакт-диска), у якому містяться дані додаткових пакунків.

Ви можете створити образ диска за допомогою L<genisoimage(1)> або L<virt-make-fs(1)>. Для genisoimage скористайтеся такою командою:

 genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/

Створіть скрипт, який монтує ISO і налаштовує сховище. Для dnf створіть /tmp/install.sh з таким вмістом:

 mkdir /tmp/mount
 mount LABEL=EXTRA /tmp/mount
 
 cat <<'EOF' > /etc/yum.repos.d/extra.repo
 [extra]
 name=extra
 baseurl=file:///tmp/mount
 enabled=1
 EOF
 
 dnf -y install famousdatabase

Для apt створіть файл /tmp/install.sh із таким вмістом:

 mkdir /tmp/mount
 mount LABEL=EXTRA /tmp/mount
 
 apt-cdrom -d=/tmp/mount add
 apt-get -y install famousdatabase

Скористайтеся параметром I<--attach> для долучення компакт-диска або образу диска та параметром I<--run> для запуску скрипту:

 virt-builder fedora-27 \
   --attach extra-packages.iso \
   --run /tmp/install.sh

=head2 КОРИСТУВАЧІ І ПАРОЛІ

Параметр I<--root-password> використовується для зміни пароля адміністратора (root) (якщо ви не скористаєтеся цим параметром, буде використано випадковий пароль). Цьому параметру можна передати C<ВАРІАНТ> пароля у одному з таких форматів:

=over 4

=item B<--root-password> file:НАЗВА_ФАЙЛА

Прочитати пароль адміністратора з файла C<НАЗВА_ФАЙЛА>. Паролем вважатиметься вміст усього першого рядка цього файла. Усі інші рядки файла буде проігноровано. Файл має бути створено із режимом доступу 0600, щоб його не могли читати сторонні користувачі.

=item B<--root-password> password:ПАРОЛЬ

Встановити для пароля root буквальне значення рядка C<ПАРОЛЬ>.

B<Зауваження: цей спосіб не є безпечним>, оскільки будь-який користувач комп'ютера зможе побачити пароль явним чином за допомогою команди L<ps(1)>.

=item B<--root-password> random

Вибрати випадковий пароль, який буде виведено до stdout. Випадковість пароля наближено відповідатиме 120-бітовій.

Типове значення.

=item B<--root-password> disabled

Пароль для облікового запису root вимкнено. Це так, ніби у полі пароля використано C<*>.

=item B<--root-password> locked:file:НАЗВА_ФАЙЛА

=item B<--root-password> locked:password:ПАРОЛЬ

=item B<--root-password> locked:random

Обліковий запис root заблоковано, але для нього визначено пароль. Якщо обліковий запис буде вперше розблоковано (за допомогою C<passwd -u>), для входу до нього буде використано вказаний пароль.

=item B<--root-password> locked

=item B<--root-password> locked:disabled

Обліковий запис root I<і> пароль вимкнено.

=back

=head3 Створення облікових записів користувачів

Для створення облікових записів користувачів скористайтеся командою L<useradd(8)> з параметром L<--firstboot-command>, ось так:

 virt-builder --firstboot-command \
    'useradd -m -p "" rjones ; chage -d 0 rjones'

Вказана вище команда створить обліковий запис C<rjones> без пароля і примусить користувача встановити пароль під час першого входу до системи. Існують і інші способи керування паролями, див. L<useradd(8)>, щоб дізнатися більше.

=head2 РОЗКЛАДКА КЛАВІАТУРИ

Оскільки існує багато різних способів встановити розкладку клавіатури у дистрибутивах Linux, у virt-builder усе ще немає простого параметра командного рядка для виконання цієї дії. У цьому розділі наведено настанови щодо встановлення розкладки для деяких типових дистрибутивів Linux.

=head3 Визначення розкладки клавіатури за допомогою systemd

У дистрибутивах, де використовується C<localectl> зі складу systemd, скористайтеся такою командою:

 virt-builder fedora-27 \
   --firstboot-command 'localectl set-keymap uk'

Докладніший опис можна знайти за посиланнями L<localectl(1)> та L<https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/>.

=head3 Визначення розкладки клавіатури за допомогою F</etc/sysconfig/keyboard>

Для RHEL E<le> 6, Fedora E<le> 18 та подібних систем можна вивантажити із змінити файл налаштувань клавіатури за допомогою параметрів I<--upload>, I<--write> або I<--edit>. Приклад:

 virt-builder centos-6 \
   --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'

Документацію щодо формату даних цього файла можна знайти на багатьох сторінках інтернету.

=head3 Визначення розкладки клавіатури у дистрибутивах на основі Debian

У заснованих на Debian дистрибутивах мети можна досягти за допомогою файла F</etc/default/keyboard>. Вивантажити або внести зміни до цього файла можна за допомогою параметрів I<--upload>, I<--write> та I<--edit>. Приклад:

 virt-builder debian-8 \
   --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'

Див. L<https://wiki.debian.org/Keyboard>.

=head2 МОВА

У більшості дистрибутивів Linux передбачено можливість зміни локалі, отже ви можете бачити повідомлення гостьової системи нестандартною мовою, наприклад українською.

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

У цьому розділі наведено приклади для типових дистрибутивів Linux.

=head3 Встановлення японської локалі у Fedora 25

 virt-builder fedora-27 \
   --size 20G \
   --update \
   --install @japanese-support \
   --install @xfce \
   --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
   --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
   --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
   --firstboot-command 'localectl set-keymap jp' \
   --firstboot-command 'systemctl isolate graphical.target'

=head3 Встановлення японської мови для Debian 8 (Jessie)

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

 pkgs=locales,xfce4,\
 ibus,ibus-anthy,\
 fonts-ipafont-gothic,fonts-ipafont-mincho,\
 fonts-takao-mincho,\
 xfonts-intl-japanese,xfonts-intl-japanese-big,\
 iceweasel-l10n-ja,manpages-ja
 
 virt-builder debian-8 \
   --size 20G \
   --install $pkgs \
   --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
   --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
   --run-command "locale-gen"

=head2 ФАЙЛ ЖУРНАЛУ

Скрипти та засоби встановлення пакунків, які працюватимуть під час збирання (I<--run>, I<--run-command>, I<--install>, I<--update>, але I<не> firstboot), записуватимуть повідомлення до одного з таких файлів:

=over 4

=item F</tmp/builder.log>

У Linux, BSD та інших гостьових системах, відмінних від Windows.

=item F<C:\Temp\builder.log>

У гостьових системах Windows, DOS.

=item F</builder.log>

Якщо немає F</tmp> або F<C:\Temp>.

=back

Якщо ви не хочете, щоб до остаточного образу було записано файл журналу, скористайтеся параметром рядка команди I<--no-logfile>.

=head2 КЛЮЧІ SSH

Параметр I<--ssh-inject> використовується для вставляння ключів ssh для користувачів у гостьовій системі, щоб вони могли входити до системи без зазначення пароля.

Частина C<ВАРІАНТ> параметра є необов'язковою; у нашому випадку I<--ssh-inject> C<КОРИСТУВАЧ> означає, що ми шукаємо F<~/.ssh> у каталозі I<поточного> користувача для визначення типового файла відкритого ідентифікатора. Саме знайдений ключ і буде вивантажено до гостьової системи. «Типовий відкритий ідентифікатор» є файлом I<default_ID_file>, який описано у підручнику з L<ssh-copy-id(1)>.

Якщо вказано, C<ВАРІАНТ> можна зазначити у одному з таких форматів:

=over 4

=item B<--ssh-inject> КОРИСТУВАЧ:file:НАЗВА_ФАЙЛА

Прочитати ключ ssh з файла F<НАЗВА ФАЙЛА>. Файлом зазвичай є файл I<.pub>.

=item B<--ssh-inject> КОРИСТУВАЧ:string:РЯДОК_КЛЮЧА

Використати вказаний C<РЯДОК_КЛЮЧА>. Зазвичай, C<РЯДОК_КЛЮЧА> — рядок відкритого ключа у форматі I<ssh-rsa AAAA.... user@localhost>.

=back

Який би з варіантів не було вибрано, буде створено каталог F<~USER/.ssh> і файл F<~USER/.ssh/authorized_keys>, якщо вони досі не існували.

=head2 СКРИПТИ ПЕРШОГО ЗАВАНТАЖЕННЯ

За допомогою параметрів I<--firstboot> та I<--firstboot-command> ви можете визначити команди, які буде виконано під час першого завантаження гостьової системи. Для цього у гостьовій системі встановлюється скрипт ініціалізації, який виконує завдання із запуску усіх доданих скриптів і виконання усіх доданих команд.

Підтримувані операційні системи:

=over 4

=item Linux

Передбачено підтримку таких систем ініціалізації: systemd, System-V init (також відома як sysvinit) та Upstart (з використанням скриптів System-V).

Зауважте, що, зазвичай, скрипти ініціалізації виконуються від імені адміністратора (root), але у набагато обмеженішому середовищі ніж те, яке доступне зі звичайної оболонки. Наприклад, значення змінної середовища C<$HOME> може бути не встановленим або порожнім.

Дані, виведені скриптами першого запуску, у гостьовій системі зберігатимуться у F<~root/virt-sysprep-firstboot.log>.

=item Windows

Для запуску скриптів першого завантаження встановлюється F<rhsrvany.exe>, початковий код якого можна знайти у L<https://github.com/rwmjones/rhsrvany>, або F<pvvxsvc.exe>, який є частиною SUSE VMDP. Наявність цих файлів є обов'язковою. Якщо файлів не буде знайдено, скрипти першого завантаження виконати не вдасться.

F<rhsrvany.exe> або F<pvvxsvc.exe> буде просто скопійовано з місця, на яке вказує змінна середовища C<VIRT_TOOLS_DATA_DIR>; якщо значення змінної середовища не встановлено, буде використано типове місце, визначене під час компіляції (щось схоже на F</usr/share/virt-tools>).

Дані, виведені скриптами першого завантаження, можна знайти у гостьовій системі за адресою F<C:\Program Files\Guestfs\Firstboot\log.txt>.

=back

=head2 SUBSCRIPTION-MANAGER

Передбачено можливість автоматизації реєстрації та долучення до системи передплат за допомогою C<subscription-manager>. Потреба у подібному налаштовуванні типово виникає у системах Red Hat Enterprise Linux. Передбачено декілька параметрів, які спрощують процедуру, усувають потребу у введенні команд вручну та не роблять загальнодоступними паролі, вказані у рядку команди.

I<--sm-register> запускає процедуру реєстрації і потребує зазначення I<--sm-credentials>. Слід використовувати для параметра C<ВАРІАНТ> I<--sm-credentials> один з таких форматів:

=over 4

=item B<--sm-credentials> КОРИСТУВАЧ:file:НАЗВА_ФАЙЛА

Прочитати пароль для вказаного користувача C<КОРИСТУВАЧ> з файла F<НАЗВА_ФАЙЛА>.

=item B<--sm-credentials> КОРИСТУВАЧ:password:ПАРОЛЬ

Використати рядок C<ПАРОЛЬ> для вказаного користувача C<КОРИСТУВАЧ>.

=back

I<--sm-attach> долучає систему до передплачених послуг; формат варіантів команди може бути одним з таких:

=over 4

=item B<--sm-attach> auto

C<subscription-manager> долучається до найвідповідніших передплат для системи.

=item B<--sm-attach> file:НАЗВА_ФАЙЛА

Прочитати ідентифікатор буфера з файла F<НАЗВА_ФАЙЛА>.

=item B<--sm-attach> pool:БУФЕР

Використовувати рядок C<БУФЕР> як ідентифікатор буфера.

=back

I<--sm-remove> вилучає усі передплати з гостьової системи, а I<--sm-unregister> повністю знімає систему з реєстрації.

=head2 ПРОЦЕДУРА ВСТАНОВЛЕННЯ

Після виклику virt-builder встановлення виконується таким чином:

=over 4

=item *

Отримується образ шаблону.

Якщо образ шаблону вже є у кеші, використовується кешована версія. (Див. L</КЕШУВАННЯ>).

=item *

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

=item *

Шаблон розпаковується до файла tmp.

=item *

Розмір образ шаблону змінюється так, щоб від дорівнював розміру системи призначення, за допомогою L<virt-resize(1)>.

=item *

Долучаються додаткові диски (I<--attach>).

=item *

Створюється нова база псевдовипадкових чисел для гостьової системи.

=item *

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

=item *

SELinux relabelling is done unless disabled with I<--no-selinux-relabel>.

=back

=head2 ІМПОРТУВАННЯ ОБРАЗУ ДИСКА

=head3 Імпортування до libvirt

Імпортування образу диска до libvirt за допомогою параметра L<virt-install(1)> I<--import>.

 virt-install --import \
   --name guest --ram 2048 \
   --disk path=disk.img,format=raw --os-variant fedora27

Нотатки:

=over 4

=item 1.

Вам I<слід> вказати правильний формат. Форматом є C<raw>, якщо вами не було використано параметр virt-builder I<--format>.

=item 2.

Наполегливо рекомендуємо скористатися I<--os-variant>, оскільки він надає змогу підібрати оптимальний набір пристроїв, які слід увімкнути у системі, щоб гостьова система працювала найефективніше. Щоб отримати список усіх варіантів, скористайтеся такою командою:

 osinfo-query ОС

Вказана вище програма є частиною пакунка libosinfo.

=item 3.

Запускати virt-install можна від імені адміністратора (root) або від імені простого користувача. Між цими способами є незначні відмінності, оскільки libvirt керує різними наборами віртуальних машин для кожного користувача. Зокрема, virt-manager показує віртуальні машини, власником яких є root, а «Коробки» з GNOME показують лише віртуальні машини поточного користувача. Інші ж програми можуть також мати свої особливості показу.

=back

=head3 Імпортування до OpenStack

Імпортувати образ до Glance (сховища образів OpenStack) можна такими командами:

 glance image-create --name fedora-27-image --file fedora-27.img \
   --disk-format raw --container-format bare \
   --is-public True

Параметр I<--file> визначає створений за допомогою virt-builder образ диска. Його значення має узгоджуватися із значення параметра I<--output> virt-builder. Значення параметра I<--disk-format> має узгоджуватися зі значенням параметра I<--format> virt-builder (або бути рівним C<raw>, якщо ви не вказували цього параметра). Значенням параметра I<--container-format> завжди має бути C<bare>, оскільки virt-builder ніколи не вкладає образ до контейнерів.

Ви можете скористатися командою S<C<glance image-show I<fedora-27-image>>>, щоб переглянути властивості образу.

Для завантаження екземпляра вашого образу на обчислювальному вузлі Nova віддайте таку команду:

 nova boot fedora-27-server --image fedora-27-image \
   --flavor m1.medium

Скористайтеся командою S<C<nova flavor-list>>, щоб переглянути список можливих варіантів машин. Скористайтеся командою S<C<nova list>>, щоб переглянути список запущених екземплярів.

=head3 Безпосереднє завантаження за допомогою qemu або KVM

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

 qemu-system-x86_64 \
   -machine accel=kvm:tcg \
   -cpu host \
   -m 2048 \
   -drive file=disk.img,format=raw,if=virtio

Як і з libvirt, дуже важливо вибрати правильний формат. Цим форматом буде C<raw>, якщо раніше не було використано параметр I<--format>.

=head2 КЕРУВАННЯ НАЛАШТУВАННЯМИ

=head3 Puppet

Щоб увімкнути агент Puppet у гостьовій системі, встановіть пакунок, вкажіть налаштування на вашому Puppetmaster і забезпечте запуск агента під час завантаження.

Типовою командою virt-builder буде:

 virt-builder fedora-27 \
   --hostname client.example.com \
   --update \
   --install puppet \
   --append-line '/etc/puppet/puppet.conf:[agent]' \
   --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
   --run-command 'systemctl enable puppet'

Точний перелік настанов залежить від дистрибутива Linux. Докладніше про це тут: L<https://docs.puppet.com/puppet/latest/install_pre.html>

=head2 ДІАГНОСТИКА ЗБИРАННЯ

Якщо сам virt-builder не може виконати роботу, слід увімкнути діагностику (I<-v>) і повідомити про ваду розробників (див. розділ L</ВАДИ> нижче).

Якщо причиною неможливості виконання завдання virt-builder є який скрипт або пакунок, який програма не може встановити, спробуйте скористатися параметром I<--no-delete-on-failure>, щоб зберегти файл результатів, і продовжіть вивчення цього розділу підручника.

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

=over 4

=item Використання virt-rescue

Запустити L<virt-rescue(1)> над образом диска:

 virt-rescue -a disk.img

Ви потрапите до оболонки порятунку. Ви зможете змонтувати файлові системи з образу диска до F</sysroot> і вивчити їх за допомогою звичних команд Linux. Ви також можете скористатися chroot щодо гостьової системи і перевстановити у ній завантажувач. На сторінці підручника з virt-rescue наведено набагато більше інформації та прикладів.

=item Використання guestfish

Запустити L<guestfish(1)> над образом диска:

 guestfish -a disk.img -i

Скористайтеся командами guestfish, зокрема C<ll /каталог> і C<cat /файл>, для перевірки каталогів та файлів.

=item Використання guestmount

Безпечно змонтувати образ диска у основній системі за допомогою FUSE і L<guestmount(1)>:

 mkdir /tmp/mp
 guestmount -a disk.img -i /tmp/mp
 cd /tmp/mp

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

 fusermount -u /tmp/mp

=item Додати послідовну консоль

Якщо гостьова система повисає під час завантаження, може допомогти додавання послідовної консолі у гостьову систему і спрямовування повідомлень ядра до послідовної консолі. Додавання послідовної консолі потребує вивчення документації до вашого гіпервізору. Щоб спрямувати повідомлення ядра до послідовної консолі, додайте таку частину до командного рядка ядра:

 console=tty0 console=ttyS0,115200

=back

=head2 ДЖЕРЕЛА ШАБЛОНІВ

virt-builder читає доступні джерела із файлів налаштування, файлів із суфіксом назви I<.conf>, які зберігаються у одному з таких місць:

=over 4

=item *

$XDG_CONFIG_HOME/virt-builder/reposd/ (C<$XDG_CONFIG_HOME> дорівнює F<$HOME/.config>, якщо не встановлено).

=item *

$VIRT_BUILDER_DIRS/virt-builder/repos.d/ (where C<$VIRT_BUILDER_DIRS> means any of the directories in that environment variable, or just F</etc> if not set).

=back

Кожен з файлів I<.conf> у вказаних каталогах зберігає дані у простому текстовому форматі, ось так:

 [libguestfs.org]
 uri=http://libguestfs.org/download/builder/index.asc
 gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg

Частина у квадратних дужках є ідентифікатором сховища, який використовується як унікальний ідентифікатор.

Можуть з’явитися такі поля:

=over 4

=item C<uri=АДРЕСА>

Адреса файла покажчика, на який посилається це сховище.

Це поле слід заповнити.

=item C<gpgkey=АДРЕСА>

Це необов'язкове поле відповідає адресі (хоча прийнятними є лише адреси I<file://>) ключа, який використано для підписування файла покажчика. Якщо поля немає, файл покажчика, на який посилається I<uri=..>, не підписано.

=item C<proxy=РЕЖИМ>

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

=over 4

=item B<no>, B<off>

Не використовувати проксі взагалі, незважаючи на  налаштування системи.

=item B<system>

Використаний проксі-сервер є системним.

=item I<усе інше>

Задає справжні налаштування проксі, якими слід скористатися, незважаючи на налаштування системи.

=back

Якщо значення не вказано, буде використано параметри проксі-сервера системи (тобто все буде так, наче вказано B<system>).

=item C<format=ФОРМАТ>

Це необов'язкове поле задає формат сховища. Можливі такі значення:

=over 4

=item B<native>

Природний формат сховища C<virt-builder>. Див. також розділ L</Створення і підписування файла покажчика> нижче.

=item B<simplestreams>

Адреса, яка визначає кореневий каталог ієрархії метаданих Simple Streams версії 1.0.

Докладніший опис Simple Streams наведено тут: L<https://launchpad.net/simplestreams>.

=back

Якщо не вказано, типовим значенням буде C<native>.

=back

Якщо ви часто користуватиметеся virt-builder, варто створити власне сховище шаблонів.

=head3 Сховище libguestfs.org

Від початку, virt-builder отримує файл L<http://libguestfs.org/download/builder/index.asc>, який є покажчиком усіх доступних шаблонів, і деяку інформацію щодо кожного з них, яку додано до цифрового підпису. За допомогою команди C<virt-builder --list> можна ознайомитися із усіма даними щодо цього файла покажчика.

Шаблони, які зберігаються на libguestfs.org, було створено за допомогою скриптів командної оболонки, файлів kickstart та файлів, які можна знайти у ієрархії коду libguestfs, у каталозі C<builder/templates>.

=head3 Налаштовування доступу до сховища

Ви можете створити власний сайт із файлом покажчика (index) і деякими шаблонами, а потім вказати virt-builder на цей сайт за допомогою вмісту файла I<.conf>.

Зауважте, що якщо ваш покажчик підписано, вам слід належним чином заповнити поле I<gpgkey=..> у вашому файлі I<.conf>, а також додати файл ключа GPG.

 virt-builder --source https://example.com/builder/index.asc \
    --fingerprint 'AAAA BBBB ...' \
    --list

Ви можете розмістити сайт будь-якому мережевому сервері або сервері FTP чи у локальній або мережевій файловій системі.

=head3 Встановлення ключа GPG

Якщо у вас ще немає ключа GnuPG, вам слід налаштувати такий. (Строго кажучи, це не є обов'язковою умовою, але якщо ваш файл покажчика і файл шаблона не буде підписано, користувачам virt-builder доведеться додавати параметр I<--no-check-signature> до команди кожного разу, коли їм потрібно буде скористатися virt-builder.)

Інструкцію зі створення ключа можна знайти у підручнику з GPG: L<http://www.gnupg.org/gph/en/manual.html>.

Експортувати ваш відкрити ключ GPG:

 gpg --export -a "you@example.com" > pubkey
 
=head3 Створення шаблонів

Існує багато способів створення шаблонів. Наприклад, ви можете клонувати наявні гостьові системи (див. L<virt-sysprep(1)>) або встановити гостьову систему вручну (L<virt-install(1)>). Щоб ознайомитися із способами створення шаблонів для virt-builder, вивчіть скрипти у C<builder/templates>

У virt-builder передбачено підтримку усіх форматів образів (наприклад, raw, qcow2 тощо) як шаблонів, у звичайному форматі та у форматі, стисненому XZ. Таким чином, як шаблонами можна скористатися наявними образами (наприклад, образами, очищеними за допомогою L<virt-sysprep(1)>).

Для досягнення найкращих результатів під час стискання шаблонів скористайтеся такими параметрами програми xz (пояснення щодо цих параметрів можна знайти на сторінці довідки до L<nbdkit-xz-plugin(1)>):

 xz --best --block-size=16777216 disk

=head3 Створення і підписування файла покажчика

Файл покажчика записується у простому текстовому форматі (тут показано без цифрового підпису):

 [fedora-18]
 name=Fedora® 18
 osinfo=fedora18
 arch=x86_64
 file=fedora-18.xz
 checksum[sha512]=...
 format=raw
 size=6442450944
 compressed_size=148947524
 expand=/dev/sda3
 
 [fedora-19]
 name=Fedora® 19
 osinfo=fedora19
 arch=x86_64
 file=fedora-19.xz
 checksum[sha512]=...
 revision=3
 format=raw
 size=4294967296
 compressed_size=172190964
 expand=/dev/sda3

Частина у квадратних дужках є C<версією-ОС>, тим самим рядком, який використано у рядку команди virt-builder, використаному для збирання цієї операційної системи.

Спростити створення і підписування файла покажчика можна за допомогою програми L<virt-builder-repository(1)>.

Після приготування файла C<index> у належному форматі підпишіть його такою командою:

 gpg --clearsign --armor index

У результаті виконання цієї команди буде створено остаточний файл із назвою F<index.asc>, який можна вивантажити на сервер (і додати у запис адреси I<uri=..>). Як ми вже зауважували вище, підписування файла покажчика є необов'язковим, але рекомендованим.

Можуть з’явитися такі поля:

=over 4

=item C<name=НАЗВА>

Зручна для користувача назва цього шаблона. Назву буде показано у виведених даних команди з параметром I<--list>, більше ніде програма її не використовує.

=item C<osinfo=ІДЕНТИФІКАТОР>

Це додаткове поле пов'язує операційну систему із відповідним ідентифікатором libosinfo.  Virt-builder (ще) не використовує ці дані.

=item C<arch=АРХІТЕКТУРА>

Архітектура операційної системи, яку встановлено у цьому шаблоні. Це поле є обов'язковим.

=item C<file=ШЛЯХ>

Шлях (відносно покажчика) стисненого xz шаблона.

Зауважте, що тут B<не> можна використовувати абсолютні шляхи або адреси файлів. Причиною є те, що у virt-builder використовується правило «одного походження» для шаблонів, тому вони не можуть походити з інших серверів.

=item C<sig=ШЛЯХ>

B<Цей параметр вважається застарілим>. Використовуйте замість нього поле контрольної суми (checksum).

Шлях (відносно покажчика) від'єднаного підпису GPG файла xz.

Зауважте, що тут B<не> можна використовувати абсолютні шляхи або адреси файлів. Причиною є те, що у virt-builder використовується правило «одного походження» для шаблонів, тому вони не можуть походити з інших серверів.

Файл можна створити такою командою:

 gpg --detach-sign --armor -o disk.xz.sig disk.xz

=item C<checksum[sha512]=7b882fe9b82eb0fef...>

Контрольну суму SHA-512 файла, вказаного у виразі I<file=..>, буде перевірено після завершення отримання даних. Для визначення підпису скористайтеся такою командою:

 sha512sum disk.xz

Зауважте, що якщо ви користуєтеся цим параметром, вам не потрібно підписувати файл, тобто використовувати параметр C<sig>. Цей параметр має вищий пріоритет за параметра C<sig>.

=item C<checksum=7b882fe9b82eb0fef...>

C<checksum> є скороченою формою запису C<checksum[sha512]>.

Якщо вам доводиться працювати з virt-builder = 1.24.0, слід користуватися C<checksum>, оскільки ця версію видаватиме повідомлення про помилку обробки, якщо у ключі поля використано квадратні дужки і цифри. Цю помилку виправлено у версіях virt-builder E<ge> 1.24.1.

=item C<revision=N>

Модифікація (revision) — ціле число, яке використовується для керування кешем шаблонів. Збільшення номера модифікації призводить до того, що клієнти отримують шаблон, навіть якщо у них є копія у кеші.

Номер модифікації є необов’язковим. Якщо його не вказано, типовим значенням вважається C<1>.

=item C<format=raw>

=item C<format=qcow2>

Визначає формат образу диска; якщо дані стиснено, слід вказати формат до стискання. Якщо формат не вказано, його буде визначено автоматично, але все ж варто явним чином вказати бажаний формат.

Зауважте, що це формат початкових даних, який відрізняється від параметра I<--format> (бажаний формат результату). Virt-builder виконує перетворення «на льоту» з початкового формату до бажаного формату результату.

=item C<size=NNN>

Віртуальний розмір образу у байтах. Це розмір нестисненого образу. Якщо використано формат, відмінний від raw, зокрема qcow2, це значення означає розмір віртуального диска, а не розмір файла qcow2.

Це поле слід заповнити.

Virt-builder також використовує це значення як мінімальний розмір, запит щодо якого можуть надсилати користувачів за допомогою параметра I<--size>, або типовий розмір, якщо не вказано параметр I<--size>.

=item C<compressed_size=NNN>

Справжній розмір образу диска у байтах, тобто розмір, який було вказано у I<file=..>. Це значення використовується лише для інформування (якщо використовуються формати C<long> і C<json> у параметрі I<--list>).

=item C<expand=/dev/sdaX>

При розпаковуванні образу до його остаточного розміру, наказати L<virt-resize(1)> розпакувати дані до іменованого розділу у образі гостьової системи для заповнення усього доступного місця. Це працює подібно до параметра I<--expand> virt-resize.

Тут вам зазвичай слід вказати назву пристрою у кореневій файловій системі гостьової операційної системи.

Цим елементом варто скористатися, але це не обов'язково. Якщо поле пропущено, virt-resize створить додатковий розділ наприкінці диска для заповнення порожнього місця, що набагато менш зручно.

=item C<lvexpand=/пристрій/група_томів/логічний_том>

При розпаковуванні образу до його остаточного розміру, наказати L<virt-resize(1)> розпакувати дані до іменованого логічного тому у образі гостьової системи для заповнення усього доступного місця. Це працює подібно до параметра I<--lv-expand> virt-resize.

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

=item C<notes=НОТАТКИ>

Будь-які нотатки, які стосуються цього образу, особливо нотатки із описом пакунків образу, способу створення образу та даних щодо ліцензування.

Ці дані буде виведено у режимах I<--notes> і I<--list> I<--long>.

Ви можете створювати багаторядкові нотатки додаванням принаймні одного пробілу на початку кожного рядка (навіть порожнього):

 notes=Цей образ було створено за допомогою
  такого скрипту kickstart:
                                <-- один пробіл на початку рядка
  part /boot --fstype ext3
  ...

=item C<hidden=true>

Використання прапорця hidden усуває шаблон зі списку, який буде показано у відповідь на використання параметра I<--list> (лишаючи образ придатним до встановлення). Цей прапорець використовується для тестових образів.

=item C<aliases=ПСЕВДОНІМ1 ПСЕВДОНІМ2 ...>

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

=back

=head3 Запуск virt-builder для декількох джерел одночасно

У virt-builder передбачено можливість використання декількох джерел. Рекомендованим способом є розгортання файлів I<.conf>, які вказують на файли покажчика. Іншим способом є визначення джерел за допомогою декількох параметрів I<--source> і/або I<--fingerprint>:

 virt-builder \
   --source http://example.com/s1/index.asc \
   --source http://example.com/s2/index.asc

Ви можете надати N відбитків або 1 відбиток. Якщо буде надано N відбитків, N = кількості джерел, а між джерелом і відбитком є однозначна відповідність:

 virt-builder \
   --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
   --source http://example.com/s2/index.asc --fingerprint '9876 ...'

Якщо вами буде надано один відбиток, його буде використано для усіх джерел.

Вам C<слід> надати принаймні 1 відбиток.

=head3 Ліцензування шаблонів

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

=head3 Формальна специфікація файла покажчика

Формат файла покажчика має формальну специфікацію, що визначається сканером flex і обробником bison, що використовуються для обробки файла. Її можна знайти у таких файлах у ієрархію коду libguestfs:

 builder/index-scan.l
 builder/index-parse.y

Для перевірки коректності файла покажчика використовується програма із назвою L<virt-index-validate(1)>.

Зауважте, що обробник і інструмент може працювати як із підписаним, так і з непідписаним файлом покажчика (тобто з F<index> або зF<index.asc>).

Кодуванням покажчика завжди є UTF-8.

=head2 КЕШУВАННЯ

=head3 Кешування шаблонів

Оскільки шаблоні зазвичай є дуже великими, отримані шаблони зберігають у кеші домашнього каталогу користувача.

Кеш розміщується у F<$XDG_CACHE_HOME/virt-builder/> або F<$HOME/.cache/virt-builder>.

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

 virt-builder --print-cache

Кеш можна вилучити з метою економії місця на диску такою командою:

 virt-builder --delete-cache

Ви можете отримати усі (поточні) шаблони до локального кешу командою:

 virt-builder --cache-all-templates

Щоб вимкнути кешування шаблонів, скористайтеся параметром I<--no-cache>.

Кешуванню підлягають лише шаблони. Для покажчика та цифрових підписів кешування не використовується.

=head3 Кешування пакунків

Virt-builder використовує для отримання файлів L<curl(1)>, а також використовує поточні параметри C<http_proxy> (та інші) під час встановлення пакунків (I<--install>, I<--update>).

Тому ви можете встановити ці змінні середовища з метою максимізації обсягу локального кешування. Див. L</ЗМІННІ СЕРЕДОВИЩА> та L<curl(1)>.

=head3 Локальні дзеркала

Щоб збільшити швидкість і надійність встановлення пакунків, ви можете налаштувати локальне дзеркало для дистрибутива призначення і вказати на нього засобу керування пакунками гостьової системи.

=head4 Використання локального дзеркала з Fedora

Для встановлення гостьової системи Fedora за допомогою локального дзеркала:

 virt-builder fedora-27 \
   --edit '/etc/yum.repos.d/fedora.repo:
       s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
       s{.*metalink=.*}{};
   ' \
   --edit '/etc/yum.repos.d/fedora-updates.repo:
       s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
       s{.*metalink=.*}{};
   ' \
   --run-command 'dnf -y update' \
   --install 'pkg1,pkg2,...'

=head4 Використання локального дзеркала з Debian

Припускаємо, що ви використовуєте C<apt-proxy> для віддзеркалення сховища, тоді вам слід створити новий файл F<sources.list> для визначення вашого проксі-сервера (див. L<https://help.ubuntu.com/community/AptProxy>), а потім віддайте таку команду:

 virt-builder debian-8 \
   --upload sources.list:/etc/apt/sources.list \
   --run-command 'apt-get -y update' \
   --install 'пакунок1,пакунок2,...'

=head2 ЦИФРОВІ ПІДПИСИ

Virt-builder використовує GNU Privacy Guard (GnuPG або gpg) для забезпечення невтручання до покажчика і шаблонів.

Джерело вказує на файл покажчика, який можна підписати.

Virt-builder отримує покажчик і перевіряє, чи є підпис коректним і чи збігається відбиток підписника із вказаним відбитком (тобто відбитком, вказаним за допомогою I<gpgkey=..> у I<.conf> або за допомогою I<--fingerprint>, саме у цьому порядку).

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

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

Хоча підписи і не є обов'язковими, якщо ви їх не використаєте, користувачам virt-builder доведеться використовувати параметр I<--no-check-signature> у рядку команди. За допомогою підпису можна запобігти заміні зловмисником підписаного файла покажчика непідписаним файлом. При цьому virt-builder без перевірки підпису не повідомлятиме про підміну. Щоб там не сталося, наполегливо рекомендуємо вам створювати підписаний покажчик і шаблони.

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

Virt-builder може збирати образ гостьової системи для будь-якої архітектури, незалежно від архітектури основної системи. Наприклад, можна зібрати образ гостьової системи архітектури x86-64 на основній системі архітектури ARM.

Втім, деякі з параметрів не працюватимуть, особливо параметри, які потребують виконання команд у гостьовій системі під час процесу збирання: I<--install>, I<--update>, I<--run>, I<--run-command>. Вам варто замінити ці команди на їхні еквіваленти у firstboot.

Основна система архітектури x86-64, збираючи гостьові системи 32-бітової архітектури i686, має працювати без використання будь-яких додаткових кроків налаштовування.

=head2 БЕЗПЕКА

Virt-builder не потребує запуску від імені користувача root (фактично, програму не слід запускати від імені root) і не використовує setuid, C<sudo> або будь-яких інших подібних механізмів.

I<--install>, I<--update>, I<--run> і I<--run-command> реалізовано за допомогою базової системи (невеличкої віртуальної машини), тому ці команди не працюватимуть у основній системі. Якщо ви користуєтеся модулем libvirt libguestfs і у системі увімкнено SELinux , віртуальну машину буде додатково огорнуто у контейнер SELinux (sVirt).

Втім, ці параметри отримуватимуть доступ до мережі основної системи і, оскільки шаблон може містити шахрайський код, цей код може намагатися отримати доступ до ресурсів мережі основної системи, які мають бути недоступними для нього. Для запобігання небажаному доступу ви можете скористатися параметром I<--no-network>.

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

Virt-builder додає випадкову базу псевдовипадкових чисел до кожної гостьової системи, яку зібрано за його допомогою. Це допомагає забезпеченню справжньої випадковості номерів послідовності TCP, UUID, ключів вузла ssh тощо під час завантаження гостьової системи.

Вам слід перевіряти цифрові підписи і не ігнорувати повідомлення про помилки під час таких перевірок.

=head2 КЛОНИ

Якщо вам потрібно створити багато гостьових систем одного типу, виникає спокуса запустити virt-builder один раз, а потім просто скопіювати файл-результат. Втім, так B<не> слід робити. Вам слід запустити virt-builder окремо для кожної нової гостьової системи, яку ви хочете створити.

Так слід робити тому, що кожен клон повинен мати (принаймні) окрему базу для псевдовипадкових чисел, а також, ймовірно, інші унікальні властивості (зокрема UUID файлових систем) у майбутніх версіях virt-builder.

Ще однією річчю, яку вам I<не> слід робити, є клонування завантаженого образу диска. Причиною цього є те, що деякі гостьові системи створюють унікальні ідентифікатори машини, ключі SSH вузла та інші дані під час першого завантаження, а дублювання таких ідентифікаторів у клонах є вкрай небажаним.

Див. також L<virt-sysprep(1)>.

=head2 ШВИДКОДІЯ

Найважливішим аспектом пришвидшення роботи програми є кешування. Шаблон завантажується до кешу, коли його вперше використовують, або якщо було використано параметр команди I<--cache-all-templates>. Докладніше про це у розділі L</КЕШУВАННЯ> вище.

Пакунки, потрібні для виконання завдань із параметрами I<--install> та I<--update>, отримуються за допомогою з'єднання з мережею основної системи. Встановлення значень змінних середовища C<http_proxy>, C<https_proxy> та C<ftp_proxy> таким чином, щоб вони вказували на локальний кеш, може забезпечити режим, за якого ці пакунки отримуватимуться із інтернету лише один раз. Ви також можете спробувати скористатися локальним сховищем пакунків, хоча налаштовування такого сховища може бути складною справою, специфічною для того дистрибутива Linux, який ви намагаєтеся встановити.

=head3 Користування I<--no-sync>

Скористайтеся I<--no-sync>.  Втім, ознайомтеся із можливими проблемами, описаними у розділі L</ПАРАМЕТРИ> вище, оскільки це може призвести до пошкодження даних на диску, якщо використовувати неправильно.

=head3 Пропускання virt-resize

За певних умов virt-builder може пропускати крок virt-resize. Це значно пришвидшує роботу virt-builder. Умови пропускання є такими:

=over 4

=item *

дані слід виводити до звичайного файла (не на блоковий пристрій), B<і>

=item *

користувачем B<не> використано параметр I<--size>, B<і>

=item *

формат виведення є тим самим, що і формат шаблона (зазвичай raw).

=back

=head3 pxzcat

Virt-builder використовує внутрішню реалізацію pxzcat (паралельного xzcat), якщо під час збирання програми було знайдено liblzma. Якщо liblzma не було знайдено під час збирання, використовуватиметься звичайний C<xzcat>, який працює у один потік.

=head2 SELINUX

Гостьові системи, у яких використовується SELinux (зокрема Fedora і Red Hat Enterprise Linux) потребують коректної мітки SELinux для кожного файла.

Virt-builder не може знайти про спосіб, у який новим файлам надаються мітки. Тому існує дві можливі стратегії, використання яких забезпечує встановлення належних міток:

=over 4

=item Automatic relabeling

Запуск L<setfiles(8)> безпосередньо перед завершенням збирання образу гостьової системи для встановлення належних міток SELinux на образі диска.

Це рекомендований метод.

=item Using I<--no-selinux-relabel> I<--touch> F</.autorelabel>

Наявність у гостьовій системі файла із назвою F</.autorelabel> або можливе його створення.

У гостьових системах, де використовується SELinux, це спричиняє запуск L<restorecon(8)> під час першого завантаження. Гостьові системи самостійно перезавантажуються під час першого використання — це нормальна і нешкідлива поведінка.

=back

=head1 ПРИДАТНЕ ДО ЧИТАННЯ КОМП'ЮТЕРОМ ВИВЕДЕННЯ

Для виведення даних у зручному для машинної обробки форматі можна скористатися параметром I<--machine-readable>. Додавання цього параметра робить зручним використання virt-builder з інших програм, графічних інтерфейсів тощо.

Скористайтеся цим параметром окремо, щоб опитати систему щодо можливостей виконуваного файла virt-builder.  Типово виведені дані виглядатимуть якось так:

 $ virt-builder --machine-readable
 virt-builder
 arch
 config-file
 customize
 json-list
 pxzcat

Виводиться список можливостей, по одній на рядок, і програма завершує роботу зі станом 0.

Можна вказати рядок форматування для керування виведенням, див. L<guestfs(3)/РОЗШИРЕНЕ ПРИДАТНЕ ДО ЧИТАННЯ КОМП'ЮТЕРОМ ВИВЕДЕННЯ>.

=head1 ЗМІННІ СЕРЕДОВИЩА

Опис інших змінних середовища, які стосуються усіх програм libguestfs, наведено у розділі L<guestfs(3)/ЗМІННІ СЕРЕДОВИЩА>.

=over 4

=item C<http_proxy>

=item C<https_proxy>

=item C<no_proxy>

Встановити проксі-сервер для отримання даних. Ці змінні середовища (та інші) насправді обробляються L<curl(1)>, а не virt-builder.

=item C<HOME>

Використовується для визначення місця кешу шаблонів та місця джерел користувача. Див. L</КЕШУВАННЯ> і L</ДЖЕРЕЛА ШАБЛОНІВ>.

=item C<VIRT_TOOLS_DATA_DIR>

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

Зазвичай, потреби у встановленні власного значення немає. Якщо значення не встановлено, буде використано вбудоване типове значення (щось схоже на F</usr/share/virt-tools>).

Цей каталог може містити такі файли:

=over 4

=item F<rhsrvany.exe>

Це виконуваний файл для Windows RHSrvAny, який використовується для встановлення скрипту «firstboot» у гостьові системи Windows. Він знадобиться, якщо ви маєте намір використовувати параметри I<--firstboot> і I<--firstboot-command> для гостьових операційних систем Windows.

Див. також C<https://github.com/rwmjones/rhsrvany>

=item F<pvvxsvc.exe>

Це виконуваний файл Windows, що постачається разом із VMDP SUSE, використовується для встановлення скрипту «firstboot» у гостьові системи Windows. Він знадобиться, якщо ви маєте намір використовувати параметри I<--firstboot> і I<--firstboot-command> для гостьових операційних систем Windows.

=back

=item C<XDG_CACHE_HOME>

Використовується для визначення місця кешу шаблонів. Див. L</КЕШУВАННЯ>.

=item C<XDG_CONFIG_HOME>

Використовується для визначення місця джерел користувача. Див. L</ДЖЕРЕЛА ШАБЛОНІВ>.

=item C<VIRT_BUILDER_DIRS>

Використовується для визначення місця джерел системи. Див. L</ДЖЕРЕЛА ШАБЛОНІВ>.

=back

=head1 СТАН ВИХОДУ

Ця програма повертає значення 0 у разі успішного завершення і ненульове значення, якщо сталася помилка.

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

L<guestfs(3)>, L<guestfish(1)>, L<guestmount(1)>, L<virt-builder-repository(1)>, L<virt-copy-out(1)>, L<virt-customize(1)>, L<virt-get-kernel(1)>, L<virt-install(1)>, L<virt-rescue(1)>, L<virt-resize(1)>, L<virt-sysprep(1)>, L<oz-install(1)>, L<gpg(1)>, L<gpg2(1)>, L<curl(1)>, L<virt-make-fs(1)>, L<genisoimage(1)>, L<http://libguestfs.org/>.

=head1 АВТОР

Richard W.M. Jones L<http://people.redhat.com/~rjones/>

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

© Red Hat Inc., 2013