Ubuntu Manpage: stap-server - kompilační server systemtapu

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ís‐
tě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í vol‐
by -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 systemta‐
pu. 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é vlast‐
ní databázi důvěryhodných certifikátů. V tomto kontextu vytvoření relace důvěry znamená přidání servero‐
vého certifikátu do databáze klienta.

Pro initscript lokálního serveru se toto děje automaticky. Jakmile se nainstaluje balíček systemtap-ser‐
ver, certifikát serveru pro výchozího uživatele (stap-server) se automaticky vygeneruje a přidá do data‐
bá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 stap‐
dev, 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 neprivilegova‐
ném režimu bez zvláštních nastavení. Neprivilegovaní uživatelé mohou též používat kompilační server pro‐
stř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ě na‐
stavení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 ji‐
ný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 KONFI‐
GURACE.

Zvolený uživatel musí mít právo čtení i zápisu do adresáře obsahujícího status soubory. Toto umís‐
tě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 souvise‐
jí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é li‐
mity 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 klien‐
tovi. 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 implemento‐
vaná 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

                                                                                                  STAP-SERVER(8)