STAP-SERVER(8)

JMÉNO
stap-server - kompilační server systemtapu

POUŽITÍ
[ service ] stap-server { start | stop | restart | condrestart | try-restart | force-reload | status } [ options ]

POPIS
Kompilační server systemtapu (stap-server) je síťová služba. Přijímá zabezpečené SSL spojení od klienta a vykonává požadavky na spuštění příkazu stap . Každý stap-server inzeruje svoji přítomnost a konfiguraci na lokální síti prostřednictvím mDNS (avahi), a tím umožňuje klientům automatickou detekci serverů.

stap-server nabízí:

•   síťovou službu umožňující přístup ke kompilačním serverům systemtapu

•   pohodlné ovládání nakonfigurovaných, nebo "ad-hoc" kompilačních serverů systemtapu

ARGUMENTY
Musí být určena alespoň jedna z následujících voleb:

start
    Spustit servery. Určené servery budou nastartovány. Pokud není určen žádný server, spustí se nakonfigurované servery. Pokud není žádný server nakonfigurován, spustí se server pro verzi jádra architekturu odpovídající hostitelskému stroji. Pokud je určený server již spuštěn, bude pro něj požadavek na spuštění ignorován. Pokud selže start daného serveru, operace skončí chybou.

stop
    Zastavit server(y). Určené servery se zastaví. Pokud žádný server není určen, zastaví se všechny běžící servery. Pokud určený server neběží, skončí pro něj "stop" akce úspěchem. Pokud pokus o zastavení serveru selže, stap-server selže též.

restart
    Zastavit a znovu nastartovat služby. Specifikované servery se zastaví a znovu nastartují. Pokud není žádný server určen, dojde k pokusu o restart všech serverů. Pokud žádné neběží, bude se 'restart' rovnat pokusu o start.

condrestart
    Zastavit a znovu nastartovat služby. Specifikované servery se zastaví a znovu nastartují. Pokud určený server neběží, nebude nastartován. Pokud není žádný server určen, dojde k pokusu o restart všech běžících serverů. Pokud žádný server neběží, nestane se nic.

try-restart
    Tato akce je shodná s condrestart.

force-reload
    Zastavit všechny běžící servery, znovu načíst konfigurační soubory, a restartovat služby jako by byl dán příkaz start .

status
    Vypsat informaci o stavu serverů. Vypíše informaci o specifikovaných serverech. Pokud nebyl žádný server specifikován, vypíše se informace o stavu všech běžících serverů.

VOLBY
Pro upřesnění argumentů je možno použít následující volby:

-c configfile
    Určuje globální konfigurační soubor jako dodatek k výchozímu globálnímu konfiguračnímu souboru popsanému níže. Zadaný soubor bude zpracován po výchozím globálním konfiguračním souboru. Pokud se volba -c použije více než jednou, bude brán zřetel jen na poslední použití.

-a architecture
    Tato volba určuje cílovou architekturu serveru a je analogická volbě -a programu stap. Viz manuálová stránka stap(1) , která obsahuje podrobnosti. Výchozí architektura je architektura hostitelského systému.

-r kernel-release
    Určuje verzi cílového jádra a je analogická volbě -r programu stap. Viz manuálová stránka stap(1) , která obsahuje podrobnosti. Výchozí verze je verze hostitelského systému.

-I path
    Tato volba určuje dodatečné umístění, ve kterém budou servery hledat tapset skripty. Je analogická volbě -I příkazu stap. Viz manuálová stránka stap(1) , která obsahuje podrobnosti.

-R path
    Tato volba určuje umístění zdrojových kódů pro překlad jaderného modulu systemtapu pro použití systemtap serverů a je analogická volbě -R programu stap. Viz manuálová stránka stap(1) , která obsahuje podrobnosti.

-B options
    Tato volba určuje volby, které se předají příkazu make při sestavování systemtap modulu a je analogická volbě -B programu stap. Viz manuálová stránka stap(1) , která obsahuje podrobnosti.

-i  Tato volba určuje systemtap server, který obsluhuje všechny verze jádra, které jsou nainstalovány v /lib/modules/.

-n nickname
    Umožňuje určit server pomocí přezdívky. Pokud se nastaví -n, bude použit běžící server s danou přezdívkou. Pokud se takový server nenajde, budou na danou přezdívku prohledány konfigurační soubory pro výchozí servery, nebo bude prohledána cesta určená v globálním konfiguračním souboru, nebo v konfiguračním souboru určeném přepínačem -c. Pokud se požadovaný server najde, použijí se pro něj přepínače -a, -r, -I, -R, -B a -u. Pokud se žádný server pro danou přezdívku nenajde a akce je start (nebo akce která se tak chová) (viz ARGUMENTY), server s danou přezdívkou se nastartuje.

