STAPVIRT

Section: User Commands (1)
Page Index

JMÉNO

stapvirt - připravit libvirt domény pro sondování systemtapem

POUŽITÍ

stapvirt [-c URI] [-d PATH] [-v] COMMAND ARGUMENTS

POPIS

Program stapvirt slouží k přidání portů do domén, které obsluhuje libvirt (viz <http://libvirt.org/>). Tyto porty pak umí využít stap ke spuštění skriptů uvnitř těchto domén (viz volba '--remote' v manuálové stránce stap(1))

Porty se do definice domény přidávají příkazem port-add a odebírají se analogickým příkazem port-remove. Poznamenejme, že počet možných systemtap sezení odpovídá počtu dostupných portů.

Při použití alespoň libvirt v1.1.1 a QEMU v0.10.0 mohou být porty přidávány a odebírány za běhu (hotpllugging). V tomto případě není iniciální port-add nutný.

Aby bylo možné se k portům přidaným za běhu připojit, je třeba zaručit, aby ovladač virtio-serial byl aktivní. Při vytváření domény programem virt-install se toho dá dosáhnout takto:

$ virt-install [...] --controller=virtio-serial

Pokud již doména existuje, použijte port-add, port-remove, a následně doménu restartujte. Port byl odebrán, ale ovladač zůstane na místě.

VOLBY

Podporují se následující volby. Jakákoliv jiná volba způsobí výpis nápovědy.

-c URI: Určí URI libvirt ovladače ke kterému se plánujeme připojit (např. 'qemu:///system'). NULL je také bezpečná hodnota, která představuje žádost o připojení k výchozímu ovladači. Kompletní seznam podporovaných hodnot shrnuje <http://libvirt.org/uri.html>.
-d PATH: Určuje adresář pro UNIX sokety odpovídající přidaným portům. Výchozí adresář je '/var/lib/libvirt/qemu'.
-v: Zvýšit upovídanost. Volbu lze opakovat pro další zvýšení povídanosti.

PŘÍKAZY

Program stapvirt přijímá následující příkazy. Jiný příkaz způsobí vypsání nápovědy.

help: Zobrazit nápovědu.
list: Vypsat dostupné domény.
port-add DOMAIN: Trvale přidat port do definice domény. Pokud doména zrovna běží, je nutné ji restartovat, aby změny byly efektivní.
port-list DOMAIN: Vypíše seznam cest k UNIX soketům, které odpovídají SystemTap portům v definici domény.
port-remove DOMAIN: Odstraní port z definice domény. Pokud doména právě běží, je nutno ji restartovat, aby změny byly efektivní.
query DOMAIN: Zobrazit následující informace o doméně: jméno, UUID, stav, čísla SystemTap portů, a zda je podporován "hotpllugging", tj. přidávání a odebírání portů za běhu.

TUTORIÁl

Následuje lehký úvod do stapvirtu. Začněme vypsáním privilegovaných domén:

$ stapvirt -c 'qemu:///system' list
Available domains on URI 'qemu:///system':
ID      State     Type        Name
2       running   persistent  TestVM

Poznamenejme, že jsme určili URI pomocí přepínače -c. Jinak by mohl libvirt použít výchozí hodnotu, např. 'qemu:///session'.

Namísto opakovaného zadávání URI může být pohodlnější nastavit odpovídající proměnnou prostředí LIBVIRT_DEFAULT_URI a přepínač -c napříště vynechat (poznamenejme, že toto je funkcionalita libvirtu, viz <libvirt.org/uri.html> ).

Příkaz list ukazuje, že doména 'TestVM' běží a má ID 2. Použijme příkaz query abychom zjistili podrobnosti:

$ stapvirt query TestVM # by name
$ stapvirt query 2      # by ID

              Name:  TestVM
              UUID:  905951c0-fa4f-409b-079c-c91ddda27028
             State:  running
                ID:  2
              Type:  persistent
   Permanent Ports:  0
       Hotplugging:  not supported

Příkaz query dává základní informace o doméně, jako UUID a stav. Z důležitějších informací jsou to pak čísla permanentních portů, a zda je podporován "hotplugging" (což technicky vzato závisí na libvirt a qemu a nesouvisí přímo s doménou).

Kdyby byl podporován "hotplugging", mohli bychom zde skončit a spustit přímo stap (s tím, že ovladač virtio-serial je dostupný, viz POPIS). Ale protože "hotplugging" v našem případě není podporován, musíme přidat porty ručně příkazem port-add:

$ stapvirt port-add TestVM
Added new port org.systemtap.stapsh.0
The domain must be powered off before changes take effect.

Ověřit, že port byl přidán, můžeme opět příkazem query:

$ stapvirt query TestVM
...
   Permanent Ports:  1
       Hotplugging:  not supported

Nyní máme k dispozici 1 permanentní port. Pro více podrobností můžeme zavolat příkaz port-list:

$ stapvirt port-list TestVM
/var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock

Po restartu domény už můžeme zavádět systemtap sondy příkazem stap:

$ stap -e 'probe begin { printf("Hello from TestVM!\n"); exit() }' \
       --remote=libvirt://TestVM
Hello from TestVM!

Na závěr můžeme použitý port opět odebrat příkazem port-remove:

$ stapvirt port-remove TestVM
Removed port org.systemtap.stapsh.0
The domain must be powered off before changes take effect.

A to je vše!

VIZ TÉŽ

stap(1),
virt-install(1)

CHYBY

Použijte projektovou bugzillu, nebo mailing list. http://sourceware.org/systemtap/, <systemtap@sourceware.org>.

error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs