stunnel.pl

title: stunnel.pl(8)

summary: uniwersalny tunel protokołu \s-1TLS\s0

text:
# stunnel.pl(8)

## NAZWA
stunnel - uniwersalny tunel protokołu TLS

## SKŁADNIA
Unix:

stunnel [PLIK] | -fd N | -help | -version | -sockets | -options

WIN32:

stunnel [ [ -install | -uninstall | -start | -stop |

-reload | -reopen | -exit ] [-quiet] [PLIK] ] |

-help | -version | -sockets | -options

## OPIS
Program stunnel został zaprojektowany do opakowywania w protokół TLS połączeń pomiędzy zdalnymi klientami a lokalnymi lub zdalnymi serwerami. Przez serwer lokalny rozumiana jest aplikacja przeznaczona do uruchamiania przy pomocy inetd. Stunnel pozwala na proste zestawienie komunikacji serwerów nie posiadających funkcjonalności TLS poprzez bezpieczne kanały TLS.

stunnel pozwala dodać funkcjonalność TLS do powszechnie stosowanych demonów inetd, np. pop3 lub imap, do samodzielnych demonów, np. nntp, smtp lub http, a nawet tunelować ppp poprzez gniazda sieciowe bez zmian w kodzie źródłowym.

## OPCJE
PLIK

użyj podanego pliku konfiguracyjnego

-fd N (tylko Unix)

wczytaj konfigurację z podanego deskryptora pliku

-help

drukuj listę wspieranych opcji

-version

drukuj wersję programu i domyślne wartości parametrów

-sockets

drukuj domyślne opcje gniazd

-options

drukuj wspierane opcje TLS

-install (tylko Windows NT lub nowszy)

instaluj serwis NT

-uninstall (tylko Windows NT lub nowszy)

odinstaluj serwis NT

-start (tylko Windows NT lub nowszy)

uruchom serwis NT

-stop (tylko Windows NT lub nowszy)

zatrzymaj serwis NT

-reload (tylko Windows NT lub nowszy)

przeładuj plik konfiguracyjny uruchomionego serwisu NT

-reopen (tylko Windows NT lub nowszy)

otwórz ponownie log uruchomionego serwisu NT

-exit (tylko Win32)

zatrzymaj uruchomiony program

-quiet (tylko Win32)

nie wyświetlaj okienek z komunikatami

## PLIK KONFIGURACYJNY
Linia w pliku konfiguracyjnym może być:

- pusta (ignorowana)

- komentarzem rozpoczynającym się znakiem ';' (ignorowana)

- parą 'nazwa_opcji = wartość_opcji'

- tekstem '[nazwa_usługi]' wskazującym początek definicji usługi

Parametr adres może być:

- numerem portu

- oddzieloną średnikiem parą adresu (IPv4, IPv6, lub nazwą domenową) i numeru portu

- ścieżką do gniazda Unix (tylko Unix)

### OPCJE GLOBALNE
chroot = KATALOG (tylko Unix)

katalog roboczego korzenia systemu plików Opcja określa katalog, w którym uwięziony zostanie proces programu stunnel tuż po jego inicjalizacji, a przed rozpoczęciem odbierania połączeń. Ścieżki podane w opcjach CApath, CRLpath, pid oraz exec muszą być umieszczone wewnątrz katalogu podanego w opcji chroot i określone względem tego katalogu.

Niektóre funkcje systemu operacyjnego mogą wymagać dodatkowych plików umieszczonych w katalogu podanego w parametrze chroot:

- opóźnione rozwinięcie adresów DNS typowo wymaga /etc/nsswitch.conf i /etc/resolv.conf

- lokalizacja strefy czasowej w logach wymaga pliku /etc/timezone

- niektóre inne pliki mogą potrzebować plików urządzeń, np. /dev/zero lub /dev/null

compression = deflate | zlib

wybór algorytmu kompresji przesyłanych danych domyślnie: bez kompresji

Algorytm deflate jest standardową metodą kompresji zgodnie z RFC 1951.

debug = [PODSYSTEM].POZIOM

szczegółowość logowania Poziom logowania można określić przy pomocy jednej z nazw lub liczb: emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6) lub debug (7). Zapisywane są komunikaty o poziomie niższym (numerycznie) lub równym podanemu. Domyślnym poziomem jest notice (5).

Jakkolwiek użycie debug = debug lub debug = 7 zapewnia najbardziej szczegółowe logi, ich zawartość jest użyteczna jedynie dla programistów zajmujących się stunnelem. Użyj tego poziomu logowania jedynie jeśli jesteś programistką/programistą stunnela, albo przygotowujesz szczegółowe informacje celem przesłania do wsparcia technicznego. W przeciwnym wypadku próba analizy zawartości logów będzie jedynie źródłem dodatkowego zamieszania.

O ile nie wyspecyfikowano podsystemu użyty będzie domyślny: daemon. Podsystemy nie są wspierane przez platformę Win32.

Wielkość liter jest ignorowana zarówno dla poziomu jak podsystemu.

EGD = ŚCIEŻKA_DO_EGD (tylko Unix)

ścieżka do gniazda programu Entropy Gathering Daemon Opcja pozwala określić ścieżkę do gniazda programu Entropy Gathering Daemon używanego do zainicjalizowania generatora ciągów pseudolosowych biblioteki OpenSSL.

engine = auto | IDENTYFIKATOR_URZĄDZENIA

wybór silnika kryptograficznego domyślnie: bez wykorzystania silników kryptograficznych

Sekcja PRZYKŁADY zawiera przykładowe konfiguracje wykorzystujące silniki kryptograficzne.

engineCtrl = KOMENDA[:PARAMETR]

konfiguracja silnika kryptograficznego

engineDefault = LISTA_ZADAŃ

lista zadań OpenSSL oddelegowanych do bieżącego silnika Parametrem jest lista oddzielonych przecinkami zadań OpenSSL, które mają zostać oddelegowane do bieżącego silnika kryptograficznego.

W zależności od konkretnego silnika dostępne mogą być następujące zadania: ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1.

fips = yes | no

tryb FIPS 140-2 Opcja pozwala wyłączyć wejście w tryb FIPS, jeśli stunnel został skompilowany ze wsparciem dla FIPS 140-2.

domyślnie: no (od wersji 5.00)

foreground = yes | quiet | no (tylko Unix)

tryb pierwszoplanowy Użycie tej opcji powoduje, że stunnel nie przechodzi w tło.

Parametr yes powoduje dodatkowo, że komunikaty diagnostyczne logowane są na standardowy strumień błędów (stderr) oprócz wyjść zdefiniowanych przy pomocy opcji syslog i output.

iconActive = PLIK_Z_IKONKĄ (tylko GUI)

ikonka wyświetlana przy obecności aktywnych połączeń do usługi W systemie Windows ikonka to plik .ico zawierający obrazek 16x16 pikseli.

iconError = PLIK_Z_IKONKĄ (tylko GUI)

ikonka wyświetlana, jeżeli nie został załadowany poprawny plik konfiguracyjny W systemie Windows ikonka to plik .ico zawierający obrazek 16x16 pikseli.

iconIdle = PLIK_Z_IKONKĄ (tylko GUI)

ikonka wyświetlana przy braku aktywnych połączeń do usługi W systemie Windows ikonka to plik .ico zawierający obrazek 16x16 pikseli.

log = append | overwrite

obsługa logów Ta opcja pozwala określić, czy nowe logi w pliku (określonym w opcji output) będą dodawane czy nadpisywane.

domyślnie: append

output = PLIK

plik, do którego dopisane zostaną logi Użycie tej opcji powoduje dopisanie logów do podanego pliku.

Do kierowania komunikatów na standardowe wyjście (na przykład po to, żeby zalogować je programem splogger z pakietu daemontools) można podać jako parametr urządzenie /dev/stdout.

pid = PLIK (tylko Unix)

położenie pliku z numerem procesu Jeżeli argument jest pusty, plik nie zostanie stworzony.

Jeżeli zdefiniowano katalog chroot, to ścieżka do pid jest określona względem tego katalogu.

RNDbytes = LICZBA_BAJTÓW

liczba bajtów do zainicjowania generatora pseudolosowego

RNDfile = PLIK

ścieżka do pliku zawierającego losowe dane Biblioteka OpenSSL użyje danych z tego pliku do zainicjowania generatora pseudolosowego.

RNDoverwrite = yes | no

nadpisz plik nowymi wartościami pseudolosowymi domyślnie: yes (nadpisz)

service = SERWIS (tylko Unix)

nazwa usługi Podana nazwa usługi będzie używana jako nazwa usługi dla inicjalizacji sysloga, oraz dla biblioteki TCP Wrapper w trybie inetd. Chociaż technicznie można użyć tej opcji w trybie w sekcji usług, to jest ona użyteczna jedynie w opcjach globalnych.

domyślnie: stunnel

syslog = yes | no (tylko Unix)

włącz logowanie poprzez mechanizm syslog domyślnie: yes (włącz)

taskbar = yes | no (tylko WIN32)

włącz ikonkę w prawym dolnym rogu ekranu domyślnie: yes (włącz)

### OPCJE USŁUG
Każda sekcja konfiguracji usługi zaczyna się jej nazwą ujętą w nawias kwadratowy. Nazwa usługi używana jest do kontroli dostępu przez bibliotekę libwrap (TCP wrappers) oraz pozwala rozróżnić poszczególne usługi w logach.

Jeżeli stunnel ma zostać użyty w trybie inetd, gdzie za odebranie połączenia odpowiada osobny program (zwykle inetd, xinetd lub tcpserver), należy przeczytać sekcję TRYB INETD poniżej.

accept = [HOST:]PORT

nasłuchuje na połączenia na podanym adresie i porcie Jeżeli nie został podany adres, stunnel domyślnie nasłuchuje na wszystkich adresach IPv4 lokalnych interfejsów.

Aby nasłuchiwać na wszystkich adresach IPv6 należy użyć:

```
    accept = :::port

```

CAengine = IDENTYFIKATOR_CA_W_ENGINE

ładuje zaufane certyfikaty Centrum certyfikacji z silnika Opcja pozwala określić położenie pliku zawierającego certyfikaty używane przez opcję verifyChain lub verifyPeer.

Opcja może być użyta wielokrotnie w pojedynczej sekcji.

Aktualnie wspierane silniki: pkcs11, cng.

CApath = KATALOG_CA

ładuje zaufane certyfikaty Centrum certyfikacji z katalogu Opcja określa katalog, w którym stunnel będzie szukał certyfikatów, jeżeli użyta została opcja verifyChain lub verifyPeer. Pliki z certyfikatami muszą posiadać specjalne nazwy XXXXXXXX.0, gdzie XXXXXXXX jest skrótem kryptograficznym reprezentacji DER nazwy podmiotu certyfikatu.

Funkcja skrótu została zmieniona w OpenSSL 1.0.0. Należy wykonać c_rehash przy zmianie OpenSSL 0.x.x na 1.x.x.

Jeżeli zdefiniowano katalog chroot, to ścieżka do CApath jest określona względem tego katalogu.

CAfile = PLIK_CA

ładuje zaufane certyfikaty Centrum certyfikacji z pliku Opcja pozwala określić położenie pliku zawierającego certyfikaty używane przez opcję verifyChain lub verifyPeer.

cert = PLIK_CERT

plik z łańcuchem certyfikatów Opcja określa położenie pliku zawierającego certyfikaty używane przez program stunnel do uwierzytelnienia się przed drugą stroną połączenia. Plik powinien zawierać kompletny łańcuch certyfikatów począwszy od certyfikatu klienta/serwera, a skończywszy na samopodpisanym certyfikacie głównego CA. Obsługiwane są pliki w formacie PEM lub P12.

Certyfikat jest konieczny, aby używać programu w trybie serwera. W trybie klienta certyfikat jest opcjonalny.

Jeżeli używany jest silnik kryptograficzny, to opcja cert pozwala wybrać identyfikator używanego certyfikatu.

checkEmail = EMAIL

adres email podmiotu przedstawionego certyfikatu Pojedyncza sekcja może zawierać wiele wystąpień opcji checkEmail. Certyfikaty są akceptowane, jeżeli sekcja nie weryfikuje podmiotu certyfikatu, albo adres email przedstawionego certyfikatu pasuje do jednego z adresów email określonych przy pomocy checkEmail.

Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej.

checkHost = NAZWA_SERWERA

nazwa serwera podmiotu przedstawionego certyfikatu Pojedyncza sekcja może zawierać wiele wystąpień opcji checkHost. Certyfikaty są akceptowane, jeżeli sekcja nie weryfikuje podmiotu certyfikatu, albo nazwa serwera przedstawionego certyfikatu pasuje do jednego nazw określonych przy pomocy checkHost.

Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej.

checkIP = IP

adres IP podmiotu przedstawionego certyfikatu Pojedyncza sekcja może zawierać wiele wystąpień opcji checkIP. Certyfikaty są akceptowane, jeżeli sekcja nie weryfikuje podmiotu certyfikatu, albo adres IP przedstawionego certyfikatu pasuje do jednego z adresów IP określonych przy pomocy checkIP.

Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej.

ciphers = LISTA_SZYFRÓW

lista dozwolonych szyfrów dla protokołów SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2 Ta opcja nie wpływa na listę parametrów kryptograficznych dla protokołu TLSv1.3

Parametrem tej opcji jest lista szyfrów, które będą użyte przy otwieraniu nowych połączeń TLS, np.: DES-CBC3-SHA:IDEA-CBC-MD5

ciphersuites = LISTA_PARAMETRÓW_KRYPTOGRAFICZNYCH

lista dozwolonych parametrów kryptograficznych dla protokołu TLSv1.3 Parametrem tej opcji są listy parametrów kryptograficznych w kolejności ich preferowania.

Opcja ciphersuites jest dostępna począwszy od OpenSSL 1.1.1.

domyślnie: TLS_CHACHA20_POLY1305_SHA256: TLS_AES_256_GCM_SHA384: TLS_AES_128_GCM_SHA256

client = yes | no

tryb kliencki (zdalna usługa używa TLS) domyślnie: no (tryb serwerowy)

config = KOMENDA[:PARAMETR]

komenda konfiguracyjna OpenSSL Komenda konfiguracyjna OpenSSL zostaje wykonana z podanym parametrem. Pozwala to na wydawanie komend konfiguracyjnych OpenSSL z pliku konfiguracyjnego stunnela. Dostępne komendy opisane są w podręczniku SSL_CONF_cmd(3ssl).

Możliwe jest wyspecyfikowanie wielu opcji OpenSSL przez wielokrotne użycie komendy config.

Zamiast wyłączać config = Curves:list_curves użyj opcji curves w celu ustawienia krzywych eliptycznych.

Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej.

connect = [HOST:]PORT

połącz się ze zdalnym serwerem na podany port Jeżeli nie został podany adres, stunnel domyślnie łączy się z lokalnym serwerem.

Komenda może być użyta wielokrotnie w pojedynczej sekcji celem zapewnienia wysokiej niezawodności lub rozłożenia ruchu pomiędzy wiele serwerów.

CRLpath = KATALOG_CRL

katalog List Odwołanych Certyfikatów (CRL) Opcja określa katalog, w którym stunnel będzie szukał list CRL używanych przez opcje verifyChain i verifyPeer. Pliki z listami CRL muszą posiadać specjalne nazwy XXXXXXXX.r0, gdzie XXXXXXXX jest skrótem listy CRL.

Funkcja skrótu została zmieniona OpenSSL 1.0.0. Należy wykonać c_rehash przy zmianie OpenSSL 0.x.x na 1.x.x.

Jeżeli zdefiniowano katalog chroot, to ścieżka do CRLpath jest określona względem tego katalogu.

CRLfile = PLIK_CRL

plik List Odwołanych Certyfikatów (CRL) Opcja pozwala określić położenie pliku zawierającego listy CRL używane przez opcje verifyChain i verifyPeer.

curves = lista

krzywe ECDH odddzielone ':' Wersje OpenSSL starsze niż 1.1.1 pozwalają na użycie tylko jednej krzywej.

Listę dostępnych krzywych można uzyskać poleceniem:

```
    openssl ecparam -list_curves

```

domyślnie:

```
    X25519:P-256:X448:P-521:P-384 (począwszy od OpenSSL 1.1.1)
    prime256v1 (OpenSSL starszy niż 1.1.1)

```

logId = TYP

typ identyfikatora połączenia klienta Identyfikator ten pozwala rozróżnić wpisy w logu wygenerowane dla poszczególnych połączeń.

Aktualnie wspierane typy:

sequential

Kolejny numer połączenia jest unikalny jedynie w obrębie pojedynczej instancji programu stunnel, ale bardzo krótki. Jest on szczególnie użyteczny przy ręcznej analizie logów.

unique

Ten rodzaj identyfikatora jest globalnie unikalny, ale znacznie dłuższy, niż kolejny numer połączenia. Jest on szczególnie użyteczny przy zautomatyzowanej analizie logów.

thread

Identyfikator wątku systemu operacyjnego nie jest ani unikalny (nawet w obrębie pojedynczej instancji programu stunnel), ani krótki. Jest on szczególnie użyteczny przy diagnozowaniu problemów z oprogramowaniem lub konfiguracją.

process

Identyfikator procesu (PID) może być użyteczny w trybie inetd.

domyślnie: sequential

debug = POZIOM

szczegółowość logowania Poziom logowania można określić przy pomocy jednej z nazw lub liczb: emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6) lub debug (7). Zapisywane są komunikaty o poziomie niższym (numerycznie) lub równym podanemu. Do uzyskania najwyższego poziomu szczegółowości można użyć opcji debug = debug lub debug = 7. Domyślnym poziomem jest notice (5).

delay = yes | no

opóźnij rozwinięcie adresu DNS podanego w opcji connect Opcja jest przydatna przy dynamicznym DNS, albo gdy usługa DNS nie jest dostępna przy starcie programu stunnel (klient VPN, połączenie wdzwaniane).

Opóźnione rozwijanie adresu DNS jest włączane automatycznie, jeżeli nie powiedzie się rozwinięcie któregokolwiek z adresów connect dla danej usługi.

Opóźnione rozwijanie adresu automatycznie aktywuje failover = prio.

domyślnie: no

engineId = NUMER_URZĄDZENIA

wybierz silnik kryptograficzny dla usługi

engineNum = NUMER_URZĄDZENIA

wybierz silnik kryptograficzny dla usługi Urządzenia są numerowane od 1 w górę.

exec = ŚCIEŻKA_DO_PROGRAMU

wykonaj lokalny program przystosowany do pracy z superdemonem inetd Jeżeli zdefiniowano katalog chroot, to ścieżka do exec jest określona względem tego katalogu.

Na platformach Unix ustawiane są następujące zmienne środowiskowe: REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.

execArgs = $0 $1 $2 ...

argumenty do opcji exec włącznie z nazwą programu ($0) Cytowanie nie jest wspierane w obecnej wersji programu. Argumenty są rozdzielone dowolną liczbą białych znaków.

failover = rr | prio

Strategia wybierania serwerów wyspecyfikowanych parametrami "connect".

rr

round robin - sprawiedliwe rozłożenie obciążenia

prio

priority - użyj kolejności opcji w pliku konfiguracyjnym

domyślnie: prio

ident = NAZWA_UŻYTKOWNIKA

weryfikuj nazwę zdalnego użytkownika korzystając z protokołu IDENT (RFC 1413)

include = KATALOG

wczytaj fragmenty plików konfiguracyjnych z podanego katalogu Pliki są wczytywane w rosnącej kolejności alfabetycznej ich nazw. Rekomendowana konwencja nazewnictwa plików

dla opcji globalnych:

```
        00-global.conf

```

dla lokalnych opcji usług:

```
        01-service.conf
        02-service.conf

```

key = PLIK_KLUCZA

klucz prywatny do certyfikatu podanego w opcji cert Klucz prywatny jest potrzebny do uwierzytelnienia właściciela certyfikatu. Ponieważ powinien on być zachowany w tajemnicy, prawa do jego odczytu powinien mieć wyłącznie właściciel pliku. W systemie Unix można to osiągnąć komendą:

```
    chmod 600 keyfile

```

Jeżeli używany jest silnik kryptograficzny, to opcja key pozwala wybrać identyfikator używanego klucza prywatnego.

domyślnie: wartość opcji cert

libwrap = yes | no

włącz lub wyłącz korzystanie z /etc/hosts.allow i /etc/hosts.deny. domyślnie: no (od wersji 5.00)

local = HOST

IP źródła do nawiązywania zdalnych połączeń Domyślnie używane jest IP najbardziej zewnętrznego interfejsu w stronę serwera, do którego nawiązywane jest połączenie.

OCSP = URL

responder OCSP do weryfikacji certyfikatu drugiej strony połączenia

OCSPaia = yes | no

weryfikuj certyfikaty przy użyciu respondertów AIA Opcja OCSPaia pozwala na weryfikowanie certyfikatów przy pomocy listy URLi responderów OCSP przesłanych w rozszerzeniach AIA (Authority Information Access).

OCSPflag = FLAGA_OCSP

flaga respondera OCSP Aktualnie wspierane flagi: NOCERTS, NOINTERN, NOSIGS, NOCHAIN, NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER, RESPID_KEY, NOTIME

Aby wyspecyfikować kilka flag należy użyć OCSPflag wielokrotnie.

OCSPnonce = yes | no

wysyłaj i weryfikuj OCSP nonce Opcja OCSPnonce zabezpiecza protokół OCSP przed atakami powtórzeniowymi. Ze względu na złożoność obliczeniową rozszerzenie nonce jest zwykle wspierane jedynie przez wewnętrzne (np. korporacyjne), a nie przez publiczne respondery OCSP.

OCSPrequire = yes | no

wymagaj rozstrzygającej odpowiedzi respondera OCSP

OCSPrequire = yes | no

Wyłączenie tej opcji pozwala na zaakceptowanie połączenia pomimo braku otrzymania rozstrzygającej odpowiedzi OCSP ze staplingu i bezpośredniego żądania wysłanego do respondera. default: yes

domyślnie: yes

options = OPCJE_SSL

opcje biblioteki OpenSSL Parametrem jest nazwa opcji zgodnie z opisem w SSL_CTX_set_options(3ssl), ale bez przedrostka SSL_OP_. stunnel -options wyświetla opcje dozwolone w aktualnej kombinacji programu stunnel i biblioteki OpenSSL.

Aby wyspecyfikować kilka opcji należy użyć options wielokrotnie. Nazwa opcji może być poprzedzona myślnikiem ("-") celem wyłączenia opcji.

Na przykład, dla zachowania kompatybilności z błędami implementacji TLS w programie Eudora, można użyć opcji:

```
    options = DONT_INSERT_EMPTY_FRAGMENTS

```

domyślnie:

```
    options = NO_SSLv2
    options = NO_SSLv3

```

Począwszy od OpenSSL 1.1.0, zamiast wyłączać określone wersje protokołów TLS użyj opcji sslVersionMax lub sslVersionMin.

protocol = PROTOKÓŁ

negocjuj TLS podanym protokołem aplikacyjnym Opcja ta włącza wstępną negocjację szyfrowania TLS dla wybranego protokołu aplikacyjnego. Opcji protocol nie należy używać z szyfrowaniem TLS na osobnym porcie.

Aktualnie wspierane protokoły:

cifs

Nieudokumentowane rozszerzenie protokołu CIFS wspierane przez serwer Samba. Wsparcie dla tego rozszerzenia zostało zarzucone w wersji 3.0.0 serwera Samba.

capwin

Wsparcie dla aplikacji http://www.capwin.org/

capwinctrl

Wsparcie dla aplikacji http://www.capwin.org/ Ten protokół jest wspierany wyłącznie w trybie klienckim.

connect

Negocjacja RFC 2817 - Upgrading to TLS Within HTTP/1.1, rozdział 5.2 - Requesting a Tunnel with CONNECT Ten protokół jest wspierany wyłącznie w trybie klienckim.

imap

Negocjacja RFC 2595 - Using TLS with IMAP, POP3 and ACAP

ldap

Negocjacja RFC 2830 - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security

nntp

Negocjacja RFC 4642 - Using Transport Layer Security (TLS) with Network News Transfer Protocol (NNTP) Ten protokół jest wspierany wyłącznie w trybie klienckim.

pgsql

Negocjacja http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982

pop3

Negocjacja RFC 2449 - POP3 Extension Mechanism

proxy

Przekazywanie oryginalnego IP klienta przez protokół HAProxy PROXY w wersji 1 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

smtp

Negocjacja RFC 2487 - SMTP Service Extension for Secure SMTP over TLS

socks

Wspierany jest protokół SOCKS w wersjach 4, 4a i 5. Protokół SOCKS enkapsulowany jest w protokole TLS, więc adres serwera docelowego nie jest widoczny dla napastnika przechwytującego ruch sieciowy. http://www.openssh.com/txt/socks4.protocol

http://www.openssh.com/txt/socks4a.protocol

Nie jest wspierana komenda BIND protokołu SOCKS. Przesłana wartość parametru USERID jest ignorowana.

Sekcja PRZYKŁADY zawiera przykładowe pliki konfiguracyjne VPNa zbudowanego w oparciu o szyfrowany protokół SOCKS.

protocolAuthentication = UWIERZYTELNIENIE

rodzaj uwierzytelnienia do negocjacji protokołu Opcja ta jest wpierana wyłącznie w klienckich protokołach 'connect' i 'smtp'.

W protokole 'connect' wspierane jest uwierzytelnienie 'basic' oraz 'ntlm'. Domyślnym rodzajem uwierzytelnienia protokołu 'connect' jest 'basic'.

W protokole 'smtp' wspierane jest uwierzytelnienie 'plain' oraz 'login'. Domyślnym rodzajem uwierzytelnienia protokołu 'smtp' jest 'plain'.

protocolDomain = DOMENA

domena do negocjacji protokołu W obecnej wersji opcja ma zastosowanie wyłącznie w protokole 'connect'.

protocolHeader = NAGŁÓWEK

nagłówek do negocjacji protokołu W obecnej wersji opcja ma zastosowanie wyłącznie w protokole 'connect'.

protocolHost = ADRES

adres hosta do negocjacji protokołu Dla protokołu 'connect', protocolHost określa docelowy serwer TLS, do którego połączyć ma się proxy. Adres serwera proxy, do którego łączy się stunnel, musi być określony przy pomocy opcji connect.

Dla protokołu 'smtp', protocolHost określa wartość HELO/EHLO wysyłanego przy negocjacji klienta.

protocolPassword = HASŁO

hasło do negocjacji protokołu Opcja ta jest wspierana wyłącznie w klienckich protokołach 'connect' i 'smtp'.

protocolUsername = UŻYTKOWNIK

nazwa użytkownika do negocjacji protokołu Opcja ta jest wspierana wyłącznie w klienckich protokołach 'connect' i 'smtp'.

PSKidentity = TOŻSAMOŚĆ

tożsamość klienta PSK PSKidentity może zostać użyte w sekcjach klienckich do wybrania tożsamości użytej do uwierzytelnienia PSK. Opcja jest ignorowana w sekcjach serwerowych.

domyślnie: pierwsza tożsamość zdefiniowana w pliku PSKsecrets

PSKsecrets = PLIK

plik z tożsamościami i kluczami PSK Każda linia pliku jest w następującym formacie:

```
    TOŻSAMOŚĆ:KLUCZ

```

Szesnastkowe klucze są automatycznie konwertowane do postaci binarnej. Klucz musi być mieć przynajmniej 16 bajtów, co w przypadku kluczy szesnastkowych przekłada się na przynajmniej 32 znaki. Należy ograniczyć dostęp do czytania lub pisania do tego pliku.

pty = yes | no (tylko Unix)

alokuj pseudo-terminal dla programu uruchamianego w opcji 'exec'

redirect = [HOST:]PORT

przekieruj klienta, któremu nie udało się poprawnie uwierzytelnić przy pomocy certyfikatu Opcja działa wyłącznie w trybie serwera. Część negocjacji protokołów jest niekompatybilna z opcją redirect.

renegotiation = yes | no

pozwalaj na renegocjację TLS Zastosowania renegocjacji TLS zawierają niektóre scenariusze uwierzytelniania oraz renegocjację kluczy dla długotrwałych połączeń.

Z drugiej strony własność na może ułatwić trywialny atak DoS poprzez wygenerowanie obciążenia procesora:

http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html

Warto zauważyć, że zablokowanie renegocjacji TLS nie zabezpiecza w pełni przed opisanym problemem.

domyślnie: yes (o ile wspierane przez OpenSSL)

reset = yes | no

sygnalizuj wystąpienie błędu przy pomocy flagi TCP RST Opcja nie jest wspierana na niektórych platformach.

domyślnie: yes

retry = yes | no | OPÓŹNIENIE

połącz ponownie sekcję connect+exec po rozłączeniu Wartość parametru OPÓŹNIENIE określa liczbę milisekund oczekiwania przed wykonaniem ponownego połączenia. "retry = yes" jest synonimem dla "retry = 1000".

domyślnie: no

securityLevel = POZIOM

ustaw poziom bezpieczeństwa Znaczenie każdego poziomu opisano poniżej:

poziom 0

Wszystko jest dozwolone.

poziom 1

Poziom bezpieczeństwa zapewniający minimum 80 bitów bezpieczeństwa. Żadne parametry kryptograficzne oferujące poziom bezpieczeństwa poniżej 80 bitów nie mogą zostać użyte. W związku z tym RSA, DSA oraz klucze DH krótsze niż 1024 bity, a także klucze ECC krótsze niż 160 bitów i wszystkie eksportowe zestawy szyfrów są niedozwolone. Użycie SSLv2 jest zabronione. Wszelkie listy parametrów kryptograficznych używające MD5 do MAC są zabronione.

poziom 2

Poziom bezpieczeństwa zapewniający 112 bitów bezpieczeństwa. W związku z tym RSA, DSA oraz klucze DH krótsze niż 2048 bitów, a także klucze ECC krótsze niż 224 bity są niedozwolone. Oprócz wyłączeń z poziomu 1 zabronione jest także korzystanie z zestawów szyfrów używających RC4. Użycie SSLv3 jest zabronione. Kompresja jest wyłączona.

poziom 3

Poziom bezpieczeństwa zapewniający 128 bitów bezpieczeństwa. W związku z tym RSA, DSA oraz klucze DH krótsze niż 3072 bity, a także klucze ECC krótsze niż 256 bitów są niedozwolone. Oprócz wyłączeń z poziomu 2 zabronione jest także korzystanie z zestawów szyfrów nie zapewniających utajniania z wyprzedzeniem (forward secrecy). Wersje TLS starsze niż 1.1 są zabronione. Bilety sesji są wyłączone.

poziom 4

Poziom bezpieczeństwa zapewniający 192 bity bezpieczeństwa. W związku z tym RSA, DSA oraz klucze DH krótsze niż 7680 bitów, a także klucze ECC krótsze niż 384 bity są niedozwolone. Listy parametrów kryptograficznych używających SHA1 do MAC są zabronione. Wersje TLS starsze niż 1.2 są zabronione.

poziom 5

Poziom bezpieczeństwa zapewniający 256 bitów bezpieczeństwa. W związku z tym RSA, DSA oraz klucze DH krótsze niż 15360 bitów, a także klucze ECC krótsze niż 512 bitów są niedozwolone.

domyślnie: 2

Opcja securityLevel jest dostępna począwszy od OpenSSL 1.1.0.

requireCert = yes | no

wymagaj certyfikatu klienta dla verifyChain lub verifyPeer Przy opcji requireCert ustawionej na no, stunnel akceptuje połączenia klientów, które nie wysłały certyfikatu.

Zarówno verifyChain = yes jak i verifyPeer = yes automatycznie ustawiają requireCert na yes.

domyślnie: no

setgid = IDENTYFIKATOR_GRUPY (tylko Unix)

identyfikator grupy Unix Jako opcja globalna: grupa, z której prawami pracował będzie stunnel.

Jako opcja usługi: grupa gniazda Unix utworzonego przy pomocy opcji "accept".

setuid = IDENTYFIKATOR_UŻYTKOWNIKA (tylko Unix)

identyfikator użytkownika Unix Jako opcja globalna: użytkownik, z którego prawami pracował będzie stunnel.

Jako opcja usługi: właściciel gniazda Unix utworzonego przy pomocy opcji "accept".

sessionCacheSize = LICZBA_POZYCJI_CACHE

rozmiar pamięci podręcznej sesji TLS Parametr określa maksymalną liczbę pozycji wewnętrznej pamięci podręcznej sesji.

Wartość 0 oznacza brak ograniczenia rozmiaru. Nie jest to zalecane dla systemów produkcyjnych z uwagi na ryzyko ataku DoS przez wyczerpanie pamięci RAM.

sessionCacheTimeout = LICZBA_SEKUND

przeterminowanie pamięci podręcznej sesji TLS Parametr określa czas w sekundach, po którym sesja TLS zostanie usunięta z pamięci podręcznej.

sessionResume = yes | no

zezwalaj lub nie zezwalaj na wznawianie sesji domyślnie: yes

sessiond = HOST:PORT

adres sessiond - serwera cache sesji TLS

sni = NAZWA_USŁUGI:WZORZEC_NAZWY_SERWERA (tryb serwera)

Użyj usługi jako podrzędnej (virtualnego serwera) dla rozszerzenia TLS Server Name Indication (RFC 3546). NAZWA_USŁUGI wskazuje usługę nadrzędną, która odbiera połączenia od klientów przy pomocy opcji accept. WZORZEC_NAZWY_SERWERA wskazuje nazwę serwera wirtualnego. Wzorzec może zaczynać się znakiem '*', np. '*.example.com". Z pojedynczą usługą nadrzędną powiązane jest zwykle wiele usług podrzędnych. Opcja sni może być również użyta wielokrotnie w ramach jednej usługi podrzędnej.

Zarówno usługa nadrzędna jak i podrzędna nie może być skonfigurowana w trybie klienckim.

Opcja connect usługi podrzędnej jest ignorowana w połączeniu z opcją protocol, gdyż połączenie do zdalnego serwera jest w tym wypadku nawiązywane przed negocjacją TLS.

Uwierzytelnienie przy pomocy biblioteki libwrap jest realizowane dwukrotnie: najpierw dla usługi nadrzędnej po odebraniu połączenia TCP, a następnie dla usługi podrzędnej podczas negocjacji TLS.

Opcja sni jest dostępna począwszy od OpenSSL 1.0.0.

sni = NAZWA_SERWERA (tryb klienta)

Użyj parametru jako wartości rozszerzenia TLS Server Name Indication (RFC 3546). Pusta wartość parametru NAZWA_SERWERA wyłącza wysyłanie rozszerzenia SNI.

Opcja sni jest dostępna począwszy od OpenSSL 1.0.0.