-p pid
    Tato volba umožňuje určit server prostřednictvím ID procesu. Pokud se nastaví -p, bude hledán běžící server s daným PID. Pokud se takový nenajde, vznikne chyba. Pokud se takový server najde, předají se mu volby -a, -r, -I, -R, -B a -u.

-u user-name
    Každý kompilační server systemtapu se za normálních okolností spouští pod uživatelem stap-server (pro initscript) nebo jako uživatel, který spouští stap-server, pokud neexistuje jiné nastavení (viz sekce SOUBORY). Tato volba určuje uživatele, pod kterým poběží servery. Takový uživatel musí být členem skupiny stap-server.

--log logfile
    Tato volba umožňuje nastavit pro každý server separátní log soubor. Volbu lze opakovat a tím nastavit log soubor každému ze specifikovaných serverů zvlášť. Pokud je specifikováno více serverů, než voleb --log, použije se pro zbývající servery výchozí log soubor (viz sekce SOUBORY).

--port port-number
    Nastaví port pro každý specifikovaný server. Volbu lze opakovat a určit tak port pro všechny specifikované servery. Pokud je specifikováno více serverů než voleb --port, bude pro zbývající servery zvolen náhodný port.

--ssl certificate-db-path
    Tato volba umožňuje specifikaci separátní NSS databáze pro každý server, Volbu lze opakovat a aplikovat ji na jednotlivé specifikované servery. Pokud je specifikováno více serverů, než voleb --ssl, bude pro zbývající servery použita výchozí databáze (viz sekce SOUBORY).

--max-threads threads
    Určuje počet vláken pro obsluhu současných požadavků. Pokud threads == 0, budou všechny požadavky obsluhovány sériově v jediném - hlavním vlákně. Výchozí hodnota je počet dostupných jader procesoru.

KONFIGURACE
Pomocí konfiguračních souborů je možné:

•   určit globální konfiguraci logování, konfigurační soubory serverů, stavové soubory a další globální parametry.

•   určit které servery se nastartují ve výchozím nastavení.

Globální Konfigurace
Globální konfigurační soubor obsahuje nastavení globálních proměnných, které ovlivňují celkovou operaci služby. Každá řádka začínající znakem '#' se ignoruje. Všechny ostatní řádky musejí mít tvar VARIABLE=VALUE. Nejde o shell skript. Celý zbytek řáky za znakem '=' bude interpretován jako hodnota a ta bude přiřazena příslušné proměnné. Lze použít následující proměnné:

CONFIG_PATH
    Absolutní cesta k adresáři, který obsahuje výchozí konfiguraci serverů.

STAT_PATH
    Absolutní cesta k adresáři se status soubory.

LOG_FILE
    Absolutní cesta k log souboru.

STAP_USER
    Uživatel pod kterým stap-server(y) poběží. Výchozí hodnota je stap-server pro initskript, jinak uživatel, který spouští stap-server.

Následuje příklad globálního konfiguračního souboru: CONFIG_PATH=~<user>/my-stap-server-configs LOG_FILE=/tmp/stap-server/log

Individuální konfigurace serveru
Pokud pro akci start (nebo jí podobnou akci) nebyly specifikovány konkrétní servery, budou nastartovány servery odpovídající jednotlivým individuálním konfiguračním souborům. Každý konfigurační soubor obsahuje nastavení proměnných, které se použijí ke zkonfigurování individuálního serveru. Každá řádka začínající znakem '#' se ignoruje. Všechny ostatní řádky musí být tvaru VARIABLE=VALUE. Nejde o shell skript. Celý zbytek řádku za znakem '=' se interpretuje jako hodnota. Každý konfigurační soubor musí mít název s příponou .conf. Viz stappaths(7) kde je popsáno výchozí umístění těchto souborů. Toto výchozí umístění může být změněno v globálním konfiguračním souboru pomocí volby -c (viz OPTIONS). Lze použít následující proměnné:

ARCH
    Určuje cílovou architekturu pro daný server a odpovídá přepínači -a (viz VOLBY). Pokud ARCH není nastavena, použije se architektura hostitelského stroje jako výchozí.

RELEASE
    Určuje verzi jádra pro daný server a odpovídá volbě -r (viz VOLBY). Pokud RELEASE není nastavena, použije se release hostitelského stroje jako výchozí.

