STAP(1) General Commands Manual STAP(1) JMENO stap - prekladac a radic systemtap skriptu POUZITI stap [ VOLBY ] JMENO_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 hlavnim uzivatelskym rozhranim nastroje systemtap. Prijima pozadavky na sondovani systemu (probing) zapsane v jednoduchem skriptovacim jazyce, preklada je do jazyka C, vysledny kod zkompiluje a vytvori jaderny modul, ktery nasledne zavede do beziciho linuxoveho jadra nebo dyninst instrumentacniho nastroje, aby provadel pozadovanou analyzu zkoumaneho systemu. Skript muze byt cten ze souboru (JMENO_SOUBORU), ze standardniho vstupu (v tom pripade pouzijte "-" namisto JMENO_SOUBORU), z prikazove radky (prostrednictvim prepinace -e SKRIPT, pripadne -E SKRIPT). Program bezi dokud neni prerusen uzivatelem, nebo dokud skript nezavola exit(), nebo dokud nedojde k nastradani dostatecneho mnozstvi tzv. mekkych chyb (soft errors). Jazyk, ktery je popsan nize v sekci SKRIPTOVACI JAZYK, je striktne typovany, imperativni, bez explicitnich deklaraci, proceduralni, vhodny k prototypovani a inspirovany awk a C. Umoznuje spojit misto ve zdrojovem kodu linuxoveho jadra, nebo uzivatelske aplikace, pripadne systemovou udalost s obsluznymi rutinami, coz jsou bloky kodu vykonavane synchronne. Koncepcne to pripomina skriptovani v gdb. PREHLED DOKUMENTACE Pro SystemTap existuje mnozstvi vzdelavacich, dokumentacnich a referencnich materialu jak v online podobe, tak i v ramci distribucnich balicku. Online dokumentace se nachazi na projektovem webu https://sourceware.org/systemtap/ +--------------------------+------------------------------------------------------------+ |man stranky | | +--------------------------+------------------------------------------------------------+ |stap (tato stranka) | syntaxe jazyka, koncepty, funkce, volby | +--------------------------+------------------------------------------------------------+ |stapprobes | sondazni body a jejich kontextove promenne | +--------------------------+------------------------------------------------------------+ |stapref | rychla reference pro syntaxi jazyka | +--------------------------+------------------------------------------------------------+ |stappaths | seznam dulezitych umisteni vcetne knih a odkazu | +--------------------------+------------------------------------------------------------+ |stap-prep | instalator zavislosti jako napr. ladicich informaci jadra | +--------------------------+------------------------------------------------------------+ |tapset::* | vygenerovany seznam tapsetu | +--------------------------+------------------------------------------------------------+ |probe::* | vygenerovany seznam tapsetovych prezdivek | +--------------------------+------------------------------------------------------------+ |function::* | vygenerovany seznam tapsetovych funkci | +--------------------------+------------------------------------------------------------+ |macro::* | vygenerovany seznam tapsetovych maker | +--------------------------+------------------------------------------------------------+ |stapvars | vybrane globalni promenne definovane v tapsetech | +--------------------------+------------------------------------------------------------+ |staprun, stapdyn, stapbpf | programy pro spusteni zkompilovanych systemtap skriptu | +--------------------------+------------------------------------------------------------+ |systemtap | systemova sluzba, analyza startu systemu | +--------------------------+------------------------------------------------------------+ |stap-server | kompilacni server | +--------------------------+------------------------------------------------------------+ |stapex | nekolik velmi jednoduchych prikladu | +--------------------------+------------------------------------------------------------+ |knihy | | +--------------------------+------------------------------------------------------------+ |Beginner's Guide | ucebnice zakladu s praktickymi ukazkami | +--------------------------+------------------------------------------------------------+ |Tutorial | hutny uvod, cviceni | +--------------------------+------------------------------------------------------------+ |Language Reference | podrobny manual skriptovaciho jazyka | +--------------------------+------------------------------------------------------------+ |Tapset Reference | man stranky tapsetu v podobe knihy | +--------------------------+------------------------------------------------------------+ |odkazy | | +--------------------------+------------------------------------------------------------+ |example scripts | mnozstvi nastroju pro spravu systemu, ukazkovych skriptu a | | | vyukovych hracek | +--------------------------+------------------------------------------------------------+ VOLBY Prikaz stap akceptuje nasledujici volby. Jakakoliv jina volba vypise seznam podporovanych voleb. Volby lze uvest na prikazove radce, jak je obvykle. Pokud existuje $SYSTEMTAP_DIR/rc, mohou byt volby nacteny odtud a interpretovany nejdrive. Pokud neni $SYSTEMTAP_DIR nastavena, pouzije se $HOME/.systemtap jako vychozi. V nekterych pripadech muze vychozi hodnota volby zaviset na konkretni konfiguraci systemu a proto zde neni primo uvedena. V takovem pripade muze pomoci "stap --help". - Nacte skript ze standardniho vstupu namisto ze souboru JMENO_SOUBORU, pokud ovsem neni dano -e SKRIPT. -h --help Zobrazi napovedu. -V --version Zobrazi verzi. -p NUM Zastavi po dokonceni procesni faze NUM. Procesni faze jsou ocislovane 1-5 (parse, elaborate, translate, compile, run). Viz sekce ZPRACOVANI . -v Zvysi upovidanost pro vsechny procesni faze. Tuto volbu lze opakovat pro zvyseni mnozstvi informativniho (?) vystupu. --vp ABCDE Zvysi upovidanost pro jednotlive procesni faze. Napriklad, "--vp 002" prida 2 jednotky upovidanosti procesni fazi 3. Kombinace "-v --vp 00004" prida 1 jednotku upovidanosti vsem procesnim fazim, a dalsi ctyri jednotky fazi 5. -k Zachova docasny procesni adresar, ktery se jinak po dokonceni skriptu smaze. To muze byt uzitecne, chceme-li zkoumat vygenerovany C kod, nebo jej znovu pouzit pro vytvoreni jaderneho modulu. -g Guru rezim. Umozni pouzit potencialne nebezpecne expertni konstrukce, jako napriklad vlozeny (embedded) C kod v ramci systemtap skriptu. -P Rezim prohledavani prologu (prologue-searching). Ekvivalentem je --prologue-searching=always. Aktivuje heuristiku pro obchazeni problemu s nekonzistentnimi ladicimi informacemi pro kontextove promenne parametru funkci. -u Vypne optimalizace jako napr. odstranovani nepotrebneho kodu (a mnoho dalsich) behem 2., ci 3. procesni faze (elaboration, translation). -w Potlaci vsechny varovne hlaseni. -W Zachazi s varovanimi stejne jako s chybami. -b Tzv. "bulk" rezim pro prenos dat z jadra k uzivateli. V tomto rezimu jsou data pro jednotlive CPU prenasena oddelene a zapisovana do samostatnych souboru. Pro jejich pripadne slouceni lze pouzit prikaz stap-merge. -t Sbira ruzne casovaci informace jako napriklad pocet aktivaci (probe hits) pro jednotlive sondy, prumerny cas straveny v jednotlivych sondach, atd. -s NUM Nastavi velikost bufferu pro prenos dat ze systemtap modulu k uzivateli na NUM MB. Na viceprocesorovem systemu v "bulk" rezimu bude mit tuto velikost kazdy jednotlivy buffer. -I DIR Prida DIR mezi cesty ve kterych se vyhledavaji tapset skripty. Vice informaci obsahuje popis procesni faze 2. -D NAME=VALUE Prida danou direktivu do Makefile systemtap modulu. Toho lze vyuzit napriklad k predefinovani ruznych omezeni popsanych nize. -B NAME=VALUE Preda danou direktivu prikazu make pri sestavovani systemtap modulu. Toho lze vyuzit k pridani nebo zmene "kconfig" voleb. -a ARCH Pouzije rezim krizoveho prekladu (cross compilation) pro danou cilovou architekturu. Tato volba vyzaduje pristup ke kompilacnimu serveru a obvykle se pouziva spolu s volbami -B CROSS_COMPILE=arch-tool-prefix- a -r /build/tree. --modinfo NAME=VALUE Prida par klic/hodnota ve forme makra MODULE_INFO do vygenerovaneho modulu. Toho lze vyuzit k nastaveni nebo uprave ruznych jadernych kontrol souvisejicich s modulem. -G NAME=VALUE Nastavuje hodnotu globalni promenne NAME na VALUE pri volani programu staprun. Tak lze nastavit hodnotu skalarni globalni promenne skriptu. -R DIR Prohledava DIR na systemtap runtime zdroje. Vychozi hodnotu DIR lze zobrazit napr. prostrednictvim "stap --help". -r /DIR Pouzije dany jaderny "build tree". Lze take nastavit prostrednictvim promenne prostredi SYSTEMTAP_RELEASE . -r RELEASE Urci "release" jadra v ramci "build tree" /lib/modules/RELEASE/build. Lze tez nastavit prostrednictvim promenne prostredi SYSTEMTAP_RELEASE . -m MODULE Pouzije dane jmeno pro vygenerovany jaderny modul namisto obvykleho nahodne vygenerovaneho jmena. Takto vygenerovany modul se pak navic zkopiruje do aktualniho adresare. -d MODULE Prida do systemtap modulu ladici informace o symbolech a informace pro odvijeni zasobniku pro dany MODULE. Tak lze umoznit symbolicke tracebacky pro MODULE i kdyz do nej neni explicitne vlozena sonda. --ldd Prida do systemtap modulu ladici informace pro vsechny uzivatelske spustitelne soubory nebo DSO knihovny, ktere ldd podezriva z uzitecnosti pro pozadovanou analyzu. Totez bude do systemtap modulu pridano i pro moduly vyjmenovane pomoci prepinacu -d. Upozorneni: --ldd muze systemtap modul znacne zvetsit. --all-modules Ekvivalent pro "-dkernel" a "-d" pro kazdy z momentalne zavedenych modulu. Upozorneni: --all-modules muze systemtap modul znacne zvetsit. -o FILE Presmeruje vystup do souboru FILE. V bulk rezimu se pouzije pro kazdou CPU samostatny soubor s prefixem FILE_ (FILE_cpu s -F) nasledovanym cislem CPU. Pro FILE je podporovan strftime(3) format. -c CMD Zavede a nastartuje systemtap modul, spusti prikaz CMD, a vse ukonci spolu s CMD. Vedlejsim efektem je nastaveni target() na pid CMD. -x PID Nastavi target() na PID. Takto lze psat skripty se zamerenim na dany proces. V tomto pripade systemtap skript bezi bez ohledu na zivotni cyklus procesu PID. -e SKRIPT Spusti SKRIPT. Priklad: stap -e "probe oneshot { log("hello") }" -E SKRIPT Spusti SKRIPT. Ten bezi spolu s hlavnim skriptem urcenym pomoci -e nebo nactenym ze souboru. Tuto volbu lze opakovat pro nacteni vetsiho poctu skriptu. Taktez ji lze pouzit v kombinaci s -l/-L. -l PROBE Namisto obvykleho spusteni systemtap skriptu, tato volba vypise vsechny sondy ktere odpovidaji parametru PROBE. PROBE muze obsahovat zastupne symboly a prezdivky, ale ne seznam carkou oddelenych sondaznich bodu. Pokud PROBE neodpovida zadne dostupne sonde, bude vysledkem chyba. -L PROBE Podoba se "-l", ale navic vypise dostupne lokalni promenne. -F Bez -o tato volba zavede systemtap modul, spusti sondy a odpoji se od beziciho modulu. V kombinaci s volbou -o spusti staprun na pozadi jako demon a vypise jeho pid. -S size[,N] Nastavuje maximalni velikost vystupniho souboru a pripadne take pocet vystupnich souboru. V pripade, ze dojde k prekroceni maximalni velikosti vystupniho souboru size , prepne systemtap svuj vystup do dalsiho souboru. Paklize pocet vystupnich souboru prekroci N , systemtap odstrani nejstarsi vystupni soubor. Druhy z argumentu lze vynechat. -T TIMEOUT Ukoncit skript po uplynuti TIMEOUT sekund. --skip-badvars Ignoruje neidentifikovatelne nebo nedostupne kontextove promenne a, aniz by doslo k chybe, nahradi jejich hodnotu nulou. --prologue-searching[=WHEN] Rezim prologue-searching. Aktivuje heuristiku k vyrovnani se s nekvalitnimi ladici informacemi pro kontextove promenne funkcnich parametru. WHEN muze byt "never" (nikdy), "always" (vzdy), nebo "auto" (tj. zapnuto na zaklade heuristiky). Kdyz WHEN chybi, predpoklada se "always". Bez explicitni specifikace se predpoklada "auto". --suppress-handler-errors Zabali vsechny obsluzne rutiny do obalky podobne nasledujicimu kodu: try { ... } catch { next } blok, ktery zpusobuje chyby v dobe behu, bude tise potlacen. Potlacene chyby se nebudou vyhodnocovat proti limitu MAXERRORS. V tomto rezimu je taktez potlaceno testovani MAXSKIPPED , takze pri behu skriptu muze dojit k libovolnemu mnozstvi chyb. Celkove pocty chyb budou nicmene reportovany pri ukonceni skriptu. --compatible VERSION Z uzivatelskeho hlediska se tato volba pokousi napodobit chovani systemtapu dane verze a umoznit tak beh starsim skriptum. Viz tez sekce ZASTARAVANI. --check-version Tato volba slouzi k overeni, zda aktivni skript obsahuje konstrukce zavisle na verzi systemtapu. Viz tez sekce ZASTARAVANI. --clean-cache Tato volba smaze zastarale polozky v cache adresari. To se normalne deje po uspesnem ukonceni skriptu, ale tato volba vycisti cache explicitne, a pak ukonci systemtap. Viz sekce CACHE. --color[=WHEN], --colour[=WHEN] Tato volba ovlada obarvovani vystupu. WHEN muze byt "never" (nikdy), "always" (vzdy), nebo "auto" (zapnuto pokud jde vystup do terminalu). Pokud WHEN chybi, predpoklada se "auto". Barvy lze menit prostrednictvim promenne prostredi SYSTEMTAP_COLORS. Format je nasledujici: klic1=hodnota1:klic2=hodnota2:klic3=hodnota3 ...atd. Platne klice jsou: "error", "warning", "source", "caret", a "token". Hodnotami jsou "Select Graphic Rendition" (SGR) parametry. Viz dokumentace k pouzitemu terminalu. Priklad vychoziho nastaveni je: error=01;31:warning=00;33:source=00;34:caret=01:token=01. Pokud SYSTEMTAP_COLORS chybi, pouzije se vychozi nastaveni. Pokud to je prazdne nebo chybne, obarvovani se vypne. --disable-cache Tato volba vypne veskere pouzivani cache. Zadne soubory nebudou do cache adresare zapsany, ani z nej cteny. --poison-cache Tato volba zachazi se soubory v cache jako s neplatnymi. Zadne soubory nebudou z cache cteny, ale nove soubory budou do cache zapsany na zaklade aktualniho behu. Tato volba ma pomoci hledat chybu v pripade, kdy se cache systemtapu zda fungovat chybne. Pokud tato volba pomohla, provdepodobne je v nekde v systemtapu chyba, o ktere by vyvojari radi vedeli. Prosim, nahlaste ji. --privilege[=stapusr | =stapsys | =stapdev] Tato volba zkontroluje skript na pritomnost konstruktu, ktere nejsou povoleny pro zadanou uroven opravneni (viz NEPRIVILEGOVANI UZIVATELE). Pokud skript nepovolene konstrukty obsahuje, kompilace skonci chybou. Pokud je stapusr nebo stapsys specifikovano pri pouziti kompilacniho serveru (viz --use-server), pak server zkontroluje skript a, pokud kompilace uspeje, server kryptograficky podepise vysledny modul, kde specifikuje, ze dany modul je bezpecny pro pouziti uzivatelem s danou urovni opravneni. Pokud se --privilege nespecifikuje, -pN se take nespecifikuje s N < 5 a dany uzivatel neni root ani clen skupiny stapdev, pak stap automaticky prida odpovidajici --privilege volbu k jiz specifikovanym volbam. --unprivileged Ekvivalent pro --privilege=stapusr. --use-server[=HOSTNAME[:PORT] | =IP_ADDRESS[:PORT] | =CERT_SERIAL] Specifikuje kompilacni server(y) pro kompilaci, a/nebo - v kombinaci s --list-servers a --trust-servers (viz nize) pro vypis serveru. Pokud je tato volba pouzita bez parametru v neprivilegovanem rezimu (viz --privilege) , pak vychozi server, ktery bude pro kompilaci pouzit, bude nektery z dostupnych kompatibilnich serveru "online SSL peer", a zaroven "module signer". Jinak bude jako vychozi server pouzit nektery z dostupnych kompatibilnich serveru "online SSL peer". --use-server lze pouzit opakovane a v tomto pripade bude seznam pouzitelnych serveru postupne rozsirovan v danem poradi. Servery lze specifikovat pomoci hostaname, IP adresy, nebo serialnim cislem certifikatu (ziskanym prostrednictvim --list-servers). Posledni moznost je nejbeznejsi pro (od)nastavovani duveryhodnosti serveru. Viz --trust-servers nize. Pokud je server specifikovan pomoci hostname nebo IP adresy, pak je volitelne mozne urcit i cislo portu. To je vhodne pro pristup k serverum, ktere nejsou na lokalni siti, nebo pro specifikovani konkretniho serveru. IP adresou muze byt jak IPv4, tak IPv6. Pokud existuje vice nez jedno rozhrani s danou link-local IPv6 adresou, pak je mozne zvolit konkretni rozhrani pripojenim znaku "%" a nazvu rozhrani k adrese, napriklad: "fe80::5eff:35ff:fe07:55ca%eth0". Pro urceni cisla portu IPv6 adresy je nutne uzavrit adresu do hranatych zavorek , aby doslo k oddeleni adresy od cisla portu. Napriklad: "[fe80::5eff:35ff:fe07:55ca]:5000" nebo "[fe80::5eff:35ff:fe07:55ca%eth0]:5000". Pokud --use-server nebylo specifikovano, -pN nebylo specifikovano s N < 5, a uzivatel neni root, neni clen skupiny stapdev, ale je clenem skupiny stapusr, pak stap automaticky prida --use-server k jiz specifikovanym volbam. --use-server-on-error[=yes|=no] Pozada stap, aby zkusil kompilaci znovu s pouzitim kompilacniho serveru, pokud lokalni kompilace selze. Pokud tato volba neni specifikovana, pak se za vychozi povazuje --use-server-on-error=no --use-server-on-error je ekvivalentem pro --use-server-on-error=yes. Kompilace muze byt prerusena pro urcity typ chyby, jako napriklad nedostatek dat nebo zdroju. K tomu muze dojit i behem rekompilace. Pro rekompilaci budou servery voleny automaticky tak, jako by byla pouzita volba --use-server bez parametru. --list-servers[=SERVERS] Zobrazi stav pozadovanych SERVERS, kde SERVERS je carkou oddeleny seznam atributu popisujicich servery. Sjednoceni atributu slouzi k vygenerovani seznamu serveru. Dostupne atributy jsou: all specifikuje vsechny zname servery (duveryhodne servery "SSL peer", duveryhodne servery "module signer", servery ve stavu "online"). specified urcuje servery specifikovane pomoci --use-server. online vybere ze seznamu jen ty servery, ktere jsou aktualne ve stavu "online". trusted vybere ze seznamu jen duveryhodne servery "SSL peer". signer vybere ze seznamu jen servery "module signer", viz --privilege. compatible vybere jen kompatibilni servery ve smyslu kernel release a architektury. Pokud neni dan zadny argument, pak vychozi volbou je specified. Pokud zadne servery nebyly specifikovany pomoci --use-server, pak budou vypsany vychozi servery pro --use-server. Poznamenejme, ze --list-servers pouziva avahi-daemon k detekci online serveru. Pokud tato sluzba neni dostupna, pak --list-servers nebude detekovat zadne online servery. Aby --list-servers detekoval servery poslouchajici na IPv6 adresach, musi konfiguracni soubor avahi demona, /etc/avahi/avahi-daemon.conf , obsahovat "use-ipv6=yes". Po pripadne uprave konfiguracniho souboru je treba sluzbu restartovat. --trust-servers[=TRUST_SPEC] Nastavit nebo odvolat nataveni duveryhodnosti kompilacniho serveru specifikovaneho pomoci --use-server podle TRUST_SPEC, kde TRUST_SPEC je carkou oddeleny seznam typu duveryhodnosti. Podporovane typy jsou: ssl duverovat specifikovanym serverum jako "SSL peer". signer duverovat specifikovanym serverum jako "module signer" (viz --privilege). Jen root muze nastavit signer. all-users duverovat specifikovanym serverum jako "SSL peer" pro vsechny uzivatele na localhostu. Vychozi chovani je nastavit tento typ duverovani jen pro aktualniho uzivatele. Duvera typu "module signer" se vzdy vztahuje na vsechny uzivatele. Jen root muze nastavit all-users. revoke rusi urcenou relaci duvery. Vychozi chovani je zapnuti relace duvery. no-prompt nezadat uzivatele o potvrzeni pred provedenim akce. Vychozi chovani je pozadat o potvrzeni pred provedenim akce. Pokud zadny argument neni nastaven, pouzije se vychozi hodnota ssl. Pokud pomoci --use-server, nebyly urcene zadne servery, zadna relace duvery nebude nastavena ani zrusena. Dokud se nespecifikuje no-prompt, uzivatel bude pozadan o potvrzeni pozadovane akce. --dump-probe-types Vypise vsechny podporovane typy sond a skonci. Pokud je tez nastaveno --privilege=stapusr , pak tento seznam bude omezen tak, aby videt byly pouze sondy, ktere ma dany uzivatel pravo pouzit. --dump-probe-aliases Vypise vsechny prezdivky nalezene v tapset skriptech a skonci. --dump-functions Vypise vsechny verejne funkce nalezene v tapset skriptech a skonci. Take vypise jejich parametry a typy. Navratovy typ "unknown" znaci, ze dana funkce nevraci hodnotu. Poznamenejme, ze ne vsechny navratove typy / typy parametru je vzdy mozne pri syntakticke analyze stanovit. Nestanovene typy budou tez oznaceny jako "unknown". Funkce --dump-functions je narocna na pamet a proto nemusi spravne fungovat s --use-server pokud na cilovem systemu narazi na rlimit pro pamet procesu, napriklad prostrednictvim konfiguracniho souboru ~stap- server/.systemtap/rc, viz stap-server(8). --remote URL Provede skript na vzdalenem stroji. Tuto volbu je mozne opakovat pro provedeni skriptu na vice strojich. Procesni faze 1-4 se provedou lokalne, jak je bezne, a pak behem faze 5, se modul zkopiruje na specifikovane stroje a na nich provede. Prijatelne URL jsou: [USER@]HOSTNAME, ssh://[USER@]HOSTNAME Tento rezim vyuziva SSH, volitelne s vyuzitim specifickeho uzivatelskeho jmena username. Pokud je pouzit uzivatelsky ssh_config, je treba do nej pridat SendEnv LANG pro zachovani nastaveni lokalizace. libvirt://DOMAIN, libvirt://DOMAIN/LIBVIRT_URI Tento rezim vyuziva ke spusteni skriptu stapvirt v domene obsluhovane libvirt demonem. Volitelne je mozno specifikovat LIBVIRT_URI pro pripojeni ke specifickemu driveru nebo vzdalenemu stroji. Napriklad pro pripojeni k mistnimu privilegovanemu QEMU driveru pouzijte: --remote libvirt://MyDomain/qemu:///system Viz pro podrobnosti ohledne podporovanych formatu URI. Viz tez stapvirt(1). unix:PATH V tomto rezimu dojde k pripojeni pres UNIX soket. Toho lze vyuzit pro pripojeni pres QEMU virtio-serial port pro spusteni skriptu uvnitr beziciho virtualniho stroje. direct:// Loopback rezim pro spousteni na localhostu. --remote-prefix Oprefixuje kazdou radku vystupu "N: ", kde N je index vzdaleneho stroje ze ktereho dany vystup pochazi. --download-ladiciinfo[=OPTION] Podle OPTION zapne, vypne, nebo nastavi timeout pro funkci automatickeho stahovani balicku s ladicimi informacemi, kterou nabizi ABRT. Pripustne hodnoty pro OPTION jsou: yes povoli automaticke stahovani bez casoveho omezeni. Totez jako --download-debuginfo bez parametru. no explicitne vypne automaticke stahovani Totez jako nepouziti --download-debuginfo vubec. ask ukaze vystup ABRTu a dotaze se uzivatele, zda se ma pokracovat v downloadu. Zadny timeout nebude nastaven. specifikuje timeout jako pozitivni cele cislo vyjadrujici maximalni pocet sekund pro download. --rlimit-as=NUM Urci maximalni velikost virtualni pameti procesu v bajtech. Bez specifikace NUM nebude zadny limit nastaven. --rlimit-cpu=NUM Urci limit pro cas CPU v sekundach. Bez specifikace NUM neni zadny limit nastaven. --rlimit-nproc=NUM Urci maximalni pocet procesu ktere muze systemtap vytvorit. Bez specifikace NUM neni zadny limit nastaven. --rlimit-stack=NUM Nastavi maximalni velikost zasobniku v bajtech. Bez specifikace NUM neni zadny limit nastaven. --rlimit-fsize=NUM Nastavi maximalni velikost souboru, ktery je mozno vytvorit, v bajtech. Bez specifikace NUM neni zadny limit nastaven. --sysroot=DIR Nastavi "sysroot" adresar, kde budou umisteny cilove soubory (programy, knihovny atd.) Po nastaveni -r RELEASE bude v adresari "sysroot" hledan "build" adresar jadra, ovsem po nastaveni -r /DIR nebude "sysroot" prohledavan na "build" adresar jadra. --sysenv=VAR=VALUE Nastavi alternativni hodnotu promenne prostredi pokud se tato hodnota na vzdalenem systemu lisi. Predpoklada se, ze promenne vyjadrujici cesty budou uvedeny jako relativni cesty vzhledem k --sysroot (pokud je nastaven). --suppress-time-limits Potlaci -DSTP_OVERLOAD*, -DMAXACTION a -DMAXTRYLOCK. Vyzaduje guru rezim (-g). --runtime=MODE Nastavi runtime rezim pro procesni fazi 5. Validni hodnoty jsou kernel (vychozi), dyninst a bpf. Viz sekce ALTERNATIVNI RUNTIME. --dyninst Zkratka pro --runtime=dyninst. --save-uprobes Na strojich, kde si SystemTap musi sestavit svuj vlastni modul "uprobes" (jadra pred 3.5), tato volba instruuje SystemTap, aby po sestaveni tento pomocny modul zachoval v aktualnim adresari. --target-namespaces=PID Nastavuje cilovy "namespace" (jmenny prostor procesu) na "namespace" do ktereho patri PID. Volba souvisi s "namespace-aware" tapset funkcemi. Pokud cilovy "namespace" neni specifikovan, pouzije se "namespace" v kterem bezi stap. --monitor=INTERVAL Umoznuje zobrazovat informace o stavu modulu (cas behu, jmeno modulu, id uzivatele, ktery modul aktivoval, informace o pameti, globalni promenne, seznam sond vcetne jejich statistik). Je mozno nastavit volitelny parametr INTERVAL, ktery urcuje obnovovaci frekvenci stavoveho okna v sekundach. Cinnost modulu lze ovladat nasledujicimi klavesami: r prenastavi vsechny globalni promenne na jejich vychozi hodnoty nebo na nulu, pokud vychozi hodnota nebyla urcena. s cyklicky meni hodnoty daneho atributu za ucelem zmeny trideni seznamu sond. t umoznuje aktivovat/deaktivovat sondu indexem. navigacni-klavesy Klavesami j/k/Up/Down lze posouvat seznam sond. Klavesami d/u/PgDn/PgUp lze rolovat v statistice modulu. ARGUMENTY Vsechny dalsi argumenty z prikazove radky se predaji kompilatoru ke zpracovani. Viz nize. SKRIPTOVACI JAZYK Skriptovaci jazyk systemtapu pripomina awk a C. Existuji v nem dva hlavni konstrukty: sondy a funkce. V jejich ramci se pouzivaji prikazy a vyrazy se syntaxi podobnou syntaxi jazyka C. OBECNA SYNTAXE Bile misto se ignoruje. Podporovany jsou komentare tri typu: # ... shell styl, do konce radku, mimo $# a @# // ... C++ styl, do konce radku /* ... C styl ... */ Literaly jsou budto retezce uzavrene v uvozovkach (dovoluji obvykle C escape sekvence se zpetnymi lomitky, ktere lze retezit podobne jako v C), nebo cela cisla (dekadicka, hexadecimalni, nebo oktalova, zapsana stejne jako v C). Maximalni delka retezce je rozumne omezena na nekolik set bajtu. Cela cisla jsou 64-bitova se znamenkem. Parser formalne prijima i kladna cisla nad 2**63, pro ktere pak pouziva modulo aritmetiku z duvodu preteceni (wrap around). Na konci prikazove radky lze skriptum predat parametry. V ramci skriptu k nim pak lze pristupovat prostrednictvim $1 ... $ pokud jde literaly neuzavrene do uvozovek, nebo @1 ... @ pokud jde o retezcove literaly uzavrene do uvozovek. Pocet argumentu je pristupny prostrednictvim $# (jakozto cislo neuzavrene do uvozovek) nebo prostrednictvim @# (jakozto cislo do uvozovek uzavrene). Tyto symboly lze pouzit na miste libovolne lexikalni jednotky skriptu, a k jejich vyhodnoceni dojde jiz v pocatecni fazi prekladu (preprocessing). FAZE PREDZPRACOVANI (PREPROCESSING) Soucasti lexikalni analyzy je jednoducha faze predzpracovani. V ni lze (ne)vyhodnocovat casti kodu na zaklade podminky. Prislusna syntaxe se obecne podoba ternarnimu operatoru: podminka ? vyraz1 : vyraz2 %( PODMINKA %? VYRAZ-1 %) %( PODMINKA %? VYRAZ-1 %: VYRAZ-2 %) PODMINKA je budto vyraz, jehoz format je urcen prvnim klicovym slovem, nebo porovnani retezcovych ci numerickych literalu, nebo vyraz slozeny z takovych podminek s vyuzitim operatoru || a &&. Nicmene, zavorky zde zatim nejsou podporovany, takze je dulezite mit na zreteli, ze && ma pri vyhodnoceni prednost pred ||. Pokud prvni casti podminky je identifikator kernel_vr nebo kernel_v odkazujici se k verzi jadra s priponou ("2.6.13-1.322FC3smp"), nebo bez pripony ("2.6.13"), pak nasledovat musi jeden z operatoru porovnani: <, <=, ==, !=, >, a >=, a treti casti podminky je retezcovy literal vyjadrujici verzi jadra v RPM-stylu. Podminka se povazuje za splnenou, pokud verze beziciho jadra (volitelne predefinovana volbou -r ) se srovnava se zadanou hodnotou. Srovnani provadi glibc funkce strverscmp(). Pokud operatorem je jednoducha rovnost (==), nebo nerovnost (!=), a pravy operand obsahuje zastupne symboly (* nebo ? nebo [), , pak cely vyraz bude interpretovan jako "wildcard (mis)match" a bude vyhodnocen glibc funkci fnmatch(). Pokud prvni casti podminky je arch odkazujici se k architekture procesoru (pojmenovane podle ARCH/SUBARCH v terminologii jadra), pak druhou casti podminky je jeden z operatoru: == nebo !=, a treti casti podminky je pozadovany retezcovy literal, ktery muze obsahovat zastupne symboly ("wildcard (mis)match"). Podobne, pokud prvni slozkou podminky je identifikator jako CONFIG_* odkazujici se ke konfiguracni volbe jadra, pak druhou casti podminky je == nebo !=, a treti casti podminky je retezcovy literal odpovidajici volby (obvykle "y", nebo "m"). Neexistujici, nebo nenastavene konfiguracni volby v tomto kontextu odpovidaji prazdnemu retezci. Vyhodnoceni opet probiha jako "wildcard (mis)match" s vyuzitim fnmatch(). Pokud prvni casti je identifikator systemtap_v, pak se test odkazuje k verzi systemtapu, kterou lze volitelne pro stare skripty nastavit prostrednictvim volby --compatible. Operator porovnani je jako u kernel_v , a pravym operandem je retezec vyjadrujici verzi jadra. Viz tez sekce ZASTARAVANI nize. Pokud prvni casti podminky je systemtap_privilege, pak se test odkazuje k urovni opravneni se kterou je systemtap skript prekladan. V tomto pripade je podminkou jeden z operatoru == nebo !=, a treti casti podminky je jeden z retezcovych literalu "stapusr", "stapsys", nebo "stapdev". Pokud prvni casti podminky je identifikator guru_mode, pak test overuje, zda je systemtap skript prekladan v "guru" rezimu (-g). Operatorem pro tento pripad muze byt == nebo !=, a treti casti podminky je cislo. Budto 1, nebo 0. Pokud prvnim indetifikatorem je runtime, testuje se runtime rezim (--runtime). Viz sekce ALTERNATIVNI RUNTIME nize pro informaci o dostupnych runtime backendech. Porovnavaci operator v tomto pripade je == nebo !=, a treti casti podminky je retezcovy literal odpovidajici runtime. Porovnani je typu "wildcard (mis)match" s vyuzitim fnmatch() Posledni moznosti je situace, kdy PODMINKA srovnava proste ciselne, nebo retezcove literaly. VYRAZ-1 a VYRAZ-2 predstavuji vyskyt nuly nebo vice obecnych lexikalnich jednotek (ktere mohou obsahovat dalsi vlozene podminky preprocesoru), a jsou preprocesorem predany na vstup parseru v zavislosti na vyhodnoceni uvedene podminky. Napriklad nasledujici kod vyvola kompilacni chybu v pripade ze verze beziciho jadra na cilovem systemu je novejsi, nez 2.6.5: %( kernel_v <= "2.6.5" %? **ERROR** %) # "invalid token sequence" Naproti tomu nasledujici kod umozni elegantne se vyrovnat s ruznymi verzemi jadra: 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 prijima jednoducha makra a vyhodnocuje je v ramci samostatne procesni faze pred vyhodnocenim podminek. Makra se definuji nasledujici konstrukci: @define NAME %( BODY %) @define NAME(PARAM_1, PARAM_2, ...) %( BODY %) Makra (a take parametry uvnitr tela maker) jsou pristupna pridanim prefixu "@" pred jejich jmeno" @define foo %( x %) @define add(a,b) %( ((@a)+(@b)) %) @foo = @add(2,2) K expanzi maker v soucasnosti dochazi v samostatne preprocesni fazi pred zpracovanim podminek. Proto dojde k vyhodnoceni vsech maker v ramci kondicionalu bez ohledu na konkretni podminku. To muze vest k nezamyslenym chybam: // Nasledujici kod zpusobi chybu: %( CONFIG_UPROBE == "y" %? @define foo %( process.syscall %) %: @define foo %( **ERROR** %) %) // Nasledujici kod bude fungovat spravne: @define foo %( %( CONFIG_UPROBE == "y" %? process.syscall %: **ERROR** %) %) Prvni priklad je chybny, protoze vyvola duplicitni definici makra "foo". Za normalnich okolnosti je definice platna lokalne - pouze v souboru kde se vyskytuje. Makro definovane v tapset skriptu tedy neni verejne pouzitelne v ramci uzivatelskeho skriptu. Makra, ktera maji byt verejne dostupna, lze sdruzovat do knihoven s priponou ".stpm" nachazejici se v "tapset search path". Tyto soubory mohou obsahovat @define konstrukty, ktere budou dostupne nejen ve vsech tapsetech, ale i v uzivatelskych skriptech. Volitelne mohou byt definice maker v ramci ".stpm" souboru zabaleny v kondicionalech preprocesoru. KONSTANTY V ramci tapset skriptu, nebo guru skriptu je mozno pristupovat ke konstantnim symbolum, jako jsou napriklad makra jazyka C, prostrednictvim vestaveneho operatoru @const(). Pokud je potreba pridat prislusny #include dodatecneho hlavickoveho souboru, lze tak ucinit prostrednictvim vlozeneho kodu jazyka C. @const("STP_SKIP_BADVARS") PROMENNE Identifikatory pro promenne a funkce jsou alfanumericke sekvence, ktere mohou obsahovat _ a $. Nesmi zacinat cislici (stejne jako v C). Promenne jsou lokalni vzhledem ke svemu bloku (funkce nebo sondy) a jejich zivotnost je spojena s timto blokem. Skalarni promenne jsou implicitne retezcoveho, nebo celociselneho typu. Asociativni pole mohou take obsahovat retezcove nebo celociselne hodnoty a jako klic jim slouzi n-tice retezcu nebo celych cisel. Zde je nekolik prikladu: var1 = 5 var2 = "bar" array1 [pid()] = "name" # jednoduchy ciselny klic pole array2 ["foo",4,i++] += 5 # n-tice jako klic pole if (["hello",5,4] in array2) println ("yes") # test na clenstvi Prekladac provadi typove odvozeni (type inference) na vsech identifikatorech vcetne indexu poli a parametru funkci. Nekonzistentni zachazeni s typy zpusobi chybu prekladu. Promenne lze definovat jako globalni, takze mohou byt sdileny mezi sondami a funkcemi, a ziji stejne dlouho jako cele systemtap sezeni. Pro globalni promenne existuje jediny jmenny prostor. Pristup ke globalnim promennym je chranen zamky, viz BEZPECNOST A OCHRANA SOUKROMI. Globalni promennou lze deklarovat kdekoli ve vnejsi urovni zdrojoveho kodu, tedy mimo bloky sond a funkci. Globalni promenne, kterym byla prirazena hodnota, ale nikdy nebyla ctena, budou automaticky zobrazeny na konci systemtap sezeni. Prekladac se pokusi odvodit datovy typ z hodnot a pripadne, pokud jde o pole, i z klicu. Volitelne lze globalni promennou inicializovat retezcovym, nebo ciselnym literalem. Zde jsou priklady deklarace globalnich promennych: global var1, var2, var3=4 Globalni promenne lze take pouzit jako parametry systemtap modulu. Toho lze dosahnout budto pouzitim prepinace stap -G, nebo modul pripravit predem pomoci stap -p4 a parametry mu predat pozdeji pri jeho zavadeni na prikazove radce programu staprun. Viz staprun(8). Rozsah platnosti globalni promenne lze omezit na tapset soubor, nebo na uzivatelsky skript prostrednictvim klicoveho slova "private". V tom pripade je klicove slovo "global" volitelne. Nasledujici deklarace oznacuje var1 a var2 jako privatni globalni promenne: private global var1=2 private var2 Pole maji omezenou velikost parametrem MAXMAPENTRIES. Viz BEZPECNOST A OCHRANA SOUKROMI Volitelne lze polim (ktera jsou vzdy globalni) nastavit maximalni velikost v hranatych zavorkach, cimz se predefinuje MAXMAPENTRIES pro dane pole. Poznamenejme, ze velikost se vztahuje jen k poctu prvku, nikoliv k celkove velikosti pole v pameti. Priklad: global tiny_array[10], normal_array, big_array[50000] Polim lze nastavit priznak "%". To zpusobi, ze pokud do pole pridame vice prvku, nez pro kolik je dimenzovano, zacnou stare prvky mizet (LIFO). To plati jak pro asociativni, tak pro statisticka pole, viz nize. Priklad: global wrapped_array1%[10], wrapped_array2% Mnohe sondy poskytuji kontextove promenne, coz jsou hodnoty ziskane za behu z jadra, nebo zkoumane uzivatelske aplikace. Jejich identifikatory zacinaji znakem $. Sekce KONTEXTOVE PROMENNE v manualove strance stapprobes(3stap) obsahuje jejich seznamy pro jednotlive typy sond. Tyto kontextove promenne se stanou normalnimi retezcovymi nebo numerickymi promennymi pouzitelnymi ve skriptu, jakmile provedeme prislusne prirazeni (napr. foo=$foo). Podivejte se nize na sekci PRETYPOVANI, kde je popsano jak takovou promennou pretypovat zpet na ukazatel je-li to treba. PRIKAZY Prikazy umoznuji proceduralni rizeni behu skriptu. Mohou se vyskytovat uvnitr funkci a obsluznych rutin sond. Celkovy pocet prikazu, ktere je v reakci na nejakou udalost mozno spustit, je omezen na hodnotu definovanou makry MAXACTION_* ve vygenerovanem C-kodu a pohybuje se kolem 1000. EXP Vyhodnotit retezcovy, nebo ciselny vyraz a zahodit hodnotu. { STMT1 STMT2 ... } Vykonat kazdy prikaz v sekvenci v tomto bloku. Poznamenejme, ze oddelovace a znaky pro ukonceni prikazu nejsou mezi jednotlivymi prikazy nezbytne. ; Prazdny prikaz, nedelat nic. Je uzitecny jako volitelny oddelovac mezi prikazy ke zlepseni detekce syntaktickych chyb a k upresneni nekterych syntaktickych nejednoznacnosti gramatiky. if (EXP) STMT1 [ else STMT2 ] Porovnat ciselny vyraz EXP s nulou. Pak vykonat prikaz STMT1 (EXP neni nula), nebo prikaz STMT2 (EXP je nula). while (EXP) STMT Dokud ma ciselny vyraz EXP nenulovou hodnotu, spoustej STMT. for (EXP1; EXP2; EXP3) STMT Vykona EXP1 jako inicializaci. Dokud EXP2 ma nenulovou hodnotu, bude vykonavat STMT a iteracni vyraz EXP3. foreach (VAR in ARRAY [ limit EXP ]) STMT Cykleni pres kazdy prvek globalniho pole ARRAY s prirazenim aktualniho prvku promenne VAR. Pole neni v ramci STMT dovoleno menit. Pridanim operatoru + nebo - za identifikator VAR nebo ARRAY, se zajisti iterovani pres setridene pole jednim, nebo druhym smerem. Pokud pole obsahuje statisticke agregatory, pak pridanim pozadovaneho operatoru @operator mezi ARRAY a symbol + nebo - urcime tridici agregacni funkci. Viz priklad nize v sekci STATISTIKA. Vychozi je @count. S vyuzitim volitelneho klicoveho slova limit lze maximalni pocet iteraci omezit na EXP. Poznamenejme, ze EXP se vyhodnocuje na zacatku smycky. foreach ([VAR1, VAR2, ...] in ARRAY [ limit EXP ]) STMT Podobne jako vyse, ovsem v tomto pripade je klicem pole n-tice hodnot. Tridici priponu lze pouzit maximalne na jednom z prvku n-tice. foreach ([VAR1, VAR2, ...] in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT Podobne jako vyse, ovsem iterovat se bude pouze pres prvky, kde klic vyhovuje dane hodnote. Pro urceni indexu lze pouzit znak *, se kterym bude zachazeno jako se zastupnym symbolem. foreach (VAR0 = VAR in ARRAY [ limit EXP ]) STMT Tato varianta foreach uchova aktualni hodnotu pri kazde iteraci ve VAR0, takze bude odpovidat ARRAY[VAR]. Tohle analogicky funguje s n-tici klicu. Tridici pripony na VAR0 maji stejny vyznam jako na ARRAY. foreach (VAR0 = VAR in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT Podobne jako vyse, ovsem iteruje se pouze pres prvky, kde klice vyhovuji danym hodnotam. Pro urceni indexu lze pouzit znak * se kterym bude zachazeno jako se zastupnym symbolem. break, continue Ukoncit, nebo znovu iterovat vnitrni smycku. Aplikovatelne na while nebo for nebo foreach. return EXP Vratit hodnotu EXP z funkce. Prikaz return neni ve funkci povinny. Pokud se vynecha, bude funkce mit specialni navratovy datovy typ "unknown". next Ihned ukonci obsluznou rutinu sondy. To je obzvlast uzitecne u prezdivek, ktere pouzivaji filtrovaci podminky. try { STMT1 } catch { STMT2 } Vykonej prikazy v prvnim bloku STMT1. Pokud pri tom dojde k chybe behu, ukonci STMT1 a zacni provadet STMT2. Pripadne chyby v STMT2 se budou propagovat do vnejsiho catch bloku, pokud tam takovy je. try { STMT1 } catch(VAR) { STMT2 } Podobne jako v predchozim pripade, ale navic se chybova hlaska, jakozto retezec, uchova v promenne VAR. delete ARRAY[INDEX1, INDEX2, ...] Odstrani z pole prvky urcene n-tici klicu. Pokud n-tice klicu obsahuje symbol * na miste indexu, bude s * zachazeno jako jako se zastupnym symbolem. Neni chybou pokusit se smazat prvek, ktery neexistuje. delete ARRAY Smazat vsechny prvky pole ARRAY. delete SCALAR Maze hodnotu SCALAR. Celociselne promenne budou vynulovany, retezcove promenne nastaveny na "", a statisticke promenne budou nastaveny do vychoziho prazdneho stavu. VYRAZY SystemTap podporuje mnozstvi operatoru, ktere maji syntaxi a semantiku velmi podobnou jejich C a awk protejskum. Aritmeticke operace se provadeji v souladu s pravidly jazyka C pro cela cisla se znamenkem. Deleni nulou nebo preteceni rozsahu se detekuje a zpusobi chybu. binarni numericke operatory * / % + - >> << & ^ | && || binarni operatory nad retezci . (spojeni retezcu) ciselne prirazovaci operatory = *= /= %= += -= >>= <<= &= ^= |= retezcove prirazovaci operatory = .= unarni ciselne operatory + - ! ~ ++ -- operatory pro srovnavani cisel, retezcu a praci s regularnimi vyrazy < > <= >= == != =~ !~ ternarni operator podminka ? exp1 : exp2 seskupovaci operator ( exp ) volani funkce fn ([ arg1, arg2, ... ]) operator testujici clenstvi v poli exp in array [exp1, exp2, ...] in array [*, *, ... ]in array REGULARNI VYRAZY Skriptovaci jazyk systemtapu podporuje praci s regularnimi vyrazy. Zakladni operace testujici (ne)shodu retezce s regularnim vyrazem: exp =~ regex exp !~ regex Prvni operand musi byt vyraz vyhodnotitelny na retezec; druhy operand musi byt retezcovy literal obsahujici platny regularni vyraz. Syntaxe regularnich vyrazu podporuje vetsinu rozsirenych regularnich vyrazu POSIX standardu. Vyjimkou je znovupouziti casti regularniho vyrazu ("\1"). Po uspesnem nalezeni je text vyhovujici regularnimu vyrazu dostupny prostrednictvim tapsetovych funkci matched() a ngroups() nasledovne: if ("an example string" =~ "str(ing)") { matched(0) // -> vraci "string", t.j. cely odpovidajici retezec matched(1) // -> vraci "ing", t.j. prvni odpovidajici podretezec ngroups() // -> vraci 2, t.j. pocet odpovidajicich skupin retezcu } SONDY Hlavnim syntaktickym konstruktem skriptovaciho jazyka jsou sondy (probes). Sondy spojuji abstraktni udalosti s bloky prikazu a vytvareji tak obsluzne rutiny udalosti. Obecna syntaxe je nasledujici: probe PROBEPOINT [, PROBEPOINT] { [STMT ...] } probe PROBEPOINT [, PROBEPOINT] if (CONDITION) { [STMT ...] } Udalosti jsou urceny syntaxi nazyvanou sondazni body (probe points). Existuje mnozstvi variant sondaznich bodu. Nektere jsou definovany prekladacem a mnohe dalsi jsou definovany v tapset skriptech jako prezdivky. Sondazni body mohou vyuzivat zastupne znaky, byt seskupovany, muze byt urcovano jejich poradi, ci mohou byt deklarovany jako volitelne. Vice podrobnosti o syntaxi a semantice sondaznich bodu viz stapprobes(3stap). Obsluzna rutina sondy se interpretuje relativne ke kontextu dane udalosti. Pro udalosti souvisejici s kernel kodem muze tento kontext obsahovat promenne definovane ve zdrojovem kodu jadra. Takove "kontextove" promenne jsou pak pristupne ve skriptu z prefixem "$". Jsou pristupne pouze pokud byly kompilatorem jadra zachovany navzdory optimalizacim. To je stejne omezeni s jakym se potyka debugger kdyz pracuje s optimalizovanym kodem. Navic musi tyto objekty byt v momente vykonavani obsluzne rutiny sondy pritomny primo v nastrankovane (in- paged) pameti, protoze systemtap nesmi zapricinit zadne dodatecne strankovani. Nektere sondy maji velmi malo kontextovych promennych. Viz stapprobes(3stap). Proby mohou byt doplneny podminkou pro uzamceni, sestavajici z jednoducheho booleovskeho vyrazu. Sonda je "odemcena" (tedy neaktivni) vyhodnocuje-li se zamykaci podminka na false. V tomto stavu nektere sondy snizuji nebo zcela eliminuji svoji rezii, tedy nekonzumuji systemove prostredky. Jakmile se zamykaci podminka vyhodnoti na true bude sonda brzy znovu uzamcena a jeji obsluzna rutina zacne brzy byt opet volana kdyz nastane prislusna udalost. Prestoze je zamykani rychle, trva nenulovy cas, a nektere udalosti nemuseji byt zachyceny. V pripadech kdy toto muze predstavovat problem, je lepsi zamykani sond nepouzivat. Nove sondazni body lze definovat pomoci prezdivek (probe aliases). Definice prezdivky vypada podobne jako definice sondy samotne, ale namisto aktivovani sondy v danem miste pouze definuji nove jmeno - prezdivku pro jiz existujici sondazni bod. Existuji dva typy prezdivek: "prologue" a "epilogue", ktere jsou definovany pomoci "=" nebo resp. "+=". Prezdivka typu "prologue" vznikne tak, ze se blok prikazu, ktery nasleduje definici teto prezdivky, prida pred sondu ke ktere se vaze jako jeji prolog. Naproti tomu prezdika typu "epilogue" vznikne tak, ze blok prikazu, ktery nasleduje definici teto prezdivky, se prida za sondu ke ktere se vaze jako jeji epilog. Napriklad: probe syscall.read = kernel.function("sys_read") { fildes = $fd if (execname() == "init") next # preskocit zbytek sondy } definuje novy sondazni bod. syscall.read, ktery se rozsiruje na kernel.function("sys_read"), s danym prikazem jako prologem, coz je vyhodne k preddefinovani nekterych promennych pro danou prezdivku a/nebo pro preskoceni dane sondy v zavislosti na podmince. Naproti tomu probe syscall.read += kernel.function("sys_read") { if (tracethis) println ($fd) } definuje novy sondazni bod s danym prikazem jako epilogem, coz muze byt uzitecne k provedeni cinnosti v zavislosti na hodnotach promennych nastavenych uzivatelem prezdivky. Poznamenejme, ze v kazdem pripade jsou prikazy v obsluzne rutine prezdivky vykonavany za behu, takze v danou chvili zejmena nedochazi k vyhodnocovani/substituci maker. Prezdivku lze pouzit stejne jako vestavenou sondu prekladace. probe syscall.read { printf("reading fd=%d\n", fildes) if (fildes > 10) tracethis = 1 } FUNKCE Systemtap skripty mohou definovat funkce. Ty mohou prijimat libovolny pocet skalarnich (celociselnych nebo retezcovych) parametru, a vraci jednu skalarni funkcni hodnotu. Priklad funkce: function thisfn (arg1, arg2) { return arg1 + arg2 } Povsimneme si absence explicitnich deklaraci typu. Typy, jsou odvozeny (inferred) prekladacem. Nicmene, pokud je to potreba, muze definice funkce zahrnovat explicitni deklarace navratoveho typu a/nebo typu argumentu. To je uzitecne zejmena pro vlozene C funkce. V nasledujicim priklade je automaticke odvozeni typu nutne jen pro arg2 (retezec): function thatfn:string (arg1:long, arg2) { return sprint(arg1) . arg2 } Funkce se mohou volat navzajem az do urciteho limitu zanoreni. Tento limit je definovan makrem MAXNESTING ve vygenerovanem zdrojovem kodu modulu a pohybuje se okolo 10. Funkce lze oznacit za privatni pouzitim klicoveho slova "private". Tim se omezi jejich platnost soubor (tapset nebo uzivatelsky skript) ve kterem jsou definovany. Priklad: private function three:long () { return 3 } TISK Existuje nekolik funkci, se kterymi prekladac zachazi neobvykle. Poznamenejme, ze data jsou generovana v jadernem modulu a pred tiskem musi byt prenesena do uzivatelskeho prostoru. Tyto funkce formatuji hodnoty pro pohodlny tisk do vystupniho proudu systemtapu. Varianty funkce sprint* vraceji formatovany retezec namisto aby ho primo vypisovaly. print, sprint Vypis jedne nebo vice hodnot libovolneho typu spojenych dohromady. println, sprintln vypisuji hodnoty stejne jako print a sprint, ale navic pripojuji znak noveho radku. printd, sprintd Prijimaji retezcovy oddelovac a dve nebo vice hodnot libovolneho typu, a vytisknou je prolozene timto oddelovacem. Oddelovacem musi byt retezcovy literal - konstanta. printdln, sprintdln Vytisknou hodnoty prolozene oddelovacem podobne jako printd a sprintd, ale zaroven pripoji znak konce radku. printf, sprintf prijimaji formatovaci retezec s mnozinou hodnot odpovidajicich typu a vsechny je vytisknou. Formatovacim retezcem musi byt retezcovy literal - konstanta. Formatovaci retezec prikazu printf je podobny jako v jazyce C s tim, ze zde probiha typova kontrola. %b Vypisuje binarni blob dane hodnoty namisto ASCII textu. Specifikator "width" urcuje pocet bajtu k vypsani. Validni specifikace jsou: %b %1b %2b %4b %8b. Vychozi je (%b), t.j. 8 bajtu. %c Znak. %d,%i Cele cislo se znamenkem. %m Bezpecne cte pamet jadra na dane adrese, vraci jeji obsah. Volitelny specifikator presnosti (ne sirky pole) urcuje pocet bajtu k precteni. Vychozi hodnota je 1 bajt. %10.4m vytiskne 4 bajty pameti v ramci 10 znaku sirokeho pole. %M Stejne jako %m, ale vystup je hexadecimalni. Minimalni sirka vystupu je urcitelna volitelnym specifikatorem r - vychozi hodnota je 1 bajt (2 hexadecimalni znaky). %10.4M vytiskne 4 bajty pameti jako 8 hexadecimalnich znaku v ramci 10 znaku sirokeho pole. %o Oktalove cislo bez znamenka. %p Ukazatel bez znamenka. %s Retezec. %u Desitkove cislo bez znamenka. %x Hexadecimalni hodnota bez znamenka, mala pismena. %X Hexadecimalni hodnota bez znamenka, velka pismena. %% Vypise znak %. Znak # zapina alternativni formatovani: Oktalovym cislum prida prefix "0", hexadecimalnim "0x", nebo "0X", a netisknutelnym znakum v retezci prida prefix "escape" sekvence. Priklady: a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = -1, id[a] = 1234, id[b] = 4567 print("hello") Vypise: hello println(b) Vypise: bob\n println(a . " is " . sprint(16)) Vypise: alice is 16 foreach (name in id) printdln("|", strlen(name), name, id[name]) Vypise: 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) Vypise: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; -1 or 18446744073709551615\n printf("2 bytes of kernel buffer at address %p: %2m", p, p) Vypise: 2 byte of kernel buffer at address 0x1234abcd: printf("%4b", p) Vypise (these values as binary data): 0x1234abcd printf("%#o %#x %#X\n", 1, 2, 3) Vypise: 01 0x2 0X3 printf("%#c %#c %#c\n", 0, 9, 42) Vypise: \000 \t * STATISTIKA Casto je vyhodne sbirat statisticka data zpusobem, ktery netrpi problemy s exkluzivnim zamykanim globalnich promennych, kde se data udrzuji. Systemtap nabizi reseni ve forme specialniho operatoru pro uchovavani statistickych dat a sady agregacnich pseudofunkci. Agregacni operator je <<<, a pripomina prirazeni, nebo operaci pro zapis do vystupniho proudu znamou z C++. Levy operand je skalarni promenna (nebo /skalarni/ prvek pole - viz priklad nize), ktera musi byt deklarovana jako globalni. Pravym operandem je ciselny vyraz. Vyznam je intuitivni: Pridej dane cislo na hromadu nad kterou bude pozdeji mozno provadet statisticke operace. Seznam funkci pro extrakci statistickych udaju je uveden nize. Priklad: foo <<< 1 stats[pid()] <<< memsize Funkce pro extrakci statistiky jsou neobvykle. Pro kazdy vyskyt extrakcni funkce pracujici s danym identifikatorem zajisti prekladac vypocet pozadovaneho statistickeho udaje. Statisticky subsystem tedy funguje "na pozadani" a vypocet probiha v realnem case na vsech dostupnych CPU. Zde je seznam extrakcnich funkci. Prvnim argumentem kazde z nich je ta stejna l-hodnota, ktera byla pouzita pro akumulaci statistiky operatorem <<<. Extrakcni funkce @count(v), @sum(v), @min(v), @max(v), @avg(v), @variance(v[, b]) pocitaji pocet, sumu, minimum, maximum, aritmeticky prumer, a stredni kvadratickou odchylku pres vsechny nashromazdene hodnoty. Funkcnimi hodnotami jsou cela cisla. Pole obsahujici agregacni data lze tridit a/nebo pres ne iterovat. Viz cyklus foreach vyse. Stredni kvadraticka odchylka se vycisluje s pouzitim Welfordova algoritmu. Vypocty jsou provadeny v celociselne aritmetice, proto mohou trpet nizkou presnosti. Pro zlepseni presnosti lze vyuzit volitelny parametr b, tzv. bitovy posun, s hodnotami od 0 (vychozi hodnota) do 62. Pro danou statistickou velicinu, resp. ji odpovidajici globalni promennou ve skriptu, lze pouzit pouze jednu jedinou hodnotu bitoveho posunu. Vyssi hodnoty bitoveho posunu zvysuji presnost, ale zaroven zvysuji riziko preteceni. $ stap -e \ > 'global x probe oneshot { for(i=1;i<=5;i++) x<< 'global x probe oneshot { for(i=1;i<=5;i++) x<<member Takto bude p interpretovan jako ukazatel do struktury/unionu type_name a dereferencovat member . Lze pripojit dalsi ->subfield a dereferencovat tak dalsi urovne. Poznamenejme, ze pro prime dereferencovani ukazatele se doporucuje pouzit funkci {kernel,user}_{char,int,...}($p). Vice v sekci stapfuncs(5). POZNAMKA: stejny operator -> se pouziva jak pro primy odkaz na clena, tak pro dereferenci ukazatele. Systemtap automaticky interpretuje tuto dvojakost. Volitelna slozka module informuje prekladac, kde ma hledat informaci o danem typu. module lze uvest vicekrat jako seznam s oddelovacem :. Pokud module neni explicitne urcen, budou pro jeho urceni vyuzity ladici informace, nebo bude nastaven na "kernel" pro funkce a vsechny ostatni typy sond. Prekladac muze vytvorit svuj vlastni modul s informacemi o typech odvozenim z hlavickovych souboru uzavrenych ve spicatych zavorkach v pripade, ze ladici informace nejsou k dispozici. Hlavickovym souborum jadra je treba pridat retezec "kernel" jako predponu. Ostatni hlavickove soubory budou zpracovany s vychozimi volbami kompilatoru. Lze specifikovat vice hlavickovych souboru za sebou pro vyreseni zavislosti. @cast(tv, "timeval", "")->tv_sec @cast(task, "task_struct", "kernel")->tgid @cast(task, "task_struct", "kernel")->fs->umask Hodnoty ziskane operatorem @cast lze prehledne vytisknout (pretty-print) pripojenim operatoru $ a $$ jak je popsano v sekci KONTEXTOVE PROMENNE man stranky stapprobes(3stap). V guru rezimu (-g) umoznuje prekladac take priradit novou hodnotu dereferencovanym ukazatelum. Pretypovani je take uzitecne v pripade void* clenu jejichz typ lze urcit az za behu. Priklad: 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 rezimu prijima prekladac vlozeny C kod v uzivatelskych skriptech. Takovy kod je uzavren mezi znackami %{ a %} a je doslovne, bez analyzy, vlozen do vnejsi urovne vygenerovaneho kodu systemtap modulu. Protoze je vlozen do vnejsi urovne, je mozne takto definovat #include direktivy a ruzne pomocne definice pouzitelne ve zbytku kodu. Dalsim mistem, kde je vlozene C povoleno, je telo funkce. V tomto pripade bude telo systemtap funkce doslovne tvoreno vlozenym C kodem uzavrenym mezi znacky %{ a %}. Takto vlozeny C kod muze vykonavat libovolnou rozumnou a bezpecnou cinnost. Existuje mnozstvi nedokumentovanych a komplexnich omezeni ohledne atomicity, soubeznosti, spotreby zdroju a casovych omezeni, takze jde o pokrocilou techniku. Pametova umisteni vyhrazena pro vstupni a vystupni hodnoty jsou zpristupnena pomoci maker STAP_ARG_* a STAP_RETVALUE. Chyby lze signalizovat pomoci STAP_ERROR, vystup pomoci STAP_PRINTF a navratovou hodnotu lze predat prostrednictvim STAP_RETURN. Zde je nekolik prikladu: 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 mel byt be three-two-"); %} function no_ops () %{ STAP_RETURN(); /* funkce bez navratove hodnoty */ %} Typy funkcnich hodnot a typ navratove hodnoty odvodi prekladac ze zpusobu volani dane funkce. Pred vytvarenim vlastnich vlozenych C funkci je vhodne prostudovat zdrojovy kod, ktery prekladac generuje pro bezne funkce skriptovaciho jazyka a tim se inspirovat. Posledni misto, kde je vlozene C povoleno, je r-hodnota ve vyrazu. V tomto pripade se C-kod uzavre mezi znacky %{ a %} a interpretuje se jako bezna hodnota vyrazu. Predpoklada se pak, ze jde o 64 bitove cislo se znamenkem, ovsem pokud se pouzije znacka /* string */, bude hodnota vyrazu interpretovana jako retezec. Priklad: function add_one (val) { return val + %{ 1 %} } function add_string_two (val) { return val . %{ /* string */ "two" %} } K nastaveni bezpecnosti a optimalizace lze pouzit nasledujici znacky: /* pure */ znamena, ze C kod nema zadne vedlejsi efekty a muze byt v ramci optimalizace zcela zahozen pokud nema vazby na zbytek kodu. /* stable */ znamena, ze C kod ma vzdy stejnou hodnotu (pri vyvolani v ramci libovolne obsluzne rutiny sondy), takze opakovana volani mohou byt nahrazena zapamatovanou hodnotou. Takove funkce nesmi prijimat parametry a musi byt /*pure*/. /* unprivileged */ znamena, ze C kod je tak bezpecny, ze ho mohou pouzivat i neprivilegovani uzivatele. /* myproc-unprivileged */ znamena, ze C kod je tak bezpecny, ze ho mohou pouzivat i neprivilegovani uzivatele, ovsem jen pri analyze svych vlastnich uzivatelskych procesu. /* guru */ znamena, ze C kod je tak nebezpecny, ze vyzaduje pouziti guru rezimu -g. /* unmangled */ ve vlozene C funkci zpristupni zastaralou (pre-1.8) syntaxi pro pristup k funkcnim parametrum. V tomto pripade lze uvnitr funkce krome STAP_ARG_foo a STAP_RETVALUE pouzit take THIS->foo a THIS->__retvalue . /* unmodified-fnargs */ ve vlozene C funkci znamena, ze parametry nejsou uvnitr tela funkce meneny. /* string */ ve vlozene C funkci znamena, ze vyraz ma typ const char * a melo by s nim byt nakladano jako s retezcovou hodnotou namisto numericke (coz je vychozi chovani). BUILT-INS Skripty instalovane v umisteni definovanem ve stappaths(7) poskytuji mnozstvi vestavenych sondaznich bodu. Ty jsou popsany v man strance stapprobes(3stap). ZPRACOVANI SKRIPTU Systemtap zpracovava skript v peti procesnich fazich: "parse", "elaborate", "translate", "compile" a "run". Prekladac zahaji fazi 1 lexikalni analyzou uzivatelskeho skriptu spolu se vsemi tapset skripty (coz jsou soubory s priponou *.stp) nalezenymi v tapset adresari. Adresare vyjmenovane prostrednictvim -I jsou nasledne zpracovany take, a to v guru rezimu. Adresarova struktura se prohledava do hloubky. Nektere podadresare jsou specificke pro verzi jadra (volba -R ), a podle ni jsou (nebo nejsou) prohledavany, takze skripty specifictejsi pro danou verzi jadra mohou predefinovat sve mene specificke protejsky. Napriklad pro verzi jadra 2.6.12-23.FC3 by byly prohledavany nasledujici adresare: 2.6.12-23.FC3/*.stp, 2.6.12/*.stp, 2.6/*.stp, a nakonec *.stp v tomto poradi. Pokud preklad skonci na konci faze 1 (-p1), pak prekladac na standardni vystup vypise derivacni strom (parse tree). Ve fazi 2 prekladac analyzuje vstupni skript, aby vyhodnotil symboly a datove typy. Odkazy na promenne, funkce a prezdivky, ktere se nepodari vyhodnotit lokalne, se vyhodnoti proti tapset skriptum. Pokud je urcity symbol nalezen v tapset skriptu, pak dany tapset bude cely pridan do fronty pro zpracovani prekladacem. Tento iterativni proces skonci jakmile jsou vyhodnoceny vsechny symboly s vyuzitim dane podmnoziny tapset skriptu. Dale se overi validnost sondaznich bodu. Sondy, ktere se odkazuji k umistenim ve zdrojovem kodu ("synchronni sondazni body") vyzaduji, aby byly nainstalovany prislusne ladici informace. V obsluznych rutinach sond se naleznou cilove promenne (ty, ktere zacinaji znakem "$") a dekoduji se jejich "run-time" lokace. Dale se vsechny sondy a funkce optimalizuji. Cilem je odstranit zbytecne promenne, vyrazy a funkce, ktere nemaji vedlejsi ucinky. U vlozenych C funkci se predpoklada, ze maji vedlejsi ucinky pokud ovsem neobsahuji kouzelnou znacku /* pure */. Vzhledem k tomu, ze optimalizace mohou zpusobit latentni chyby jako je napriklad typova nekompatibilita, nebo neplatne kontextove promenne, muze byt v nekterych pripadech uzitecne optimalizace vypnout prepinacem -u. Nakonec se z kontextu odvodi datove typy promennych, funkci, parametru, poli a indexu. Ukonceni prekladu po fazi 2 (-p2) zpusobi vypsani seznamu vsech sond, funkci a promennych spolu s jejich odvozenymi typy. Nekonzistentni nebo neodvoditelne typy zpusobi chybu prekladu. Ve fazi 3 prekladac zapise vygenerovany C kod a vytvori Makefile ktery slouzi k jeho prelozeni do podoby jaderneho modulu. Tyto soubory budou umisteny v docasnem adresari. Zastaveni prekladace v teto fazi (-p3) zpusobi vypsani C souboru na standardni vystup. Ve fazi 4 prekladac vyvola jaderny "build system", aby sestavil systemtap modul. Pri tom se v danem docasnem adresari vola prikaz make. K uspesnemu provedeni tohoto kroku je treba, aby byl nainstalovan "build system" jadra, tj. hlavickove soubory, config a Makefile soubory a to v obvyklem umisteni /lib/modules/VERSION/build. Zastaveni prekladace v teto fazi (-p4) muze byt uzitecne, pokud chceme modul archivovat. Je to take posledni sance zastavit systemtap pred zavedenim a spustenim modulu. Ve fazi 5 prekladac zavola pomocny program staprun a preda mu vznikly systemtap modul. Program staprun zavede modul do jadra, spusti jej a zajistuje komunikaci s nim dokud cinnost modulu neskonci. Jakakoliv chyba behu, ktera se vyskytne v obsluznych rutinach sond, jako napr. vycerpani dostupne pameti, deleni nulou, prilis hluboke zanoreni, nebo prekroceni "run-time" limitu, zpusobi mekkou chybu (soft error). Pokud pocet mekkych chyb prekroci MAXERRORS, zastavi se vsechny sondy (krome tech, ktere obsluhuji chyby), a zastavi se sezeni. Nakonec staprun odstrani modul z jadra a provede uklid. NEOBVYKLE UKONCENI Je dobre neukoncovat stap proces nasilim, napriklad prostrednictvim signalu SIGKILL, protoze proces stapio (potomek procesu stap) a systemtap modul by se nemusely korektne ukoncit. Pokud se to precejen stane, poslete vsem zbyvajicim stapio procesum SIGTERM nebo SIGINT a pouzijte rmmod pro odstraneni systemtap modulu z jadra. PRIKLADY Viz stapex(3stap) , kde se nachazi nekolik kratkych prikladu, nebo viz adresar "examples" v RPM baliccich "systemtap-client", ci "systemtap- testsuite", kde se nachazi rozsahla sbirka prikladu. Viz stappaths(7stap) pro podrobny popis konkretnich umisteni. Priklady jsou take zverejneny na webove strance projektu systemtap. CACHE Prekladac systemtapu uklada do cache vystup faze 3 (tj. vygenerovany C kod) a vystup faze 4 (tj. zkompilovany jaderny modul) pokud tyto faze skonci bez chyb. Obsah cache se pouzije pokud se znovu preklada stejny skript a za predpokladu, ze plati stejne podminky (verze jadra, verze systemtapu atp.). Cache se nachazi v adresari $SYSTEMTAP_DIR/cache . Velikost cache lze omezit umistenim souboru cache_mb_limit do cache adresare, pricemz tento soubor obsahuje ASCII ciselnou hodnotu limitu, ktera vyjadruje velikost cache v MiB. Pokud tento soubor neexistuje, vytvori se novy s vychozi hodnotou 256. Jde o mekky limit v tom smyslu, ze cache bude promazana az po urcite dobe. Docasne tedy muze velikost cache prekrocit stanoveny limit. Zminenou periodu je mozno nastavit prostrednictvim souboru cache_clean_interval_s umisteneho opet v cache adresari. Predpoklada se, ze tento soubor obsahuje ASCII cele cislo vyjadrujici casovy interval pro promazavani cache v sekundach. Pokud tento soubor neexistuje, vytvori se novy s vychozi hodnotou 300. BEZPECNOST A OCHRANA SOUKROMI Systemtap muze byt pouzit jako mocny administrativni nastroj. Muze zpristupnit privatni uzivatelske informace v ramci internich jadernych struktur. To se netyka dyninst runtime, viz ALTERNATIVNI RUNTIME . Prekladac zajistuje dodrzovani mnoha ruznych bezpecnostnich omezeni behem kompilace a behu modulu. Snazi se zajistit, aby zadna sonda nebezela prilis dlouho, aby nealokovala prilis mnoho pameti, neprovadela nebezpecne operace, nebo nezadoucim zpusobem neovlivnovala system. Pri praci s globalnimi promennymi se vyuzivaji zamky pro cteni a zapis, aby nedochazelo k chybam pri soubehu. Pravidelne dochazi k testu na deadlocky. Pro zjisteni neprimereneho pouziti zamku lze pouzit prepinac -t. Experimentovani se skripty je tedy v zasade bezpecne. Guru"rezim -g umoznuje administratorum obejit vetsinu bezpecnostnich opatreni a umoznit tak invazivni zasahy a zmeny stavu systemu, pouzit vlozene C a obecne zvysit riziko prusvihu. Za normalnich okolnosti je pro vsechny moduly aktivni ochrana proti pretizeni. Tu lze vypnout prepinacem --suppress-time-limits. Chyby zachycene pri behu za normalnich okolnosti vedou k cistemu ukonceni skriptu s chybovou hlaskou. Prepinac --suppress-handler-errors umoznuje zcela ignorovat mekke chyby, takze ani po nastradani jejich vetsiho poctu nedojde k ukonceni skriptu. OPRAVNENI Aby bylo mozne spustit systemtap modul v ramci vychozi kernel runtime, musi uzivatel splnit jednu z nasledujicich podminek: o byt root. o byt clenem skupin stapdev a stapusr o byt clenem skupin stapsys a stapusr ; nebo o byt clenem skupiny stapusr . Uzivatel root, nebo uzivatel, ktery je clenem skupin stapdev a stapusr , muze prelozit a spustit libovolny systemtap skript. Uzivatel, ktery je clenem skupin stapsys a stapusr, muze pouzit predem pripravene systemtap moduly za nasledujicich podminek: o Modul byl podepsan kompilacnim serverem "trusted signer", tj. systemtap kompilacnim serverem, ktery podepsal modul klientovi, ktery pouzil volbu --privilege. Viz stap-server(8). o Modul byl sestaven s pouzitim jedne z voleb --privilege=stapsys nebo --privilege=stapusr. Clenove pouze skupiny stapusr mohou pouzivat jen predem pripravene moduly za nasledujicich podminek: o Modul je umisten v adresari /lib/modules/VERSION/systemtap. Tento adresar musi byt vlastnen uzivatelem root a nesmi byt otevreny pro zapis vsem. nebo o Modul byl podepsan kompilacnim serverem "trusted signer", tj. systemtap kompilacnim serverem, ktery podepsal modul klientovi, ktery pouzil volbu --privilege. Podrobnejsi informace viz stap-server(8). o Modul byl prelozen s volbou --privilege=stapusr. Jaderne moduly vygenerovane programem stap se zavadeji do jadra a spousteji pomoci programu staprun. Staprun je soucasti systemtap balicku urceneho k zavadeni a odstranovani modulu (za danych podminek). Slouzi take k prenosu dat mezi systemtap modulem a uzivatelelm. Protoze staprun neprovadi zadne bezpecnostni kontroly modulu se kterym pracuje, bylo by od administratora systemu nemoudre pridat neduveryhodneho uzivatele do skupiny stapdev nebo stapusr . SECUREBOOT Pokud ma system v ramci UEFI firmware zapnuty SecureBoot, vsechny jaderne moduly museji byt kryptograficky podepsany. (Nektera jadra dovoluji vypnout SecureBoot za behu kombinaci klaves SysRq-X. Pote nemusi byt moduly podepsane.) Kompilacni server systemtapu muze podepisovat moduly klicem MOK (Machine Owner Key) ktery sdili s danym systemem. Pro vice informaci viz nasledujici wiki: https://sourceware.org/systemtap/wiki/SecureBoot LIMITY NA ZDROJE Mnoho omezeni pro vyuzivani prostredku systemu se nachazi ve forme maker ve vygenerovanem C kodu systemtap modulu. Ty lze predefinovat prostrednictvim prepinace -D. Seznam zminenych maker: MAXNESTING Maximalni pocet zanorenych funkcnich volani. Vychozi hodnota se urcuje pri analyze skriptu. Skripty zalozene na rekurzi obdrzi 10 bonusovych slotu. MAXSTRINGLEN Maximalni delka retezce. Vychozi hodnota je 128 znaku. MAXTRYLOCK Maximalni pocet iteraci pri cekani na uvolneni zamku na globalni promenne pred tim, nez se vyhlasi deadlock a sonda se preskoci. Vychozi hodnota je 1000 iteraci. MAXACTION Maximalni pocet prikazu, ktere mohou byt vykonany behem jednoho hitu sondy (s vypnutymi prerusenimi). Vychozi hodnota je 1000. MAXACTION_INTERRUPTIBLE Maximalni pocet prikazu, ktere mohou byt vykonany behem jedne aktivace (probe hit) sondy, ktera se provadi s povolenymi prerusenimi. (jako napr. sondy begin a end). Vychozi hodnota je 10 * MAXACTION. MAXBACKTRACE Maximalni pocet zasobnikovych ramcu, ktere budou zpracovany pri vypisu backtrace. Relevantni tapset je [u]context-unwind.stp, a vychozi hodnota je 20. MAXMAPENTRIES Maximalni pocet radku v kazdem jednom globalnim poli. Vychozi hodnota je 2048. Jednotliva pole mohou byt deklarovana s odlisnym limitem. Priklad: global big[10000],little[5] nebo je mozno vyuzit modifikatoru % , cimz se zapne array-wrapping (nahrazovani "starych" prvku) jako v nasledujicim prikladu: global big% Viz sekce o polich. MAXERRORS Maximalni mnozstvi mekkych chyb, ktere jeste nezpusobi ukonceni skriptu. Vychozi hodnotou je 0, tedy skript skonci pri prvni mekke chybe. Poznamenejme, ze --suppress-handler-errors tento limit vypina. MAXSKIPPED Maximalni pocet preskocenych sond, ktery jeste nevede k ukonceni skriptu. Vychozi hodnotou je 100. Pozn., ze systemtap lze spustit s prepinacem -t (timing), ktery zobrazi podrobnosti ohledne poctu preskocenych sond. Pri pouziti -DINTERRUPTIBLE=1 se nebudou brat v potaz sondy preskocene kvuli re-entranci. Dale poznamenejme, ze --suppress-handler-errors vypina i tento limit. MINSTACKSPACE Minimalni mnozstvi volneho mista na zasobniku jadra dostatecne pro start sondy. Vychozi hodnota 1024 bajtu. Tato hodnota by mela byt dostacujici pro vlastni potrebu obsluzne rutiny vcetne male rezervy. MAXUPROBES Maximalni mnozstvi soucasne zamcenych uzivatelskych sond (uprobes). Vychozi hodnota je o neco malo vyssi, nez pocet uzivatelskych sond ve skriptu. Tato hodnota musi byt relativne velka, protoze jednotlive uzivatelske sondy (kazda z nich okupuje priblizne 46 bajtu), se alokuji pro kazdy proces a pro kazdou odpovidajici sondu ve skriptu. STP_MAXMEMORY Maximalni velikost pameti (v kilobajtech), kterou je systemtap modul opravnen pouzit. Vychozi hodnota je neomezena. Limit zahrnuje velikost modulu samotneho plus dodatecne alokace. Zahrnuty jsou jen prime alokace provedene systemtap runtime. Neprime alokace, ktere provadeji napr, "kprobes", "uprobes", atd., nejsou zapocteny. STP_OVEROAD_THRESHOLD, STP_OVERLOAD_INTERVAL Maximalni pocet cyklu, ktere lze stravit v sondach za dany cas (tez vyjadreny v cyklech). Pri prekroceni teto podminky dojde k pretizeni a skript se zastavi. Vychozi hodnoty jsou 5e+8 a 1e+9, coz odpovida max. 50% povolenemu vytizeni. STP_PROCFS_BUFSIZE Velikost procfs bufferu pro cteni (v bajtech). Vychozi hodnota je MAXSTRINGLEN. Tento limit lze nastavit specificky pro jednotlive sondy pomoci syntaxe .maxsize(MAXSIZE) . Pokud skript obsahuje sondy vazane na preruseni, je mozne, ze k preruseni dojde tak casto, ze handler daneho preruseni jeste nedobehne zatimco dojde k dalsimu preruseni. V tomto pripade bude obsluzna rutina preskocena, aby se zamezilo reentranci. Tento problem lze obejit pouzitim -DINTERRUPTIBLE=0kodstinenibeziciobsluznerutinyoddanehopreruseni. Tento pristup prinasi jistou rezii, ale v beznych pripadech zamezi reentranci. Nicmene, sondy v NMI handlerech a v samotnem procesu stap, mohou stale byt preskoceny, aby se zamezilo reentranci. Vznikne-li problem pri behu programu stap nebo staprun kdyz uz sondy bezi, je mozne bezpecne zabit oba tyto uzivatelske procesy a odstranit systemtap modul pomoci rmmod. Cast vystupu se tak nicmene muze ztratit. NEPRIVILEGOVANI UZIVATELE Systemtap umoznuje pristup k internim datum jadra a tedy potencialne k soukromym datum uzivatele. Z tohoto duvodu je plny pristup k systemtapu omezen na uzivatele root a na uzivatele, kteri jsou cleny skupin stapdev a stapusr. Nicmene omezena sada funkci systemtapu muze byt dostupna duveryhodnym neprivilegovanym uzivatelum. Tito uzivatele jsou cleny pouze skupiny stapusr plus pripadne skupiny stapsys. Tito uzivatele mohou zavest do jadra predem pripraveny modul, ktery byl podepsan duveryhodnym kompilacnim serverem. Viz popis voleb --privilege a --use-server. Viz take README.unprivileged mezi zdrojovymi soubory systemtapu. Tam je mj. popsano jak nastavit duveryhodny kompilacni server. Omezeni ktera plynou z volby --privilege=stapsys maji zabranit neprivilegovanym uzivatelum v o zamernem poskozovani systemu. Omezeni, ktera plynou z volby --privilege=stapusr maji zabranit neprivilegovanym uzivatelum v o zamernem poskozovani systemu. o ziskani pristupu k neverejnym / soukromym informacim. o snizovani vykonu procesu vlastnenych jinymi uzivateli systemu. Urcitemu vlivu na vykon celeho systemu nelze zabranit, nebot sondy neprivilegovaneho uzivatele budou v prislusny cas aktivni. Nicmene hlavnim cilem zde je, aby neprivilegovany uzivatel nezadoucim nezpusobem zasahoval do procesu jinych uzivatelu. OMEZENI NA SONDY Clen skupin stapusr a stapsys ma pristup ke vsem sondam. Clen pouze skupiny stapusr muze pouzit nasledujici sondy: o begin, begin(n) o end, end(n) o error(n) o never o process.*, s tim, ze cilovy proces je jeho vlastni. o timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)* o timer.hz(n) OMEZENI SKRIPTOVACIHO JAZYKA Nasledujici vlastnosti skriptovaciho jazyka jsou pro neprivilegovaneho uzivatele nedostupne: o jakakoliv funkcionalita podminena guru rezimem (-g). o vlozeny C kod. RUNTIME OMEZENI Neprivilegovanych uzivatelu se tykaji take nasledujici omezeni runtime: o Lze pouzit jen vychozi runtime kod (viz -R). Na cleny pouze skupiny stapusr se vztahuji dodatecna omezeni: o Analyza procesu vlastnenych jinymi uzivateli neni dovolena. o Pristup do pameti jadra neni dovolen ani pro zapis, ani pro cteni. OMEZENI NA VOLBY PRIKAZOVE RADKY Nektere volby prikazove radky poskytuji pristup k funkcionalite, ktera nesmi byt pristupna zadnemu neprivilegovanemu uzivateli. Konkretne o Nesmi nastavit -g . o Nasledujici volby nesmeji byt pouzity klientem kompilacniho serveru: -a, -B, -D, -I, -r, -R OMEZENI NA PROMENNE PROSTREDI Neprivilegovani uzivatele nesmeji nastavit nasledujici promenne prostredi: SYSTEMTAP_RUNTIME SYSTEMTAP_TAPSET SYSTEMTAP_DEBUGINFO_PATH OMEZENI NA TAPSETY Obecne jsou tapset funkce pristupne clenum skupiny stapusr pokud nepristupuji k informacim, ktere by nemel pravo ziskat libovolny uzivatelsky program bezici s identitou daneho uzivatele. Existuji dve skupiny tapset funkci pro neprivilegovane uzivatele. Prvni kategorie sestava z funkci, ktere mohou pouzit vsichni uzivatele, jako napriklad: cpu:long () exit () str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) Druhou skupinou jsou tzv. myproc-unprivileged funkce, ktere mohou sbirat informace pouze o procesech, ktere dany uzivatel vlastni. Skripty, ktere maji pouzivat myproc-unprivileged funkce musi testovat is_myproc() a volat takove funkce jen kdyz vysledek je 1. Skript se ihned ukonci, pokud tato podminka nebude splnena. Priklady myproc-unprivileged funkci: print_usyms (stk:string) user_int:long (addr:long) usymname:string (addr:long) Pokud se uzivatel patrici pouze do skupiny stapusr pokusi pouzit tapset funkci, ktera nespada do zadne ze zminenych dvou kategorii, dojde k chybe pri kompilaci. ALTERNATIVNI RUNTIME BACKENDY Jak jiz bylo zmineno, systemtap pouziva jako vychozi tzv. "kernel runtime backend", ktery pracuje na principu jaderneho modulu. To prinasi vyse zminena bezpecnostni uskali. Systemtap nove obsahuje dva prototypy novych "backendu", ktere lze aktivovat volbami --runtime=dyninst a --runtime=bpf. --runtime=dyninst vyuziva Dyninst a lze jej pouzit k instrumentaci uzivatelskych procesu. Neni zalozen na bazi jadernych modulu a nevyzaduje rootovske opravneni. Zustavaji v nem ale v platnosti omezeni na povolene typy sond. Dyninst backend pracuje v rezimu pripojeni se k cilovemu procesu, proto vyzaduje volbu -c COMMAND, nebo -x PID process. Napriklad: stap --runtime=dyninst -c "stap -V" \ -e "probe process.function("main") { println("hi from dyninst!") }" Pro spravnou funkci dyninst runtime muze byt nezbytne zapnout na cilovem systemu SELinux volbu allow_execstack: # setsebool allow_execstack 1 --runtime=bpf preklada systemtap skript na extended Berkeley Packet Filter (eBPF) program. Linuxove jadro kontroluje eBPF programy z hlediska bezpecnosti, a spousti je na svem internim virtualnim stroji. Tento "runtime backend" je v casne fazi vyvoje, a momentalne trpi radou omezeni, viz stapbpf(8). NAVRATOVY KOD V pripade uspesneho behu vrati prikaz stap kod 0 (exit code). V opacnem pripade se na standardni chybovy vystup muze vypsat chybova hlaska a stap vrati nenulovy kod. Pro zvyseni upovidanosti pouzijte -v nebo -vp N . V "listing" rezimu (-l and -L), se chyby obvykle potlacuji. Pokud byla nalezena alespon jedna sonda vyhovujici zadanym pozadavkum, stap skonci s navratovym kodem 0. Skript, ktery skonci svuj beh na zadost uzivatele pouzitim ^C / SIGINT, se povazuje za uspesne ukonceny. ZASTARAVANI Behem vyvoje systemtapu dochazi obcas ve skriptovacim jazyce k nekompatibilnim zmenam, takze stare skripty mohou prestat fungovat. V takovem pripade muze pomoci volba --compatible VERSION kde se urci posledni znama verze systemtapu, se kterou dany skript fungoval. Pri pouziti volby --check-version vypise systemtap varovani pokud narazi pri lexikalni analyze na nekompatibilni element. Informace o zastaravani se udrzuji v souboru NEWS. Smyslem mechanizmu zastaravani je prinest zadouci inovace skriptovaciho jazyka a soucasne nerozbit kompatibilitu se starymi existujicimi skripty. Mechanizmus zastaravani by tedy mel byt chapan predevsim jako sluzba prinasejici pohodli uzivatelum (a nepohodli vyvojarum) spise nez naopak. Poznamenejme, ze tapset identifikatory s predponou "_" jsou povazovany za interni a obcas podstupuji zmeny pri kterych je tezke zarucit zpetnou kompatibilitu i pri pouziti mechanizmu zastaravani. V pripade potreby, prosim, navrhnete takovy symbol k regulernimu zverejneni. SOUBORY Dulezite soubory a jim prislusne cesty dokumentuje manualova stranka stappaths (7). VIZ TAKE 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 Prosim, pouzijte nasledujici bugzilla link, nebo nas mailing list. http://sourceware.org/systemtap/, . error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs STAP(1)