STAPVIRT(1)

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