.\" -*- nroff -*- .TH STAPVIRT 1 .SH JMÉNO stapvirt \- připravit libvirt domény pro sondování systemtapem .\" macros .de SAMPLE .nr oldin \\n(.i .br .RS .nf .nh .. .de ESAMPLE .hy .fi .RE .in \\n[oldin]u .. .SH POUŽITÍ \fBstapvirt\fR [\fB-c\fR \fIURI\fR] [\fB-d\fR \fIPATH\fR] [\fB-v\fR] \fICOMMAND\fR \fIARGUMENTS\fR .SH POPIS Program \fIstapvirt\fR slouží k přidání portů do domén, které obsluhuje libvirt (viz .nh ). .hy Tyto porty pak umí využít \fIstap\fR ke spuštění skriptů uvnitř těchto domén (viz volba '--remote' v manuálové stránce \fIstap\fR(1)) .PP Porty se do definice domény přidávají příkazem \fBport-add\fR a odebírají se analogickým příkazem \fBport-remove\fR. Poznamenejme, že počet možných systemtap sezení odpovídá počtu dostupných portů. .PP 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í \fBport-add\fR nutný. .PP 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: .SAMPLE \fB$\fR virt-install [...] --controller=virtio-serial .ESAMPLE Pokud již doména existuje, použijte \fBport-add\fR, \fBport-remove\fR, a následně doménu restartujte. Port byl odebrán, ale ovladač zůstane na místě. .SH VOLBY Podporují se následující volby. Jakákoliv jiná volba způsobí výpis nápovědy. .IP "\fB-c\fR \fIURI\fR" 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 . .IP "\fB-d\fR \fIPATH\fR" Určuje adresář pro UNIX sokety odpovídající přidaným portům. Výchozí adresář je '/var/lib/libvirt/qemu'. .IP "\fB-v\fR" Zvýšit upovídanost. Volbu lze opakovat pro další zvýšení povídanosti. .SH PŘÍKAZY Program stapvirt přijímá následující příkazy. Jiný příkaz způsobí vypsání nápovědy. .IP "\fBhelp\fR" Zobrazit nápovědu. .IP "\fBlist\fR" Vypsat dostupné domény. .IP "\fBport-add\fR \fIDOMAIN\fR" Trvale přidat port do definice domény. Pokud doména zrovna běží, je nutné ji restartovat, aby změny byly efektivní. .IP "\fBport-list\fR \fIDOMAIN\fR" Vypíše seznam cest k UNIX soketům, které odpovídají SystemTap portům v definici domény. .IP "\fBport-remove\fR \fIDOMAIN\fR" Odstraní port z definice domény. Pokud doména právě běží, je nutno ji restartovat, aby změny byly efektivní. .IP "\fBquery\fR \fIDOMAIN\fR" 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. .SH TUTORIÁl Následuje lehký úvod do stapvirtu. Začněme vypsáním privilegovaných domén: .SAMPLE \fB$\fR stapvirt -c 'qemu:///system' list Available domains on URI 'qemu:///system': ID State Type Name 2 running persistent TestVM .ESAMPLE Poznamenejme, že jsme určili URI pomocí přepínače \-c. Jinak by mohl libvirt použít výchozí hodnotu, např. 'qemu:///session'. .PP Namísto opakovaného zadávání URI může být pohodlnější nastavit odpovídající proměnnou prostředí .nh LIBVIRT_DEFAULT_URI .ni a přepínač \-c napříště vynechat (poznamenejme, že toto je funkcionalita libvirtu, viz .nh .hy ). .PP Příkaz \fBlist\fR ukazuje, že doména 'TestVM' běží a má ID 2. Použijme příkaz \fBquery\fR abychom zjistili podrobnosti: .SAMPLE \fB$\fR stapvirt query TestVM # by name \fB$\fR 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 .ESAMPLE Příkaz \fBquery\fR 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). .PP Kdyby byl podporován "hotplugging", mohli bychom zde skončit a spustit přímo \fIstap\fR (s tím, že ovladač virtio-serial je dostupný, viz \fBPOPIS\fR). Ale protože "hotplugging" v našem případě není podporován, musíme přidat porty ručně příkazem \fBport-add\fR: .SAMPLE \fB$\fR stapvirt port-add TestVM Added new port org.systemtap.stapsh.0 The domain must be powered off before changes take effect. .ESAMPLE Ověřit, že port byl přidán, můžeme opět příkazem \fBquery\fR: .SAMPLE \fB$\fR stapvirt query TestVM \fB...\fR Permanent Ports: 1 Hotplugging: not supported .ESAMPLE Nyní máme k dispozici 1 permanentní port. Pro více podrobností můžeme zavolat příkaz \fBport-list\fR: .SAMPLE \fB$\fR stapvirt port-list TestVM /var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock .ESAMPLE Po restartu domény už můžeme zavádět systemtap sondy příkazem \fIstap\fR: .SAMPLE \fB$\fR stap -e 'probe begin { printf("Hello from TestVM!\\n"); exit() }' \\ --remote=libvirt://TestVM Hello from TestVM! .ESAMPLE Na závěr můžeme použitý port opět odebrat příkazem \fBport-remove\fR: .SAMPLE \fB$\fR stapvirt port-remove TestVM Removed port org.systemtap.stapsh.0 The domain must be powered off before changes take effect. .ESAMPLE A to je vše! .SH VIZ TÉŽ .nh .nf .IR stap (1), .IR virt-install (1) .SH CHYBY Použijte projektovou bugzillu, nebo mailing list. .nh .BR http://sourceware.org/systemtap/ ", " . .hy .PP .IR error::reporting (7stap), .BR https://sourceware.org/systemtap/wiki/HowToReportBugs .hy