BUILD
    Určuje volby, které se předají příkazu make při sestavování jaderného modulu systemtapu. Jde o proměnnou typu pole, kde každý prvek odpovídá volbě -B (viz VOLBY). Pomocí BUILD=STRING se pole vymaže a první prvek se nastaví na STRING. Pomocí BUILD+=STRING se do pole přidá STRING jako další prvek.

INCLUDE
    Určuje seznam adresářů, ve kterých bude server hledat tapset skripty. Jde o pole, kde každý prvek odpovídá přepínači -I, viz VOLBY). Prostřednictvím zápisu INCLUDE=PATH se pole smaže a první jeho prvek se nastaví na PATH. Pomocí zápisu INCLUDE+=PATH se do pole přidá PATH jako další prvek.

RUNTIME
    Určuje adresář, který obsahuje zdrojové soubory potřebné pro sestavení jaderného modulu systemtapu. Odpovídá přepínači -R (viz VOLBY).

USER
    Určuje uživaltele, pod kterým server poběží a odpovídá volbě -u (viz VOLBY).

NICKNAME
    Odpovídá přezdívce pro server a také volbě -n (viz VOLBY).

LOG Určuje umístění logovacího souboru pro daný server a odpovídá volbě --log (viz VOLBY).

PORT
    Určuje síťový port, na kterém má daný server poslouchat. Odpovídá volbě --port (viz VOLBY).

SSL Určuje umístění certifikační databáze NSS, kterou má daný server použít a odpovídá volbě --ssl (viz VOLBY).

MAXTHREADS
    Určuje maximální počet vláken pro obsluhu současných požadavků daným serverem Odpovídá volbě --max-threads (viz VOLBY).

Následuje ukázka konfiguračního souboru: ARCH= USER= RELEASE= NICKNAME=native Tím, že ponecháme ARCH, USER, a RELEASE prázdné docílíme toho, že se pro ně použijí výchozí hodnoty. Konkrétnější příklad: ARCH=i386 RELEASE=2.6.18-128.el5 PORT=5001 LOG=/path/to/log/file Komplikovanější příklad: USER=serveruser RELEASE=/kernels/2.6.18-92.1.18.el5/build INCLUDE=/mytapsets INCLUDE+=/yourtapsets BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2' DEFINE=STP_MAXMEMORY=1024 DEFINE+=DEBUG_TRANS RUNTIME=/myruntime NICKNAME=my-server SSL=/path/to/NSS/certificate/database

AUTENTIZACE
Bezpečnost SSL spojení mezi klientem a serverem závisí na správném zacházení s certifikáty.

Důvěryhodnost daného systemtap serveru nelze určit automaticky bez důvěryhodné autority, která vydala certifikát. To nemusí být praktické pro každodenní použití, proto se klienti autentizují proti své vlastní databázi důvěryhodných certifikátů. V tomto kontextu vytvoření relace důvěry znamená přidání serverového certifikátu do databáze klienta.

Pro initscript lokálního serveru se toto děje automaticky. Jakmile se nainstaluje balíček systemtap-server, certifikát serveru pro výchozího uživatele (stap-server) se automaticky vygeneruje a přidá do databáze lokálního klienta. Lokální klient tak automaticky považuje lokální server za důvěryhodný "module signer".

Je-li stap spuštěn neprivilegovaným uživatelem (t.j. uživatelem, který není root, ani člen skupiny stapdev, ale může být členem skupiny stapusr a/nebo stapsys) automaticky se použijí volby --use-server a --privilege. To znamená, že neprivilegovaní uživatelé mohou používat lokální stap server v neprivilegovaném režimu bez zvláštních nastavení. Neprivilegovaní uživatelé mohou též používat kompilační server prostřednictvím přepínačů --use-server a --privilege, ale samozřejmě nebudou moci zavést systemtap modul do jádra (s volbou -p4 se o to systemtap nebude pokoušet).

Aby bylo možno použít stap server na vzdáleném stroji, je potřeba nainstalovat jeho serverový certifikát do klienta. Viz volba --trust-servers v manuálové stránce stap(1) a také soubor README.unprivileged mezi zdrojovými soubory systemtapu.

PŘÍKLADY
Jednoduché příklady shrnuje manuálová stránka stapex(3stap).

Nastartovat zkonfigurovaný server, nebo výchozí server pokud žádný server není zkonfigurovaný:

$ [ service ] stap-server start

Spustit systemtap server, který bude obsluhovat všechna jádra nainstalovaná v /lib/modules:

$ [ service ] stap-server start -i

Vypsat informace o běžících serverech:

