virsh(1).
Приведен вольный перевод man-страницы virsh, дополненый переводом
man’а идущего в дистрибутиве libvirt-0.7.6-r1 и данные из help’а самого
virsh. Утилита virsh является основным интерфейсом для управления
виртуальными окружениями и сетями, пулами хранения данных, сетевыми
интерфесами и различными объектами виртуальной инфраструктуры.
Общий синтаксис
virsh <subcommand> [args]
Утилита virsh является основным интерфейсом для управления гостевыми
доменами. Программа может использоваться для создания, приостановки и
выключения гостевых окружений. Также можно просмотреть список
существующих доменов и различную статистическую информацию.
Взаимодествие осуществляется через Libvirt – набор программ и библиотек
для работы с возможностями виртуализации последних версий Linux (и
других ОС). Виртуализация в ОС Linux подразумевает возможность
одновременного запуска нескольких независимых друг от друга инстанций
различных ОС на одном аппаратном обеспечении, где основные ресурсы
находятся под управлением Linux. Libvirt способен работать как с Xen так
и с QEmu и KVM.
Основная структура команды выполнит следующим образом:
virsh <command> <domain-id> [OPTIONS]
где command это одна из подкоманд, domain-id это числовой
идентификационный номер домена или его имя (которое может быть
автоматически транслировано в id), и OPTIONS это дополнительные
параметры специфичные для каждой команды. Правда есть несколько
исключений из этого правила, в основном это относится к командам
применительных для всех доменов, на всю машину или непосредственно на
гипервизор. Virsh может быть запущена без параметров, как
самостоятельная оболочка в которой можно будет выполнять встроенные
команды. Все операции virsh отдаются на выполнение libvirt который в
свою очередь обращается к xend/qemu или любой другой системе
виртуализации (которую он поддерживает). Учитывая это, следует при
загрузке запустить службу xend/qemu, обычно это делается с помощью
команды service start libvirtd (для RHEL/Fedora/CentOS). Большинство
команд virsh требуют прав root для общения с гипервизором, поэтому
команды выполненые из под непривилегированной учетной записи завершатся с
ошибкой. Также стоит отметить что выполнение некоторых команды virsh
занимает некоторое время (от 30 секунд и более) такие как создание или
выключение. Поэтому когда оболочка вернула приглашение для ввода
следующей команды, это не значит что операция инициированая предыдущей
командой уже завершилась, поэтому периодически следует выполнять ‘virsh
list’ для проверки состояния системы.
1. Общие команды. Следующие команды являются базовыми.
help – вывод списка доступных команд, help <command> выведет справку по конкретной программе;
quit – выход из virsh-терминала;
version – отображает версию ПО и версию используемого гипервизора;
connect URI [––readonly] – (пере-)подключиться к гипервизору. Это
команда является встроенной и запускается сразу после старта
virsh-шелла. Параметр URI может принимать следующие аргументы:
xen:/// – подключиться к xen гипервизору;
qemu:///system – подключиться к службе которая управляет QEmu\KVM-доменами и запущена из под root;
qemu:///session – подключиться к службе которая управляет QEmu\KVM-доменами и запущена из под непривилегированного пользователя.
c дополнительным параметром –readonly выполняется read-only подключение.
hostname – выводит имя хост-системы;
nodeinfo – выводит основную информацию об аппаратных характеристиках хост-системы (cpu, mem, sockets);
capabilities – вывод XML-документа в котором перечислены характеристики гипервизора к которому выполнено подключение;
list [ ––inactive | ––all ] – вывод информации о гостевых доменах. Без параметров выводит информацию о запущенных доменах;
freecell [cellno] – выводит количество свободно памяти хост-системы.
2. Команды применительные к доменам. Следующие команды позволяют
напрямую управлять доменами. Большинство команд требуют в качестве
первого параметра id домена. ID домена может быть указан в виде имени
либо в виде полного значения UUID.
autostart [––disable] <domain-id> – включить автозапуск домена при загрузке. Опция ––disable отключает автозапуск;
console <domain-id> – подключиться к консоли гостевого домена;
create <FILE> – создать домен из XML-файла. Эта команда запускает
домен описаный в файле, НО не сохраняет его конфигурацию; конфигурация
исчезнет после выключения домена;
define <FILE> – назначить домен из XML-файла. Будет создано описание домена, но сам домен не будет запущен;
destroy <domain-id> – немедленно завершить работу гостевого
домена. Эта команда не дает никакой возможности среагировать ОС
запущенной в госте, это эквивалентно выдергиванию шнура питания из
физической машины. В большинстве случаев вместо нее можно использовать
команду shutdown;
domblkstat <domain-name> <block-device> – получить статистику блочных устройств устройств для домена;
domifstat <domain-name> <interface-device> – получить статистику сетевого интерфейса для домена;
dominfo <domain-id> – вывод информации о домене;
domuuid <domain-name-or-id> – конвертация ID домена или его имени в полный UUID;
domid <domain-name> – конвертация доменного имени в ID;
domname <domain-id> – конвертация ID домена в имя;
domstate <domain-id> – вывод состояния указанного домена;
dump <domain-id> <corefilepath> – выполнить дамп ядра гостя в файл для последующего анализа;
dumpxml <domain-id> – вывод информации о домене в XML-формате.
Этот формат должен использоваться в командах create и define;
edit <domain-id> – редактировать XML-файл с конфигурацией домена;
migrate [––live] <domain-id> <desturi> <migrateuri> –
мигрировать домен на другой хост. Параметр –live применяется для живой
миграции. desturi это URI хост-системы назначения, и migrateuri это
URI миграции, который обычно опускают;
reboot <domain-id> – перезагрузить домен. Действие аналогичное если бы команда reboot была введена в консоли гостя;
save <domain-id> <state-file> - сохранение запущенного
домена в файл, из которого он может быть восстановлен позднее. Однажды
сохраненный, домен остается выключенным и высвобожденная память может
быть использована для нужд других доменов. Команда virsh restore
восстанавливает состояние машины. Это действие эквивалентно процессу
hibernate на запущенной машине, со всеми ее ограничениями, например
открытые сетевые соединения будут восстановлены, но TCP-таймауты будут
истекшими;
restore <state-file> – восстанавливает домен из сохраненного в файл состояния;
schedinfo [––set <parameter=value>] [––weight <number>]
[––cap <number>] <domain-id> – просмотр/установка параметров
планировщика в домене;
setmem <domain-id> <kilobytes> – изменить текущее выделение
памяти в гостевом домене. Действие немедленно вступает в силу. Значение
указывается в килобайтах;
setmaxmem <domain-id> <kilobytes> – изменить максимальное
значение выделенной памяти для гостевого домена. Это не меняет текущее
использование памяти в домене. Значение указывается в килобайтах;
setvcpus <domain-id> <count> – изменить количество
виртуальных процессоров в гостевом домене. Значение может быть
ограничено хост-системой, гипервизором или оригинальной конфигурацией
домена;
shutdown <domain-id> – выключить домен. Гостевая ОС выполняет
завершение работы, однако успешное завершение не гарантируется, это
зависит длины времени которое уходит на остановку служб в домене;
start <domain-name> – запустить (предварительно назначеный) неактивный домен;
suspend <domain-id> – приостановить запущенный домен. Он держится в памяти, но останавливает свою работу;
resume <domain-id> – запускает остановленный ранее домен.
Позволяет передать гипервизору ранее остановленный домен для продолжения
работы;
ttyconsole <domain-id> – показать устройство используемое в качестве TTY консоли домена;
undefine <domain-id> – удалить конфигурацию неактивного домена;
vcpuinfo <domain-id> – возвращает информацию о виртуальных
процессорах домена, такую как количество, время работы и привязку к
физическим процессорам;
vcpupin <domain-id> <vcpu> <cpulist> – назначить
виртуальный процессоры к физическим процессорам. Должен быть определен
параметр vcpu, cpulist это список физических процессоров перечисленных
через запятую (нумерация с нуля);
vncdisplay <domain-id> – вывод информации о ip-адресе и номере VNC-дисплея.
3. Команды для работы с устройствами. Следующие команды управляют
связанными с доменом устройствами. ID домена может быть указан в виде
имени либо в виде полного значения UUID. Чтобы лучше понять разрешенные
значения в параметрах команд, прочтите документацию о формате секции
устройств.
attach-device <domain-id> <FILE> – подключить устройство к домену, используя описание устройства из XML-файла;
attach-disk <domain-id> <source> <target> [––driver
<driver>] [––subdriver <subdriver>] [––type <type>]
[––mode <mode>] – добавить блочное устройство в домен:
<source> и <target> определяет пути к файлам и устройствам;
––driver может быть file, tap или phy в зависимости от типа доступа;
––type может быть cdrom или floppy в отличие от значения disk по умолчанию;
––mode может быть readonly или shareable(доступное для записи).
attach-interface <domain-id> <type> <source>
[––target <target>] [––mac <mac>] [––script <script>]
– добавить новый сетевой интерфейс в гостевой домен:
<type> может быть network(физическое подключение к сети) или bridge(подключение к сети через мостовое соединение);
<source это само устройство;
––target это целевое устройство в гостевом домене;
––mac позволяет определить mac-адрес;
––script позволяет указать путь к скрипту вместо использующегося по умолчанию;
detach-device <domain-id> <FILE> – отключить устройство
от домена. Необходимо тоже XML-описание как и при использовании
attach-device;
detach-disk <domain-id> <target> – отключить диск от домена. target это устройство видимое в гостевом домене;
detach-interface <domain-id> <type> [––mac <mac>] –
отключить сетевой интерфейс от домена. type может быть
network(физическое подключение к сети) или bridge(подключение к сети
через мостовое соединение). Если в системе несколько интерфейсов,
рекомендуется использовать опцию mac чтобы отличить их.
4. Команды управления виртуальным сетевым окружением. Следующие
команды позволяют управлять виртуальными сетями. Libvirt способен
назначать виртуальные сетевые окружения которые могут использоваться
доменами и могут быть сассоциированы с физическими интерфейсами. Для
более детальной информации можно прочесть документацию. Некоторые
команды для виртуальных сетей, подобны командам используемыми для
доменов и соответственно в параметрах, виртуальную сеть можно также
назвать по имени или по ее UUID.
net-autostart <network> [––disable] – включить автозапуск
виртуальной сети в при загрузке. Параметр ––disable отключает
автозапуск;
net-create <FILE> – создать виртуальную сеть из XML-файла;
net-define <FILE> – назначить сеть из XML-файла, но не запускать ее;
net-destroy <network> – удалить сеть. Действие вступает в силу незамедлительно;
net-dumpxml <network> – вывести информацию о виртуальной сети в XML-формате;
net-edit <network> – редактировать XML-файл с опсианием сети;
net-list [––inactive | ––all] – вывести список активных виртуальных
сетей. ––all отображает все сети, ––inactive отображает только
неактивные;
net-name <network-UUID> – конвертация UUID сети в ее имя;
net-start <network> – запустить (назначенную ранее) неактивную сеть;
net-undefine <network> – удалить конфигурацию неактивной сети;
net-uuid <network> – конвертация имени сети в ее UUID.
5. Команды управления “секретом”. Следующие команды управляют
“секретом” (пароли, секретные фразы, ключи шифрования). Libvirt может
хранить секретные данные независимо от их использования и другие
объекты (тома или домены) могут использовать их или ссылаться на них.
Секреты индентифицируются посредством UUID. Описание XML-формата
приведено здесь.
secret-define <FILE> – назначить секрет из XML-файла без ассоциации с секретным значением;
secret-dumpxml <secret> – вывод параметров секрета в XML-формате;
secret-set-value <secret> <base64> – установка значения
связанного с секретом (секретную информацию предварительно нужно
закодировать в base64);
secret-get-value <secret> – вывести значение секрета закодированное в base64;
secret-undefine <secret> – удалить секрет вместе с ассоциированым значением;
secret-list – вывести список секретов.
6. Команды управления сетевыми интерфейсами. Стоит отметить, чтобы
эти функции исправно работали необходимо чтобы в системе был установлен
пакет netcf и libvirt был собран с поддержкой netcf.
iface-list [––inactive|––all] – просмотреть список физических сетевых интерфейсов;
iface-name <interface> – конвертация mac-адреса интерфейса в его имя;
iface-mac <interface> – конвертация имени интерфейса в mac-адрес;
iface-dumpxml <interface> – вывод информации о сетевых интерфесах в XML-формате;
iface-define <FILE> – назначить (но не запускать) сетевой интерфейс из XML-файла;
iface-undefine <interface> – удалить конфигурацию сетевого интерфейса;
iface-edit <interface> – редактировать конфигурацию сетевого интерфейса;
iface-start <interface> – запустить сетевой интерфейс;
iface-destroy <interface> – остановить сетевой интерфейс.
7. Команды управления физическими устройствами. Следующие команды
позволяют пробрасывать физические устройства в виртуальные окружения.
nodedev-list [––tree] [––cap <string>] – просмотреть список доступных устройств;
nodedev-dumpxml <device> – вывод информации о устройстве в XML-формате;
nodedev-dettach <device> – отключить драйвер от устройства, перед последующим включением устройства в домен;
nodedev-reattach <device> – подключить драйвер к устройству после его извлечения из домена;
nodedev-reset <device> – выполнить сброс устройства, перед его включением в домен, или наоборот после извлечения;
nodedev-create <FILE> – создать устройство из XML-файла. Эта команда включает устройство, в виртуальную машину;
nodedev-destroy <name> – удалить устройство из виртуальной машины.
8. Команды управления пулами хранения. Пулы хранения могут
использоваться для хранения виртуальных дисков гостевых систем.
Подробнее здесь.
pool-autostart <pool> [––disable] – запускать пул автоматически
при загрузке системы. Параметр “––disable” отключает автозапуск;
pool-build <pool> – построить новый пул;
pool-create <FILE> – создать новый пул из XML-файла;
pool-create-as <name> [––print-xml] <type>
[<source-host>] [<source-path>] [<source-dev>]
[<source-name>] [<target>] – создать новый пул с набором
параметров:
<name> – имя пула;
––print-xml - напечатать XML-формат, но не назначать и не создавать конфигурацию;
<type> – тип создаваемого пула;
<source-host> – хост-источник для создаваемого хранилища (например localhost);
<source-path> - путь-источник для хранилища;
<source-dev> – устройство-источник для хранилища;
<source-name> – имя-источника для хранилища;
<target> – путь к хранилищу.
pool-define <FILE> – назначить (но не запускать) пул из XML-файла;
pool-define-as <name> [––print-xml] <type>
[<source-host>] [<source-path>] [<source-dev>]
[<source-name>] [<target>] – создать пул с набором
параметров:
<name> – имя пула;
––print-xml – напечатать XML-формат, но не назначать и не создавать конфигурацию;
<type> – тип создаваемого пула (dir, fs, netfs, logical, disk, scsi, iscsi, mpath);
<source-host> – хост-источник для создаваемого хранилища;
<source-path> – путь-источник для хранилища;
<source-dev> – устройство-источник для хранилища;
<source-name> - имя-источника для хранилища;
<target> – путь к хранилищу.
pool-destroy <pool> – остановить указанный пул;
pool-delete <pool> – удалить пул;
pool-dumpxml <pool> – вывести информацию о пуле в XML-формате;
pool-edit <pool> – редактировать XML-конфигурацию пула;
pool-info <pool> – вывести информацию о пуле;
pool-list [––inactive|––all] – вывести список пулов;
pool-name <uuid> – конвертация UUID пула в его имя;
pool-refresh <pool> – обновить состояние пула;
pool-start <pool> – запустить (предварительно назначеный) неактивный пул;
pool-undefine <pool> – удалить конфигурацию неактивного пула;
pool-uuid <pool> – конвертация имени пула в его UUID.
9. Команды управления томами. Тома используются в качестве виртуальных дисков в гостевых системах.
vol-create <pool> <FILE> – создать том из XML-файла в указанном пуле;
vol-create-from <pool> <FILE> [––inputpool <string>] <vol> – создать том, в указанном пуле;
vol-create-as <pool> <name> <capacity> [––allocation
<string>] [––format <string>] – создать том с набором
параметров, размер определяется суффиксами k, M, G, T; типы форматов:
raw – обычный файл
bochs – формат образа диска Bochs
cloop – формат сжатого loopback образа диска
cow – формат User Mode Linux
dmg – Mac формат
iso – CDROM формат
qcow – QEMU v1 формат
qcow2 – QEMU v2 формат
vmdk – VMWare формат
vpc – VirtualPC формат
vol-clone [––pool <string>] <vol> <newname> – клонировать существующий том;
vol-delete [––pool <string>] <vol> – удалить указанный том;
vol-dumpxml [––pool <string>] <vol> – вывести информацию о томе в XML-формате;
vol-info [––pool <string>] <vol> – вывести основную информацию о томе;
vol-list <pool> – вывести список томов в указанном пуле;
vol-path [––pool <string>] <vol> – показать путь к тому используя его имя;
vol-name <path> – сконвертировать путь тома в его имя (ориг.текст – convert a vol UUID to vol name);
vol-key <vol> – сконвертировать UUID тома в его имя. (не совсем понятно где взять UUID в XML-описании я его не увидел).
Авторами оригинальных текстов являются Andrew Puch, Daniel Veillard, Sean Dague (xm man page) и Daniel Stekloff.
Примеры:
назначить и запустить пул ‘test’ типа ‘dir’ размещенный в каталоге
/var/pooldir (каталог находится на устройстве /dev/volgroup00/var)
virsh> pool-create-as testpool dir localhost /var/pooldir /dev/volgroup00/var testpool /var/pooldir
virsh> pool-autostart testpool
создать том c именем server01-sdb, в пуле testpool, размером 8 Гб с форматом raw
virsh> vol-create-as testpool server01-sdb 8G ––format raw
подключить файл /var/testpool/server01-sdb к гостевой машине server01, как дополнительный диск sdb
virsh> attach-disk server01 /var/testpool/server01-sdb sdb ––driver file ––type disk