socket = a|l|r:OPCJA=WARTOŚĆ[:WARTOŚĆ]

ustaw opcję na akceptującym/lokalnym/zdalnym gnieździe Dla opcji linger wartości mają postać l_onof:l_linger. Dla opcji time wartości mają postać tv_sec:tv_usec.

Przykłady:

```
    socket = l:SO_LINGER=1:60
        ustaw jednominutowe przeterminowanie
        przy zamykaniu lokalnego gniazda
    socket = r:SO_OOBINLINE=yes
        umieść dane pozapasmowe (out-of-band)
        bezpośrednio w strumieniu danych
        wejściowych dla zdalnych gniazd
    socket = a:SO_REUSEADDR=no
        zablokuj ponowne używanie portu
        (domyślnie włączone)
    socket = a:SO_BINDTODEVICE=lo
        przyjmuj połączenia wyłącznie na
        interfejsie zwrotnym (ang. loopback)

```

sslVersion = WERSJA_SSL

wersja protokołu TLS Wspierane wersje: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

Dostępność konkretnych protokołów zależy od użytej wersji OpenSSL. Starsze wersje OpenSSL nie wspierają TLSv1.1, TLSv1.2, TLSv1.3. Nowsze wersje OpenSSL nie wspierają SSLv2.

Przestarzałe protokoły SSLv2 i SSLv3 są domyślnie wyłączone.

Począwszy od OpenSSL 1.1.0, ustawienie

```
    sslVersion = WERSJA_SSL

```

jest równoważne opcjom

```
    sslVersionMax = WERSJA_SSL
    sslVersionMin = WERSJA_SSL

```

sslVersionMax = WERSJA_SSL

maksymalna wspierana wersja protokołu TLS Wspierane wersje: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

all włącza wszystkie wersje protokołów aż do maksymalnej wersji wspieranej przez bibliotekę użytej wersji OpenSSL.

Dostępność konkretnych protokołów zależy od użytej wersji OpenSSL.

Opcja sslVersionMax jest dostępna począwszy od OpenSSL 1.1.0.

domyślnie: all

sslVersionMin = WERSJA_SSL

minimalna wspierana wersja protokołu TLS Wspierane wersje: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

all włącza wszystkie wersje protokołów aż do minimalnej wersji wspieranej przez bibliotekę użytej wersji OpenSSL.

Dostępność konkretnych protokołów zależy od użytej wersji OpenSSL.

Opcja sslVersionMin jest dostępna począwszy od OpenSSL 1.1.0.

domyślnie: TLSv1

stack = LICZBA_BAJTÓW (z wyjątkiem modelu FORK)

rozmiar stosu procesora tworzonych wątków Zbyt duży stos zwiększa zużycie pamięci wirtualnej. Zbyt mały stos może powodować problemy ze stabilnością aplikacji.

domyślnie: 65536 bytes (wystarczający dla testowanych platform)

ticketKeySecret = SECRET

szesnastkowy klucz symetryczny używany przez serwer do zapewnienia poufności biletów sesji Bilety sesji zdefiniowane w RFC 5077 zapewniają ulepszoną możliwość wznawiania sesji, w której implementacja serwera nie jest wymagana do utrzymania stanu sesji.

Łączne użycie opcji ticketKeySecret i ticketMacSecret umożliwia wznawianie sesji na klastrze serwerów lub wznowienie sesji po restarcie serwera.

Klucz musi mieć rozmiar 16 lub 32 bajtów, co przekłada się na dokładnie 32 lub 64 cyfry szesnastkowe. Poszczególne bajty mogą być opcjonalnie oddzielone dwukropkami.

Opcja działa wyłącznie w trybie serwera.

Opcja ticketKeySecret jest dostępna począwszy od OpenSSL 1.0.0.

Wyłączenie opcji NO_TICKET jest wymagane dla obsługi biletów sesji w OpenSSL-u starszym niż 1.1.1, ale opcja ta jest niekompatybilna z opcją redirect.

ticketMacSecret = SECRET

szesnastkowy klucz symetryczny używany przez serwer zapewnienia integralności biletów sesji Klucz musi mieć rozmiar 16 lub 32 bajtów, co przekłada się na dokładnie 32 lub 64 cyfry szesnastkowe. Poszczególne bajty mogą być opcjonalnie oddzielone dwukropkami.

Opcja działa wyłącznie w trybie serwera.

Opcja ticketMacSecret jest dostępna począwszy od OpenSSL 1.0.0.

TIMEOUTbusy = LICZBA_SEKUND

czas oczekiwania na spodziewane dane

TIMEOUTclose = LICZBA_SEKUND

czas oczekiwania na close_notify (ustaw na 0, jeżeli klientem jest MSIE)

TIMEOUTconnect = LICZBA_SEKUND

czas oczekiwania na nawiązanie połączenia

TIMEOUTidle = LICZBA_SEKUND

maksymalny czas utrzymywania bezczynnego połączenia

TIMEOUTocsp = LICZBA_SEKUND

czas oczekiwania na nawiązanie połączenia z serwerem OCSP

transparent = none | source | destination | both (tylko Unix)

tryb przezroczystego proxy na wspieranych platformach Wspierane wartości:

none

Zablokuj wsparcie dla przezroczystego proxy. Jest to wartość domyślna.

source

Przepisz adres, aby nawiązywane połączenie wydawało się pochodzić bezpośrednio od klienta, a nie od programu stunnel. Opcja jest aktualnie obsługiwana w:

Trybie zdalnym (opcja connect) w systemie Linux >=2.6.28

Konfiguracja wymaga następujących ustawień iptables oraz routingu (na przykład w pliku /etc/rc.local lub analogicznym):

```
    iptables -t mangle -N DIVERT
    iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
    iptables -t mangle -A DIVERT -j MARK --set-mark 1
    iptables -t mangle -A DIVERT -j ACCEPT
    ip rule add fwmark 1 lookup 100
    ip route add local 0.0.0.0/0 dev lo table 100
    echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter

```

Konfiguracja ta wymaga, aby stunnel był wykonywany jako root i bez opcji setuid.

Trybie zdalnym (opcja connect) w systemie Linux 2.2.x

Konfiguracja ta wymaga skompilowania jądra z opcją transparent proxy. Docelowa usługa musi być umieszczona na osobnej maszynie, do której routing kierowany jest poprzez serwer stunnela. Dodatkowo stunnel powinien być wykonywany jako root i bez opcji setuid.

Trybie zdalnym (opcja connect) w systemie FreeBSD >=8.0

Konfiguracja ta wymaga skonfigurowania firewalla i routingu. stunnel musi być wykonywany jako root i bez opcji setuid.

Trybie lokalnym (opcja exec)

Konfiguracja ta jest realizowana przy pomocy biblioteki libstunnel.so. Do załadowania biblioteki wykorzystywana jest zmienna środowiskowa _RLD_LIST na platformie Tru64 lub LD_PRELOAD na innych platformach.

destination

Oryginalny adres docelowy jest używany zamiast opcji connect. Przykładowa konfiguracja przezroczystego adresu docelowego:

```
    [transparent]
    client = yes
    accept = <port_stunnela>
    transparent = destination

```

Konfiguracja wymaga ustawień iptables, na przykład w pliku /etc/rc.local lub analogicznym.

W przypadku docelowej usługi umieszczonej na tej samej maszynie:

```
    /sbin/iptables -t nat -I OUTPUT -p tcp --dport <port_przekierowany> \
        -m ! --uid-owner <identyfikator_użytkownika_stunnela> \
        -j DNAT --to-destination <lokalne_ip>:<lokalny_port>

```

W przypadku docelowej usługi umieszczonej na zdalnej maszynie:

```
    /sbin/iptables -I INPUT -i eth0 -p tcp --dport <port_stunnela> -j ACCEPT
    /sbin/iptables -t nat -I PREROUTING -p tcp --dport <port_przekierowany> \
        -i eth0 -j DNAT --to-destination <lokalne_ip>:<port_stunnela>

```

Przezroczysty adres docelowy jest aktualnie wspierany wyłącznie w systemie Linux.

both

Użyj przezroczystego proxy zarówno dla adresu źródłowego jak i docelowego.

Dla zapewnienia kompatybilności z wcześniejszymi wersjami wspierane są dwie dodatkowe opcje:

yes

Opcja została przemianowana na source.

no

Opcja została przemianowana na none.

verify = POZIOM

weryfikuj certyfikat drugiej strony połączenia Opcja ta jest przestarzała i należy ją zastąpić przez opcje verifyChain i verifyPeer.

poziom 0

zarządaj certyfikatu i zignoruj go

poziom 1

weryfikuj, jeżeli został przedstawiony

poziom 2

weryfikuj z zainstalowanym certyfikatem Centrum Certyfikacji

poziom 3

weryfikuj z lokalnie zainstalowanym certyfikatem drugiej strony

poziom 4

weryfikuj z certyfikatem drugiej strony ignorując łańcuch CA

domyślnie

nie weryfikuj

verifyChain = yes | no

weryfikuj łańcuch certyfikatów drugiej strony Do weryfikacji certyfikatu serwera kluczowe jest, aby wymagać również konkretnego certyfikatu przy pomocy checkHost lub checkIP.

Samopodpisany certyfikat głównego CA należy umieścić albo w pliku podanym w opcji CAfile, albo w katalogu podanym w opcji CApath.

domyślnie: no

verifyPeer = yes | no

weryfikuj certyfikat drugiej strony Certyfikat drugiej strony należy umieścić albo w pliku podanym w opcji CAfile, albo w katalogu podanym w opcji CApath.

domyślnie: no

## ZWRACANA WARTOŚĆ
stunnel zwraca zero w przypadku sukcesu, lub wartość niezerową w przypadku błędu.

## SIGNAŁY
Następujące sygnały mogą być użyte do sterowania programem w systemie Unix:

SIGHUP

Załaduj ponownie plik konfiguracyjny. Niektóre globalne opcje nie będą przeładowane:

- chroot

- foreground

- pid

- setgid

- setuid

Jeżeli wykorzystywana jest opcja 'setuid' stunnel nie będzie mógł załadować ponownie konfiguracji wykorzystującej uprzywilejowane (<1024) porty.

Jeżeli wykorzystywana jest opcja 'chroot' stunnel będzie szukał wszystkich potrzebnych plików (łącznie z plikiem konfiguracyjnym, certyfikatami, logiem i plikiem pid) wewnątrz katalogu wskazanego przez 'chroot'.

SIGUSR1

Zamknij i otwórz ponownie log. Funkcja ta może zostać użyta w skrypcie rotującym log programu stunnel.

SIGUSR2

Zapisz w logu listę aktywnych połączeń.

SIGTERM, SIGQUIT, SIGINT

Zakończ działanie programu.

Skutek wysłania innych sygnałów jest niezdefiniowany.

## PRZYKŁADY
Szyfrowanie połączeń do lokalnego serwera imapd można użyć:

```
    [imapd]
    accept = 993
    exec = /usr/sbin/imapd
    execArgs = imapd
```

albo w trybie zdalnym:

```
    [imapd]
    accept = 993
    connect = 143
```

Aby umożliwić lokalnemu klientowi poczty elektronicznej korzystanie z serwera imapd przez TLS należy skonfigurować pobieranie poczty z adresu localhost i portu 119, oraz użyć następującej konfiguracji:

```
    [imap]
    client = yes
    accept = 143
    connect = serwer:993
```

W połączeniu z programem pppd stunnel pozwala zestawić prosty VPN. Po stronie serwera nasłuchującego na porcie 2020 jego konfiguracja może wyglądać następująco:

```
    [vpn]
    accept = 2020
    exec = /usr/sbin/pppd
    execArgs = pppd local
    pty = yes
```

