| 1 |
.\" -*- nroff -*- |
| 2 |
.TH STAPVIRT 1 |
| 3 |
.SH JMÉNO |
| 4 |
stapvirt \- připravit libvirt domény pro sondování systemtapem |
| 5 |
|
| 6 |
.\" macros |
| 7 |
.de SAMPLE |
| 8 |
|
| 9 |
.nr oldin \\n(.i |
| 10 |
.br |
| 11 |
.RS |
| 12 |
.nf |
| 13 |
.nh |
| 14 |
.. |
| 15 |
.de ESAMPLE |
| 16 |
.hy |
| 17 |
.fi |
| 18 |
.RE |
| 19 |
.in \\n[oldin]u |
| 20 |
|
| 21 |
.. |
| 22 |
|
| 23 |
.SH POUŽITÍ |
| 24 |
\fBstapvirt\fR |
| 25 |
[\fB-c\fR \fIURI\fR] |
| 26 |
[\fB-d\fR \fIPATH\fR] |
| 27 |
[\fB-v\fR] |
| 28 |
\fICOMMAND\fR |
| 29 |
\fIARGUMENTS\fR |
| 30 |
|
| 31 |
.SH POPIS |
| 32 |
|
| 33 |
Program \fIstapvirt\fR slouží k přidání portů do domén, které obsluhuje |
| 34 |
libvirt (viz |
| 35 |
.nh |
| 36 |
<http://libvirt.org/>). |
| 37 |
.hy |
| 38 |
Tyto porty pak umí využít \fIstap\fR ke spuštění skriptů uvnitř těchto domén |
| 39 |
(viz volba '--remote' v manuálové stránce \fIstap\fR(1)) |
| 40 |
|
| 41 |
.PP |
| 42 |
Porty se do definice domény přidávají příkazem \fBport-add\fR a odebírají se |
| 43 |
analogickým příkazem \fBport-remove\fR. Poznamenejme, že počet možných systemtap |
| 44 |
sezení odpovídá počtu dostupných portů. |
| 45 |
|
| 46 |
.PP |
| 47 |
Při použití alespoň libvirt v1.1.1 a QEMU v0.10.0 mohou být porty přidávány a |
| 48 |
odebírány za běhu (hotpllugging). V tomto případě není iniciální \fBport-add\fR |
| 49 |
nutný. |
| 50 |
|
| 51 |
.PP |
| 52 |
Aby bylo možné se k portům přidaným za běhu připojit, je třeba zaručit, aby |
| 53 |
ovladač virtio-serial byl aktivní. Při vytváření domény programem virt-install |
| 54 |
se toho dá dosáhnout takto: |
| 55 |
.SAMPLE |
| 56 |
\fB$\fR virt-install [...] --controller=virtio-serial |
| 57 |
.ESAMPLE |
| 58 |
Pokud již doména existuje, použijte \fBport-add\fR, \fBport-remove\fR, a |
| 59 |
následně doménu restartujte. Port byl odebrán, ale ovladač zůstane na místě. |
| 60 |
|
| 61 |
.SH VOLBY |
| 62 |
Podporují se následující volby. Jakákoliv jiná volba způsobí výpis nápovědy. |
| 63 |
|
| 64 |
.IP "\fB-c\fR \fIURI\fR" |
| 65 |
Určí URI libvirt ovladače ke kterému se plánujeme připojit (např. 'qemu:///system'). |
| 66 |
NULL je také bezpečná hodnota, která představuje žádost o připojení k výchozímu |
| 67 |
ovladači. Kompletní seznam podporovaných hodnot shrnuje <http://libvirt.org/uri.html>. |
| 68 |
|
| 69 |
.IP "\fB-d\fR \fIPATH\fR" |
| 70 |
Určuje adresář pro UNIX sokety odpovídající přidaným portům. Výchozí adresář |
| 71 |
je '/var/lib/libvirt/qemu'. |
| 72 |
|
| 73 |
.IP "\fB-v\fR" |
| 74 |
Zvýšit upovídanost. Volbu lze opakovat pro další zvýšení povídanosti. |
| 75 |
|
| 76 |
.SH PŘÍKAZY |
| 77 |
Program stapvirt přijímá následující příkazy. Jiný příkaz způsobí vypsání |
| 78 |
nápovědy. |
| 79 |
|
| 80 |
.IP "\fBhelp\fR" |
| 81 |
Zobrazit nápovědu. |
| 82 |
|
| 83 |
.IP "\fBlist\fR" |
| 84 |
Vypsat dostupné domény. |
| 85 |
|
| 86 |
.IP "\fBport-add\fR \fIDOMAIN\fR" |
| 87 |
Trvale přidat port do definice domény. Pokud doména zrovna běží, je nutné ji |
| 88 |
restartovat, aby změny byly efektivní. |
| 89 |
|
| 90 |
.IP "\fBport-list\fR \fIDOMAIN\fR" |
| 91 |
Vypíše seznam cest k UNIX soketům, které odpovídají SystemTap portům v definici |
| 92 |
domény. |
| 93 |
|
| 94 |
.IP "\fBport-remove\fR \fIDOMAIN\fR" |
| 95 |
Odstraní port z definice domény. Pokud doména právě běží, je nutno ji |
| 96 |
restartovat, aby změny byly efektivní. |
| 97 |
|
| 98 |
.IP "\fBquery\fR \fIDOMAIN\fR" |
| 99 |
Zobrazit následující informace o doméně: jméno, UUID, stav, čísla SystemTap |
| 100 |
portů, a zda je podporován "hotpllugging", tj. přidávání a odebírání portů za |
| 101 |
běhu. |
| 102 |
|
| 103 |
.SH TUTORIÁl |
| 104 |
Následuje lehký úvod do stapvirtu. Začněme vypsáním privilegovaných domén: |
| 105 |
|
| 106 |
.SAMPLE |
| 107 |
\fB$\fR stapvirt -c 'qemu:///system' list |
| 108 |
Available domains on URI 'qemu:///system': |
| 109 |
ID State Type Name |
| 110 |
2 running persistent TestVM |
| 111 |
.ESAMPLE |
| 112 |
|
| 113 |
Poznamenejme, že jsme určili URI pomocí přepínače \-c. Jinak by mohl libvirt |
| 114 |
použít výchozí hodnotu, např. 'qemu:///session'. |
| 115 |
.PP |
| 116 |
Namísto opakovaného zadávání URI může být pohodlnější nastavit odpovídající |
| 117 |
proměnnou prostředí |
| 118 |
.nh |
| 119 |
LIBVIRT_DEFAULT_URI |
| 120 |
.ni |
| 121 |
a přepínač \-c napříště vynechat (poznamenejme, že toto je funkcionalita |
| 122 |
libvirtu, viz |
| 123 |
.nh |
| 124 |
<libvirt.org/uri.html> |
| 125 |
.hy |
| 126 |
). |
| 127 |
.PP |
| 128 |
Příkaz \fBlist\fR ukazuje, že doména 'TestVM' běží a má ID 2. Použijme příkaz |
| 129 |
\fBquery\fR abychom zjistili podrobnosti: |
| 130 |
|
| 131 |
.SAMPLE |
| 132 |
\fB$\fR stapvirt query TestVM # by name |
| 133 |
\fB$\fR stapvirt query 2 # by ID |
| 134 |
|
| 135 |
Name: TestVM |
| 136 |
UUID: 905951c0-fa4f-409b-079c-c91ddda27028 |
| 137 |
State: running |
| 138 |
ID: 2 |
| 139 |
Type: persistent |
| 140 |
Permanent Ports: 0 |
| 141 |
Hotplugging: not supported |
| 142 |
.ESAMPLE |
| 143 |
|
| 144 |
Příkaz \fBquery\fR dává základní informace o doméně, jako UUID a stav. Z |
| 145 |
důležitějších informací jsou to pak čísla permanentních portů, a zda je podporován |
| 146 |
"hotplugging" (což technicky vzato závisí na libvirt a qemu a nesouvisí přímo |
| 147 |
s doménou). |
| 148 |
|
| 149 |
.PP |
| 150 |
Kdyby byl podporován "hotplugging", mohli bychom zde skončit a spustit přímo |
| 151 |
\fIstap\fR (s tím, že ovladač virtio-serial je dostupný, viz \fBPOPIS\fR). Ale |
| 152 |
protože "hotplugging" v našem případě není podporován, musíme přidat porty ručně |
| 153 |
příkazem \fBport-add\fR: |
| 154 |
|
| 155 |
.SAMPLE |
| 156 |
\fB$\fR stapvirt port-add TestVM |
| 157 |
Added new port org.systemtap.stapsh.0 |
| 158 |
The domain must be powered off before changes take effect. |
| 159 |
.ESAMPLE |
| 160 |
|
| 161 |
Ověřit, že port byl přidán, můžeme opět příkazem \fBquery\fR: |
| 162 |
|
| 163 |
.SAMPLE |
| 164 |
\fB$\fR stapvirt query TestVM |
| 165 |
\fB...\fR |
| 166 |
Permanent Ports: 1 |
| 167 |
Hotplugging: not supported |
| 168 |
.ESAMPLE |
| 169 |
|
| 170 |
Nyní máme k dispozici 1 permanentní port. Pro více podrobností můžeme zavolat |
| 171 |
příkaz \fBport-list\fR: |
| 172 |
|
| 173 |
.SAMPLE |
| 174 |
\fB$\fR stapvirt port-list TestVM |
| 175 |
/var/lib/libvirt/qemu/TestVM.org.systemtap.stapsh.0.sock |
| 176 |
.ESAMPLE |
| 177 |
|
| 178 |
Po restartu domény už můžeme zavádět systemtap sondy příkazem \fIstap\fR: |
| 179 |
|
| 180 |
.SAMPLE |
| 181 |
\fB$\fR stap -e 'probe begin { printf("Hello from TestVM!\\n"); exit() }' \\ |
| 182 |
--remote=libvirt://TestVM |
| 183 |
Hello from TestVM! |
| 184 |
.ESAMPLE |
| 185 |
|
| 186 |
Na závěr můžeme použitý port opět odebrat příkazem \fBport-remove\fR: |
| 187 |
|
| 188 |
.SAMPLE |
| 189 |
\fB$\fR stapvirt port-remove TestVM |
| 190 |
Removed port org.systemtap.stapsh.0 |
| 191 |
The domain must be powered off before changes take effect. |
| 192 |
.ESAMPLE |
| 193 |
|
| 194 |
A to je vše! |
| 195 |
|
| 196 |
.SH VIZ TÉŽ |
| 197 |
.nh |
| 198 |
.nf |
| 199 |
.IR stap (1), |
| 200 |
.IR virt-install (1) |
| 201 |
|
| 202 |
.SH CHYBY |
| 203 |
Použijte projektovou bugzillu, nebo mailing list. |
| 204 |
.nh |
| 205 |
.BR http://sourceware.org/systemtap/ ", " <[email protected]> . |
| 206 |
.hy |
| 207 |
.PP |
| 208 |
.IR error::reporting (7stap), |
| 209 |
.BR https://sourceware.org/systemtap/wiki/HowToReportBugs |
| 210 |
.hy |