Debian Codegraph @

man/cs/stapvirt.1

raw
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