$ [ service ] stap-server status

Nastartovat server s konfigurací podobnou jinému již běžícímu serveru s danou přezdívkou NICKNAME, ovšem pro odlišnou architekturu:

$ [ service ] stap-server start -n NICKNAME -a ARCH

Nastartovat server pro nenainstalované jádro (křížová kompilace)

$ [ service ] stap-server start -a ARCH -r /BUILDDIR

Zastavit jeden ze serverů odkazem na jeho PID (dle stap-server status): stap-server status):

$ [ service ] stap-server stop -p PID

Spustit skript prostřednictvím kompilačního serveru:

$ stap SCRIPT --use-server

Spustit skript jako neprivilegovaný uživatel pomocí kompilačního serveru:

$ stap SCRIPT

Zastavit všechny kompilační servery:

$ [ service ] stap-server stop

Restartovat server po změně globální konfigurace a/nebo když byl přidán nový , nebo odebrán, či změněn existující server:

$ [ service ] stap-server force-reload

BEZPEČNOST A OCHRANA SOUKROMÍ
Systemtap je systémový administrační nástroj. Zpřístupňuje interní datové struktury jádra, které mohou obsahovat privátní informace. Přečtěte si manuálovou stránku stap(1) která přináší více informací.

Jako síťový server by měl stap-server být aktivován s rozvahou, aby se omezila všechna relevantní rizika. Zvažte následující opatření:

1   Spouštějte stap-server pod běžným uživatelem, nikdy ne pod uživatelem root. Když je stap-server spuštěn jako služba (t.j. service stap-server ...), pak výchozí chování je, že všechny servery běží pod uživatelem stap-server. Při přímém spuštění běží service stap-server pod uživatelem který jej vyvolal. V každém případě lze uživatele změnit volbou -u, nebo případně nastavením STAP_USER=username v globálním konfiguračním souboru, nebo nastavením USER=username v konfiguračním souboru individuálního serveru. Daný uživatel musí mít právo spustit proces pod jiným uživatelem. Vice informací viz KONFIGURACE. Zvolený uživatel musí mít také právo zapisovat do logovacího souboru. Umístění logovacího souboru lze upravit nastavením LOG_FILE=path v globálním konfiguračním souboru. Vice informací viz KONFIGURACE. Zvolený uživatel musí mít právo čtení i zápisu do adresáře obsahujícího status soubory. Toto umístění lze upravit nastavením STAT_PATH=path v globálním konfiguračním souboru. Vice informací viz KONFIGURACE. Zvolený uživatel musí mít právo čtení a zápisu pro adresář, kde se sestavuje uprobes.ko a související soubory. Systemtap server nepoběží, pokud zvoleným uživatelem je root.

2   Spusťte stap-server s omezeními na maximální čas běhu, velikost souboru, velikost použité paměti tak, aby ani potenciálně chybné vstupy nezpůsobily škody. Pokud uživatelem, pod kterým server běží, je stap-server, pak každý požadavek server obsluhuje v rámci limitů nastavených v souboru ~stap-server/.systemtap/rc. V opačném případě nejsou žádné limity nastaveny.

3   Spusťte stap-server při nastavené proměnné prostřdí TMPDIR, která ukazuje do odděleného umístění, kde jsou zapnuty uživatelské kvóty. Tím se zabrání nežádoucímu zaplnění souborového systému. Výchozí TMPDIR je /tmp/.

4   Aktivujte firewall tak, aby klientské požadavky mohly přicházet jen z relativně bezpečných sítí. Pro automatickou volbu serverů klienty je třeba nainstalovat avahi jak na serveru, tak i na klientovi. Firewall musí propouštět mDNS zprávy.

Kompilační server systemtapu a související nástroje používají k síťové komunikaci SSL jak je implementovaná v rámci NSS. NSS se také používá pro správu certifikátů. Související databáze certifikátů musí být odpovídajícím způsobem chráněná, aby nedošlo ke snížení bezpečnosti systému. Pro navýšení bezpečnosti kontroluje systemtap klient správná přístupová oprávnění dříve než přistoupí k databázi certifikátů.

SOUBORY

Důležité soubory a jim odpovídající umístění shrnuje manuálová stránka
    stappaths (7).

VIZ TÉŽ
stap(1),
staprun(8),
stapprobes(3stap),
stappaths(7),
stapex(3stap),
avahi,
ulimit(1),
NSS

CHYBY
Použijte projektovou bugzillu, nebo mailing list. http://sourceware.org/systemtap/, <systemtap@sourceware.org>.

error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs