Provided by: systemtap-doc_4.8-1_amd64 
JMÉNO
stap - překladač a řadič systemtap skriptů
POUŽITÍ
stap [ VOLBY ] JMÉNO_SOUBORU [ ARGUMENTY ]
stap [ VOLBY ] - [ ARGUMENTY ]
stap [ VOLBY ] -e SKRIPT [ ARGUMENTY ]
stap [ VOLBY ] -l PROBE [ ARGUMENTY ]
stap [ VOLBY ] -L PROBE [ ARGUMENTY ]
stap [ VOLBY ] --dump-probe-types
stap [ VOLBY ] --dump-probe-aliases
stap [ VOLBY ] --dump-functions
POPIS
Program stap je hlavním uživatelským rozhraním nástroje systemtap. Přijímá požadavky na
sondování systému (probing) zapsané v jednoduchém skriptovacím jazyce, překládá je do
jazyka C, výsledný kód zkompiluje a vytvoří jaderný modul, který následně zavede do
běžícího linuxového jádra nebo dyninst instrumentačního nástroje, aby prováděl požadovanou
analýzu zkoumaného systému. Skript může být čten ze souboru (JMÉNO_SOUBORU), ze
standardního vstupu (v tom případě použijte "-" namísto JMÉNO_SOUBORU), z příkazové řádky
(prostřednictvím přepínače -e SKRIPT, případně -E SKRIPT). Program běží dokud není
přerušen uživatelem, nebo dokud skript nezavolá exit(), nebo dokud nedojde k nastřádání
dostatečného množství tzv. měkkých chyb (soft errors).
Jazyk, který je popsán níže v sekci SKRIPTOVACÍ JAZYK, je striktně typovaný, imperativní,
bez explicitních deklarací, procedurální, vhodný k prototypování a inspirovaný awk a C.
Umožňuje spojit místo ve zdrojovém kódu linuxového jádra, nebo uživatelské aplikace,
případně systémovou událost s obslužnými rutinami, což jsou bloky kódu vykonávané
synchronně. Koncepčně to připomíná skriptování v gdb.
PŘEHLED DOKUMENTACE
Pro SystemTap existuje množství vzdělávacích, dokumentačních a referenčních materiálů jak
v online podobě, tak i v rámci distribučních balíčků. Online dokumentace se nachází na
projektovém webu https://sourceware.org/systemtap/
┌──────────────────────────┬────────────────────────────────────────────────────────┐
│man stránky │ │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stap (tato stránka) │ syntaxe jazyka, koncepty, funkce, volby │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stapprobes │ sondážní body a jejich kontextové proměnné │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stapref │ rychlá reference pro syntaxi jazyka │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stappaths │ seznam důležitých umístění včetně knih a odkazů │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stap-prep │ instalátor závislostí jako např. ladicích informací │
│ │ jádra │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│tapset::* │ vygenerovaný seznam tapsetů │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│probe::* │ vygenerovaný seznam tapsetových přezdívek │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│function::* │ vygenerovaný seznam tapsetových funkcí │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│macro::* │ vygenerovaný seznam tapsetových maker │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stapvars │ vybrané globální proměnné definované v tapsetech │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│staprun, stapdyn, stapbpf │ programy pro spuštění zkompilovaných systemtap skriptů │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│systemtap │ systémová služba, analýza startu systému │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stap-server │ kompilační server │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│stapex │ několik velmi jednoduchých příkladů │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│knihy │ │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│Beginner's Guide │ učebnice základů s praktickými ukázkami │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│Tutorial │ hutný úvod, cvičení │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│Language Reference │ podrobný manuál skriptovacího jazyka │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│Tapset Reference │ man stránky tapsetů v podobě knihy │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│odkazy │ │
├──────────────────────────┼────────────────────────────────────────────────────────┤
│example scripts │ množství nástrojů pro správu systému, ukázkových │
│ │ skriptů a výukových hraček │
└──────────────────────────┴────────────────────────────────────────────────────────┘
VOLBY
Příkaz stap akceptuje následující volby. Jakákoliv jiná volba vypíše seznam podporovaných
voleb. Volby lze uvést na příkazové řádce, jak je obvyklé. Pokud existuje
$SYSTEMTAP_DIR/rc, mohou být volby načteny odtud a interpretovány nejdříve. Pokud není
$SYSTEMTAP_DIR nastavena, použije se $HOME/.systemtap jako výchozí.
V některých případech může výchozí hodnota volby záviset na konkrétní konfiguraci systému
a proto zde není přímo uvedena. V takovém případě může pomoci "stap --help".
- Načte skript ze standardního vstupu namísto ze souboru JMÉNO_SOUBORU, pokud ovšem
není dáno -e SKRIPT.
-h --help
Zobrazí nápovědu.
-V --version
Zobrazí verzi.
-p NUM Zastaví po dokončení procesní fáze NUM. Procesní fáze jsou očíslované 1-5 (parse,
elaborate, translate, compile, run). Viz sekce ZPRACOVÁNÍ .
-v Zvýší upovídanost pro všechny procesní fáze. Tuto volbu lze opakovat pro zvýšení
množství informativního (?) výstupu.
--vp ABCDE
Zvýší upovídanost pro jednotlivé procesní fáze. Například, "--vp 002" přidá 2
jednotky upovídanosti procesní fázi 3. Kombinace "-v --vp 00004" přidá 1 jednotku
upovídanosti všem procesním fázím, a další čtyři jednotky fázi 5.
-k Zachová dočasný procesní adresář, který se jinak po dokončení skriptu smaže. To
může být užitečné, chceme-li zkoumat vygenerovaný C kód, nebo jej znovu použít pro
vytvoření jaderného modulu.
-g Guru režim. Umožní použít potenciálně nebezpečné expertní konstrukce, jako
například vložený (embedded) C kód v rámci systemtap skriptu.
-P Režim prohledávání prologu (prologue-searching). Ekvivalentem je
--prologue-searching=always. Aktivuje heuristiku pro obcházení problémů s
nekonzistentními ladicími informacemi pro kontextové proměnné parametrů funkcí.
-u Vypne optimalizace jako např. odstraňování nepotřebného kódu (a mnoho dalších)
během 2., či 3. procesní fáze (elaboration, translation).
-w Potlačí všechny varovné hlášení.
-W Zachází s varováními stejně jako s chybami.
-b Tzv. "bulk" režim pro přenos dat z jádra k uživateli. V tomto režimu jsou data pro
jednotlivé CPU přenášena odděleně a zapisována do samostatných souborů. Pro jejich
případné sloučení lze použít příkaz stap-merge.
-t Sbírá různé časovací informace jako například počet aktivací (probe hits) pro
jednotlivé sondy, průměrný čas strávený v jednotlivých sondách, atd.
-s NUM Nastaví velikost bufferu pro přenos dat ze systemtap modulu k uživateli na NUM MB.
Na víceprocesorovém systému v "bulk" režimu bude mít tuto velikost každý jednotlivý
buffer.
-I DIR Přidá DIR mezi cesty ve kterých se vyhledávají tapset skripty. Více informací
obsahuje popis procesní fáze 2.
-D NAME=VALUE
Přidá danou direktivu do Makefile systemtap modulu. Toho lze využít například k
předefinování různých omezení popsaných níže.
-B NAME=VALUE
Předá danou direktivu příkazu make při sestavování systemtap modulu. Toho lze
využít k přidání nebo změně "kconfig" voleb.
-a ARCH
Použije režim křížového překladu (cross compilation) pro danou cílovou
architekturu. Tato volba vyžaduje přístup ke kompilačnímu serveru a obvykle se
používá spolu s volbami -B CROSS_COMPILE=arch-tool-prefix- a -r /build/tree.
--modinfo NAME=VALUE
Přidá pár klíč/hodnota ve formě makra MODULE_INFO do vygenerovaného modulu. Toho
lze využít k nastavení nebo úpravě různých jaderných kontrol souvisejících s
modulem.
-G NAME=VALUE
Nastavuje hodnotu globální proměnné NAME na VALUE při volání programu staprun. Tak
lze nastavit hodnotu skalární globální proměnné skriptu.
-R DIR Prohledává DIR na systemtap runtime zdroje. Výchozí hodnotu DIR lze zobrazit např.
prostřednictvím "stap --help".
-r /DIR
Použije daný jaderný "build tree". Lze také nastavit prostřednictvím proměnné
prostředí SYSTEMTAP_RELEASE .
-r RELEASE
Určí "release" jádra v rámci "build tree" /lib/modules/RELEASE/build. Lze též
nastavit prostřednictvím proměnné prostředí SYSTEMTAP_RELEASE .
-m MODULE
Použije dané jméno pro vygenerovaný jaderný modul namísto obvyklého náhodně
vygenerovaného jména. Takto vygenerovaný modul se pak navíc zkopíruje do aktuálního
adresáře.
-d MODULE
Přidá do systemtap modulu ladicí informace o symbolech a informace pro odvíjení
zásobníku pro daný MODULE. Tak lze umožnit symbolické tracebacky pro MODULE i když
do něj není explicitně vložena sonda.
--ldd Přidá do systemtap modulu ladicí informace pro všechny uživatelské spustitelné
soubory nebo DSO knihovny, které ldd podezřívá z užitečnosti pro požadovanou
analýzu. Totéž bude do systemtap modulu přidáno i pro moduly vyjmenované pomocí
přepínačů -d. Upozornění: --ldd může systemtap modul značně zvětšit.
--all-modules
Ekvivalent pro "-dkernel" a "-d" pro každý z momentálně zavedených modulů.
Upozornění: --all-modules může systemtap modul značně zvětšit.
-o FILE
Přesměruje výstup do souboru FILE. V bulk režimu se použije pro každou CPU
samostatný soubor s prefixem FILE_ (FILE_cpu s -F) následovaným číslem CPU. Pro
FILE je podporován strftime(3) formát.
-c CMD Zavede a nastartuje systemtap modul, spustí příkaz CMD, a vše ukončí spolu s CMD.
Vedlejším efektem je nastavení target() na pid CMD.
-x PID Nastaví target() na PID. Takto lze psát skripty se zaměřením na daný proces. V
tomto případě systemtap skript běží bez ohledu na životní cyklus procesu PID.
-e SKRIPT
Spustí SKRIPT. Příklad: stap -e "probe oneshot { log("hello") }"
-E SKRIPT
Spustí SKRIPT. Ten běží spolu s hlavním skriptem určeným pomocí -e nebo načteným ze
souboru. Tuto volbu lze opakovat pro načtení většího počtu skriptů. Taktéž ji lze
použít v kombinaci s -l/-L.
-l PROBE
Namísto obvyklého spuštění systemtap skriptu, tato volba vypíše všechny sondy které
odpovídají parametru PROBE. PROBE může obsahovat zástupné symboly a přezdívky, ale
ne seznam čárkou oddělených sondážních bodů. Pokud PROBE neodpovídá žádné dostupné
sondě, bude výsledkem chyba.
-L PROBE
Podobá se "-l", ale navíc vypíše dostupné lokální proměnné.
-F Bez -o tato volba zavede systemtap modul, spustí sondy a odpojí se od běžícího
modulu. V kombinaci s volbou -o spustí staprun na pozadí jako démon a vypíše jeho
pid.
-S size[,N]
Nastavuje maximální velikost výstupního souboru a případně také počet výstupních
souborů. V případě, že dojde k překročení maximální velikosti výstupního souboru
size , přepne systemtap svůj výstup do dalšího souboru. Pakliže počet výstupních
souborů překročí N , systemtap odstraní nejstarší výstupní soubor. Druhý z
argumentů lze vynechat.
-T TIMEOUT
Ukončit skript po uplynutí TIMEOUT sekund.
--skip-badvars
Ignoruje neidentifikovatelné nebo nedostupné kontextové proměnné a, aniž by došlo k
chybě, nahradí jejich hodnotu nulou.
--prologue-searching[=WHEN]
Režim prologue-searching. Aktivuje heuristiku k vyrovnání se s nekvalitními ladicí
informacemi pro kontextové proměnné funkčních parametrů. WHEN může být "never"
(nikdy), "always" (vždy), nebo "auto" (tj. zapnuto na základě heuristiky). Když
WHEN chybí, předpokládá se "always". Bez explicitní specifikace se předpokládá
"auto".
--suppress-handler-errors
Zabalí všechny obslužné rutiny do obálky podobné následujícímu kódu:
try { ... } catch { next }
blok, který způsobuje chyby v době běhu, bude tiše potlačen. Potlačené chyby se
nebudou vyhodnocovat proti limitu MAXERRORS. V tomto režimu je taktéž potlačeno
testování MAXSKIPPED , takže při běhu skriptu může dojít k libovolnému množství
chyb. Celkové počty chyb budou nicméně reportovány při ukončení skriptu.
--compatible VERSION
Z uživatelského hlediska se tato volba pokouší napodobit chování systemtapu dané
verze a umožnit tak běh starším skriptům. Viz též sekce ZASTARÁVÁNÍ.
--check-version
Tato volba slouží k ověření, zda aktivní skript obsahuje konstrukce závislé na
verzi systemtapu. Viz též sekce ZASTARÁVÁNÍ.
--clean-cache
Tato volba smaže zastaralé položky v cache adresáři. To se normálně děje po
úspěšném ukončení skriptu, ale tato volba vyčistí cache explicitně, a pak ukončí
systemtap. Viz sekce CACHE.
--color[=WHEN], --colour[=WHEN]
Tato volba ovládá obarvování výstupu. WHEN může být "never" (nikdy), "always"
(vždy), nebo "auto" (zapnuto pokud jde výstup do terminálu). Pokud WHEN chybí,
předpokládá se "auto". Barvy lze měnit prostřednictvím proměnné prostředí
SYSTEMTAP_COLORS. Formát je následující:
klíč1=hodnota1:klíč2=hodnota2:klíč3=hodnota3 ...atd. Platné klíče jsou: "error",
"warning", "source", "caret", a "token". Hodnotami jsou "Select Graphic Rendition"
(SGR) parametry. Viz dokumentace k použitému terminálu. Příklad výchozího nastavení
je: error=01;31:warning=00;33:source=00;34:caret=01:token=01. Pokud
SYSTEMTAP_COLORS chybí, použije se výchozí nastavení. Pokud to je prázdné nebo
chybné, obarvování se vypne.
--disable-cache
Tato volba vypne veškeré používání cache. Žádné soubory nebudou do cache adresáře
zapsány, ani z něj čteny.
--poison-cache
Tato volba zachází se soubory v cache jako s neplatnými. Žádné soubory nebudou z
cache čteny, ale nové soubory budou do cache zapsány na základě aktuálního běhu.
Tato volba má pomoci hledat chybu v případě, kdy se cache systemtapu zdá fungovat
chybně. Pokud tato volba pomohla, provděpodobně je v někde v systemtapu chyba, o
které by vývojáři rádi věděli. Prosím, nahlašte ji.
--privilege[=stapusr | =stapsys | =stapdev]
Tato volba zkontroluje skript na přítomnost konstruktů, které nejsou povoleny pro
zadanou úroveň oprávnění (viz NEPRIVILEGOVANÍ UŽIVATELÉ). Pokud skript nepovolené
konstrukty obsahuje, kompilace skončí chybou.
Pokud je stapusr nebo stapsys specifikováno při použití kompilačního serveru (viz
--use-server), pak server zkontroluje skript a, pokud kompilace uspěje, server
kryptograficky podepíše výsledný modul, kde specifikuje, že daný modul je bezpečný
pro použití uživatelem s danou úrovní oprávnění.
Pokud se --privilege nespecifikuje, -pN se také nespecifikuje s N < 5 a daný
uživatel není root ani člen skupiny stapdev, pak stap automaticky přidá
odpovídající --privilege volbu k již specifikovaným volbám.
--unprivileged
Ekvivalent pro --privilege=stapusr.
--use-server[=HOSTNAME[:PORT] | =IP_ADDRESS[:PORT] | =CERT_SERIAL]
Specifikuje kompilační server(y) pro kompilaci, a/nebo - v kombinaci s
--list-servers a --trust-servers (viz níže) pro výpis serverů. Pokud je tato volba
použita bez parametrů v neprivilegovaném režimu (viz --privilege) , pak výchozí
server, který bude pro kompilaci použit, bude některý z dostupných kompatibilních
serverů "online SSL peer", a zároveň "module signer". Jinak bude jako výchozí
server použit některý z dostupných kompatibilních serverů "online SSL peer".
--use-server lze použít opakovaně a v tomto případě bude seznam použitelných
serverů postupně rozšiřován v daném pořadí. Servery lze specifikovat pomocí
hostaname, IP adresy, nebo seriálním číslem certifikátu (získaným prostřednictvím
--list-servers). Poslední možnost je nejběžnější pro (od)nastavování důvěryhodnosti
serveru. Viz --trust-servers níže.
Pokud je server specifikován pomocí hostname nebo IP adresy, pak je volitelně možné
určit i číslo portu. To je vhodné pro přístup k serverům, které nejsou na lokální
síti, nebo pro specifikování konkrétního serveru.
IP adresou může být jak IPv4, tak IPv6.
Pokud existuje více než jedno rozhraní s danou link-local IPv6 adresou, pak je
možné zvolit konkrétní rozhraní připojením znaku "%" a názvu rozhraní k adrese,
například: "fe80::5eff:35ff:fe07:55ca%eth0".
Pro určení čísla portu IPv6 adresy je nutné uzavřít adresu do hranatých závorek ,
aby došlo k oddělení adresy od čísla portu. Například:
"[fe80::5eff:35ff:fe07:55ca]:5000" nebo "[fe80::5eff:35ff:fe07:55ca%eth0]:5000".
Pokud --use-server nebylo specifikováno, -pN nebylo specifikováno s N < 5, a
uživatel není root, není člen skupiny stapdev, ale je členem skupiny stapusr, pak
stap automaticky přidá --use-server k již specifikovaným volbám.
--use-server-on-error[=yes|=no]
Požádá stap, aby zkusil kompilaci znovu s použitím kompilačního serveru, pokud
lokální kompilace selže. Pokud tato volba není specifikována, pak se za výchozí
považuje --use-server-on-error=no
--use-server-on-error je ekvivalentem pro --use-server-on-error=yes.
Kompilace může být přerušena pro určitý typ chyby, jako například nedostatek dat
nebo zdrojů. K tomu může dojít i během rekompilace. Pro rekompilaci budou servery
voleny automaticky tak, jako by byla použita volba --use-server bez parametrů.
--list-servers[=SERVERS]
Zobrazí stav požadovaných SERVERS, kde SERVERS je čárkou oddělený seznam atributů
popisujících servery. Sjednocení atributů slouží k vygenerování seznamu serverů.
Dostupné atributy jsou:
all specifikuje všechny známé servery (důvěryhodné servery "SSL peer",
důvěryhodné servery "module signer", servery ve stavu "online").
specified
určuje servery specifikované pomocí --use-server.
online vybere ze seznamu jen ty servery, které jsou aktuálně ve stavu "online".
trusted
vybere ze seznamu jen důvěryhodné servery "SSL peer".
signer vybere ze seznamu jen servery "module signer", viz --privilege.
compatible
vybere jen kompatibilní servery ve smyslu kernel release a architektury.
Pokud není dán žádný argument, pak výchozí volbou je specified. Pokud žádné servery
nebyly specifikovány pomocí --use-server, pak budou vypsány výchozí servery pro
--use-server.
Poznamenejme, že --list-servers používá avahi-daemon k detekci online serverů.
Pokud tato služba není dostupná, pak --list-servers nebude detekovat žádné online
servery. Aby --list-servers detekoval servery poslouchající na IPv6 adresách, musí
konfigurační soubor avahi démona, /etc/avahi/avahi-daemon.conf , obsahovat "use-
ipv6=yes". Po případné úpravě konfiguračního souboru je třeba službu restartovat.
--trust-servers[=TRUST_SPEC]
Nastavit nebo odvolat natavení důvěryhodnosti kompilačního serveru specifikovaného
pomocí --use-server podle TRUST_SPEC, kde TRUST_SPEC je čárkou oddělený seznam typů
důvěryhodnosti. Podporované typy jsou:
ssl důvěřovat specifikovaným serverům jako "SSL peer".
signer důvěřovat specifikovaným serverům jako "module signer" (viz --privilege).
Jen root může nastavit signer.
all-users
důvěřovat specifikovaným serverům jako "SSL peer" pro všechny uživatele na
localhostu. Výchozí chování je nastavit tento typ důvěřování jen pro
aktuálního uživatele. Důvěra typu "module signer" se vždy vztahuje na
všechny uživatele. Jen root může nastavit all-users.
revoke ruší určenou relaci důvěry. Výchozí chování je zapnutí relace důvěry.
no-prompt
nežádat uživatele o potvrzení před provedením akce. Výchozí chování je
požádat o potvrzení před provedením akce.
Pokud žádný argument není nastaven, použije se výchozí hodnota ssl. Pokud pomocí
--use-server, nebyly určené žádné servery, žádná relace důvěry nebude nastavena ani
zrušena.
Dokud se nespecifikuje no-prompt, uživatel bude požádán o potvrzení požadované
akce.
--dump-probe-types
Vypíše všechny podporované typy sond a skončí. Pokud je též nastaveno
--privilege=stapusr , pak tento seznam bude omezen tak, aby vidět byly pouze sondy,
které má daný uživatel právo použít.
--dump-probe-aliases
Vypíše všechny přezdívky nalezené v tapset skriptech a skončí.
--dump-functions
Vypíše všechny veřejné funkce nalezené v tapset skriptech a skončí. Také vypíše
jejich parametry a typy. Návratový typ "unknown" značí, že daná funkce nevrací
hodnotu. Poznamenejme, že ne všechny návratové typy / typy parametrů je vždy možné
při syntaktické analýze stanovit. Nestanovené typy budou též označeny jako
"unknown". Funkce --dump-functions je náročná na paměť a proto nemusí správně
fungovat s --use-server pokud na cílovém systému narazí na rlimit pro paměť
procesu, například prostřednictvím konfiguračního souboru ~stap-
server/.systemtap/rc, viz stap-server(8).
--remote URL
Provede skript na vzdáleném stroji. Tuto volbu je možné opakovat pro provedení
skriptu na více strojích. Procesní fáze 1-4 se provedou lokálně, jak je běžné, a
pak během fáze 5, se modul zkopíruje na specifikované stroje a na nich provede.
Přijatelné URL jsou:
[USER@]HOSTNAME, ssh://[USER@]HOSTNAME
Tento režim využívá SSH, volitelně s využitím specifického uživatelského
jména username. Pokud je použit uživatelský ssh_config, je třeba do něj
přidat SendEnv LANG pro zachování nastavení lokalizace.
libvirt://DOMAIN, libvirt://DOMAIN/LIBVIRT_URI
Tento režim využívá ke spuštění skriptu stapvirt v doméně obsluhované
libvirt démonem. Volitelně je možno specifikovat LIBVIRT_URI pro připojení
ke specifickému driveru nebo vzdálenému stroji. Například pro připojení k
místnímu privilegovanému QEMU driveru použijte:
--remote libvirt://MyDomain/qemu:///system
Viz <http://libvirt.org/uri.html> pro podrobnosti ohledně podporovaných
formátů URI. Viz též stapvirt(1).
unix:PATH
V tomto režimu dojde k připojení přes UNIX soket. Toho lze využít pro
připojení přes QEMU virtio-serial port pro spuštění skriptu uvnitř běžícího
virtuálního stroje.
direct://
Loopback režim pro spouštění na localhostu.
--remote-prefix
Oprefixuje každou řádku výstupu "N: ", kde N je index vzdáleného stroje ze kterého
daný výstup pochází.
--download-ladicíinfo[=OPTION]
Podle OPTION zapne, vypne, nebo nastaví timeout pro funkci automatického stahování
balíčků s ladicími informacemi, kterou nabízí ABRT. Přípustné hodnoty pro OPTION
jsou:
yes povolí automatické stahování bez časového omezení. Totéž jako
--download-debuginfo bez parametru.
no explicitně vypne automatické stahování Totéž jako nepoužití
--download-debuginfo vůbec.
ask ukáže výstup ABRTu a dotáže se uživatele, zda se má pokračovat v downloadu.
Žádný timeout nebude nastaven.
<timeout>
specifikuje timeout jako pozitivní celé číslo vyjadřující maximální počet
sekund pro download.
--rlimit-as=NUM
Určí maximální velikost virtuální paměti procesu v bajtech. Bez specifikace NUM
nebude žádný limit nastaven.
--rlimit-cpu=NUM
Určí limit pro čas CPU v sekundách. Bez specifikace NUM není žádný limit nastaven.
--rlimit-nproc=NUM
Určí maximální počet procesů které může systemtap vytvořit. Bez specifikace NUM
není žádný limit nastaven.
--rlimit-stack=NUM
Nastaví maximální velikost zásobníku v bajtech. Bez specifikace NUM není žádný
limit nastaven.
--rlimit-fsize=NUM
Nastaví maximální velikost souboru, který je možno vytvořit, v bajtech. Bez
specifikace NUM není žádný limit nastaven.
--sysroot=DIR
Nastaví "sysroot" adresář, kde budou umístěny cílové soubory (programy, knihovny
atd.) Po nastavení -r RELEASE bude v adresáři "sysroot" hledán "build" adresář
jádra, ovšem po nastavení -r /DIR nebude "sysroot" prohledáván na "build" adresář
jádra.
--sysenv=VAR=VALUE
Nastaví alternativní hodnotu proměnné prostředí pokud se tato hodnota na vzdáleném
systému liší. Předpokládá se, že proměnné vyjadřující cesty budou uvedeny jako
relativní cesty vzhledem k --sysroot (pokud je nastaven).
--suppress-time-limits
Potlačí -DSTP_OVERLOAD*, -DMAXACTION a -DMAXTRYLOCK. Vyžaduje guru režim (-g).
--runtime=MODE
Nastaví runtime režim pro procesní fázi 5. Validní hodnoty jsou kernel (výchozí),
dyninst a bpf. Viz sekce ALTERNATIVNÍ RUNTIME.
--dyninst
Zkratka pro --runtime=dyninst.
--save-uprobes
Na strojích, kde si SystemTap musí sestavit svůj vlastní modul "uprobes" (jádra
před 3.5), tato volba instruuje SystemTap, aby po sestavení tento pomocný modul
zachoval v aktuálním adresáři.
--target-namespaces=PID
Nastavuje cílový "namespace" (jmenný prostor procesů) na "namespace" do kterého
patří PID. Volba souvisí s "namespace-aware" tapset funkcemi. Pokud cílový
"namespace" není specifikován, použije se "namespace" v kterém běží stap.
--monitor=INTERVAL
Umožňuje zobrazovat informace o stavu modulu (čas běhu, jméno modulu, id uživatele,
který modul aktivoval, informace o paměti, globální proměnné, seznam sond včetně
jejich statistik). Je možno nastavit volitelný parametr INTERVAL, který určuje
obnovovací frekvenci stavového okna v sekundách. Činnost modulu lze ovládat
následujícími klávesami:
r přenastaví všechny globální proměnné na jejich výchozí hodnoty nebo na nulu,
pokud výchozí hodnota nebyla určena.
s cyklicky mění hodnoty daného atributu za účelem změny třídění seznamu sond.
t umožňuje aktivovat/deaktivovat sondu indexem.
navigační-klávesy
Klávesami j/k/Up/Down lze posouvat seznam sond. Klávesami d/u/PgDn/PgUp lze
rolovat v statistice modulu.
ARGUMENTY
Všechny další argumenty z příkazové řádky se předají kompilátoru ke zpracování. Viz níže.
SKRIPTOVACÍ JAZYK
Skriptovací jazyk systemtapu připomíná awk a C. Existují v něm dva hlavní konstrukty:
sondy a funkce. V jejich rámci se používají příkazy a výrazy se syntaxí podobnou syntaxi
jazyka C.
OBECNÁ SYNTAXE
Bílé místo se ignoruje. Podporovány jsou komentáře tří typů:
# ... shell styl, do konce řádku, mimo $# a @#
// ... C++ styl, do konce řádku
/* ... C styl ... */
Literály jsou buďto řetězce uzavřené v uvozovkách (dovolují obvyklé C escape sekvence se
zpětnými lomítky, které lze řetězit podobně jako v C), nebo celá čísla (dekadická,
hexadecimální, nebo oktalová, zapsaná stejně jako v C). Maximální délka řetězce je rozumně
omezená na několik set bajtů. Celá čísla jsou 64-bitová se znaménkem. Parser formálně
přijímá i kladná čísla nad 2**63, pro které pak používá modulo aritmetiku z důvodu
přetečení (wrap around).
Na konci příkazové řádky lze skriptům předat parametry. V rámci skriptu k nim pak lze
přistupovat prostřednictvím $1 ... $<NN> pokud jde literály neuzavřené do uvozovek, nebo
@1 ... @<NN> pokud jde o řetězcové literály uzavřené do uvozovek. Počet argumentů je
přístupný prostřednictvím $# (jakožto číslo neuzavřené do uvozovek) nebo prostřednictvím
@# (jakožto číslo do uvozovek uzavřené). Tyto symboly lze použit na místě libovolné
lexikální jednotky skriptu, a k jejich vyhodnocení dojde již v počáteční fázi překladu
(preprocessing).
FÁZE PŘEDZPRACOVÁNÍ (PREPROCESSING)
Součástí lexikální analýzy je jednoduchá fáze předzpracování. V ní lze (ne)vyhodnocovat
části kódu na základě podmínky. Příslušná syntaxe se obecně podobá ternárnímu operátoru:
podmínka ? výraz1 : výraz2
%( PODMÍNKA %? VÝRAZ-1 %)
%( PODMÍNKA %? VÝRAZ-1 %: VÝRAZ-2 %)
PODMÍNKA je buďto výraz, jehož formát je určen prvním klíčovým slovem, nebo porovnání
řetězcových či numerických literálů, nebo výraz složený z takových podmínek s využitím
operátorů || a &&. Nicméně, závorky zde zatím nejsou podporovány, takže je důležité mít na
zřeteli, že && má při vyhodnocení přednost před ||.
Pokud první částí podmínky je identifikátor kernel_vr nebo kernel_v odkazující se k verzi
jádra s příponou ("2.6.13-1.322FC3smp"), nebo bez přípony ("2.6.13"), pak následovat musí
jeden z operátorů porovnání: <, <=, ==, !=, >, a >=, a třetí částí podmínky je řetězcový
literál vyjadřující verzi jádra v RPM-stylu.
Podmínka se považuje za splněnou, pokud verze běžícího jádra (volitelně předefinovaná
volbou -r ) se srovnává se zadanou hodnotou. Srovnání provádí glibc funkce strverscmp().
Pokud operátorem je jednoduchá rovnost (==), nebo nerovnost (!=), a pravý operand obsahuje
zástupné symboly (* nebo ? nebo [), , pak celý výraz bude interpretován jako "wildcard
(mis)match" a bude vyhodnocen glibc funkcí fnmatch().
Pokud první částí podmínky je arch odkazující se k architektuře procesoru (pojmenované
podle ARCH/SUBARCH v terminologii jádra), pak druhou částí podmínky je jeden z operátorů:
== nebo !=, a třetí částí podmínky je požadovaný řetězcový literál, který může obsahovat
zástupné symboly ("wildcard (mis)match").
Podobně, pokud první složkou podmínky je identifikátor jako CONFIG_* odkazující se ke
konfigurační volbě jádra, pak druhou částí podmínky je == nebo !=, a třetí částí podmínky
je řetězcový literál odpovídající volby (obvykle "y", nebo "m"). Neexistující, nebo
nenastavené konfigurační volby v tomto kontextu odpovídají prázdnému řetězci. Vyhodnocení
opět probíhá jako "wildcard (mis)match" s využitím fnmatch().
Pokud první částí je identifikátor systemtap_v, pak se test odkazuje k verzi systemtapu,
kterou lze volitelně pro staré skripty nastavit prostřednictvím volby --compatible.
Operátor porovnání je jako u kernel_v , a pravým operandem je řetězec vyjadřující verzi
jádra. Viz též sekce ZASTARÁVÁNÍ níže.
Pokud první částí podmínky je systemtap_privilege, pak se test odkazuje k úrovni oprávnění
se kterou je systemtap skript překládán. V tomto případě je podmínkou jeden z operátorů ==
nebo !=, a třetí částí podmínky je jeden z řetězcových literálů "stapusr", "stapsys", nebo
"stapdev".
Pokud první částí podmínky je identifikátor guru_mode, pak test ověřuje, zda je systemtap
skript překládán v "guru" režimu (-g). Operátorem pro tento případ může být == nebo !=, a
třetí částí podmínky je číslo. Buďto 1, nebo 0.
Pokud prvním indetifikátorem je runtime, testuje se runtime režim (--runtime). Viz sekce
ALTERNATIVNÍ RUNTIME níže pro informaci o dostupných runtime backendech. Porovnávací
operátor v tomto případě je == nebo !=, a třetí částí podmínky je řetězcový literál
odpovídající runtime. Porovnání je typu "wildcard (mis)match" s využitím fnmatch()
Poslední možností je situace, kdy PODMÍNKA srovnává prosté číselné, nebo řetězcové
literály.
VÝRAZ-1 a VÝRAZ-2 představují výskyt nuly nebo více obecných lexikálních jednotek (které
mohou obsahovat další vložené podmínky preprocesoru), a jsou preprocesorem předány na
vstup parseru v závislosti na vyhodnocení uvedené podmínky. Například následující kód
vyvolá kompilační chybu v případě že verze běžícího jádra na cílovém systému je novější,
než 2.6.5:
%( kernel_v <= "2.6.5" %? **ERROR** %) # "invalid token sequence"
Naproti tomu následující kód umožní elegantně se vyrovnat s různými verzemi jádra:
probe kernel.function (
%( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
%( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
UNSUPPORTED %) %)
) { /* ... */ }
%( arch == "ia64" %?
probe syscall.vliw = kernel.function("vliw_widget") {}
%)
MAKRA PREPROCESORU
Preprocesor přijímá jednoduchá makra a vyhodnocuje je v rámci samostatné procesní fáze
před vyhodnocením podmínek.
Makra se definují následující konstrukcí:
@define NAME %( BODY %)
@define NAME(PARAM_1, PARAM_2, ...) %( BODY %)
Makra (a také parametry uvnitř těla maker) jsou přístupná přidáním prefixu "@" před jejich
jméno"
@define foo %( x %)
@define add(a,b) %( ((@a)+(@b)) %)
@foo = @add(2,2)
K expanzi maker v současnosti dochází v samostatné preprocesní fázi před zpracováním
podmínek. Proto dojde k vyhodnocení všech maker v rámci kondicionálu bez ohledu na
konkrétní podmínku. To může vést k nezamýšleným chybám:
// Následující kód způsobí chybu:
%( CONFIG_UTRACE == "y" %?
@define foo %( process.syscall %)
%:
@define foo %( **ERROR** %)
%)
// Následující kód bude fungovat správně:
@define foo %(
%( CONFIG_UTRACE == "y" %? process.syscall %: **ERROR** %)
%)
První příklad je chybný, protože vyvolá duplicitní definici makra "foo".
Za normálních okolností je definice platná lokálně - pouze v souboru kde se vyskytuje.
Makro definované v tapset skriptu tedy není veřejně použitelné v rámci uživatelského
skriptu. Makra, která mají být veřejně dostupná, lze sdružovat do knihoven s příponou
".stpm" nacházející se v "tapset search path". Tyto soubory mohou obsahovat @define
konstrukty, které budou dostupné nejen ve všech tapsetech, ale i v uživatelských
skriptech. Volitelně mohou být definice maker v rámci ".stpm" souborů zabaleny v
kondicionálech preprocesoru.
KONSTANTY
V rámci tapset skriptů, nebo guru skriptů je možno přistupovat ke konstantním symbolům,
jako jsou například makra jazyka C, prostřednictvím vestavěného operátoru @const(). Pokud
je potřeba přidat příslušný #include dodatečného hlavičkového souboru, lze tak učinit
prostřednictvím vloženého kódu jazyka C.
@const("STP_SKIP_BADVARS")
PROMĚNNÉ
Identifikátory pro proměnné a funkce jsou alfanumerické sekvence, které mohou obsahovat _
a $. Nesmí začínat číslicí (stejně jako v C). Proměnné jsou lokální vzhledem ke svému
bloku (funkce nebo sondy) a jejich životnost je spojena s tímto blokem.
Skalární proměnné jsou implicitně řetězcového, nebo celočíselného typu. Asociativní pole
mohou také obsahovat řetězcové nebo celočíselné hodnoty a jako klíč jim slouží n-tice
řetězců nebo celých čísel. Zde je několik příkladů:
var1 = 5
var2 = "bar"
array1 [pid()] = "name" # jednoduchý číselný klíč pole
array2 ["foo",4,i++] += 5 # n-tice jako klíč pole
if (["hello",5,4] in array2) println ("yes") # test na členství
Překladač provádí typové odvození (type inference) na všech identifikátorech včetně indexů
polí a parametrů funkcí. Nekonzistentní zacházení s typy způsobí chybu překladu.
Proměnné lze definovat jako globální, takže mohou být sdíleny mezi sondami a funkcemi, a
žijí stejně dlouho jako celé systemtap sezení. Pro globální proměnné existuje jediný
jmenný prostor. Přístup ke globálním proměnným je chráněn zámky, viz BEZPEČNOST A OCHRANA
SOUKROMÍ. Globální proměnnou lze deklarovat kdekoli ve vnější úrovni zdrojového kódu, tedy
mimo bloky sond a funkcí. Globální proměnné, kterým byla přiřazena hodnota, ale nikdy
nebyla čtena, budou automaticky zobrazeny na konci systemtap sezení. Překladač se pokusí
odvodit datový typ z hodnot a případně, pokud jde o pole, i z klíčů. Volitelně lze
globální proměnnou inicializovat řetězcovým, nebo číselným literálem. Zde jsou příklady
deklarace globálních proměnných:
global var1, var2, var3=4
Globální proměnné lze také použít jako parametry systemtap modulu. Toho lze dosáhnout
buďto použitím přepínače stap -G, nebo modul připravit předem pomocí stap -p4 a parametry
mu předat později při jeho zavádění na příkazové řádce programu staprun. Viz staprun(8).
Rozsah platnosti globální proměnné lze omezit na tapset soubor, nebo na uživatelský skript
prostřednictvím klíčového slova "private". V tom případě je klíčové slovo "global"
volitelné. Následující deklarace označuje var1 a var2 jako privátní globální proměnné:
private global var1=2
private var2
Pole mají omezenou velikost parametrem MAXMAPENTRIES. Viz BEZPEČNOST A OCHRANA SOUKROMÍ
Volitelně lze polím (která jsou vždy globální) nastavit maximální velikost v hranatých
závorkách, čímž se předefinuje MAXMAPENTRIES pro dané pole. Poznamenejme, že velikost se
vztahuje jen k počtu prvků, nikoliv k celkové velikosti pole v paměti. Příklad:
global tiny_array[10], normal_array, big_array[50000]
Polím lze nastavit příznak "%". To způsobí, že pokud do pole přidáme více prvků, než pro
kolik je dimenzováno, začnou staré prvky mizet (LIFO). To platí jak pro asociativní, tak
pro statistická pole, viz níže. Příklad:
global wrapped_array1%[10], wrapped_array2%
Mnohé sondy poskytují kontextové proměnné, což jsou hodnoty získané za běhu z jádra, nebo
zkoumané uživatelské aplikace. Jejich identifikátory začínají znakem $. Sekce KONTEXTOVÉ
PROMĚNNÉ v manuálové stránce stapprobes(3stap) obsahuje jejich seznamy pro jednotlivé typy
sond. Tyto kontextové proměnné se stanou normálními řetězcovými nebo numerickými
proměnnými použitelnými ve skriptu, jakmile provedeme příslušné přiřazení (např.
foo=$foo). Podívejte se níže na sekci PŘETYPOVÁNÍ, kde je popsáno jak takovou proměnnou
přetypovat zpět na ukazatel je-li to třeba.
PŘÍKAZY
Příkazy umožňují procedurální řízení běhu skriptu. Mohou se vyskytovat uvnitř funkcí a
obslužných rutin sond. Celkový počet příkazů, které je v reakci na nějakou událost možno
spustit, je omezen na hodnotu definovanou makry MAXACTION_* ve vygenerovaném C-kódu a
pohybuje se kolem 1000.
EXP Vyhodnotit řetězcový, nebo číselný výraz a zahodit hodnotu.
{ STMT1 STMT2 ... }
Vykonat každý příkaz v sekvenci v tomto bloku. Poznamenejme, že oddělovače a znaky
pro ukončení příkazu nejsou mezi jednotlivými příkazy nezbytné.
; Prázdný příkaz, nedělat nic. Je užitečný jako volitelný oddělovač mezi příkazy ke
zlepšení detekce syntaktických chyb a k upřesnění některých syntaktických
nejednoznačností gramatiky.
if (EXP) STMT1 [ else STMT2 ]
Porovnat číselný výraz EXP s nulou. Pak vykonat příkaz STMT1 (EXP není nula), nebo
příkaz STMT2 (EXP je nula).
while (EXP) STMT
Dokud má číselný výraz EXP nenulovou hodnotu, spouštěj STMT.
for (EXP1; EXP2; EXP3) STMT
Vykoná EXP1 jako inicializaci. Dokud EXP2 má nenulovou hodnotu, bude vykonávat STMT
a iterační výraz EXP3.
foreach (VAR in ARRAY [ limit EXP ]) STMT
Cyklení přes každý prvek globálního pole ARRAY s přiřazením aktuálního prvku
proměnné VAR. Pole není v rámci STMT dovoleno měnit. Přidáním operátoru + nebo - za
identifikátor VAR nebo ARRAY, se zajistí iterování přes setříděné pole jedním, nebo
druhým směrem. Pokud pole obsahuje statistické agregátory, pak přidáním
požadovaného operátoru @operator mezi ARRAY a symbol + nebo - určíme třídicí
agregační funkci. Viz příklad níže v sekci STATISTIKA. Výchozí je @count. S
využitím volitelného klíčového slova limit lze maximální počet iterací omezit na
EXP. Poznamenejme, že EXP se vyhodnocuje na začátku smyčky.
foreach ([VAR1, VAR2, ...] in ARRAY [ limit EXP ]) STMT
Podobně jako výše, ovšem v tomto případě je klíčem pole n-tice hodnot. Třídicí
příponu lze použít maximálně na jednom z prvků n-tice.
foreach ([VAR1, VAR2, ...] in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT
Podobně jako výše, ovšem iterovat se bude pouze přes prvky, kde klíč vyhovuje dané
hodnotě. Pro určení indexu lze použít znak *, se kterým bude zacházeno jako se
zástupným symbolem.
foreach (VAR0 = VAR in ARRAY [ limit EXP ]) STMT
Tato varianta foreach uchová aktuální hodnotu při každé iteraci ve VAR0, takže bude
odpovídat ARRAY[VAR]. Tohle analogicky funguje s n-ticí klíčů. Třídicí přípony na
VAR0 mají stejný význam jako na ARRAY.
foreach (VAR0 = VAR in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT
Podobné jako výše, ovšem iteruje se pouze přes prvky, kde klíče vyhovují daným
hodnotám. Pro určení indexu lze použít znak * se kterým bude zacházeno jako se
zástupným symbolem.
break, continue
Ukončit, nebo znovu iterovat vnitřní smyčku. Aplikovatelné na while nebo for nebo
foreach.
return EXP
Vrátit hodnotu EXP z funkce. Příkaz return není ve funkci povinný. Pokud se
vynechá, bude funkce mít speciální návratový datový typ "unknown".
next Ihned ukončí obslužnou rutinu sondy. To je obzvlášť užitečné u přezdívek, které
používají filtrovací podmínky.
try { STMT1 } catch { STMT2 }
Vykonej příkazy v prvním bloku STMT1. Pokud při tom dojde k chybě běhu, ukonči
STMT1 a začni provádět STMT2. Případné chyby v STMT2 se budou propagovat do
vnějšího catch bloku, pokud tam takový je.
try { STMT1 } catch(VAR) { STMT2 }
Podobně jako v předchozím případě, ale navíc se chybová hláška, jakožto řetězec,
uchová v proměnné VAR.
delete ARRAY[INDEX1, INDEX2, ...]
Odstraní z pole prvky určené n-ticí klíčů. Pokud n-tice klíčů obsahuje symbol * na
místě indexu, bude s * zacházeno jako jako se zástupným symbolem.
Není chybou pokusit se smazat prvek, který neexistuje.
delete ARRAY
Smazat všechny prvky pole ARRAY.
delete SCALAR
Maže hodnotu SCALAR. Celočíselné proměnné budou vynulovány, řetězcové proměnné
nastaveny na "", a statistické proměnné budou nastaveny do výchozího prázdného
stavu.
VÝRAZY
SystemTap podporuje množství operátorů, které mají syntaxi a sémantiku velmi podobnou
jejich C a awk protějškům. Aritmetické operace se provádějí v souladu s pravidly jazyka C
pro celá čísla se znaménkem. Dělení nulou nebo přetečení rozsahu se detekuje a způsobí
chybu.
binární numerické operátory
* / % + - >> << & ^ | && ||
binární operátory nad řetězci
. (spojení řetězců)
číselné přiřazovací operátory
= *= /= %= += -= >>= <<= &= ^= |=
řetězcové přiřazovací operátory
= .=
unární číselné operátory
+ - ! ~ ++ --
operátory pro srovnávání čísel, řetězců a práci s regulárními výrazy
< > <= >= == != =~ !~
ternární operátor
podmínka ? exp1 : exp2
seskupovací operátor
( exp )
volání funkce
fn ([ arg1, arg2, ... ])
operátor testující členství v poli
exp in array
[exp1, exp2, ...] in array
[*, *, ... ]in array
REGULÁRNÍ VÝRAZY
Skriptovací jazyk systemtapu podporuje práci s regulárními výrazy. Základní operace
testující (ne)shodu řetězce s regulárním výrazem:
exp =~ regex
exp !~ regex
První operand musí být výraz vyhodnotitelný na řetězec; druhý operand musí být řetězcový
literál obsahující platný regulární výraz.
Syntaxe regulárních výrazů podporuje většinu rozšířených regulárních výrazů POSIX
standardu. Výjimkou je znovupoužití částí regulárního výrazu ("\1").
Po úspěšném nalezení je text vyhovující regulárnímu výrazu dostupný prostřednictvím
tapsetových funkcí matched() a ngroups() následovně:
if ("an example string" =~ "str(ing)") {
matched(0) // -> vrací "string", t.j. celý odpovídající řetězec
matched(1) // -> vrací "ing", t.j. první odpovídající podřetězec
ngroups() // -> vrací 2, t.j. počet odpovídajících skupin řetězců
}
SONDY
Hlavním syntaktickým konstruktem skriptovacího jazyka jsou sondy (probes). Sondy spojují
abstraktní události s bloky příkazů a vytvářejí tak obslužné rutiny událostí. Obecná
syntaxe je následující:
probe PROBEPOINT [, PROBEPOINT] { [STMT ...] }
probe PROBEPOINT [, PROBEPOINT] if (CONDITION) { [STMT ...] }
Události jsou určeny syntaxí nazývanou sondážní body (probe points). Existuje množství
variant sondážních bodů. Některé jsou definovány překladačem a mnohé další jsou definovány
v tapset skriptech jako přezdívky. Sondážní body mohou využívat zástupné znaky, být
seskupovány, může být určováno jejich pořadí, či mohou být deklarovány jako volitelné.
Více podrobností o syntaxi a sémantice sondážních bodů viz
stapprobes(3stap).
Obslužná rutina sondy se interpretuje relativně ke kontextu dané události. Pro události
související s kernel kódem může tento kontext obsahovat proměnné definované ve zdrojovém
kódu jádra. Takové "kontextové" proměnné jsou pak přístupné ve skriptu z prefixem "$".
Jsou přístupné pouze pokud byly kompilátorem jádra zachovány navzdory optimalizacím. To je
stejné omezení s jakým se potýká debugger když pracuje s optimalizovaným kódem. Navíc musí
tyto objekty být v momentě vykonávání obslužné rutiny sondy přítomny přímo v nastránkované
(in-paged) paměti, protože systemtap nesmí zapříčinit žádné dodatečné stránkování. Některé
sondy mají velmi málo kontextových proměnných. Viz stapprobes(3stap).
Proby mohou být doplněny podmínkou pro uzamčení, sestávající z jednoduchého booleovského
výrazu. Sonda je "odemčená" (tedy neaktivní) vyhodnocuje-li se zamykací podmínka na false.
V tomto stavu některé sondy snižují nebo zcela eliminují svoji režii, tedy nekonzumují
systémové prostředky. Jakmile se zamykací podmínka vyhodnotí na true bude sonda brzy znovu
uzamčena a její obslužná rutina začne brzy být opět volána když nastane příslušná událost.
Přestože je zamykání rychlé, trvá nenulový čas, a některé události nemusejí být zachyceny.
V případech kdy toto může představovat problém, je lepší zamykání sond nepoužívat.
Nové sondážní body lze definovat pomocí přezdívek (probe aliases). Definice přezdívky
vypadá podobně jako definice sondy samotné, ale namísto aktivování sondy v daném místě
pouze definují nové jméno - přezdívku pro již existující sondážní bod. Existují dva typy
přezdívek: "prologue" a "epilogue", které jsou definovány pomocí "=" nebo resp. "+=".
Přezdívka typu "prologue" vznikne tak, že se blok příkazů, který následuje definici této
přezdívky, přidá před sondu ke které se váže jako její prolog. Naproti tomu přezdíka typu
"epilogue" vznikne tak, že blok příkazů, který následuje definici této přezdívky, se přidá
za sondu ke které se váže jako její epilog. Například:
probe syscall.read = kernel.function("sys_read") {
fildes = $fd
if (execname() == "init") next # přeskočit zbytek sondy
}
definuje nový sondážní bod. syscall.read, který se rozšiřuje na
kernel.function("sys_read"), s daným příkazem jako prologem, což je výhodné k
předdefinování některých proměnných pro danou přezdívku a/nebo pro přeskočení dané sondy v
závislosti na podmínce. Naproti tomu
probe syscall.read += kernel.function("sys_read") {
if (tracethis) println ($fd)
}
definuje nový sondážní bod s daným příkazem jako epilogem, což může být užitečné k
provedení činností v závislosti na hodnotách proměnných nastavených uživatelem přezdívky.
Poznamenejme, že v každém případě jsou příkazy v obslužné rutině přezdívky vykonávány za
běhu, takže v danou chvíli zejména nedochází k vyhodnocování/substituci maker.
Přezdívku lze použít stejně jako vestavěnou sondu překladače.
probe syscall.read {
printf("reading fd=%d\n", fildes)
if (fildes > 10) tracethis = 1
}
FUNKCE
Systemtap skripty mohou definovat funkce. Ty mohou přijímat libovolný počet skalárních
(celočíselných nebo řetězcových) parametrů, a vrací jednu skalární funkční hodnotu.
Příklad funkce:
function thisfn (arg1, arg2) {
return arg1 + arg2
}
Povšimněme si absence explicitních deklarací typů. Typy, jsou odvozeny (inferred)
překladačem. Nicméně, pokud je to potřeba, může definice funkce zahrnovat explicitní
deklarace návratového typu a/nebo typů argumentů. To je užitečné zejména pro vložené C
funkce. V následujícím příkladě je automatické odvození typu nutné jen pro arg2 (řetězec):
function thatfn:string (arg1:long, arg2) {
return sprint(arg1) . arg2
}
Funkce se mohou volat navzájem až do určitého limitu zanoření. Tento limit je definován
makrem MAXNESTING ve vygenerovaném zdrojovém kódu modulu a pohybuje se okolo 10.
Funkce lze označit za privátní použitím klíčového slova "private". Tím se omezí jejich
platnost soubor (tapset nebo uživatelský skript) ve kterém jsou definovány. Příklad:
private function three:long () { return 3 }
TISK
Existuje několik funkcí, se kterými překladač zachází neobvykle. Poznamenejme, že data
jsou generována v jaderném modulu a před tiskem musí být přenesena do uživatelského
prostoru. Tyto funkce formátují hodnoty pro pohodlný tisk do výstupního proudu systemtapu.
Varianty funkce
sprint* vracejí formátovaný řetězec namísto aby ho přímo vypisovaly.
print, sprint
Výpis jedné nebo více hodnot libovolného typu spojených dohromady.
println, sprintln
vypisují hodnoty stejně jako print a sprint, ale navíc připojují znak nového řádku.
printd, sprintd
Přijímají řetězcový oddělovač a dvě nebo více hodnot libovolného typu, a vytisknou
je proložené tímto oddělovačem. Oddělovačem musí být řetězcový literál - konstanta.
printdln, sprintdln
Vytisknou hodnoty proložené oddělovačem podobně jako printd a sprintd, ale zároveň
připojí znak konce řádku.
printf, sprintf
přijímají formátovací řetězec s množinou hodnot odpovídajících typů a všechny je
vytisknou. Formátovacím řetězcem musí být řetězcový literál - konstanta.
Formátovací řetězec příkazu printf je podobný jako v jazyce C s tím, že zde probíhá typová
kontrola.
%b Vypisuje binární blob dané hodnoty namísto ASCII textu. Specifikátor "width"
určuje počet bajtů k vypsání. Validní specifikace jsou: %b %1b %2b %4b %8b.
Výchozí je (%b), t.j. 8 bajtů.
%c Znak.
%d,%i Celé číslo se znaménkem.
%m Bezpečně čte paměť jádra na dané adrese, vrací její obsah. Volitelný
specifikátor přesnosti (ne šířky pole) určuje počet bajtů k přečtení.
Výchozí hodnota je 1 bajt. %10.4m vytiskne 4 bajty paměti v rámci 10 znaků
širokého pole.
%M Stejné jako %m, ale výstup je hexadecimální. Minimální šířka výstupu je
určitelná volitelným specifikátorem r - výchozí hodnota je 1 bajt (2
hexadecimální znaky). %10.4M vytiskne 4 bajty paměti jako 8 hexadecimálních
znaků v rámci 10 znaků širokého pole.
%o Oktalové číslo bez znaménka.
%p Ukazatel bez znaménka.
%s Řetězec.
%u Desítkové číslo bez znaménka.
%x Hexadecimální hodnota bez znaménka, malá písmena.
%X Hexadecimální hodnota bez znaménka, velká písmena.
%% Vypíše znak %.
Znak # zapíná alternativní formátování: Oktalovým číslům přidá prefix "0", hexadecimálním
"0x", nebo "0X", a netisknutelným znakům v řetězci přidá prefix "escape" sekvence.
Příklady:
a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = -1, id[a] = 1234, id[b] = 4567
print("hello")
Vypíše: hello
println(b)
Vypíše: bob\n
println(a . " is " . sprint(16))
Vypíše: alice is 16
foreach (name in id) printdln("|", strlen(name), name, id[name])
Vypíše: 5|alice|1234\n3|bob|4567
printf("%c is %s; %x or %X or %p; %d or %u\n",97,a,p,p,p,j,j)
Vypíše: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; -1 or 18446744073709551615\n
printf("2 bytes of kernel buffer at address %p: %2m", p, p)
Vypíše: 2 byte of kernel buffer at address 0x1234abcd: <binary data>
printf("%4b", p)
Vypíše (these values as binary data): 0x1234abcd
printf("%#o %#x %#X\n", 1, 2, 3)
Vypíše: 01 0x2 0X3
printf("%#c %#c %#c\n", 0, 9, 42)
Vypíše: \000 \t *
STATISTIKA
Často je výhodné sbírat statistická data způsobem, který netrpí problémy s exkluzivním
zamykáním globálních proměnných, kde se data udržují. Systemtap nabízí řešení ve formě
speciálního operátoru pro uchovávání statistických dat a sady agregačních pseudofunkcí.
Agregační operátor je <<<, a připomíná přiřazení, nebo operaci pro zápis do výstupního
proudu známou z C++. Levý operand je skalární proměnná (nebo /skalární/ prvek pole - viz
příklad níže), která musí být deklarována jako globální. Pravým operandem je číselný
výraz. Význam je intuitivní: Přidej dané číslo na hromadu nad kterou bude později možno
provádět statistické operace. Seznam funkcí pro extrakci statistických údajů je uveden
níže. Příklad:
foo <<< 1
stats[pid()] <<< memsize
Funkce pro extrakci statistiky jsou neobvyklé. Pro každý výskyt extrakční funkce pracující
s daným identifikátorem zajistí překladač výpočet požadovaného statistického údaje.
Statistický subsystém tedy funguje "na požádání" a výpočet probíhá v reálném čase na všech
dostupných CPU.
Zde je seznam extrakčních funkcí. Prvním argumentem každé z nich je ta stejná l-hodnota,
která byla použita pro akumulaci statistiky operátorem <<<. Extrakční funkce @count(v),
@sum(v), @min(v), @max(v), @avg(v), @variance(v[, b]) počítají počet, sumu, minimum,
maximum, aritmetický průměr, a střední kvadratickou odchylku přes všechny nashromážděné
hodnoty. Funkčními hodnotami jsou celá čísla. Pole obsahující agregační data lze třídit
a/nebo přes ně iterovat. Viz cyklus foreach výše.
Střední kvadratická odchylka se vyčísluje s použitím Welfordova algoritmu. Výpočty jsou
prováděny v celočíselné aritmetice, proto mohou trpět nízkou přesností. Pro zlepšení
přesnosti lze využít volitelný parametr b, tzv. bitový posun, s hodnotami od 0 (výchozí
hodnota) do 62. Pro danou statistickou veličinu, resp. jí odpovídající globální proměnnou
ve skriptu, lze použít pouze jednu jedinou hodnotu bitového posunu. Vyšší hodnoty bitového
posunu zvyšují přesnost, ale zároveň zvyšují riziko přetečení.
$ stap -e \
> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x)) }'
12
$ stap -e \
> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x,1)) }'
2
$ python3 -c 'import statistics; print(statistics.variance([1, 2, 3, 4, 5]))'
2.5
$
K přetečení může dojít zejména při interním násobení velkých čísel. Pokud k tomu dojde,
může střední kvadratická odchylka vycházet záporná, což je normálně nepřípustné. Zvažte
normalizování vašich dat. Přičtení, či odečtení konstanty ke všem hodnotám statistického
vzorku nemění hodnotu střední kvadratické odchylky. Podělení všech hodnot statistického
vzorku konstantou způsobí zmenšení střední kvadratické odchylky o čtverec dané konstanty.
Dostupné jsou též histogramy. Například @hist_linear(v,start,stop,interval) reprezentuje
lineární histogram od "start" do "stop" s inkrementem "interval". Inkrement musí být
kladný. Podobně @hist_log(v) představuje binárně logaritmický histogram. Histogram lze
vytisknout některou z rodiny print funkcí. Výsledkem je ASCII-art. Příklad:
probe timer.profile {
x[1] <<< pid()
x[2] <<< uid()
y <<< tid()
}
global x // pole
global y // skalár
probe end {
foreach ([i] in x @count+) {
printf ("x[%d]: avg %d = sum %d / count %d\n",
i, @avg(x[i]), @sum(x[i]), @count(x[i]))
println (@hist_log(x[i]))
}
println ("y:")
println (@hist_log(y))
}
PŘETYPOVÁNÍ
Jakmile se ukazatel uloží do celočíselné proměnné v rámci systemtap skriptu, překladač
ztrácí informaci o typu, která je potřebná k dereferencování.
(viz KONTEXTOVÉ PROMĚNNÉ man stránky stapprobes(3stap)). Použitím operátoru @cast()
sdělujeme kompilátoru, jak má interpretovat takové číslo jakožto typovaný ukazatel.
Příklad:
@cast(p, "type_name"[, "module"])->member
Takto bude p interpretován jako ukazatel do struktury/unionu type_name a dereferencovat
member . Lze připojit další ->subfield a dereferencovat tak další úrovně. Poznamenejme, že
pro přímé dereferencování ukazatele se doporučuje použít funkcí
{kernel,user}_{char,int,...}($p). Více v sekci stapfuncs(5).
POZNÁMKA: stejný operátor -> se používá jak pro přímý odkaz na člena, tak pro dereferenci
ukazatele. Systemtap automaticky interpretuje tuto dvojakost. Volitelná složka module
informuje překladač, kde má hledat informaci o daném typu. module lze uvést vícekrát jako
seznam s oddělovačem :. Pokud module není explicitně určen, budou pro jeho určení využity
ladicí informace, nebo bude nastaven na "kernel" pro funkce a všechny ostatní typy sond.
Překladač může vytvořit svůj vlastní modul s informacemi o typech odvozením z hlavičkových
souborů uzavřených ve špičatých závorkách v případě, že ladicí informace nejsou k
dispozici. Hlavičkovým souborům jádra je třeba přidat řetězec "kernel" jako předponu.
Ostatní hlavičkové soubory budou zpracovány s výchozími volbami kompilátoru. Lze
specifikovat více hlavičkových souborů za sebou pro vyřešení závislostí.
@cast(tv, "timeval", "<sys/time.h>")->tv_sec
@cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
@cast(task, "task_struct",
"kernel<linux/sched.h><linux/fs_struct.h>")->fs->umask
Hodnoty získané operátorem @cast lze přehledně vytisknout (pretty-print) připojením
operátoru $ a $$ jak je popsáno v sekci KONTEXTOVÉ PROMĚNNÉ man stránky stapprobes(3stap).
V guru režimu (-g) umožňuje překladač také přiřadit novou hodnotu dereferencovaným
ukazatelům.
Přetypování je také užitečné v případě void* členů jejichž typ lze určit až za běhu.
Příklad:
probe foo {
if ($var->type == 1) {
value = @cast($var->data, "type1")->bar
} else {
value = @cast($var->data, "type2")->baz
}
print(value)
}
EMBEDDED C
V guru režimu přijímá překladač vložený C kód v uživatelských skriptech. Takový kód je
uzavřen mezi značkami %{ a %} a je doslovně, bez analýzy, vložen do vnější úrovně
vygenerovaného kódu systemtap modulu. Protože je vložen do vnější úrovně, je možné takto
definovat #include direktivy a různé pomocné definice použitelné ve zbytku kódu.
Dalším místem, kde je vložené C povoleno, je tělo funkce. V tomto případě bude tělo
systemtap funkce doslovně tvořeno vloženým C kódem uzavřeným mezi značky %{ a %}. Takto
vložený C kód může vykonávat libovolnou rozumnou a bezpečnou činnost. Existuje množství
nedokumentovaných a komplexních omezení ohledně atomicity, souběžnosti, spotřeby zdrojů a
časových omezení, takže jde o pokročilou techniku.
Paměťová umístění vyhrazená pro vstupní a výstupní hodnoty jsou zpřístupněna pomocí maker
STAP_ARG_* a STAP_RETVALUE. Chyby lze signalizovat pomocí STAP_ERROR, výstup pomocí
STAP_PRINTF a návratovou hodnotu lze předat prostřednictvím STAP_RETURN. Zde je několik
příkladů:
function integer_ops (val) %{
STAP_PRINTF("%d\n", STAP_ARG_val);
STAP_RETVALUE = STAP_ARG_val + 1;
if (STAP_RETVALUE == 4)
STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE);
if (STAP_RETVALUE == 3)
STAP_RETURN(0);
STAP_RETVALUE ++;
%}
function string_ops (val) %{
strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
if (strcmp (STAP_RETVALUE, "three-two-one"))
STAP_RETURN("parametr měl být be three-two-");
%}
function no_ops () %{
STAP_RETURN(); /* funkce bez návratové hodnoty */
%}
Typy funkčních hodnot a typ návratové hodnoty odvodí překladač ze způsobu volání dané
funkce. Před vytvářením vlastních vložených C funkcí je vhodné prostudovat zdrojový kód,
který překladač generuje pro běžné funkce skriptovacího jazyka a tím se inspirovat.
Poslední místo, kde je vložené C povoleno, je r-hodnota ve výrazu. V tomto případě se C-
kód uzavře mezi značky %{ a %} a interpretuje se jako běžná hodnota výrazu. Předpokládá se
pak, že jde o 64 bitové číslo se znaménkem, ovšem pokud se použije značka /* string */,
bude hodnota výrazu interpretována jako řetězec. Příklad:
function add_one (val) {
return val + %{ 1 %}
}
function add_string_two (val) {
return val . %{ /* string */ "two" %}
}
K nastavení bezpečnosti a optimalizace lze použít následující značky:
/* pure */
znamená, že C kód nemá žádné vedlejší efekty a může být v rámci optimalizace zcela
zahozen pokud nemá vazby na zbytek kódu.
/* stable */
znamená, že C kód má vždy stejnou hodnotu (při vyvolání v rámci libovolné obslužné
rutiny sondy), takže opakovaná volání mohou být nahrazena zapamatovanou hodnotou.
Takové funkce nesmí přijímat parametry a musí být /*pure*/.
/* unprivileged */
znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní
uživatelé.
/* myproc-unprivileged */
znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní
uživatelé, ovšem jen při analýze svých vlastních uživatelských procesů.
/* guru */
znamená, že C kód je tak nebezpečný, že vyžaduje použití guru režimu -g.
/* unmangled */
ve vložené C funkci zpřístupní zastaralou (pre-1.8) syntaxi pro přístup k funkčním
parametrům. V tomto případě lze uvnitř funkce kromě STAP_ARG_foo a STAP_RETVALUE
použít také THIS->foo a THIS->__retvalue .
/* unmodified-fnargs */
ve vložené C funkci znamená, že parametry nejsou uvnitř těla funkce měněny.
/* string */
ve vložené C funkci znamená, že výraz má typ const char * a mělo by s ním být
nakládáno jako s řetězcovou hodnotou namísto numerické (což je výchozí chování).
BUILT-INS
Skripty instalované v umístění definovaném ve stappaths(7) poskytují množství vestavěných
sondážních bodů. Ty jsou popsány v man stránce stapprobes(3stap).
ZPRACOVÁNÍ SKRIPTU
Systemtap zpracovává skript v pěti procesních fázích: "parse", "elaborate", "translate",
"compile" a "run". Překladač zahájí fázi 1 lexikální analýzou uživatelského skriptu spolu
se všemi tapset skripty (což jsou soubory s příponou *.stp) nalezenými v tapset adresáři.
Adresáře vyjmenované prostřednictvím -I jsou následně zpracovány také, a to v guru režimu.
Adresářová struktura se prohledává do hloubky. Některé podadresáře jsou specifické pro
verzi jádra (volba -R ), a podle ní jsou (nebo nejsou) prohledávány, takže skripty
specifičtější pro danou verzi jádra mohou předefinovat své méně specifické protějšky.
Například pro verzi jádra 2.6.12-23.FC3 by byly prohledávány následující adresáře:
2.6.12-23.FC3/*.stp, 2.6.12/*.stp, 2.6/*.stp, a nakonec *.stp v tomto pořadí. Pokud
překlad skončí na konci fáze 1 (-p1), pak překladač na standardní výstup vypíše derivační
strom (parse tree).
Ve fázi 2 překladač analyzuje vstupní skript, aby vyhodnotil symboly a datové typy. Odkazy
na proměnné, funkce a přezdívky, které se nepodaří vyhodnotit lokálně, se vyhodnotí proti
tapset skriptům. Pokud je určitý symbol nalezen v tapset skriptu, pak daný tapset bude
celý přidán do fronty pro zpracování překladačem. Tento iterativní proces skončí jakmile
jsou vyhodnoceny všechny symboly s využitím dané podmnožiny tapset skriptů.
Dále se ověří validnost sondážních bodů. Sondy, které se odkazují k umístěním ve zdrojovém
kódu ("synchronní sondážní body") vyžadují, aby byly nainstalovány příslušné ladicí
informace. V obslužných rutinách sond se naleznou cílové proměnné (ty, které začínají
znakem "$") a dekódují se jejich "run-time" lokace.
Dále se všechny sondy a funkce optimalizují. Cílem je odstranit zbytečné proměnné, výrazy
a funkce, které nemají vedlejší účinky. U vložených C funkcí se předpokládá, že mají
vedlejší účinky pokud ovšem neobsahují kouzelnou značku /* pure */. Vzhledem k tomu, že
optimalizace mohou způsobit latentní chyby jako je například typová nekompatibilita, nebo
neplatné kontextové proměnné, může být v některých případech užitečné optimalizace vypnout
přepínačem -u.
Nakonec se z kontextu odvodí datové typy proměnných, funkcí, parametrů, polí a indexů.
Ukončení překladu po fázi 2 (-p2) způsobí vypsání seznamu všech sond, funkcí a proměnných
spolu s jejich odvozenými typy. Nekonzistentní nebo neodvoditelné typy způsobí chybu
překladu.
Ve fázi 3 překladač zapíše vygenerovaný C kód a vytvoří Makefile který slouží k jeho
přeložení do podoby jaderného modulu. Tyto soubory budou umístěny v dočasném adresáři.
Zastavení překladače v této fázi (-p3) způsobí vypsání C souboru na standardní výstup.
Ve fázi 4 překladač vyvolá jaderný "build systém", aby sestavil systemtap modul. Při tom
se v daném dočasném adresáři volá příkaz make. K úspěšnému provedení tohoto kroku je
třeba, aby byl nainstalován "build systém" jádra, tj. hlavičkové soubory, config a
Makefile soubory a to v obvyklém umístění /lib/modules/VERSION/build. Zastavení překladače
v této fázi (-p4) může být užitečné, pokud chceme modul archivovat. Je to také poslední
šance zastavit systemtap před zavedením a spuštěním modulu.
Ve fázi 5 překladač zavolá pomocný program staprun a předá mu vzniklý systemtap modul.
Program staprun zavede modul do jádra, spustí jej a zajišťuje komunikaci s ním dokud
činnost modulu neskončí. Jakákoliv chyba běhu, která se vyskytne v obslužných rutinách
sond, jako např. vyčerpání dostupné paměti, dělení nulou, příliš hluboké zanoření, nebo
překročení "run-time" limitů, způsobí měkkou chybu (soft error). Pokud počet měkkých chyb
překročí MAXERRORS, zastaví se všechny sondy (kromě těch, které obsluhují chyby), a
zastaví se sezení. Nakonec staprun odstraní modul z jádra a provede úklid.
NEOBVYKLÉ UKONČENÍ
Je dobré neukončovat stap proces násilím, například prostřednictvím signálu SIGKILL,
protože proces stapio (potomek procesu stap) a systemtap modul by se nemusely korektně
ukončit. Pokud se to přecejen stane, pošlete všem zbývajícím stapio procesům SIGTERM nebo
SIGINT a použijte rmmod pro odstranění systemtap modulu z jádra.
PŘÍKLADY
Viz stapex(3stap) , kde se nachází několik krátkých příkladů, nebo viz adresář "examples"
v RPM balíčcích "systemtap-client", či "systemtap-testsuite", kde se nachází rozsáhlá
sbírka příkladů. Viz stappaths(7stap) pro podrobný popis konkrétních umístění. Příklady
jsou také zveřejněny na webové stránce projektu systemtap.
CACHE
Překladač systemtapu ukládá do cache výstup fáze 3 (tj. vygenerovaný C kód) a výstup fáze
4 (tj. zkompilovaný jaderný modul) pokud tyto fáze skončí bez chyb. Obsah cache se použije
pokud se znovu překládá stejný skript a za předpokladu, že platí stejné podmínky (verze
jádra, verze systemtapu atp.). Cache se nachází v adresáři $SYSTEMTAP_DIR/cache . Velikost
cache lze omezit umístěním souboru cache_mb_limit do cache adresáře, přičemž tento soubor
obsahuje ASCII číselnou hodnotu limitu, která vyjadřuje velikost cache v MiB. Pokud tento
soubor neexistuje, vytvoří se nový s výchozí hodnotou 256. Jde o měkký limit v tom smyslu,
že cache bude promazána až po určité době. Dočasně tedy může velikost cache překročit
stanovený limit. Zmíněnou periodu je možno nastavit prostřednictvím souboru
cache_clean_interval_s umístěného opět v cache adresáři. Předpokládá se, že tento soubor
obsahuje ASCII celé číslo vyjadřující časový interval pro promazávání cache v sekundách.
Pokud tento soubor neexistuje, vytvoří se nový s výchozí hodnotou 300.
BEZPEČNOST A OCHRANA SOUKROMÍ
Systemtap může být použit jako mocný administrativní nástroj. Může zpřístupnit privátní
uživatelské informace v rámci interních jaderných struktur. To se netýká dyninst runtime,
viz ALTERNATIVNÍ RUNTIME .
Překladač zajišťuje dodržování mnoha různých bezpečnostních omezení během kompilace a běhu
modulu. Snaží se zajistit, aby žádná sonda neběžela příliš dlouho, aby nealokovala příliš
mnoho paměti, neprováděla nebezpečné operace, nebo nežádoucím způsobem neovlivňovala
systém. Při práci s globálními proměnnými se využívají zámky pro čtení a zápis, aby
nedocházelo k chybám při souběhu. Pravidelně dochází k testu na deadlocky. Pro zjištění
nepřiměřeného použití zámků lze použít přepínač -t. Experimentování se skripty je tedy v
zásadě bezpečné. Guru"režim -g umožňuje administrátorům obejít většinu bezpečnostních
opatření a umožnit tak invazivní zásahy a změny stavu systému, použít vložené C a obecně
zvýšit riziko průšvihu. Za normálních okolností je pro všechny moduly aktivní ochrana
proti přetížení. Tu lze vypnout přepínačem --suppress-time-limits.
Chyby zachycené při běhu za normálních okolností vedou k čistému ukončení skriptu s
chybovou hláškou. Přepínač --suppress-handler-errors umožňuje zcela ignorovat měkké chyby,
takže ani po nastřádání jejich většího počtu nedojde k ukončení skriptu.
OPRÁVNĚNÍ
Aby bylo možné spustit systemtap modul v rámci výchozí kernel runtime, musí uživatel
splnit jednu z následujících podmínek:
• být root.
• být členem skupin stapdev a stapusr
• být členem skupin stapsys a stapusr ; nebo
• být členem skupiny stapusr .
Uživatel root, nebo uživatel, který je členem skupin stapdev a stapusr , může přeložit a
spustit libovolný systemtap skript.
Uživatel, který je členem skupin stapsys a stapusr, může použít předem připravené
systemtap moduly za následujících podmínek:
• Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap kompilačním
serverem, který podepsal modul klientovi, který použil volbu --privilege. Viz
stap-server(8).
• Modul byl sestaven s použitím jedné z voleb --privilege=stapsys nebo
--privilege=stapusr.
Členové pouze skupiny stapusr mohou používat jen předem připravené moduly za následujících
podmínek:
• Modul je umístěn v adresáři /lib/modules/VERSION/systemtap. Tento adresář musí být
vlastněn uživatelem root a nesmí být otevřený pro zápis všem.
nebo
• Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap kompilačním
serverem, který podepsal modul klientovi, který použil volbu --privilege. Podrobnější
informace viz stap-server(8).
• Modul byl přeložen s volbou --privilege=stapusr.
Jaderné moduly vygenerované programem stap se zavádějí do jádra a spouštějí pomocí
programu staprun. Staprun je součástí systemtap balíčku určeného k zavádění a odstraňování
modulů (za daných podmínek). Slouží také k přenosu dat mezi systemtap modulem a
uživatelelm. Protože staprun neprovádí žádné bezpečnostní kontroly modulu se kterým
pracuje, bylo by od administrátora systému nemoudré přidat nedůvěryhodného uživatele do
skupiny stapdev nebo stapusr .
SECUREBOOT
Pokud má systém v rámci UEFI firmware zapnutý SecureBoot, všechny jaderné moduly musejí
být kryptograficky podepsány. (Některá jádra dovolují vypnout SecureBoot za běhu kombinací
kláves SysRq-X. Poté nemusí být moduly podepsané.) Kompilační server systemtapu může
podepisovat moduly klíčem MOK (Machine Owner Key) který sdílí s daným systémem. Pro více
informací viz následující wiki:
https://sourceware.org/systemtap/wiki/SecureBoot
LIMITY NA ZDROJE
Mnoho omezení pro využívání prostředků systému se nachází ve formě maker ve vygenerovaném
C kódu systemtap modulu. Ty lze předefinovat prostřednictvím přepínače -D. Seznam
zmíněných maker:
MAXNESTING
Maximální počet zanořených funkčních volání. Výchozí hodnota se určuje při analýze
skriptu. Skripty založené na rekurzi obdrží 10 bonusových slotů.
MAXSTRINGLEN
Maximální délka řetězce. Výchozí hodnota je 128 znaků.
MAXTRYLOCK
Maximální počet iterací při čekání na uvolnění zámku na globální proměnné před tím,
než se vyhlásí deadlock a sonda se přeskočí. Výchozí hodnota je 1000 iterací.
MAXACTION
Maximální počet příkazů, které mohou být vykonány během jednoho hitu sondy (s
vypnutými přerušeními). Výchozí hodnota je 1000.
MAXACTION_INTERRUPTIBLE
Maximální počet příkazů, které mohou být vykonány během jedné aktivace (probe hit)
sondy, která se provádí s povolenými přerušeními. (jako např. sondy begin a end).
Výchozí hodnota je 10 * MAXACTION.
MAXBACKTRACE
Maximální počet zásobníkových rámců, které budou zpracovány při výpisu backtrace.
Relevantní tapset je [u]context-unwind.stp, a výchozí hodnota je 20.
MAXMAPENTRIES
Maximální počet řádků v každém jednom globálním poli. Výchozí hodnota je 2048.
Jednotlivá pole mohou být deklarována s odlišným limitem. Příklad:
global big[10000],little[5]
nebo je možno využít modifikátoru % , čímž se zapne array-wrapping (nahrazování
"starých" prvků) jako v následujícím příkladu:
global big%
Viz sekce o polích.
MAXERRORS
Maximální množství měkkých chyb, které ještě nezpůsobí ukončení skriptu. Výchozí
hodnotou je 0, tedy skript skončí při první měkké chybě. Poznamenejme, že
--suppress-handler-errors tento limit vypíná.
MAXSKIPPED
Maximální počet přeskočených sond, který ještě nevede k ukončení skriptu. Výchozí
hodnotou je 100. Pozn., že systemtap lze spustit s přepínačem -t (timing), který
zobrazí podrobnosti ohledně počtu přeskočených sond. Při použití -DINTERRUPTIBLE=1
se nebudou brát v potaz sondy přeskočené kvůli re-entranci. Dále poznamenejme, že
--suppress-handler-errors vypíná i tento limit.
MINSTACKSPACE
Minimální množství volného místa na zásobníku jádra dostatečné pro start sondy.
Výchozí hodnota 1024 bajtů. Tato hodnota by měla být dostačující pro vlastní
potřebu obslužné rutiny včetně malé rezervy.
MAXUPROBES
Maximální množství současně zamčených uživatelských sond (uprobes). Výchozí hodnota
je o něco málo vyšší, než počet uživatelských sond ve skriptu. Tato hodnota musí
být relativně velká, protože jednotlivé uživatelské sondy (každá z nich okupuje
přibližně 46 bajtů), se alokují pro každý proces a pro každou odpovídající sondu ve
skriptu.
STP_MAXMEMORY
Maximální velikost paměti (v kilobajtech), kterou je systemtap modul oprávněn
použít. Výchozí hodnota je neomezená. Limit zahrnuje velikost modulu samotného plus
dodatečné alokace. Zahrnuty jsou jen přímé alokace provedené systemtap runtime.
Nepřímé alokace, které provádějí např, "kprobes", "uprobes", atd., nejsou
započteny.
STP_OVEROAD_THRESHOLD, STP_OVERLOAD_INTERVAL
Maximální počet cyklů, které lze strávit v sondách za daný čas (též vyjádřený v
cyklech). Při překročení této podmínky dojde k přetížení a skript se zastaví.
Výchozí hodnoty jsou 5e+8 a 1e+9, což odpovídá max. 50% povolenému vytížení.
STP_PROCFS_BUFSIZE
Velikost procfs bufferů pro čtení (v bajtech). Výchozí hodnota je
MAXSTRINGLEN. Tento limit lze nastavit specificky pro jednotlivé sondy pomocí
syntaxe .maxsize(MAXSIZE) .
Pokud skript obsahuje sondy vázané na přerušení, je možné, že k přerušení dojde tak často,
že handler daného přerušení ještě nedoběhne zatímco dojde k dalšímu přerušení. V tomto
případě bude obslužná rutina přeskočena, aby se zamezilo reentranci. Tento problém lze
obejít použitím -DINTERRUPTIBLE=0kodstíněníběžícíobslužnérutinyoddanéhopřerušení. Tento
přístup přináší jistou režii, ale v běžných případech zamezí reentranci. Nicméně, sondy v
NMI handlerech a v samotném procesu stap, mohou stále být přeskočeny, aby se zamezilo
reentranci.
Vznikne-li problém při běhu programu stap nebo staprun když už sondy běží, je možné
bezpečně zabít oba tyto uživatelské procesy a odstranit systemtap modul pomocí rmmod. Část
výstupu se tak nicméně může ztratit.
NEPRIVILEGOVANÍ UŽIVATELÉ
Systemtap umožňuje přístup k interním datům jádra a tedy potenciálně k soukromým datům
uživatele. Z tohoto důvodu je plný přístup k systemtapu omezen na uživatele root a na
uživatele, kteří jsou členy skupin stapdev a stapusr.
Nicméne omezená sada funkcí systemtapu může být dostupná důvěryhodným neprivilegovaným
uživatelům. Tito uživatelé jsou členy pouze skupiny stapusr plus případně skupiny stapsys.
Tito uživatelé mohou zavést do jádra předem připravený modul, který byl podepsán
důvěryhodným kompilačním serverem. Viz popis voleb --privilege a --use-server. Viz také
README.unprivileged mezi zdrojovými soubory systemtapu. Tam je mj. popsáno jak nastavit
důvěryhodný kompilační server.
Omezení která plynou z volby --privilege=stapsys mají zabránit neprivilegovaným
uživatelům v
• záměrném poškozování systému.
Omezení, která plynou z volby --privilege=stapusr mají zabránit neprivilegovaným
uživatelům v
• záměrném poškozování systému.
• získání přístupu k neveřejným / soukromým informacím.
• snižování výkonu procesů vlastněných jinými uživateli systému. Určitému vlivu
na výkon celého systému nelze zabránit, neboť sondy neprivilegovaného uživatele
budou v příslušný čas aktivní. Nicméně hlavním cílem zde je, aby
neprivilegovaný uživatel nežádoucím nezpůsobem zasahoval do procesů jiných
uživatelů.
OMEZENÍ NA SONDY
Člen skupin stapusr a stapsys má přístup ke všem sondám.
Člen pouze skupiny stapusr může použít následující sondy:
• begin, begin(n)
• end, end(n)
• error(n)
• never
• process.*, s tím, že cílový proces je jeho vlastní.
• timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*
• timer.hz(n)
OMEZENÍ SKRIPTOVACÍHO JAZYKA
Následující vlastnosti skriptovacího jazyka jsou pro neprivilegovaného uživatele
nedostupné:
• jakákoliv funkcionalita podmíněná guru režimem (-g).
• vložený C kód.
RUNTIME OMEZENÍ
Neprivilegovaných uživatelů se týkají také následující omezení runtime:
• Lze použít jen výchozí runtime kód (viz -R).
Na členy pouze skupiny stapusr se vztahují dodatečná omezení:
• Analýza procesů vlastněných jinými uživateli není dovolena.
• Přístup do paměti jádra není dovolen ani pro zápis, ani pro čtení.
OMEZENÍ NA VOLBY PŘÍKAZOVÉ ŘÁDKY
Některé volby příkazové řádky poskytují přístup k funkcionalitě, která nesmí být přístupná
žádnému neprivilegovanému uživateli. Konkrétně
• Nesmí nastavit -g .
• Následující volby nesmějí být použity klientem kompilačního serveru:
-a, -B, -D, -I, -r, -R
OMEZENÍ NA PROMĚNNÉ PROSTŘEDÍ
Neprivilegovaní uživatelé nesmějí nastavit následující proměnné prostředí:
SYSTEMTAP_RUNTIME
SYSTEMTAP_TAPSET
SYSTEMTAP_DEBUGINFO_PATH
OMEZENÍ NA TAPSETY
Obecně jsou tapset funkce přístupné členům skupiny stapusr pokud nepřistupují k
informacím, které by neměl právo získat libovolný uživatelský program běžící s identitou
daného uživatele.
Existují dvě skupiny tapset funkcí pro neprivilegované uživatele. První kategorie sestává
z funkcí, které mohou použít všichni uživatelé, jako napřiklad:
cpu:long ()
exit ()
str_replace:string (prnt_str:string, srch_str:string, rplc_str:string)
Druhou skupinou jsou tzv. myproc-unprivileged funkce, které mohou sbírat informace pouze o
procesech, které daný uživatel vlastní. Skripty, které mají používat myproc-unprivileged
funkce musí testovat is_myproc() a volat takové funkce jen když výsledek je 1. Skript se
ihned ukončí, pokud tato podmínka nebude splněna. Přiklady myproc-unprivileged funkcí:
print_usyms (stk:string)
user_int:long (addr:long)
usymname:string (addr:long)
Pokud se uživatel patřící pouze do skupiny stapusr pokusí použít tapset funkci, která
nespadá do žádné ze zmíněných dvou kategorií, dojde k chybě při kompilaci.
ALTERNATIVNÍ RUNTIME BACKENDY
Jak již bylo zmíněno, systemtap používá jako výchozí tzv. "kernel runtime backend", který
pracuje na principu jaderného modulu. To přináší výše zmíněná bezpečnostní úskalí.
Systemtap nově obsahuje dva prototypy nových "backendů", které lze aktivovat volbami
--runtime=dyninst a --runtime=bpf.
--runtime=dyninst využívá Dyninst a lze jej použít k instrumentaci uživatelských procesů.
Není založen na bázi jaderných modulů a nevyžaduje rootovské oprávnění. Zůstávají v něm
ale v platnosti omezení na povolené typy sond.
Dyninst backend pracuje v režimu připojení se k cílovému procesu, proto vyžaduje volbu -c
COMMAND, nebo -x PID process. Napřiklad:
stap --runtime=dyninst -c "stap -V" \
-e "probe process.function("main")
{ println("hi from dyninst!") }"
Pro správnou funkci dyninst runtime může být nezbytné zapnout na cílovém systému SELinux
volbu allow_execstack:
# setsebool allow_execstack 1
--runtime=bpf překládá systemtap skript na extended Berkeley Packet Filter (eBPF) program.
Linuxové jádro kontroluje eBPF programy z hlediska bezpečnosti, a spouští je na svém
interním virtuálním stroji. Tento "runtime backend" je v časné fázi vývoje, a momentálně
trpí řadou omezení, viz stapbpf(8).
NÁVRATOVÝ KÓD
V případě úspěšného běhu vrátí příkaz stap kód 0 (exit code). V opačném případě se na
standardní chybový výstup může vypsat chybová hláška a stap vrátí nenulový kód. Pro
zvýšení upovídanosti použijte -v nebo -vp N .
V "listing" režimu (-l and -L), se chyby obvykle potlačují. Pokud byla nalezena alespoň
jedna sonda vyhovující zadaným požadavkům, stap skončí s návratovým kódem 0.
Skript, který skončí svůj běh na žádost uživatele použitím ^C / SIGINT, se považuje za
úspěšně ukončený.
ZASTARÁVÁNÍ
Během vývoje systemtapu dochází občas ve skriptovacím jazyce k nekompatibilním změnám,
takže staré skripty mohou přestat fungovat. V takovém případě může pomoci volba
--compatible VERSION kde se určí poslední známá verze systemtapu, se kterou daný skript
fungoval.
Při použití volby --check-version vypíše systemtap varování pokud narazí při lexikální
analýze na nekompatibilní element. Informace o zastarávání se udržují v souboru NEWS.
Smyslem mechanizmu zastarávání je přinést žádoucí inovace skriptovacího jazyka a současně
nerozbít kompatibilitu se starými existujícími skripty. Mechanizmus zastarávání by tedy
měl být chápán především jako služba přinášející pohodlí uživatelům (a nepohodlí
vývojářům) spíše než naopak.
Poznamenejme, že tapset identifikátory s předponou "_" jsou považovány za interní a občas
podstupují změny při kterých je těžké zaručit zpětnou kompatibilitu i při použití
mechanizmu zastarávání. V případě potřeby, prosím, navrhněte takový symbol k regulernímu
zveřejnění.
SOUBORY
Důležité soubory a jim příslušné cesty dokumentuje manuálová stránka stappaths (7).
VIZ TAKÉ
stapprobes(3stap),
function::*(3stap),
probe::*(3stap),
tapset::*(3stap),
stappaths(7),
staprun(8),
stapdyn(8),
systemtap(8),
stapvars(3stap),
stapex(3stap),
stap-server(8),
stap-prep(1),
stapref(1),
awk(1),
gdb(1)
CHYBY
Prosím, použijte následující bugzilla link, nebo náš mailing list.
http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs
STAP(1)