Debian Codegraph @

man/cs/systemtap.8.in

raw
1 .\" -*- nroff -*-
2 .TH SYSTEMTAP 8
3 .SH JMÉNO
4 systemtap \- systemtap initskript služba
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 .B service systemtap
25 .IR COMMAND " [" OPTIONS "] [" SCRIPT ...]
26
27 .SH POPIS
28 SystemTap initskript služba umožňuje spouštět systemtap skripty jako systémové služby a
29 pohodlně je ovládat. Skripty mohou být nastartovány na individuální žádost, nebo
30 při startu systému. Na systémech, které využívají dracut je také možné umístit
31 skripty do initramfs a mít je spuštěné během boot procesu.
32
33 Existují volby a parametry, které ovlivňují globální chování služby nebo
34 jednotlivých skriptů. Mezi skripty lze vytvořit závislosti, tak že nastartování
35 jednoho automaticky způsobí nastartování jiného.
36
37 Konfigurační soubor initskriptu se nachází v
38 \fB@sysconfdir@/systemtap/config\fR. Přijatelné parametry jsou detailně popsány
39 v sekci GLOBÁLNÍ PARAMETRY.
40
41 Skript musí být umístěn v adresáři \fB@sysconfdir@/systemtap/script.d\fR a musí
42 mít příponu \fB.stp\fR. Poznamenejme, že když se systemtap skripty pouštějí z
43 příkazové řádky, jak je obvyklé, není přípona \fB.stp\fR povinná. Jméno skriptu
44 smí obsahovat jen alfanumerické znaky a '_', a nesmí začínat číslem. Adresář pro
45 skripty lze změnit nastavením parametru SCRIPT_PATH v konfiguračním souboru.
46
47 .SH PŘÍKAZY
48 Musí být uveden jeden z následující příkazů:
49
50 .TP
51 .B start
52 Start skriptů. Pokud žádné skripty nebyly určeny, nastartují se skripty určené
53 nastavením DEFAULT_START. Pokud DEFAULT_START není nastaveno, nastartují se
54 všechny skripty v adresáři skriptů. Pro skripty, které již běží se příkaz "start"
55 ignoruje. Příkaz "start" selže, pokud start skriptů selže (viz též nastavení
56 PASSALL).
57
58 Pokud je zapnutá volba AUTOCOMPILE, příkaz se pokusí sestavit (nebo obnovit
59 sestavení) skriptů v případě, že je platná jedna z následujících podmínek:
60 .RS
61 .IP - 2
62 Cache se zkompilovanými skripty neexistuje.
63 .IP -
64 Čas modifikace (mtime) původního skriptu se změnil.
65 .IP -
66 Skript se spouští s jinými volbami.
67 .IP -
68 Změnil se výstup `uname -a`.
69 .RE
70
71 .TP
72 .B stop
73 Zastavit skripty. Pokud žádné skripty nebyly určeny, zastaví se všechny běžící
74 skripty. Pro skripty, které neběží, se tento příkaz bude ignorovat. Příkaz selže
75 pokud selže zastavení některého ze skriptů (viz též nastavení PASSALL).
76
77 .TP
78 .B restart
79 Zastavit a opět nastartovat skripty.
80
81 .TP
82 .B status
83 Zobrazit stav skriptů a jejich závislosti.
84
85 .TP
86 .B compile
87 Přeložit skripty, ale nestartovat je. Pokud skripty již byly přeloženy, dotázat
88 se na potvrzení dříve, než dojde k přepsání cache. Kompilovat pro běžící jádro,
89 nebo pro jádro určené prostřednictvím volby \fB-r\fR.
90
91 .TP
92 .B onboot
93 Učinit určené skripty součástí initramfs, aby mohly být spuštěny během startu stroje.
94 Tento příkaz je dostupný jen na systémech, které používají dracut. Pokud se neurčí
95 žádný skript, všechny systemtap skripty se z initramfs odstraní.
96
97 Initramfs se vytváří pro aktuální jádro, nebo pro jádro určené volbou \fB-r\fR.
98 Výchozí umístění initramfs je \fB/boot/initramfs-KVER.img\fR, kde KVER odpovídá
99 výstupu `uname -r`. Příkaz "onboot" dále obnoví nastavení zavaděče systému tak,
100 aby byl použit nový initramfs. Pokud se má vytvořit initramfs v jiném umístění,
101 použijte volbu \fB-o\fR. V tomto případě se nastavení zavaděče systému nezmění.
102
103 Pokud výstupní soubor již existuje, bude přepsán pokud není dán přepínač \fB-b\fR
104 , kdy se původnímu souboru přidá přípona \fB.bak\fR namísto přepsání. Pokud ale
105 \fB.bak\fR soubor již existuje, nebude přepsán.
106
107 UPOZORNĚNÍ: Nepoužívejte volbu \fB-o\fR příkazu \fIstap\fR(1) u "onboot" skriptů,
108 protože skript poběží dříve, než se namountuje kořenový souborový systém. Pokud
109 potřebujete více místa pro výstup, zvětšete velikost bufferu.
110
111 .TP
112 .B cleanup
113 Odstranit specifikované skripty z cache. Pokud není specifikován žádný skript,
114 budou smazány všechny. Smaže se jen cache pro aktuální jádro, nebo pro jádro
115 určené volbou \fB-r\fR. Před smazáním cache bude požadováno potvrzení.
116
117 .SH VOLBY
118 Některé příkazy přijímají volby. Nicméně, protože uživatelé nemohou předávat
119 volby při zavádění OS, jsou volby určeny pouze pro ovládání skriptů běžících až
120 po nabootování systému a pro testování.
121
122 .TP
123 .BI "-c " CONFIG_FILE
124 Určuje alternativní konfigurační soubor.
125
126 .TP
127 .B -R
128 Při použití s \fBstart\fR a \fBstop\fR příkazy značí, že mají být vzaty v potaz
129 závislosti mezi skripty a to rekurzivně.
130
131 .TP
132 .BI "-r " KERNEL_RELEASE
133 Při použití s \fBcompile\fR, \fBonboot\fR, a \fBcleanup\fR příkazy, určuje cílové
134 jádro. Formát KERNEL_RELEASE musí odpovídat formátu `uname -r`.
135
136 .TP
137 .B -y
138 Odpověz ano na všechny dotazy.
139
140 .TP
141 .BI "-o " PATH.IMG
142 Při použití s příkazem \fBonboot\fR určuje umístění initramfs. Pokud se určí,
143 konfigurace zavaděče se nezmění. Pokud určen není, konfigurace zavaděče se změní
144 tak, aby byl při následujícím startu použit nový initramfs.
145
146 .TP
147 .B -b
148 Při použití s příkazem \fBonboot\fR, zazálohuje existující initramfs připojením
149 přípony \fB.bak\fR namísto aby existující initramfs přepsal, což se stane není-li
150 tato volba použita.
151
152 .SH GLOBÁLNÍ PARAMETRY
153 Tyto parametry ovlivňují obecné chování služby. Nastavují se v konfiguračním
154 souboru.
155
156 .TP
157 .B SCRIPT_PATH
158 Určuje absolutní cestu adresáře pro skripty, se kterými může služba pracovat.
159 Skripty musí mít příponu \fB.stp\fR. Výchozí hodnota je
160 \fB@sysconfdir@/systemtap/script.d\fR.
161
162 .TP
163 .B CONFIG_PATH
164 Určuje absolutní cestu adresáře pro konfigurační soubory skriptů.
165 Tyto konfigurační soubory obsahují volby specifické pro jednotlivé skripty. Musí
166 mít příponu \fB.conf\fR. Výchozí umístění je \fB@sysconfdir@/systemtap/conf.d\fR.
167
168 .TP
169 .B CACHE_PATH
170 Umístění cache adresáře. Výchozí umístění je \fB@localstatedir@/cache/systemtap\fR.
171
172 .TP
173 .B TEMP_PATH
174 Umístění dočasného adresáře, kam systemtap odkládá dočasné soubory, které vznikají
175 při kompilaci systemtap jaderného modulu. Výchozí umístění je \fB/tmp\fR.
176
177 .TP
178 .B STAT_PATH
179 Absolutní cesta k adresáři se stavovými soubory pro jednotlivé skripty. Výchozí
180 umístění je \fB@localstatedir@/run/systemtap\fR.
181
182 .TP
183 .B LOG_FILE
184 Absolutní cesta k logovacímu souboru. Všechny zprávy se posílají do tohoto
185 souboru (včetně kompilačních chybových hlášení a hlášení o chybách běhu).
186 Výchozí umístění je \fB@localstatedir@/log/systemtap.log\fR.
187
188 .TP
189 .B PASSALL
190 Pokud tato volba je nastavena (\fByes\fR), pak systemtap služba pracující s mnoha
191 skripty zahlásí chybu, pokud kterýkoliv ze skriptů zhavaruje. Pokud tato volba
192 není nastavena (\fBno\fR) vypíše systemtap služba v takovém případě jen varování.
193
194
195 .TP
196 .B RECURSIVE
197 Pokud tato volba je nastavena (\fByes\fR), služba systemtap bude brát v potaz
198 závislosti mezi skripty a to rekurzivně (odpovídá volbě \fB-R\fR). Tato volba
199 je platná jen pokud byly na příkazové řádce určeny skripty. Výchozí hodnota je
200 \fBno\fR.
201
202 .TP
203 .B AUTOCOMPILE
204 Pokud je tato volba nastavena (\fByes\fR), služba systemtap se pokusí zkompilovat
205 určené skripty pokud nenalezne odpovídající validní položky v cache.
206 Jinak související příkaz selže. Výchozí hodnota je \fByes\fR.
207
208 .TP
209 .B DEFAULT_START
210 Určuje skripty, které se mají nastartovat jako výchozí. Pokud je tato volba
211 vynechána (nebo nastavena na prázdnou hodnotu), nastartují se všechny skripty v
212 adresáři. Výchozí hodnota je \fB""\fR.
213
214 .TP
215 .B ALLOW_CACHEONLY
216 Pokud je tato volba nastaveba (\fByes\fR), služba umožní nastartování také
217 skriptům, pro něž existují v cache validní data, ale v adresáři pro skripty jejich
218 zdrojový kód chybí. Výchozí hodnota je \fBno\fR.
219
220 VAROVÁNÍ: S touto volbou může služba nastartovat neočekávané skripty nacházející
221 se v cache. Před startem služby je vhodné obsah cache zkontrolovat.
222
223 .TP
224 .B LOG_BOOT_ERR
225 Protože "boot-time" skripty se spouštějí dříve než je namountován kořenový
226 souborový systém, nelze chybový výstup programy staprun posílat do LOG_FILE
227 jak je obvyklé. Nicméně log lze přesměrovat do /run/systemtap/$script.log
228 nastavením LOG_BOOT_ERR na \fByes\fR. Pokud STAT_PATH je odlišná od výchozí
229 hodnoty, budou logovací soubory přesunuty na požadované místo dříve, než se
230 spustí jakýkoliv příkaz služby. Výchozí hodnota je \fBno\fR.
231
232 .PP
233 Zde je ukázka konfiguračního souboru.
234 .SAMPLE
235 SCRIPT_PATH=/var/systemtap/script.d/
236 PASSALL=yes
237 RECURSIVE=no
238 .ESAMPLE
239
240 .SH PARAMETRY SKRIPTŮ
241 Tyto parametry ovlivňují kompilaci skriptů, nebo jejich chování za běhu.
242 Nastavují se v konfiguračních souborech umístěných v adresáři CONFIG_PATH.
243
244 .TP
245 .B <SCRIPT>_OPT
246 Určuje volby, které se předají příkazu \fIstap\fR(1) před vykonáním skriptu.
247 Zde SCRIPT je jméno skriptu bez přípony \fB.stp\fR. Poznamenejme, že volba
248 \fB-F\fR se použije vždy.
249
250 Při kompilaci skriptů se ignorují následující volby: -p, -m, -r, -c, -x,
251 -e, -s, -o, -h, -V, -k.
252
253 Při spouštění skriptů se ignorují následující volby: -h, -V, -v, -t,
254 -p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F, a
255 všechny dlouhé volby.
256
257 .TP
258 .B <SCRIPT>_REQ
259 Určuje závislosti skriptu (t.j. určuje, který skript je vyžadován daným
260 skriptem). Pokud foo.stp vyžaduje (nebo potřebuje běžet po) bar.stp, nastavte
261 .SAMPLE
262 foo_REQ="bar"
263 .ESAMPLE
264 Více skriptů lze nastavit jako mezerami oddělený seznam.
265
266 .PP
267 Příklad konfiguračního souboru:
268 .SAMPLE
269 script1_OPT="-o /var/log/script1.out"
270 script2_OPT="-o /var/log/script2.out"
271 script2_REQ="script1"
272 .ESAMPLE
273
274 .SH PŘÍKLADY
275
276 .TP
277 .B INSTALACE SKRIPTŮ
278 Nakopírujme SystemTap skript (např. "script1.stp") do relevantního adresáře:
279 .SAMPLE
280 \fB#\fR cp script1.stp /etc/systemtap/script.d/
281 .ESAMPLE
282 Pak můžeme nastavit volby pro daný skript. Například:
283 .SAMPLE
284 \fB#\fR vi /etc/systemtap/conf.d/group1
285 script1_OPT="-o /var/log/group1.out"
286 .ESAMPLE
287 Pokud poté nainstalujeme skript, např. "script2.stp", který má být spuštěn po
288 "script1.stp", máme zde závislost mezi skripty. Tu ošetříme následovně:
289 .SAMPLE
290 \fB#\fR cp script2.stp /etc/systemtap/script.d/
291 \fB#\fR vi /etc/systemtap/conf.d/group1
292 script2_OPT="-o /var/log/group2.out"
293 script2_REQ="script1"
294 .ESAMPLE
295 V tomto případě, pokud \fIstap\fR(1) selže při startu, služba SystemTap se ani
296 nepokusí nastartovat script2.
297
298 .TP
299 .B TESTOVÁNÍ
300 Po nainstalování skriptů můžeme ověřit, že fungují takto:
301 .SAMPLE
302 \fB#\fR service systemtap start
303 \fB#\fR service systemtap stop
304 .ESAMPLE
305 Mohli bychom být konkrétnější, například takto:
306 .SAMPLE
307 \fB#\fR service systemtap start script1
308 \fB#\fR service systemtap stop script1
309 .ESAMPLE
310 Pokud nenastaly chyby, máme vše připraveno k použití.
311
312 .TP
313 .B ZAPNUTÍ SLUŽBY
314 Jakmile jsme spokojeni se skripty a testování dopadlo úspěšně, můžeme
315 SystemTap službu zapnout tak, aby se automaticky nastartovala po zavedení
316 systému:
317 .SAMPLE
318 \fB#\fR chkconfig systemtap on
319 .ESAMPLE
320
321 .TP
322 .B MAZÁNÍ SKRIPTŮ
323 Skripty se smažou prostým jejich odstraněním z adresáře pro skripty a také
324 odstraněním jejich konfiguračních souborů plus případně relevantních nastavení:
325 .SAMPLE
326 \fB#\fR rm /etc/systemtap/script.d/script2.stp
327 \fB#\fR vi /etc/systemtap/conf.d/group1
328 .ESAMPLE
329 Pokud skript stále běží, měli bychom jej zastavit:
330 .SAMPLE
331 \fB#\fR service systemtap stop script2
332 .ESAMPLE
333 Také můžeme smazat relevantní cache:
334 .SAMPLE
335 \fB#\fR service systemtap cleanup script2
336 .ESAMPLE
337
338 .TP
339 .B PŘÍPRAVA NA POVÝŠENÍ JÁDRA
340 Obvykle není třeba dělat nic neobvyklého když se startuje nové jádro. Služba
341 SystemTap pozná, že verze jádra se liší proti obsahu cache a rekompiluje skripty.
342 Kompilaci lze provést předem, abychom se vyhnuli kompilaci v době závádění
343 systému:
344 .SAMPLE
345 \fB#\fR service systemtap compile myscript -r <NEW_KERNEL_VERSION>
346 .ESAMPLE
347
348 .TP
349 .B IMPORT ZKOMPILOVANÝCH SKRIPTŮ
350 V prostředí, kde nejsou k dispozici kompilační nástroje (např. kompilátor, nebo
351 ladicí informace), jako je např. produkční systém, lze skripty přeložit na jiném
352 (vývojářském) stroji:
353 .SAMPLE
354 \fB#\fR service systemtap compile myscript -r \\
355 .br
356 > <KERNEL_VERSION_OF_TARGET_MACHINE>
357 \fB#\fR tar czf stap-scripts-<kernel-version>.tar.gz \\
358 .br
359 > /var/cache/systemtap/<kernel-version> \\
360 .br
361 > /etc/systemtap/conf.d/<configfile>
362 .ESAMPLE
363 A poté je přesunout na cílový stroj.
364
365 .TP
366 .B STARTOVÁNÍ SKRIPTŮ V DOBĚ ZAVÁDĚNÍ SYSTÉMU (ONBOOT PROBING)
367 lužba SystemTap umožňuje také nastartovat skripty poblíž začátku procesu
368 zavádění OS tím, že vytvoří initramfs obsahující systemtap modul pro daný
369 skript. Tato funkcionalita je dostupná jen na systémech, které používají
370 dracut. Spuštění skriptu v této časné fázi startu OS zpřístupňuje informace,
371 které je jinak obtížné získat.
372
373 Nejdříve nainstalujeme skript do odpovídajícího adresáře a provedeme potřebná
374 nastavení:
375 .SAMPLE
376 \fB#\fR cp myscript.stp /etc/systemtap/script.d
377 \fB#\fR vi /etc/systemtap/conf.d/myscript.conf
378 .ESAMPLE
379 Pro přidání skriptu do initramfs použijeme příkaz\fBonboot\fR:
380 .SAMPLE
381 \fB#\fR service systemtap onboot myscript
382 .ESAMPLE
383 Pokud daný skript není zkompilovaný a uložený v cache, dojde ke kompilaci.
384 Ve výchozím umístění bude vytvořen nový initramfs. Mohli bychom použít volbu
385 \fB-b\fR pro vytvoření zálohy původního initramfs. Nyní můžeme restartovat
386 systém.
387
388 .TP
389 .B POUŽITÍ ALTERNATIVNÍHO INITRAMFS
390 Pokud bychom chtěli nastartovat skript během následujícího bootu, ale ne
391 později, můžeme použít volbu \fB-o\fR k určení alternativního umístění
392 initramfs:
393 .SAMPLE
394 \fB#\fR service systemtap onboot myscript \\
395 > -o /boot/special_initramfs.img
396 .ESAMPLE
397 Jakmile je initramfs vytvořen, je možné jej použít prostou úpravou parametrů
398 jádra při startu systému.
399
400 .TP
401 .B VYTVOŘENÍ INITRAMFS PRO JINÉ JÁDRO
402 Stejně jako u příkazu compile, můžeme i zde použít volbu \fB-r\fR, abychom
403 určili jádro pro které chceme vytvořit initramfs. To může být užitečné např.
404 chceme-li se připravit na upgrade. Například:
405 .SAMPLE
406 \fB#\fR service systemtap onboot myscript \\
407 > -r 3.12.6-200.fc19.x86_64
408 .ESAMPLE
409
410 .TP
411 .B ODSTRANĚNÍ SKRIPTŮ Z INITRAMFS
412 K odstranění skriptů z initramfs stačí spustit příkaz \fBonboot\fR bez parametrů:
413 .SAMPLE
414 \fB#\fR service systemtap onboot
415 .ESAMPLE
416 Takto se vytvoří nový initramfs bez SystemTap modulů.
417
418 .TP
419 .B HLEDÁNÍ CHYB ONBOOT MECHANIZMU
420 Přidáním parametru 'rdinitdebug' mezi parametry jádra lze zvýšit upovídanost
421 programu dracut. Další informace lze získat z dmesg/journalctl -ae. Chybový
422 výstup programu staprun lze získat nastavením LOG_BOOT_ERR na \fByes\fR.
423
424 .SH VIZ TÉŽ
425 .IR stap (1)
426 .IR dracut (8)
427 .IR new-kernel-pkg (8)
428
429 .SH CHYBY
430 Použijte projektovou bugzillu, nebo mailing list.
431 .nh
432 .BR http://sourceware.org/systemtap/ ", " <[email protected]> .
433 .hy
434 .PP
435 .IR error::reporting (7stap),
436 .BR https://sourceware.org/systemtap/wiki/HowToReportBugs
437 .hy
438