Poniższy plik konfiguracyjny może być wykorzystany do uruchomienia programu stunnel w trybie inetd. Warto zauważyć, że w pliku konfiguracyjnym nie ma sekcji [nazwa_usługi].

```
    exec = /usr/sbin/imapd
    execArgs = imapd
```

Aby skonfigurować VPN można użyć następującej konfiguracji klienta:

```
    [socks_client]
    client = yes
    accept = 127.0.0.1:1080
    connect = vpn_server:9080
    verifyPeer = yes
    CAfile = stunnel.pem
```

Odpowiadająca jej konfiguracja serwera vpn_server:

```
    [socks_server]
    protocol = socks
    accept = 9080
    cert = stunnel.pem
    key = stunnel.key
```

Do przetestowania konfiguracji można wydać na maszynie klienckiej komendę:

```
    curl --socks4a localhost http://www.example.com/
```

Przykładowa konfiguracja serwera SNI:

```
    [virtual]
    ; usługa nadrzędna
    accept = 443
    cert =  default.pem
    connect = default.internal.mydomain.com:8080
    [sni1]
    ; usługa podrzędna 1
    sni = virtual:server1.mydomain.com
    cert = server1.pem
    connect = server1.internal.mydomain.com:8081
    [sni2]
    ; usługa podrzędna 2
    sni = virtual:server2.mydomain.com
    cert = server2.pem
    connect = server2.internal.mydomain.com:8082
    verifyPeer = yes
    CAfile = server2-allowed-clients.pem
```

Przykładowa konfiguracja umożliwiająca uwierzytelnienie z użyciem klucza prywatnego przechowywanego w Windows Certificate Store (tylko Windows):

```
    engine = capi
    [service]
    engineId = capi
    client = yes
    accept = 127.0.0.1:8080
    connect = example.com:8443
```

W przypadku użycia silnika CAPI, nie należy ustawiać opcji cert, gdyż klucz klienta zostanie automatycznie pobrany z Certificate Store na podstawie zaufanych certyfikatów CA przedstawionych przez serwer.

Przykładowa konfiguracja umożliwiająca użycie certyfikatu i klucza prywatnego z urządzenia obsługiwanego przez silnik pkcs11:

```
    engine = pkcs11
    engineCtrl = MODULE_PATH:opensc-pkcs11.so
    engineCtrl = PIN:123456
    [service]
    engineId = pkcs11
    client = yes
    accept = 127.0.0.1:8080
    connect = example.com:843
    cert = pkcs11:token=MyToken;object=MyCert
    key = pkcs11:token=MyToken;object=MyKey
```

Przykładowa konfiguracja umożliwiająca użycie certyfikatu i klucza prywatnego umieszczonego na tokenie SoftHSM:

```
    engine = pkcs11
    engineCtrl = MODULE_PATH:softhsm2.dll
    engineCtrl = PIN:12345
    [service]
    engineId = pkcs11
    client = yes
    accept = 127.0.0.1:8080
    connect = example.com:843
    cert = pkcs11:token=MyToken;object=KeyCert
```

## NOTKI

### OGRANICZENIA
stunnel nie może być używany do szyfrowania protokołu FTP, ponieważ do przesyłania poszczególnych plików używa on dodatkowych połączeń otwieranych na portach o dynamicznie przydzielanych numerach. Istnieją jednak specjalne wersje klientów i serwerów FTP pozwalające na szyfrowanie przesyłanych danych przy pomocy protokołu TLS.

### TRYB INETD (tylko Unix)
W większości zastosowań stunnel samodzielnie nasłuchuje na porcie podanym w pliku konfiguracyjnym i tworzy połączenie z innym portem podanym w opcji connect lub nowym programem podanym w opcji exec. Niektórzy wolą jednak wykorzystywać oddzielny program, który odbiera połączenia, po czym uruchamia program stunnel. Przykładami takich programów są inetd, xinetd i tcpserver.

Przykładowa linia pliku /etc/inetd.conf może wyglądać tak:

```
    imaps stream tcp nowait root /usr/bin/stunnel
        stunnel /etc/stunnel/imaps.conf
```

Ponieważ w takich przypadkach połączenie na zdefiniowanym porcie (tutaj imaps) nawiązuje osobny program (tutaj inetd), stunnel nie może używać opcji accept. W pliku konfiguracyjnym nie może być również zdefiniowana żadna usługa ([nazwa_usługi]), ponieważ konfiguracja taka pozwala na nawiązanie tylko jednego połączenia. Wszystkie OPCJE USŁUG powinny być umieszczone razem z opcjami globalnymi. Przykład takiej konfiguracji znajduje się w sekcji PRZYKŁADY.

### CERTYFIKATY
Protokół TLS wymaga, aby każdy serwer przedstawiał się nawiązującemu połączenie klientowi prawidłowym certyfikatem X.509. Potwierdzenie tożsamości serwera polega na wykazaniu, że posiada on odpowiadający certyfikatowi klucz prywatny. Najprostszą metodą uzyskania certyfikatu jest wygenerowanie go przy pomocy wolnego pakietu OpenSSL. Więcej informacji na temat generowania certyfikatów można znaleźć na umieszczonych poniżej stronach.

Plik .pem powinien zawierać klucz prywatny oraz podpisany certyfikat (nie żądanie certyfikatu). Otrzymany plik powinien mieć następującą postać:

```
    -----BEGIN RSA PRIVATE KEY-----
    [zakodowany klucz]
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    [zakodowany certyfikat]
    -----END CERTIFICATE-----
```

### LOSOWOŚĆ
stunnel potrzebuje zainicjować PRNG (generator liczb pseudolosowych), gdyż protokół TLS wymaga do bezpieczeństwa kryptograficznego źródła dobrej losowości. Następujące źródła są kolejno odczytywane aż do uzyskania wystarczającej ilości entropii:

- Zawartość pliku podanego w opcji RNDfile.

- Zawartość pliku o nazwie określonej przez zmienną środowiskową RANDFILE, o ile jest ona ustawiona.

- Plik .rnd umieszczony w katalogu domowym użytkownika, jeżeli zmienna RANDFILE nie jest ustawiona.

- Plik podany w opcji '--with-random' w czasie konfiguracji programu.

- Zawartość ekranu w systemie Windows.

- Gniazdo egd, jeżeli użyta została opcja EGD.

- Gniazdo egd podane w opcji '--with-egd-socket' w czasie konfiguracji programu.

- Urządzenie /dev/urandom.

Warto zwrócić uwagę, że na maszynach z systemem Windows, na których konsoli nie pracuje użytkownik, zawartość ekranu nie jest wystarczająco zmienna, aby zainicjować PRNG. W takim przypadku do zainicjowania generatora należy użyć opcji RNDfile.

Plik RNDfile powinien zawierać dane losowe -- również w tym sensie, że powinny być one inne przy każdym uruchomieniu programu stunnel. O ile nie użyta została opcja RNDoverwrite jest to robione automatycznie. Do ręcznego uzyskania takiego pliku użyteczna może być komenda openssl rand dostarczana ze współczesnymi wersjami pakietu OpenSSL.

Jeszcze jedna istotna informacja -- jeżeli dostępne jest urządzenie /dev/urandom biblioteka OpenSSL ma zwyczaj zasilania nim PRNG w trakcie sprawdzania stanu generatora. W systemach z /dev/urandom urządzenie to będzie najprawdopodobniej użyte, pomimo że znajduje się na samym końcu powyższej listy. Jest to właściwość biblioteki OpenSSL, a nie programu stunnel.

### PARAMETRY DH
Począwszy od wersji 4.40 stunnel zawiera w kodzie programu 2048-bitowe parametry DH. Od wersji 5.18 te początkowe wartości parametrów DH są wymieniane na automatycznie generowane parametry tymczasowe. Wygenerowanie parametrów DH może zająć nawet wiele minut.

Alternatywnie parametry DH można umieścić w pliku razem z certyfikatem, co wyłącza generowanie parametrów tymczasowych:

```
    openssl dhparam 2048 >> stunnel.pem
```

## PLIKI
/etc/stunnel/stunnel.conf

plik konfiguracyjny programu

## BŁĘDY
Opcja execArgs oraz linia komend Win32 nie obsługuje cytowania.

## ZOBACZ RÓWNIEŻ
tcpd(8)

biblioteka kontroli dostępu do usług internetowych

inetd(8)

'super-serwer' internetowy

http://www.stunnel.org/

strona domowa programu stunnel

http://www.openssl.org/

strona projektu OpenSSL

## AUTOR
Michał Trojnara

<Michal.Trojnara@stunnel.org>


svnserve

package: subversion-server-common

title: svnserve(8)

text:
# svnserve(8)

## NAME
svnserve - Server for the 'svn' repository access method

## SYNOPSIS
svnserve [options]

## DESCRIPTION
svnserve allows access to Subversion repositories using the svn network protocol. It can both run as a standalone server process, or it can run out of inetd. You must choose a mode of operation when you start svnserve. The following options are recognized:

-d, --daemon

Causes svnserve to run in daemon mode. svnserve backgrounds itself and accepts and serves TCP/IP connections on the svn port (3690, by default).

--listen-port=port

Causes svnserve to listen on port when run in daemon mode.

--listen-host=host

Causes svnserve to listen on the interface specified by host, which may be either a hostname or an IP address.

--foreground

When used together with -d, this option causes svnserve to stay in the foreground. This option is mainly useful for debugging.

-i, --inetd

Causes svnserve to use the stdin/stdout file descriptors, as is appropriate for a daemon running out of inetd.

-h, --help

Displays a usage summary and exits.

--version

Print svnserve's version and the repository filesystem back-end(s) a particular svnserve supports.

-r root, --root=root

Sets the virtual root for repositories served by svnserve. The pathname in URLs provided by the client will be interpreted relative to this root, and will not be allowed to escape this root.

-R --read-only

Force all write operations through this svnserve instance to be forbidden, overriding all other access policy configuration. Do not use this option to set general repository access policy - that is what the conf/svnserve.conf repository configuration file is for. This option should be used only to restrict access via a certain method of invoking svnserve - for example, to allow write access via SSH, but not via a svnserve daemon, or to create a restricted SSH key which is only capable of read access.

-t, --tunnel

Causes svnserve to run in tunnel mode, which is just like the inetd mode of operation (serve one connection over stdin/stdout) except that the connection is considered to be pre-authenticated with the username of the current uid. This flag is selected by the client when running over a tunnel agent.

--tunnel-user=username

When combined with --tunnel, overrides the pre-authenticated username with the supplied username. This is useful in combination with the ssh authorized_key file's "command" directive to allow a single system account to be used by multiple committers, each having a distinct ssh identity.

-T, --threads

When running in daemon mode, causes svnserve to spawn a thread instead of a process for each connection. The svnserve process still backgrounds itself at startup time.

--config-file=filename

When specified, svnserve reads filename once at program startup and caches the svnserve configuration. The password and authorization configurations referenced from filename will be loaded on each connection. svnserve will not read any per-repository conf/svnserve.conf files when this option is used. See the svnserve.conf(5) man page for details of the file format for this option.

--pid-file=filename

When specified, svnserve will write its process ID to filename.

-X, --listen-once

Causes svnserve to accept one connection on the svn port, serve it, and exit. This option is mainly useful for debugging.

Unless the --config-file option was specified on the command line, once the client has selected a repository by transmitting its URL, svnserve reads a file named conf/svnserve.conf in the repository directory to determine repository-specific settings such as what authentication database to use and what authorization policies to apply. See the svnserve.conf(5) man page for details of that file format.

## SEE ALSO
svnserve.conf(5)


sudo

package: sudo

title: sudo(8)

summary: execute a command as another user

text:
# sudo(8)

## NAME
sudo, sudoedit — execute a command as another user

## SYNOPSIS
sudo

-h | -K | -k | -V

sudo

-v [-ABkNnS] [-g group] [-h host] [-p prompt] [-u user]

sudo

-l [-ABkNnS] [-g group] [-h host] [-p prompt] [-U user] [-u user] [command [arg ...]]

sudo

[-ABbEHnPS] [-C num] [-D directory] [-g group] [-h host] [-p prompt] [-R directory] [-r role] [-t type] [-T timeout] [-u user] [VAR=value] [-i | -s] [command [arg ...]]

sudoedit

[-ABkNnS] [-C num] [-D directory] [-g group] [-h host] [-p prompt] [-R directory] [-r role] [-t type] [-T timeout] [-u user] file ...

## DESCRIPTION
sudo allows a permitted user to execute a command as the superuser or another user, as specified by the security policy. The invoking user's real (not effective) user-ID is used to determine the user name with which to query the security policy.

sudo supports a plugin architecture for security policies, auditing, and input/output logging. Third parties can develop and distribute their own plugins to work seamlessly with the sudo front-end. The default security policy is sudoers, which is configured via the file /etc/sudoers, or via LDAP. See the Plugins section for more information.

The security policy determines what privileges, if any, a user has to run sudo. The policy may require that users authenticate themselves with a password or another authentication mechanism. If authentication is required, sudo will exit if the user's password is not entered within a configurable time limit. This limit is policy-specific; the default password prompt timeout for the sudoers security policy is 5 minutes.

Security policies may support credential caching to allow the user to run sudo again for a period of time without requiring authentication. By default, the sudoers policy caches credentials on a per-terminal basis for 5 minutes. See the timestamp_type and timestamp_timeout options in sudoers(5) for more information. By running sudo with the -v option, a user can update the cached credentials without running a command.

On systems where sudo is the primary method of gaining superuser privileges, it is imperative to avoid syntax errors in the security policy configuration files. For the default security policy, sudoers(5), changes to the configuration files should be made using the visudo(8) utility which will ensure that no syntax errors are introduced.

When invoked as sudoedit, the -e option (described below), is implied.

Security policies and audit plugins may log successful and failed attempts to run sudo. If an I/O plugin is configured, the running command's input and output may be logged as well.

The options are as follows:

-A, --askpass

Normally, if sudo requires a password, it will read it from the user's terminal. If the -A (askpass) option is specified, a (possibly graphical) helper program is executed to read the user's password and output the password to the standard output. If the SUDO_ASKPASS environment variable is set, it specifies the path to the helper program. Otherwise, if sudo.conf(5) contains a line specifying the askpass program, that value will be used. For example:

```
# Path to askpass helper program
Path askpass /usr/X11R6/bin/ssh-askpass
```

If no askpass program is available, sudo will exit with an error.

-B, --bell

Ring the bell as part of the password prompt when a terminal is present. This option has no effect if an askpass program is used.

-b, --background

Run the given command in the background. It is not possible to use shell job control to manipulate background processes started by sudo. Most interactive commands will fail to work properly in background mode.

-C num, --close-from=num

Close all file descriptors greater than or equal to num before executing a command. Values less than three are not permitted. By default, sudo will close all open file descriptors other than standard input, standard output, and standard error when executing a command. The security policy may restrict the user's ability to use this option. The sudoers policy only permits use of the -C option when the administrator has enabled the closefrom_override option.

-D directory, --chdir=directory

Run the command in the specified directory instead of the current working directory. The security policy may return an error if the user does not have permission to specify the working directory.

-E, --preserve-env

Indicates to the security policy that the user wishes to preserve their existing environment variables. The security policy may return an error if the user does not have permission to preserve the environment.

--preserve-env=list

Indicates to the security policy that the user wishes to add the comma-separated list of environment variables to those preserved from the user's environment. The security policy may return an error if the user does not have permission to preserve the environment. This option may be specified multiple times.

-e, --edit

Edit one or more files instead of running a command. In lieu of a path name, the string "sudoedit" is used when consulting the security policy. If the user is authorized by the policy, the following steps are taken:

- Temporary copies are made of the files to be edited with the owner set to the invoking user.

- The editor specified by the policy is run to edit the temporary files. The sudoers policy uses the SUDO_EDITOR, VISUAL and EDITOR environment variables (in that order). If none of SUDO_EDITOR, VISUAL or EDITOR are set, the first program listed in the editor sudoers(5) option is used.

- If they have been modified, the temporary files are copied back to their original location and the temporary versions are removed.

To help prevent the editing of unauthorized files, the following restrictions are enforced unless explicitly allowed by the security policy:

- Symbolic links may not be edited (version 1.8.15 and higher).

- Symbolic links along the path to be edited are not followed when the parent directory is writable by the invoking user unless that user is root (version 1.8.16 and higher).

- Files located in a directory that is writable by the invoking user may not be edited unless that user is root (version 1.8.16 and higher).

Users are never allowed to edit device special files.

If the specified file does not exist, it will be created. Unlike most commands run by sudo, the editor is run with the invoking user's environment unmodified. If the temporary file becomes empty after editing, the user will be prompted before it is installed. If, for some reason, sudo is unable to update a file with its edited version, the user will receive a warning and the edited copy will remain in a temporary file.

-g group, --group=group

Run the command with the primary group set to group instead of the primary group specified by the target user's password database entry. The group may be either a group name or a numeric group-ID (GID) prefixed with the ‘#’ character (e.g., ‘#0’ for GID 0). When running a command as a GID, many shells require that the ‘#’ be escaped with a backslash (‘\’). If no -u option is specified, the command will be run as the invoking user. In either case, the primary group will be set to group. The sudoers policy permits any of the target user's groups to be specified via the -g option as long as the -P option is not in use.

-H, --set-home

Request that the security policy set the HOME environment variable to the home directory specified by the target user's password database entry. Depending on the policy, this may be the default behavior.

-h, --help

Display a short help message to the standard output and exit.

-h host, --host=host

Run the command on the specified host if the security policy plugin supports remote commands. The sudoers plugin does not currently support running remote commands. This may also be used in conjunction with the -l option to list a user's privileges for the remote host.

-i, --login

Run the shell specified by the target user's password database entry as a login shell. This means that login-specific resource files such as .profile, .bash_profile, or .login will be read by the shell. If a command is specified, it is passed to the shell as a simple command using the -c option. The command and any args are concatenated, separated by spaces, after escaping each character (including white space) with a backslash (‘\’) except for alphanumerics, underscores, hyphens, and dollar signs. If no command is specified, an interactive shell is executed. sudo attempts to change to that user's home directory before running the shell. The command is run with an environment similar to the one a user would receive at log in. Most shells behave differently when a command is specified as compared to an interactive session; consult the shell's manual for details. The Command environment section in the sudoers(5) manual documents how the -i option affects the environment in which a command is run when the sudoers policy is in use.

-K, --remove-timestamp

Similar to the -k option, except that it removes every cached credential for the user, regardless of the terminal or parent process ID. The next time sudo is run, a password must be entered if the security policy requires authentication. It is not possible to use the -K option in conjunction with a command or other option. This option does not require a password. Not all security policies support credential caching.

-k, --reset-timestamp

When used without a command, invalidates the user's cached credentials for the current session. The next time sudo is run in the session, a password must be entered if the security policy requires authentication. By default, the sudoers policy uses a separate record in the credential cache for each terminal (or parent process ID if no terminal is present). This prevents the -k option from interfering with sudo commands run in a different terminal session. See the timestamp_type option in sudoers(5) for more information. This option does not require a password, and was added to allow a user to revoke sudo permissions from a .logout file. When used in conjunction with a command or an option that may require a password, this option will cause sudo to ignore the user's cached credentials. As a result, sudo will prompt for a password (if one is required by the security policy) and will not update the user's cached credentials.

Not all security policies support credential caching.

-l, --list

If no command is specified, list the privileges for the invoking user (or the user specified by the -U option) on the current host. A longer list format is used if this option is specified multiple times and the security policy supports a verbose output format. If a command is specified and is permitted by the security policy for the invoking user (or the, user specified by the -U option) on the current host, the fully-qualified path to the command is displayed along with any args. If -l is specified more than once (and the security policy supports it), the matching rule is displayed in a verbose format along with the command. If a command is specified but not allowed by the policy, sudo will exit with a status value of 1.

-N, --no-update

Do not update the user's cached credentials, even if the user successfully authenticates. Unlike the -k flag, existing cached credentials are used if they are valid. To detect when the user's cached credentials are valid (or when no authentication is required), the following can be used:

```
sudo -Nnv
```

Not all security policies support credential caching.

-n, --non-interactive

Avoid prompting the user for input of any kind. If a password is required for the command to run, sudo will display an error message and exit.

-P, --preserve-groups

Preserve the invoking user's group vector unaltered. By default, the sudoers policy will initialize the group vector to the list of groups the target user is a member of. The real and effective group-IDs, however, are still set to match the target user.

-p prompt, --prompt=prompt

Use a custom password prompt with optional escape sequences. The following percent (‘%’) escape sequences are supported by the sudoers policy: %H

expanded to the host name including the domain name (only if the machine's host name is fully qualified or the fqdn option is set in sudoers(5))

%h

expanded to the local host name without the domain name

%p

expanded to the name of the user whose password is being requested (respects the rootpw, targetpw, and runaspw flags in sudoers(5))

%U

expanded to the login name of the user the command will be run as (defaults to root unless the -u option is also specified)

%u

expanded to the invoking user's login name

%%

two consecutive ‘%’ characters are collapsed into a single ‘%’ character

The custom prompt will override the default prompt specified by either the security policy or the SUDO_PROMPT environment variable. On systems that use PAM, the custom prompt will also override the prompt specified by a PAM module unless the passprompt_override flag is disabled in sudoers.

-R directory, --chroot=directory

Change to the specified root directory (see chroot(8)) before running the command. The security policy may return an error if the user does not have permission to specify the root directory. This option is deprecated and will be removed in a future version of sudo.

-r role, --role=role

Run the command with an SELinux security context that includes the specified role.

-S, --stdin

Write the prompt to the standard error and read the password from the standard input instead of using the terminal device.

-s, --shell

Run the shell specified by the SHELL environment variable if it is set or the shell specified by the invoking user's password database entry. If a command is specified, it is passed to the shell as a simple command using the -c option. The command and any args are concatenated, separated by spaces, after escaping each character (including white space) with a backslash (‘\’) except for alphanumerics, underscores, hyphens, and dollar signs. If no command is specified, an interactive shell is executed. Most shells behave differently when a command is specified as compared to an interactive session; consult the shell's manual for details.

-t type, --type=type

Run the command with an SELinux security context that includes the specified type. If no type is specified, the default type is derived from the role.

-U user, --other-user=user

Used in conjunction with the -l option to list the privileges for user instead of for the invoking user. The security policy may restrict listing other users' privileges. When using the sudoers policy, the -U option is restricted to the root user and users with either the “list” priviege for the specified user or the ability to run any command as root or user on the current host.

-T timeout, --command-timeout=timeout

Used to set a timeout for the command. If the timeout expires before the command has exited, the command will be terminated. The security policy may restrict the user's ability to set timeouts. The sudoers policy requires that user-specified timeouts be explicitly enabled.

-u user, --user=user

Run the command as a user other than the default target user (usually root). The user may be either a user name or a numeric user-ID (UID) prefixed with the ‘#’ character (e.g., ‘#0’ for UID 0). When running commands as a UID, many shells require that the ‘#’ be escaped with a backslash (‘\’). Some security policies may restrict UIDs to those listed in the password database. The sudoers policy allows UIDs that are not in the password database as long as the targetpw option is not set. Other security policies may not support this.

-V, --version

Print the sudo version string as well as the version string of any configured plugins. If the invoking user is already root, the -V option will display the options passed to configure when sudo was built; plugins may display additional information such as default options.

-v, --validate

Update the user's cached credentials, authenticating the user if necessary. For the sudoers plugin, this extends the sudo timeout for another 5 minutes by default, but does not run a command. Not all security policies support cached credentials.

--

The -- is used to delimit the end of the sudo options. Subsequent options are passed to the command.

Options that take a value may only be specified once unless otherwise indicated in the description. This is to help guard against problems caused by poorly written scripts that invoke sudo with user-controlled input.

Environment variables to be set for the command may also be passed as options to sudo in the form VAR=value, for example LD_LIBRARY_PATH=/usr/local/pkg/lib. Environment variables may be subject to restrictions imposed by the security policy plugin. The sudoers policy subjects environment variables passed as options to the same restrictions as existing environment variables with one important difference. If the setenv option is set in sudoers, the command to be run has the SETENV tag set or the command matched is ALL, the user may set variables that would otherwise be forbidden. See sudoers(5) for more information.

## COMMAND EXECUTION
When sudo executes a command, the security policy specifies the execution environment for the command. Typically, the real and effective user and group and IDs are set to match those of the target user, as specified in the password database, and the group vector is initialized based on the group database (unless the -P option was specified).

The following parameters may be specified by security policy:

- real and effective user-ID

- real and effective group-ID

- supplementary group-IDs

- the environment list

- current working directory

- file creation mode mask (umask)

- SELinux role and type

- scheduling priority (aka nice value)

### Process model
There are two distinct ways sudo can run a command.

If an I/O logging plugin is configured to log terminal I/O, or if the security policy explicitly requests it, a new pseudo-terminal (“pty”) is allocated and fork(2) is used to create a second sudo process, referred to as the monitor. The monitor creates a new terminal session with itself as the leader and the pty as its controlling terminal, calls fork(2) again, sets up the execution environment as described above, and then uses the execve(2) system call to run the command in the child process. The monitor exists to relay job control signals between the user's terminal and the pty the command is being run in. This makes it possible to suspend and resume the command normally. Without the monitor, the command would be in what POSIX terms an “orphaned process group” and it would not receive any job control signals from the kernel. When the command exits or is terminated by a signal, the monitor passes the command's exit status to the main sudo process and exits. After receiving the command's exit status, the main sudo process passes the command's exit status to the security policy's close function, as well as the close function of any configured audit plugin, and exits. This mode is the default for sudo versions 1.9.14 and above when using the sudoers policy.

If no pty is used, sudo calls fork(2), sets up the execution environment as described above, and uses the execve(2) system call to run the command in the child process. The main sudo process waits until the command has completed, then passes the command's exit status to the security policy's close function, as well as the close function of any configured audit plugins, and exits. As a special case, if the policy plugin does not define a close function, sudo will execute the command directly instead of calling fork(2) first. The sudoers policy plugin will only define a close function when I/O logging is enabled, a pty is required, an SELinux role is specified, the command has an associated timeout, or the pam_session or pam_setcred options are enabled. Both pam_session and pam_setcred are enabled by default on systems using PAM. This mode is the default for sudo versions prior to 1.9.14 when using the sudoers policy.

On systems that use PAM, the security policy's close function is responsible for closing the PAM session. It may also log the command's exit status.

### Signal handling
When the command is run as a child of the sudo process, sudo will relay signals it receives to the command. The SIGINT and SIGQUIT signals are only relayed when the command is being run in a new pty or when the signal was sent by a user process, not the kernel. This prevents the command from receiving SIGINT twice each time the user enters control-C. Some signals, such as SIGSTOP and SIGKILL, cannot be caught and thus will not be relayed to the command. As a general rule, SIGTSTP should be used instead of SIGSTOP when you wish to suspend a command being run by sudo.

As a special case, sudo will not relay signals that were sent by the command it is running. This prevents the command from accidentally killing itself. On some systems, the reboot(8) utility sends SIGTERM to all non-system processes other than itself before rebooting the system. This prevents sudo from relaying the SIGTERM signal it received back to reboot(8), which might then exit before the system was actually rebooted, leaving it in a half-dead state similar to single user mode. Note, however, that this check only applies to the command run by sudo and not any other processes that the command may create. As a result, running a script that calls reboot(8) or shutdown(8) via sudo may cause the system to end up in this undefined state unless the reboot(8) or shutdown(8) are run using the exec() family of functions instead of system() (which interposes a shell between the command and the calling process).

### Plugins
Plugins may be specified via Plugin directives in the sudo.conf(5) file. They may be loaded as dynamic shared objects (on systems that support them), or compiled directly into the sudo binary. If no sudo.conf(5) file is present, or if it doesn't contain any Plugin lines, sudo will use sudoers(5) for the policy, auditing, and I/O logging plugins. See the sudo.conf(5) manual for details of the /etc/sudo.conf file and the sudo_plugin(5) manual for more information about the sudo plugin architecture.

## EXIT VALUE
Upon successful execution of a command, the exit status from sudo will be the exit status of the program that was executed. If the command terminated due to receipt of a signal, sudo will send itself the same signal that terminated the command.

If the -l option was specified without a command, sudo will exit with a value of 0 if the user is allowed to run sudo and they authenticated successfully (as required by the security policy). If a command is specified with the -l option, the exit value will only be 0 if the command is permitted by the security policy, otherwise it will be 1.

If there is an authentication failure, a configuration/permission problem, or if the given command cannot be executed, sudo exits with a value of 1. In the latter case, the error string is printed to the standard error. If sudo cannot stat(2) one or more entries in the user's PATH, an error is printed to the standard error. (If the directory does not exist or if it is not really a directory, the entry is ignored and no error is printed.) This should not happen under normal circumstances. The most common reason for stat(2) to return “permission denied” is if you are running an automounter and one of the directories in your PATH is on a machine that is currently unreachable.

## SECURITY NOTES
sudo tries to be safe when executing external commands.

To prevent command spoofing, sudo checks "." and "" (both denoting current directory) last when searching for a command in the user's PATH (if one or both are in the PATH). Depending on the security policy, the user's PATH environment variable may be modified, replaced, or passed unchanged to the program that sudo executes.

Users should never be granted sudo privileges to execute files that are writable by the user or that reside in a directory that is writable by the user. If the user can modify or replace the command there is no way to limit what additional commands they can run.

By default, sudo will only log the command it explicitly runs. If a user runs a command such as ‘sudo su’ or ‘sudo sh’, subsequent commands run from that shell are not subject to sudo's security policy. The same is true for commands that offer shell escapes (including most editors). If I/O logging is enabled, subsequent commands will have their input and/or output logged, but there will not be traditional logs for those commands. Because of this, care must be taken when giving users access to commands via sudo to verify that the command does not inadvertently give the user an effective root shell. For information on ways to address this, see the Preventing shell escapes section in sudoers(5).

To prevent the disclosure of potentially sensitive information, sudo disables core dumps by default while it is executing (they are re-enabled for the command that is run). This historical practice dates from a time when most operating systems allowed set-user-ID processes to dump core by default. To aid in debugging sudo crashes, you may wish to re-enable core dumps by setting “disable_coredump” to false in the sudo.conf(5) file as follows:

```
Set disable_coredump false
```

See the sudo.conf(5) manual for more information.

## ENVIRONMENT
sudo utilizes the following environment variables. The security policy has control over the actual content of the command's environment.

EDITOR

Default editor to use in -e (sudoedit) mode if neither SUDO_EDITOR nor VISUAL is set.

MAIL

Set to the mail spool of the target user when the -i option is specified, or when env_reset is enabled in sudoers (unless MAIL is present in the env_keep list).

HOME

Set to the home directory of the target user when the -i or -H options are specified, when the -s option is specified and set_home is set in sudoers, when always_set_home is enabled in sudoers, or when env_reset is enabled in sudoers and HOME is not present in the env_keep list.

LOGNAME

Set to the login name of the target user when the -i option is specified, when the set_logname option is enabled in sudoers, or when the env_reset option is enabled in sudoers (unless LOGNAME is present in the env_keep list).

PATH

May be overridden by the security policy.

SHELL

Used to determine shell to run with -s option.

SUDO_ASKPASS

Specifies the path to a helper program used to read the password if no terminal is available or if the -A option is specified.

SUDO_COMMAND

Set to the command run by sudo, including any args. The args are truncated at 4096 characters to prevent a potential execution error.

SUDO_EDITOR

Default editor to use in -e (sudoedit) mode.

SUDO_GID

Set to the group-ID of the user who invoked sudo.

SUDO_HOME

Set to the home directory of the user who invoked sudo.

SUDO_PROMPT

Used as the default password prompt unless the -p option was specified.

SUDO_PS1

If set, PS1 will be set to its value for the program being run.

SUDO_TTY

Set to the terminal device of the user who invoked sudo, if one is present.

SUDO_UID

Set to the user-ID of the user who invoked sudo.

SUDO_USER

Set to the login name of the user who invoked sudo.

USER

Set to the same value as LOGNAME, described above.

VISUAL

Default editor to use in -e (sudoedit) mode if SUDO_EDITOR is not set.

## FILES
/etc/sudo.conf

sudo front-end configuration

## EXAMPLES
The following examples assume a properly configured security policy.

To get a file listing of an unreadable directory:

```
$ sudo ls /usr/local/protected
```

To list the home directory of user yaz on a machine where the file system holding ~yaz is not exported as root:

```
$ sudo -u yaz ls ~yaz
```

To edit the index.html file as user www:

```
$ sudoedit -u www ~www/htdocs/index.html
```

To view system logs only accessible to root and users in the adm group:

```
$ sudo -g adm more /var/log/syslog
```

To run an editor as jim with a different primary group:

```
$ sudoedit -u jim -g audio ~jim/sound.txt
```

To shut down a machine:

```
$ sudo shutdown -r +15 "quick reboot"
```

To make a usage listing of the directories in the /home partition. The commands are run in a sub-shell to allow the ‘cd’ command and file redirection to work.

```
$ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
```

## DIAGNOSTICS
Error messages produced by sudo include:

editing files in a writable directory is not permitted

By default, sudoedit does not permit editing a file when any of the parent directories are writable by the invoking user. This avoids a race condition that could allow the user to overwrite an arbitrary file. See the sudoedit_checkdir option in sudoers(5) for more information.

editing symbolic links is not permitted

By default, sudoedit does not follow symbolic links when opening files. See the sudoedit_follow option in sudoers(5) for more information.

effective uid is not 0, is sudo installed setuid root?

sudo was not run with root privileges. The sudo binary must be owned by the root user and have the set-user-ID bit set. Also, it must not be located on a file system mounted with the ‘nosuid’ option or on an NFS file system that maps uid 0 to an unprivileged uid.

effective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?

sudo was not run with root privileges. The sudo binary has the proper owner and permissions but it still did not run with root privileges. The most common reason for this is that the file system the sudo binary is located on is mounted with the ‘nosuid’ option or it is an NFS file system that maps uid 0 to an unprivileged uid.

fatal error, unable to load plugins

An error occurred while loading or initializing the plugins specified in sudo.conf(5).

invalid environment variable name

One or more environment variable names specified via the -E option contained an equal sign (‘=’). The arguments to the -E option should be environment variable names without an associated value.

no password was provided

When sudo tried to read the password, it did not receive any characters. This may happen if no terminal is available (or the -S option is specified) and the standard input has been redirected from /dev/null.

a terminal is required to read the password

sudo needs to read the password but there is no mechanism available for it to do so. Remote commands run via ssh(1) do not have a terminal available by default; passing the -t option to ssh(1) will cause it to allocate a terminal which should allow sudo to read the password. To allow sudo to run local commands without a terminal, the -S option can be used to read a password from the standard input, or an askpass helper can be configured via either the sudo.conf(5) file or by setting the SUDO_ASKPASS environment variable.

no writable temporary directory found

sudoedit was unable to find a usable temporary directory in which to store its intermediate files.

The “no new privileges” flag is set, which prevents sudo from running as root.

sudo was run by a process that has the Linux “no new privileges” flag is set. This causes the set-user-ID bit to be ignored when running an executable, which will prevent sudo from functioning. The most likely cause for this is running sudo within a container that sets this flag. Check the documentation to see if it is possible to configure the container such that the flag is not set.

sudo must be owned by uid 0 and have the setuid bit set

sudo was not run with root privileges. The sudo binary does not have the correct owner or permissions. It must be owned by the root user and have the set-user-ID bit set.

sudoedit is not supported on this platform

It is only possible to run sudoedit on systems that support setting the effective user-ID.

timed out reading password

The user did not enter a password before the password timeout (5 minutes by default) expired.

you do not exist in the passwd database

Your user-ID does not appear in the system passwd database.

you may not specify environment variables in edit mode

It is only possible to specify environment variables when running a command. When editing a file, the editor is run with the user's environment unmodified.

## SEE ALSO
su(1), stat(2), login_cap(3), passwd(5), sudo.conf(5), sudo_plugin(5), sudoers(5), sudoers_timestamp(5), sudoreplay(8), visudo(8)

## HISTORY
See the HISTORY.md file in the sudo distribution (https://www.sudo.ws/about/history/) for a brief history of sudo.

## AUTHORS
Many people have worked on sudo over the years; this version consists of code written primarily by:

Todd C. Miller

See the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to sudo.

## CAVEATS
There is no easy way to prevent a user from gaining a root shell if that user is allowed to run arbitrary commands via sudo. Also, many programs (such as editors) allow the user to run commands via shell escapes, thus avoiding sudo's checks. However, on most systems it is possible to prevent shell escapes with the sudoers(5) plugin's noexec functionality.

It is not meaningful to run the ‘cd’ command directly via sudo, e.g.,

```
$ sudo cd /usr/local/protected
```

since when the command exits the parent process (your shell) will still be the same. The -D option can be used to run a command in a specific directory.

Running shell scripts via sudo can expose the same kernel bugs that make set-user-ID shell scripts unsafe on some operating systems (if your OS has a /dev/fd/ directory, set-user-ID shell scripts are generally safe).

## BUGS
If you believe you have found a bug in sudo, you can either file a bug report in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If you would prefer to use email, messages may be sent to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or <sudo@sudo.ws> (private).

Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

## SUPPORT
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

## DISCLAIMER
sudo is provided “AS IS” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE.md file distributed with sudo or https://www.sudo.ws/about/license/ for complete details.


sudoreplay

title: sudoreplay(8)

summary: replay sudo session logs

text:
# sudoreplay(8)

## NAME
sudoreplay — replay sudo session logs

## SYNOPSIS
sudoreplay

[-FhnRS] [-d dir] [-f filter] [-m num] [-s num] ID[@offset]

sudoreplay

[-h] [-d dir] -l [search expression]

## DESCRIPTION
sudoreplay plays back or lists the output logs created by sudo. When replaying, sudoreplay can play the session back in real-time, or the playback speed may be adjusted (faster or slower) based on the command line options.

The ID should either be a six character sequence of digits and upper case letters, e.g., “0100A5” or a path name. The ID may include an optional @offset suffix which may be used to start replaying at a specific time offset. The @offset is specified as a number in seconds since the start of the session with an optional decimal fraction.

Path names may be relative to the I/O log directory /var/log/sudo-io (unless overridden by the -d option) or fully qualified, beginning with a ‘/’ character. When a command is run via sudo with log_output enabled in the sudoers file, a “TSID=ID” string is logged via syslog(3) or to the sudo log file. The ID may also be determined using sudoreplay's list mode.

In list mode, sudoreplay can be used to find the ID of a session based on a number of criteria such as the user, tty, or command run.

In replay mode, if the standard input and output are connected to a terminal and the -n option is not specified, sudoreplay will operate interactively. In interactive mode, sudoreplay will attempt to adjust the terminal size to match that of the session and write directly to the terminal (not all terminals support this). Additionally, it will poll the keyboard and act on the following keys:

‘\n’ or ‘\r’

Skip to the next replay event; useful for long pauses.

‘ ’ (space)

Pause output; press any key to resume.

‘<’

Reduce the playback speed by one half.

‘>’

Double the playback speed.

The session can be interrupted via control-C. When the session has finished, the terminal is restored to its original size if it was changed during playback.

The options are as follows:

-d dir, --directory=dir

Store session logs in dir instead of the default, /var/log/sudo-io.

-f filter, --filter=filter

Select which I/O type(s) to display. By default, sudoreplay will display the command's standard output, standard error, and tty output. The filter argument is a comma-separated list, consisting of one or more of following: stdin, stdout, stderr, ttyin, and ttyout.

-F, --follow

Enable “follow mode”. When replaying a session, sudoreplay will ignore end-of-file and keep replaying until the log is complete. This can be used to replay a session that is still in progress, similar to “tail -f”. An I/O log file is considered to be complete when the write bits have been cleared on the session's timing file. Versions of sudo prior to 1.9.1 do not clear the write bits upon completion.

-h, --help

Display a short help message to the standard output and exit.

-l, --list [search expression]

Enable “list mode”. In this mode, sudoreplay will list available sessions in a format similar to the sudo log file format, sorted by file name (or sequence number). Any control characters present in the log data are formatted in octal with a leading ‘#’ character. For example, a horizontal tab is displayed as ‘#011’ and an embedded carriage return is displayed as ‘#015’. Space characters in the command name and arguments are also formatted in octal. If a search expression is specified, it will be used to restrict the IDs that are displayed. An expression is composed of the following predicates:

command pattern

Evaluates to true if the command run matches the POSIX extended regular expression pattern.

cwd directory

Evaluates to true if the command was run with the specified current working directory.

fromdate date

Evaluates to true if the command was run on or after date. See Date and time format for a description of supported date and time formats.

group runas_group

Evaluates to true if the command was run with the specified runas_group. Unless a runas_group was explicitly specified when sudo was run this field will be empty in the log.

host hostname

Evaluates to true if the command was run on the specified hostname.

runas runas_user

Evaluates to true if the command was run as the specified runas_user. By default, sudo runs commands as the root user.

todate date

Evaluates to true if the command was run on or prior to date. See Date and time format for a description of supported date and time formats.

tty tty name

Evaluates to true if the command was run on the specified terminal device. The tty name should be specified without the /dev/ prefix, e.g., tty01 instead of /dev/tty01.

user user name

Evaluates to true if the ID matches a command run by user name.

Predicates may be abbreviated to the shortest unique string.

Predicates may be combined using and, or, and ! operators as well as ‘(’ and ‘)’ grouping (parentheses must generally be escaped from the shell). The and operator is optional, adjacent predicates have an implied and unless separated by an or.

-m, --max-wait max_wait

Specify an upper bound on how long to wait between key presses or output data. By default, sudoreplay will accurately reproduce the delays between key presses or program output. However, this can be tedious when the session includes long pauses. When the -m option is specified, sudoreplay will limit these pauses to at most max_wait seconds. The value may be specified as a floating point number, e.g., 2.5. A max_wait of zero or less will eliminate the pauses entirely.

-n, --non-interactive

Do not prompt for user input or attempt to re-size the terminal. The session is written to the standard output, not directly to the user's terminal.

-R, --no-resize

Do not attempt to re-size the terminal to match the terminal size of the session.

-S, --suspend-wait

Wait while the command was suspended. By default, sudoreplay will ignore the time interval between when the command was suspended and when it was resumed. If the -S option is specified, sudoreplay will wait instead.

-s, --speed speed_factor

This option causes sudoreplay to adjust the number of seconds it will wait between key presses or program output. This can be used to slow down or speed up the display. For example, a speed_factor of 2 would make the output twice as fast whereas a speed_factor of .5 would make the output twice as slow.

-V, --version

Print the sudoreplay versions version number and exit.

### Date and time format
The time and date may be specified multiple ways, common formats include:

HH:MM:SS am MM/DD/CCYY timezone

24 hour time may be used in place of am/pm.

HH:MM:SS am Month, Day Year timezone

24 hour time may be used in place of am/pm, and month and day names may be abbreviated. Month and day of the week names must be specified in English.

CCYY-MM-DD HH:MM:SS

ISO time format

DD Month CCYY HH:MM:SS

The month name may be abbreviated.

Either time or date may be omitted, the am/pm and timezone are optional. If no date is specified, the current day is assumed; if no time is specified, the first second of the specified date is used. The less significant parts of both time and date may also be omitted, in which case zero is assumed.

The following are all valid time and date specifications:

now

The current time and date.

tomorrow

Exactly one day from now.

yesterday

24 hours ago.

2 hours ago

2 hours ago.

next Friday

The first second of the Friday in the next (upcoming) week. Not to be confused with “this Friday” which would match the Friday of the current week.

last week

The current time but 7 days ago. This is equivalent to “a week ago”.

a fortnight ago

The current time but 14 days ago.

10:01 am 9/17/2009

10:01 am, September 17, 2009.

10:01 am

10:01 am on the current day.

10

10:00 am on the current day.

9/17/2009

00:00 am, September 17, 2009.

10:01 am Sep 17, 2009

10:01 am, September 17, 2009.

Relative time specifications do not always work as expected. For example, the “next” qualifier is intended to be used in conjunction with a day such as “next Monday”. When used with units of weeks, months, years, etc the result will be one more than expected. For example, “next week” will result in a time exactly two weeks from now, which is probably not what was intended. This will be addressed in a future version of sudoreplay.

### Debugging sudoreplay
sudoreplay versions 1.8.4 and higher support a flexible debugging framework that is configured via Debug lines in the sudo.conf(5) file.

For more information on configuring sudo.conf(5), refer to its manual.

## FILES
/etc/sudo.conf

Debugging framework configuration

/var/log/sudo-io

The default I/O log directory.

/var/log/sudo-io/00/00/01/log

Example session log info.

/var/log/sudo-io/00/00/01/log.json

Example session log info (JSON format).

/var/log/sudo-io/00/00/01/stdin

Example session standard input log.

/var/log/sudo-io/00/00/01/stdout

Example session standard output log.

/var/log/sudo-io/00/00/01/stderr

Example session standard error log.

/var/log/sudo-io/00/00/01/ttyin

Example session tty input file.

/var/log/sudo-io/00/00/01/ttyout

Example session tty output file.

/var/log/sudo-io/00/00/01/timing

Example session timing file.

The stdin, stdout and stderr files will be empty unless sudo was used as part of a pipeline for a particular command.

## EXAMPLES
List sessions run by user millert:

```
# sudoreplay -l user millert
```

List sessions run by user bob with a command containing the string vi:

```
# sudoreplay -l user bob command vi
```

List sessions run by user jeff that match a regular expression:

```
# sudoreplay -l user jeff command '/bin/[a-z]*sh'
```

List sessions run by jeff or bob on the console:

```
# sudoreplay -l ( user jeff or user bob ) tty console
```

## SEE ALSO
script(1), sudo.conf(5), sudo(8)

## AUTHORS
Many people have worked on sudo over the years; this version consists of code written primarily by:

Todd C. Miller

See the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to sudo.

## BUGS
If you believe you have found a bug in sudoreplay, you can either file a bug report in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If you would prefer to use email, messages may be sent to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or <sudo@sudo.ws> (private).

Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

## SUPPORT
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

## DISCLAIMER
sudoreplay is provided “AS IS” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE.md file distributed with sudo or https://www.sudo.ws/about/license/ for complete details.