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í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

                                                                                   STAP-SERVER(8)