931 lines
33 KiB
Groff
931 lines
33 KiB
Groff
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
|
||
.\"
|
||
.\" Standard preamble:
|
||
.\" ========================================================================
|
||
.de Sp \" Vertical space (when we can't use .PP)
|
||
.if t .sp .5v
|
||
.if n .sp
|
||
..
|
||
.de Vb \" Begin verbatim text
|
||
.ft CW
|
||
.nf
|
||
.ne \\$1
|
||
..
|
||
.de Ve \" End verbatim text
|
||
.ft R
|
||
.fi
|
||
..
|
||
.\" Set up some character translations and predefined strings. \*(-- will
|
||
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
.\" nothing in troff, for use with C<>.
|
||
.tr \(*W-
|
||
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
.ie n \{\
|
||
. ds -- \(*W-
|
||
. ds PI pi
|
||
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
. ds L" ""
|
||
. ds R" ""
|
||
. ds C` ""
|
||
. ds C' ""
|
||
'br\}
|
||
.el\{\
|
||
. ds -- \|\(em\|
|
||
. ds PI \(*p
|
||
. ds L" ``
|
||
. ds R" ''
|
||
'br\}
|
||
.\"
|
||
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
.ie \n(.g .ds Aq \(aq
|
||
.el .ds Aq '
|
||
.\"
|
||
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
.\" output yourself in some meaningful fashion.
|
||
.ie \nF \{\
|
||
. de IX
|
||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
..
|
||
. nr % 0
|
||
. rr F
|
||
.\}
|
||
.el \{\
|
||
. de IX
|
||
..
|
||
.\}
|
||
.\" ========================================================================
|
||
.\"
|
||
.IX Title "STUNNEL 8"
|
||
.TH STUNNEL 8 "2012.01.14" "4.53" "stunnel"
|
||
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
.\" way too many mistakes in technical documents.
|
||
.if n .ad l
|
||
.nh
|
||
.SH "NAME"
|
||
stunnel \- universal SSL tunnel
|
||
.SH "SYNOPSIS"
|
||
.IX Header "SYNOPSIS"
|
||
.IP "\fBUnix:\fR" 4
|
||
.IX Item "Unix:"
|
||
\&\fBstunnel\fR [<filename>] | \-fd n | \-help | \-version | \-sockets
|
||
.IP "\fB\s-1WIN32:\s0\fR" 4
|
||
.IX Item "WIN32:"
|
||
\&\fBstunnel\fR [ [\-install | \-uninstall | \-start | \-stop] | \-exit]
|
||
[\-quiet] [<filename>] ] | \-help | \-version | \-sockets
|
||
.SH "DESCRIPTION"
|
||
.IX Header "DESCRIPTION"
|
||
The \fBstunnel\fR program is designed to work as \fI\s-1SSL\s0\fR encryption wrapper
|
||
between remote clients and local (\fIinetd\fR\-startable) or remote
|
||
servers. The concept is that having non-SSL aware daemons running on
|
||
your system you can easily set them up to communicate with clients over
|
||
secure \s-1SSL\s0 channels.
|
||
.PP
|
||
\&\fBstunnel\fR can be used to add \s-1SSL\s0 functionality to commonly used \fIInetd\fR
|
||
daemons like \s-1POP\-2\s0, \s-1POP\-3\s0, and \s-1IMAP\s0 servers, to standalone daemons like
|
||
\&\s-1NNTP\s0, \s-1SMTP\s0 and \s-1HTTP\s0, and in tunneling \s-1PPP\s0 over network sockets without
|
||
changes to the source code.
|
||
.PP
|
||
This product includes cryptographic software written by
|
||
Eric Young (eay@cryptsoft.com)
|
||
.SH "OPTIONS"
|
||
.IX Header "OPTIONS"
|
||
.IP "<\fBfilename\fR>" 4
|
||
.IX Item "<filename>"
|
||
Use specified configuration file
|
||
.IP "\fB\-fd n\fR (Unix only)" 4
|
||
.IX Item "-fd n (Unix only)"
|
||
Read the config file from specified file descriptor
|
||
.IP "\fB\-help\fR" 4
|
||
.IX Item "-help"
|
||
Print \fBstunnel\fR help menu
|
||
.IP "\fB\-version\fR" 4
|
||
.IX Item "-version"
|
||
Print \fBstunnel\fR version and compile time defaults
|
||
.IP "\fB\-sockets\fR" 4
|
||
.IX Item "-sockets"
|
||
Print default socket options
|
||
.IP "\fB\-install\fR (\s-1NT/2000/XP\s0 only)" 4
|
||
.IX Item "-install (NT/2000/XP only)"
|
||
Install \s-1NT\s0 Service
|
||
.IP "\fB\-uninstall\fR (\s-1NT/2000/XP\s0 only)" 4
|
||
.IX Item "-uninstall (NT/2000/XP only)"
|
||
Uninstall \s-1NT\s0 Service
|
||
.IP "\fB\-start\fR (\s-1NT/2000/XP\s0 only)" 4
|
||
.IX Item "-start (NT/2000/XP only)"
|
||
Start \s-1NT\s0 Service
|
||
.IP "\fB\-stop\fR (\s-1NT/2000/XP\s0 only)" 4
|
||
.IX Item "-stop (NT/2000/XP only)"
|
||
Stop \s-1NT\s0 Service
|
||
.IP "\fB\-exit\fR (Win32 only)" 4
|
||
.IX Item "-exit (Win32 only)"
|
||
Exit an already started stunnel
|
||
.IP "\fB\-quiet\fR (\s-1NT/2000/XP\s0 only)" 4
|
||
.IX Item "-quiet (NT/2000/XP only)"
|
||
Don't display any message boxes
|
||
.SH "CONFIGURATION FILE"
|
||
.IX Header "CONFIGURATION FILE"
|
||
Each line of the configuration file can be either:
|
||
.IP "\(bu" 4
|
||
an empty line (ignored)
|
||
.IP "\(bu" 4
|
||
a comment starting with ';' (ignored)
|
||
.IP "\(bu" 4
|
||
an 'option_name = option_value' pair
|
||
.IP "\(bu" 4
|
||
\&'[service_name]' indicating a start of a service definition
|
||
.PP
|
||
An address parameter of an option may be either:
|
||
.IP "\(bu" 4
|
||
a port number
|
||
.IP "\(bu" 4
|
||
a colon-separated pair of \s-1IP\s0 address (either IPv4, IPv6, or domain name) and port number
|
||
.IP "\(bu" 4
|
||
a Unix socket path (Unix only)
|
||
.SS "\s-1GLOBAL\s0 \s-1OPTIONS\s0"
|
||
.IX Subsection "GLOBAL OPTIONS"
|
||
.IP "\fBchroot\fR = directory (Unix only)" 4
|
||
.IX Item "chroot = directory (Unix only)"
|
||
directory to chroot \fBstunnel\fR process
|
||
.Sp
|
||
\&\fBchroot\fR keeps \fBstunnel\fR in chrooted jail. \fICApath\fR, \fICRLpath\fR, \fIpid\fR
|
||
and \fIexec\fR are located inside the jail and the patches have to be relative
|
||
to the directory specified with \fBchroot\fR.
|
||
.IP "\fBcompression\fR = deflate | zlib | rle" 4
|
||
.IX Item "compression = deflate | zlib | rle"
|
||
select data compression algorithm
|
||
.Sp
|
||
default: no compression
|
||
.Sp
|
||
deflate is the standard compression method as described in \s-1RFC\s0 1951.
|
||
.Sp
|
||
zlib compression of OpenSSL 0.9.8 or above is not backward compatible with
|
||
OpenSSL 0.9.7.
|
||
.Sp
|
||
rle compression is currently not implemented by the OpenSSL library.
|
||
.IP "\fBdebug\fR = [facility.]level" 4
|
||
.IX Item "debug = [facility.]level"
|
||
debugging level
|
||
.Sp
|
||
Level is a one of the syslog level names or numbers
|
||
emerg (0), alert (1), crit (2), err (3), warning (4), notice (5),
|
||
info (6), or debug (7). All logs for the specified level and
|
||
all levels numerically less than it will be shown. Use \fIdebug = debug\fR or
|
||
\&\fIdebug = 7\fR for greatest debugging output. The default is notice (5).
|
||
.Sp
|
||
The syslog facility 'daemon' will be used unless a facility name is supplied.
|
||
(Facilities are not supported on Win32.)
|
||
.Sp
|
||
Case is ignored for both facilities and levels.
|
||
.IP "\fB\s-1EGD\s0\fR = egd path (Unix only)" 4
|
||
.IX Item "EGD = egd path (Unix only)"
|
||
path to Entropy Gathering Daemon socket
|
||
.Sp
|
||
Entropy Gathering Daemon socket to use to feed OpenSSL random number
|
||
generator. (Available only if compiled with OpenSSL 0.9.5a or higher)
|
||
.IP "\fBengine\fR = auto | <engine id>" 4
|
||
.IX Item "engine = auto | <engine id>"
|
||
select hardware engine
|
||
.Sp
|
||
default: software-only cryptography
|
||
.Sp
|
||
Here is an example of advanced engine configuration to read private key from an
|
||
OpenSC engine
|
||
.Sp
|
||
.Vb 7
|
||
\& engine=dynamic
|
||
\& engineCtrl=SO_PATH:/usr/lib/opensc/engine_pkcs11.so
|
||
\& engineCtrl=ID:pkcs11
|
||
\& engineCtrl=LIST_ADD:1
|
||
\& engineCtrl=LOAD
|
||
\& engineCtrl=MODULE_PATH:/usr/lib/pkcs11/opensc\-pkcs11.so
|
||
\& engineCtrl=INIT
|
||
\&
|
||
\& [service]
|
||
\& engineNum=1
|
||
\& key=id_45
|
||
.Ve
|
||
.IP "\fBengineCtrl\fR = command[:parameter]" 4
|
||
.IX Item "engineCtrl = command[:parameter]"
|
||
control hardware engine
|
||
.Sp
|
||
Special commands \*(L"\s-1LOAD\s0\*(R" and \*(L"\s-1INIT\s0\*(R" can be used to load and initialize the
|
||
engine cryptogaphic module.
|
||
.IP "\fBfips\fR = yes | no" 4
|
||
.IX Item "fips = yes | no"
|
||
Enable or disable \s-1FIPS\s0 140\-2 mode.
|
||
.Sp
|
||
This option allows to disable entering \s-1FIPS\s0 mode if stunnel was compiled with
|
||
\&\s-1FIPS\s0 140\-2 support.
|
||
.Sp
|
||
default: yes
|
||
.IP "\fBforeground\fR = yes | no (Unix only)" 4
|
||
.IX Item "foreground = yes | no (Unix only)"
|
||
foreground mode
|
||
.Sp
|
||
Stay in foreground (don't fork) and log to stderr
|
||
instead of via syslog (unless \fIoutput\fR is specified).
|
||
.Sp
|
||
default: background in daemon mode
|
||
.IP "\fBoutput\fR = file" 4
|
||
.IX Item "output = file"
|
||
append log messages to a file
|
||
.Sp
|
||
/dev/stdout device can be used to send log messages to the standard
|
||
output (for example to log them with daemontools splogger).
|
||
.IP "\fBpid\fR = file (Unix only)" 4
|
||
.IX Item "pid = file (Unix only)"
|
||
pid file location
|
||
.Sp
|
||
If the argument is empty, then no pid file will be created.
|
||
.Sp
|
||
\&\fIpid\fR path is relative to \fIchroot\fR directory if specified.
|
||
.IP "\fBRNDbytes\fR = bytes" 4
|
||
.IX Item "RNDbytes = bytes"
|
||
bytes to read from random seed files
|
||
.Sp
|
||
Number of bytes of data read from random seed files. With \s-1SSL\s0 versions
|
||
less than 0.9.5a, also determines how many bytes of data are considered
|
||
sufficient to seed the \s-1PRNG\s0. More recent OpenSSL versions have a builtin
|
||
function to determine when sufficient randomness is available.
|
||
.IP "\fBRNDfile\fR = file" 4
|
||
.IX Item "RNDfile = file"
|
||
path to file with random seed data
|
||
.Sp
|
||
The \s-1SSL\s0 library will use data from this file first to seed the random
|
||
number generator.
|
||
.IP "\fBRNDoverwrite\fR = yes | no" 4
|
||
.IX Item "RNDoverwrite = yes | no"
|
||
overwrite the random seed files with new random data
|
||
.Sp
|
||
default: yes
|
||
.IP "\fBservice\fR = servicename (Unix only)" 4
|
||
.IX Item "service = servicename (Unix only)"
|
||
use specified string as \fIinetd\fR mode service name for \s-1TCP\s0 Wrapper library
|
||
.Sp
|
||
default: stunnel
|
||
.IP "\fBsetgid\fR = groupname (Unix only)" 4
|
||
.IX Item "setgid = groupname (Unix only)"
|
||
\&\fIsetgid()\fR to groupname in daemon mode and clears all other groups
|
||
.IP "\fBsetuid\fR = username (Unix only)" 4
|
||
.IX Item "setuid = username (Unix only)"
|
||
\&\fIsetuid()\fR to username in daemon mode
|
||
.IP "\fBsocket\fR = a|l|r:option=value[:value]" 4
|
||
.IX Item "socket = a|l|r:option=value[:value]"
|
||
Set an option on accept/local/remote socket
|
||
.Sp
|
||
The values for linger option are l_onof:l_linger.
|
||
The values for time are tv_sec:tv_usec.
|
||
.Sp
|
||
Examples:
|
||
.Sp
|
||
.Vb 9
|
||
\& socket = l:SO_LINGER=1:60
|
||
\& set one minute timeout for closing local socket
|
||
\& socket = r:SO_OOBINLINE=yes
|
||
\& place out\-of\-band data directly into the
|
||
\& receive data stream for remote sockets
|
||
\& socket = a:SO_REUSEADDR=no
|
||
\& disable address reuse (enabled by default)
|
||
\& socket = a:SO_BINDTODEVICE=lo
|
||
\& only accept connections on loopback interface
|
||
.Ve
|
||
.IP "\fBsyslog\fR = yes | no (Unix only)" 4
|
||
.IX Item "syslog = yes | no (Unix only)"
|
||
enable logging via syslog
|
||
.Sp
|
||
default: yes
|
||
.IP "\fBtaskbar\fR = yes | no (\s-1WIN32\s0 only)" 4
|
||
.IX Item "taskbar = yes | no (WIN32 only)"
|
||
enable the taskbar icon
|
||
.Sp
|
||
default: yes
|
||
.SS "SERVICE-LEVEL \s-1OPTIONS\s0"
|
||
.IX Subsection "SERVICE-LEVEL OPTIONS"
|
||
Each configuration section begins with service name in square brackets.
|
||
The service name is used for libwrap (\s-1TCP\s0 Wrappers) access control and lets
|
||
you distinguish \fBstunnel\fR services in your log files.
|
||
.PP
|
||
Note that if you wish to run \fBstunnel\fR in \fIinetd\fR mode (where it
|
||
is provided a network socket by a server such as \fIinetd\fR, \fIxinetd\fR,
|
||
or \fItcpserver\fR) then you should read the section entitled \fI\s-1INETD\s0 \s-1MODE\s0\fR
|
||
below.
|
||
.IP "\fBaccept\fR = address" 4
|
||
.IX Item "accept = address"
|
||
accept connections on specified address
|
||
.Sp
|
||
If no host specified, defaults to all IPv4 addresses for the local host.
|
||
.Sp
|
||
To listen on all IPv6 addresses use:
|
||
.Sp
|
||
.Vb 1
|
||
\& connect = :::port
|
||
.Ve
|
||
.IP "\fBCApath\fR = directory" 4
|
||
.IX Item "CApath = directory"
|
||
Certificate Authority directory
|
||
.Sp
|
||
This is the directory in which \fBstunnel\fR will look for certificates when using
|
||
the \fIverify\fR. Note that the certificates in this directory should be named
|
||
\&\s-1XXXXXXXX\s0.0 where \s-1XXXXXXXX\s0 is the hash value of the \s-1DER\s0 encoded subject of the
|
||
cert.
|
||
.Sp
|
||
The hash algorithm has been changed in OpenSSL 1.0.0. It is required to
|
||
c_rehash the directory on upgrade from OpenSSL 0.x.x to OpenSSL 1.x.x.
|
||
.Sp
|
||
\&\fICApath\fR path is relative to \fIchroot\fR directory if specified.
|
||
.IP "\fBCAfile\fR = certfile" 4
|
||
.IX Item "CAfile = certfile"
|
||
Certificate Authority file
|
||
.Sp
|
||
This file contains multiple \s-1CA\s0 certificates, used with the \fIverify\fR.
|
||
.IP "\fBcert\fR = pemfile" 4
|
||
.IX Item "cert = pemfile"
|
||
certificate chain \s-1PEM\s0 file name
|
||
.Sp
|
||
A \s-1PEM\s0 is always needed in server mode.
|
||
Specifying this flag in client mode will use this certificate chain
|
||
as a client side certificate chain. Using client side certs is optional.
|
||
The certificates must be in \s-1PEM\s0 format and must be sorted starting with the
|
||
certificate to the highest level (root \s-1CA\s0).
|
||
.IP "\fBciphers\fR = cipherlist" 4
|
||
.IX Item "ciphers = cipherlist"
|
||
Select permitted \s-1SSL\s0 ciphers
|
||
.Sp
|
||
A colon delimited list of the ciphers to allow in the \s-1SSL\s0 connection.
|
||
For example \s-1DES\-CBC3\-SHA:IDEA\-CBC\-MD5\s0
|
||
.IP "\fBclient\fR = yes | no" 4
|
||
.IX Item "client = yes | no"
|
||
client mode (remote service uses \s-1SSL\s0)
|
||
.Sp
|
||
default: no (server mode)
|
||
.IP "\fBconnect\fR = address" 4
|
||
.IX Item "connect = address"
|
||
connect to a remote address
|
||
.Sp
|
||
If no host is specified, the host defaults to localhost.
|
||
.Sp
|
||
Multiple \fBconnect\fR options are allowed in a single service section.
|
||
.Sp
|
||
If host resolves to multiple addresses and/or if multiple \fIconnect\fR
|
||
options are specified, then the remote address is chosen using a
|
||
round-robin algorithm.
|
||
.IP "\fBCRLpath\fR = directory" 4
|
||
.IX Item "CRLpath = directory"
|
||
Certificate Revocation Lists directory
|
||
.Sp
|
||
This is the directory in which \fBstunnel\fR will look for CRLs when
|
||
using the \fIverify\fR. Note that the CRLs in this directory should
|
||
be named \s-1XXXXXXXX\s0.r0 where \s-1XXXXXXXX\s0 is the hash value of the \s-1CRL\s0.
|
||
.Sp
|
||
The hash algorithm has been changed in OpenSSL 1.0.0. It is required to
|
||
c_rehash the directory on upgrade from OpenSSL 0.x.x to OpenSSL 1.x.x.
|
||
.Sp
|
||
\&\fICRLpath\fR path is relative to \fIchroot\fR directory if specified.
|
||
.IP "\fBCRLfile\fR = certfile" 4
|
||
.IX Item "CRLfile = certfile"
|
||
Certificate Revocation Lists file
|
||
.Sp
|
||
This file contains multiple CRLs, used with the \fIverify\fR.
|
||
.IP "\fBcurve\fR = nid" 4
|
||
.IX Item "curve = nid"
|
||
specify \s-1ECDH\s0 curve name
|
||
.Sp
|
||
To get a list of supported cuves use:
|
||
.Sp
|
||
.Vb 1
|
||
\& openssl ecparam \-list_curves
|
||
.Ve
|
||
.Sp
|
||
default: prime256v1
|
||
.IP "\fBdelay\fR = yes | no" 4
|
||
.IX Item "delay = yes | no"
|
||
delay \s-1DNS\s0 lookup for 'connect' option
|
||
.Sp
|
||
This option is useful for dynamic \s-1DNS\s0, or when \s-1DNS\s0 is not available during
|
||
stunnel startup (road warrior \s-1VPN\s0, dial-up configurations).
|
||
.IP "\fBengineNum\fR = engine number" 4
|
||
.IX Item "engineNum = engine number"
|
||
select engine number to read private key
|
||
.Sp
|
||
The engines are numbered starting from 1.
|
||
.IP "\fBexec\fR = executable_path" 4
|
||
.IX Item "exec = executable_path"
|
||
execute local inetd-type program
|
||
.Sp
|
||
\&\fIexec\fR path is relative to \fIchroot\fR directory if specified.
|
||
.ie n .IP "\fBexecargs\fR = $0 $1 $2 ..." 4
|
||
.el .IP "\fBexecargs\fR = \f(CW$0\fR \f(CW$1\fR \f(CW$2\fR ..." 4
|
||
.IX Item "execargs = $0 $1 $2 ..."
|
||
arguments for \fIexec\fR including program name ($0)
|
||
.Sp
|
||
Quoting is currently not supported.
|
||
Arguments are separated with arbitrary number of whitespaces.
|
||
.IP "\fBfailover\fR = rr | prio" 4
|
||
.IX Item "failover = rr | prio"
|
||
Failover strategy for multiple \*(L"connect\*(R" targets.
|
||
.Sp
|
||
.Vb 2
|
||
\& rr (round robin) \- fair load distribution
|
||
\& prio (priority) \- use the order specified in config file
|
||
.Ve
|
||
.Sp
|
||
default: rr
|
||
.IP "\fBident\fR = username" 4
|
||
.IX Item "ident = username"
|
||
use \s-1IDENT\s0 (\s-1RFC\s0 1413) username checking
|
||
.IP "\fBkey\fR = keyfile" 4
|
||
.IX Item "key = keyfile"
|
||
private key for certificate specified with \fIcert\fR option
|
||
.Sp
|
||
Private key is needed to authenticate certificate owner.
|
||
Since this file should be kept secret it should only be readable
|
||
to its owner. On Unix systems you can use the following command:
|
||
.Sp
|
||
.Vb 1
|
||
\& chmod 600 keyfile
|
||
.Ve
|
||
.Sp
|
||
default: value of \fIcert\fR option
|
||
.IP "\fBlibwrap\fR = yes | no" 4
|
||
.IX Item "libwrap = yes | no"
|
||
Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
|
||
.Sp
|
||
default: yes
|
||
.IP "\fBlocal\fR = host" 4
|
||
.IX Item "local = host"
|
||
\&\s-1IP\s0 of the outgoing interface is used as source for remote connections.
|
||
Use this option to bind a static local \s-1IP\s0 address, instead.
|
||
.IP "\fBsni\fR = service_name:server_name (server mode)" 4
|
||
.IX Item "sni = service_name:server_name (server mode)"
|
||
Use the service as a slave service (a name-based virtual server) for Server
|
||
Name Indication \s-1TLS\s0 extension (\s-1RFC\s0 3546).
|
||
.Sp
|
||
\&\fIservice_name\fR specifies the master service that accepts client connections
|
||
with \fIaccept\fR option. \fIserver_name\fR specifies the host name to be redirected.
|
||
Multiple slave services are normally specified for a single master service.
|
||
\&\fIsni\fR option can also be specified more than once within a single slave service.
|
||
.Sp
|
||
This service, as well as the master service, may not be configured in client mode.
|
||
\&\fIconnect\fR option of the slave service is ignored when \fIprotocol\fR option is
|
||
specified, as \fIprotocol\fR connects remote host before \s-1TLS\s0 handshake.
|
||
Libwrap checks (Unix only) are performed twice: with master service name after
|
||
\&\s-1TCP\s0 connection is accepted, and with slave service name during \s-1TLS\s0 handshake.
|
||
.Sp
|
||
Option \fIsni\fR is only available when compiled with OpenSSL 1.0.0 and later.
|
||
.IP "\fBsni\fR = server_name (client mode)" 4
|
||
.IX Item "sni = server_name (client mode)"
|
||
Use the parameter as the value of \s-1TLS\s0 Server Name Indication (\s-1RFC\s0 3546)
|
||
extension.
|
||
.Sp
|
||
Option \fIsni\fR is only available when compiled with OpenSSL 1.0.0 and later.
|
||
.IP "\fB\s-1OCSP\s0\fR = url" 4
|
||
.IX Item "OCSP = url"
|
||
select \s-1OCSP\s0 server for certificate verification
|
||
.IP "\fBOCSPflag\fR = flag" 4
|
||
.IX Item "OCSPflag = flag"
|
||
specify \s-1OCSP\s0 server flag
|
||
.Sp
|
||
Several \fIOCSPflag\fR can be used to specify multiple flags.
|
||
.Sp
|
||
currently supported flags: \s-1NOCERTS\s0, \s-1NOINTERN\s0 \s-1NOSIGS\s0, \s-1NOCHAIN\s0, \s-1NOVERIFY\s0,
|
||
\&\s-1NOEXPLICIT\s0, \s-1NOCASIGN\s0, \s-1NODELEGATED\s0, \s-1NOCHECKS\s0, \s-1TRUSTOTHER\s0, \s-1RESPID_KEY\s0, \s-1NOTIME\s0
|
||
.IP "\fBoptions\fR = SSL_options" 4
|
||
.IX Item "options = SSL_options"
|
||
OpenSSL library options
|
||
.Sp
|
||
The parameter is the OpenSSL option name as described in the
|
||
\&\fI\fISSL_CTX_set_options\fI\|(3ssl)\fR manual, but without \fI\s-1SSL_OP_\s0\fR prefix.
|
||
Several \fIoptions\fR can be used to specify multiple options.
|
||
.Sp
|
||
For example for compatibility with erroneous Eudora \s-1SSL\s0 implementation
|
||
the following option can be used:
|
||
.Sp
|
||
.Vb 1
|
||
\& options = DONT_INSERT_EMPTY_FRAGMENTS
|
||
.Ve
|
||
.IP "\fBprotocol\fR = proto" 4
|
||
.IX Item "protocol = proto"
|
||
application protocol to negotiate \s-1SSL\s0 (e.g. \fIstarttls\fR or \fIstls\fR)
|
||
.Sp
|
||
\&\fIprotocol\fR option should not be used with \s-1SSL\s0 encryption on a separate port.
|
||
.Sp
|
||
Currently supported protocols:
|
||
.RS 4
|
||
.IP "\fIcifs\fR" 4
|
||
.IX Item "cifs"
|
||
Proprietary (undocummented) extension of \s-1CIFS\s0 protocol implemented in Samba.
|
||
Support for this extension was dropped in Samba 3.0.0.
|
||
.IP "\fIconnect\fR" 4
|
||
.IX Item "connect"
|
||
Based on \s-1RFC\s0 2817 \- \fIUpgrading to \s-1TLS\s0 Within \s-1HTTP/1\s0.1\fR, section 5.2 \- \fIRequesting a Tunnel with \s-1CONNECT\s0\fR
|
||
.Sp
|
||
This protocol is only supported in client mode.
|
||
.IP "\fIimap\fR" 4
|
||
.IX Item "imap"
|
||
Based on \s-1RFC\s0 2595 \- \fIUsing \s-1TLS\s0 with \s-1IMAP\s0, \s-1POP3\s0 and \s-1ACAP\s0\fR
|
||
.IP "\fInntp\fR" 4
|
||
.IX Item "nntp"
|
||
Based on \s-1RFC\s0 4642 \- \fIUsing Transport Layer Security (\s-1TLS\s0) with Network News Transfer Protocol (\s-1NNTP\s0)\fR
|
||
.Sp
|
||
This protocol is only supported in client mode.
|
||
.IP "\fIpgsql\fR" 4
|
||
.IX Item "pgsql"
|
||
Based on http://www.postgresql.org/docs/8.3/static/protocol\-flow.html#AEN73982
|
||
.IP "\fIpop3\fR" 4
|
||
.IX Item "pop3"
|
||
Based on \s-1RFC\s0 2449 \- \fI\s-1POP3\s0 Extension Mechanism\fR
|
||
.IP "\fIproxy\fR" 4
|
||
.IX Item "proxy"
|
||
Haproxy client \s-1IP\s0 address http://haproxy.1wt.eu/download/1.5/doc/proxy\-protocol.txt
|
||
.IP "\fIsmtp\fR" 4
|
||
.IX Item "smtp"
|
||
Based on \s-1RFC\s0 2487 \- \fI\s-1SMTP\s0 Service Extension for Secure \s-1SMTP\s0 over \s-1TLS\s0\fR
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fBprotocolAuthentication\fR = auth_type" 4
|
||
.IX Item "protocolAuthentication = auth_type"
|
||
authentication type for protocol negotiations
|
||
.Sp
|
||
currently supported: basic, \s-1NTLM\s0
|
||
.Sp
|
||
Currently authentication type only applies to 'connect' protocol.
|
||
.Sp
|
||
default: basic
|
||
.IP "\fBprotocolHost\fR = host:port" 4
|
||
.IX Item "protocolHost = host:port"
|
||
destination address for protocol negotiations
|
||
.IP "\fBprotocolPassword\fR = password" 4
|
||
.IX Item "protocolPassword = password"
|
||
password for protocol negotiations
|
||
.IP "\fBprotocolUsername\fR = username" 4
|
||
.IX Item "protocolUsername = username"
|
||
username for protocol negotiations
|
||
.IP "\fBpty\fR = yes | no (Unix only)" 4
|
||
.IX Item "pty = yes | no (Unix only)"
|
||
allocate pseudo terminal for 'exec' option
|
||
.IP "\fBretry\fR = yes | no (Unix only)" 4
|
||
.IX Item "retry = yes | no (Unix only)"
|
||
reconnect a connect+exec section after it's disconnected
|
||
.Sp
|
||
default: no
|
||
.IP "\fBsession\fR = timeout" 4
|
||
.IX Item "session = timeout"
|
||
session cache timeout
|
||
.IP "\fBsessiond\fR = host:port" 4
|
||
.IX Item "sessiond = host:port"
|
||
address of sessiond \s-1SSL\s0 cache server
|
||
.IP "\fBsslVersion\fR = version" 4
|
||
.IX Item "sslVersion = version"
|
||
select version of \s-1SSL\s0 protocol
|
||
.Sp
|
||
Allowed options: all, SSLv2, SSLv3, TLSv1
|
||
.IP "\fBstack\fR = bytes (except for \s-1FORK\s0 model)" 4
|
||
.IX Item "stack = bytes (except for FORK model)"
|
||
thread stack size
|
||
.IP "\fBTIMEOUTbusy\fR = seconds" 4
|
||
.IX Item "TIMEOUTbusy = seconds"
|
||
time to wait for expected data
|
||
.IP "\fBTIMEOUTclose\fR = seconds" 4
|
||
.IX Item "TIMEOUTclose = seconds"
|
||
time to wait for close_notify (set to 0 for buggy \s-1MSIE\s0)
|
||
.IP "\fBTIMEOUTconnect\fR = seconds" 4
|
||
.IX Item "TIMEOUTconnect = seconds"
|
||
time to wait to connect a remote host
|
||
.IP "\fBTIMEOUTidle\fR = seconds" 4
|
||
.IX Item "TIMEOUTidle = seconds"
|
||
time to keep an idle connection
|
||
.IP "\fBtransparent\fR = none | source | destination | both (Unix only)" 4
|
||
.IX Item "transparent = none | source | destination | both (Unix only)"
|
||
enable transparent proxy support on selected platforms
|
||
.Sp
|
||
Supported values:
|
||
.RS 4
|
||
.IP "\fInone\fR" 4
|
||
.IX Item "none"
|
||
Disable transparent proxy support. This is the default.
|
||
.IP "\fIsource\fR" 4
|
||
.IX Item "source"
|
||
Re-write address to appear as if wrapped daemon is connecting
|
||
from the \s-1SSL\s0 client machine instead of the machine running \fBstunnel\fR.
|
||
.Sp
|
||
This option is currently available in:
|
||
.RS 4
|
||
.IP "Remote mode (\fIconnect\fR option) on \fILinux >=2.6.28\fR" 4
|
||
.IX Item "Remote mode (connect option) on Linux >=2.6.28"
|
||
This configuration requires stunnel to be executed as root and without
|
||
\&\fIsetuid\fR option.
|
||
.Sp
|
||
This configuration requires the following setup for iptables and routing
|
||
(possibly in /etc/rc.local or equivalent file):
|
||
.Sp
|
||
.Vb 7
|
||
\& 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
|
||
.Ve
|
||
.Sp
|
||
\&\fBstunnel\fR must also to be executed as root and without \fIsetuid\fR option.
|
||
.IP "Remote mode (\fIconnect\fR option) on \fILinux 2.2.x\fR" 4
|
||
.IX Item "Remote mode (connect option) on Linux 2.2.x"
|
||
This configuration requires kernel to be compiled with \fItransparent proxy\fR option.
|
||
Connected service must be installed on a separate host.
|
||
Routing towards the clients has to go through the stunnel box.
|
||
.Sp
|
||
\&\fBstunnel\fR must also to be executed as root and without \fIsetuid\fR option.
|
||
.IP "Remote mode (\fIconnect\fR option) on \fIFreeBSD >=8.0\fR" 4
|
||
.IX Item "Remote mode (connect option) on FreeBSD >=8.0"
|
||
This configuration requires additional firewall and routing setup.
|
||
\&\fBstunnel\fR must also to be executed as root and without \fIsetuid\fR option.
|
||
.IP "Local mode (\fIexec\fR option)" 4
|
||
.IX Item "Local mode (exec option)"
|
||
This configuration works by pre-loading \fIlibstunnel.so\fR shared library.
|
||
_RLD_LIST environment variable is used on Tru64, and \s-1LD_PRELOAD\s0 variable on
|
||
other platforms.
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fIdestination\fR" 4
|
||
.IX Item "destination"
|
||
Original destination is used instead of \fIconnect\fR option.
|
||
.Sp
|
||
A service section for transparent destination may look like this:
|
||
.Sp
|
||
.Vb 4
|
||
\& [transparent]
|
||
\& client=yes
|
||
\& accept=<stunnel_port>
|
||
\& transparent=destination
|
||
.Ve
|
||
.Sp
|
||
This configuration requires the following setup for iptables
|
||
(possibly in /etc/rc.local or equivalent file):
|
||
.Sp
|
||
.Vb 2
|
||
\& /sbin/iptables \-I INPUT \-i eth0 \-p tcp \-\-dport <stunnel_port> \-j ACCEPT
|
||
\& /sbin/iptables \-t nat \-I PREROUTING \-i eth0 \-p tcp \-\-dport <redirected_port> \-j DNAT \-\-to\-destination <local_ip>:<stunnel_port>
|
||
.Ve
|
||
.Sp
|
||
Transparent destination option is currently only supported on Linux.
|
||
.IP "\fIboth\fR" 4
|
||
.IX Item "both"
|
||
Use both \fIsource\fR and \fIdestination\fR transparent proxy.
|
||
.RE
|
||
.RS 4
|
||
.Sp
|
||
Two legacy options are also supported for backward compatibility:
|
||
.IP "\fIyes\fR" 4
|
||
.IX Item "yes"
|
||
This options has been renamed to \fIsource\fR.
|
||
.IP "\fIno\fR" 4
|
||
.IX Item "no"
|
||
This options has been renamed to \fInone\fR.
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fBverify\fR = level" 4
|
||
.IX Item "verify = level"
|
||
verify peer certificate
|
||
.RS 4
|
||
.IP "\fIlevel 0\fR \- request and ignore peer certificate" 4
|
||
.IX Item "level 0 - request and ignore peer certificate"
|
||
.PD 0
|
||
.IP "\fIlevel 1\fR \- verify peer certificate if present" 4
|
||
.IX Item "level 1 - verify peer certificate if present"
|
||
.IP "\fIlevel 2\fR \- verify peer certificate" 4
|
||
.IX Item "level 2 - verify peer certificate"
|
||
.IP "\fIlevel 3\fR \- verify peer with locally installed certificate" 4
|
||
.IX Item "level 3 - verify peer with locally installed certificate"
|
||
.IP "\fIlevel 4\fR \- ignore \s-1CA\s0 chain and only verify peer certificate" 4
|
||
.IX Item "level 4 - ignore CA chain and only verify peer certificate"
|
||
.IP "\fIdefault\fR \- no verify" 4
|
||
.IX Item "default - no verify"
|
||
.RE
|
||
.RS 4
|
||
.PD
|
||
.Sp
|
||
It is important to understand, that this option was solely designed for access
|
||
control and not for authorization. Specifically for level 2 every non-revoked
|
||
certificate is accepted regardless of its Common Name. For this reason a
|
||
dedicated \s-1CA\s0 should be used with level 2, and not a generic \s-1CA\s0 commonly used
|
||
for webservers. Level 3 is preferred for point-to-point connections.
|
||
.RE
|
||
.SH "RETURN VALUE"
|
||
.IX Header "RETURN VALUE"
|
||
\&\fBstunnel\fR returns zero on success, non-zero on error.
|
||
.SH "SIGNALS"
|
||
.IX Header "SIGNALS"
|
||
The following signals can be used to control stunnel in Unix environment:
|
||
.IP "\s-1SIGHUP\s0" 4
|
||
.IX Item "SIGHUP"
|
||
Force a reload of the configuration file.
|
||
.Sp
|
||
Some global options will not be reloaded:
|
||
.RS 4
|
||
.IP "\(bu" 4
|
||
chroot
|
||
.IP "\(bu" 4
|
||
foreground
|
||
.IP "\(bu" 4
|
||
pid
|
||
.IP "\(bu" 4
|
||
setgid
|
||
.IP "\(bu" 4
|
||
setuid
|
||
.RE
|
||
.RS 4
|
||
.Sp
|
||
The use of 'setuid' option will also prevent stunnel from binding privileged
|
||
(<1024) ports during configuration reloading.
|
||
.Sp
|
||
When 'chroot' option is used, stunnel will look for all its files (including
|
||
configuration file, certificates, log file and pid file) within the chroot
|
||
jail.
|
||
.RE
|
||
.IP "\s-1SIGUSR1\s0" 4
|
||
.IX Item "SIGUSR1"
|
||
Close and reopen stunnel log file.
|
||
This function can be used for log rotation.
|
||
.IP "\s-1SIGTERM\s0, \s-1SIGQUIT\s0, \s-1SIGINT\s0" 4
|
||
.IX Item "SIGTERM, SIGQUIT, SIGINT"
|
||
Shut stunnel down.
|
||
.PP
|
||
The result of sending any other signals to the server is undefined.
|
||
.SH "EXAMPLES"
|
||
.IX Header "EXAMPLES"
|
||
In order to provide \s-1SSL\s0 encapsulation to your local \fIimapd\fR service, use
|
||
.PP
|
||
.Vb 4
|
||
\& [imapd]
|
||
\& accept = 993
|
||
\& exec = /usr/sbin/imapd
|
||
\& execargs = imapd
|
||
.Ve
|
||
.PP
|
||
If you want to provide tunneling to your \fIpppd\fR daemon on port 2020,
|
||
use something like
|
||
.PP
|
||
.Vb 5
|
||
\& [vpn]
|
||
\& accept = 2020
|
||
\& exec = /usr/sbin/pppd
|
||
\& execargs = pppd local
|
||
\& pty = yes
|
||
.Ve
|
||
.PP
|
||
If you want to use \fBstunnel\fR in \fIinetd\fR mode to launch your imapd
|
||
process, you'd use this \fIstunnel.conf\fR.
|
||
Note there must be no \fI[service_name]\fR section.
|
||
.PP
|
||
.Vb 2
|
||
\& exec = /usr/sbin/imapd
|
||
\& execargs = imapd
|
||
.Ve
|
||
.SH "NOTES"
|
||
.IX Header "NOTES"
|
||
.SS "\s-1RESTRICTIONS\s0"
|
||
.IX Subsection "RESTRICTIONS"
|
||
\&\fBstunnel\fR cannot be used for the \s-1FTP\s0 daemon because of the nature
|
||
of the \s-1FTP\s0 protocol which utilizes multiple ports for data transfers.
|
||
There are available \s-1SSL\s0 enabled versions of \s-1FTP\s0 and telnet daemons, however.
|
||
.SS "\s-1INETD\s0 \s-1MODE\s0"
|
||
.IX Subsection "INETD MODE"
|
||
The most common use of \fBstunnel\fR is to listen on a network
|
||
port and establish communication with either a new port
|
||
via the connect option, or a new program via the \fIexec\fR option.
|
||
However there is a special case when you wish to have
|
||
some other program accept incoming connections and
|
||
launch \fBstunnel\fR, for example with \fIinetd\fR, \fIxinetd\fR,
|
||
or \fItcpserver\fR.
|
||
.PP
|
||
For example, if you have the following line in \fIinetd.conf\fR:
|
||
.PP
|
||
.Vb 1
|
||
\& imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
|
||
.Ve
|
||
.PP
|
||
In these cases, the \fIinetd\fR\-style program is responsible
|
||
for binding a network socket (\fIimaps\fR above) and handing
|
||
it to \fBstunnel\fR when a connection is received.
|
||
Thus you do not want \fBstunnel\fR to have any \fIaccept\fR option.
|
||
All the \fIService Level Options\fR should be placed in the
|
||
global options section, and no \fI[service_name]\fR section
|
||
will be present. See the \fI\s-1EXAMPLES\s0\fR section for example
|
||
configurations.
|
||
.SS "\s-1CERTIFICATES\s0"
|
||
.IX Subsection "CERTIFICATES"
|
||
Each \s-1SSL\s0 enabled daemon needs to present a valid X.509 certificate
|
||
to the peer. It also needs a private key to decrypt the incoming
|
||
data. The easiest way to obtain a certificate and a key is to
|
||
generate them with the free \fIOpenSSL\fR package. You can find more
|
||
information on certificates generation on pages listed below.
|
||
.PP
|
||
The order of contents of the \fI.pem\fR file is important. It should contain the
|
||
unencrypted private key first, then a signed certificate (not certificate
|
||
request). There should be also empty lines after certificate and private key.
|
||
Plaintext certificate information appended on the top of generated certificate
|
||
should be discarded. So the file should look like this:
|
||
.PP
|
||
.Vb 8
|
||
\& \-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-
|
||
\& [encoded key]
|
||
\& \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-
|
||
\& [empty line]
|
||
\& \-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-
|
||
\& [encoded certificate]
|
||
\& \-\-\-\-\-END CERTIFICATE\-\-\-\-\-
|
||
\& [empty line]
|
||
.Ve
|
||
.SS "\s-1RANDOMNESS\s0"
|
||
.IX Subsection "RANDOMNESS"
|
||
\&\fBstunnel\fR needs to seed the \s-1PRNG\s0 (pseudo random number generator) in
|
||
order for \s-1SSL\s0 to use good randomness. The following sources are loaded
|
||
in order until sufficient random data has been gathered:
|
||
.IP "\(bu" 4
|
||
The file specified with the \fIRNDfile\fR flag.
|
||
.IP "\(bu" 4
|
||
The file specified by the \s-1RANDFILE\s0 environment variable, if set.
|
||
.IP "\(bu" 4
|
||
The file .rnd in your home directory, if \s-1RANDFILE\s0 not set.
|
||
.IP "\(bu" 4
|
||
The file specified with '\-\-with\-random' at compile time.
|
||
.IP "\(bu" 4
|
||
The contents of the screen if running on Windows.
|
||
.IP "\(bu" 4
|
||
The egd socket specified with the \fI\s-1EGD\s0\fR flag.
|
||
.IP "\(bu" 4
|
||
The egd socket specified with '\-\-with\-egd\-sock' at compile time.
|
||
.IP "\(bu" 4
|
||
The /dev/urandom device.
|
||
.PP
|
||
With recent (>=OpenSSL 0.9.5a) version of \s-1SSL\s0 it will stop loading
|
||
random data automatically when sufficient entropy has been gathered.
|
||
With previous versions it will continue to gather from all the above
|
||
sources since no \s-1SSL\s0 function exists to tell when enough data is available.
|
||
.PP
|
||
Note that on Windows machines that do not have console user interaction
|
||
(mouse movements, creating windows, etc.) the screen contents are not
|
||
variable enough to be sufficient, and you should provide a random file
|
||
for use with the \fIRNDfile\fR flag.
|
||
.PP
|
||
Note that the file specified with the \fIRNDfile\fR flag should contain
|
||
random data \*(-- that means it should contain different information
|
||
each time \fBstunnel\fR is run. This is handled automatically
|
||
unless the \fIRNDoverwrite\fR flag is used. If you wish to update this file
|
||
manually, the \fIopenssl rand\fR command in recent versions of OpenSSL,
|
||
would be useful.
|
||
.PP
|
||
One important note \*(-- if /dev/urandom is available, OpenSSL has a habit of
|
||
seeding the \s-1PRNG\s0 with it even when checking the random state, so on
|
||
systems with /dev/urandom you're likely to use it even though it's listed
|
||
at the very bottom of the list above. This isn't \fBstunnel's\fR behaviour, it's
|
||
OpenSSLs.
|
||
.SS "\s-1DH\s0 \s-1PARAMETERS\s0"
|
||
.IX Subsection "DH PARAMETERS"
|
||
Stunnel 4.40 and later contains hardcoded 2048\-bit \s-1DH\s0 parameters.
|
||
.PP
|
||
It is also possible to specify \s-1DH\s0 parameters in the certificate file:
|
||
.PP
|
||
.Vb 1
|
||
\& openssl dhparam 2048 >> stunnel.pem
|
||
.Ve
|
||
.PP
|
||
\&\s-1DH\s0 parameter generation may take several minutes.
|
||
.SH "FILES"
|
||
.IX Header "FILES"
|
||
.IP "\fIstunnel.conf\fR" 4
|
||
.IX Item "stunnel.conf"
|
||
\&\fBstunnel\fR configuration file
|
||
.SH "BUGS"
|
||
.IX Header "BUGS"
|
||
Option \fIexecargs\fR does not support quoting.
|
||
.SH "SEE ALSO"
|
||
.IX Header "SEE ALSO"
|
||
.IP "\fItcpd\fR\|(8)" 4
|
||
.IX Item "tcpd"
|
||
access control facility for internet services
|
||
.IP "\fIinetd\fR\|(8)" 4
|
||
.IX Item "inetd"
|
||
internet 'super\-server'
|
||
.IP "\fIhttp://www.stunnel.org/\fR" 4
|
||
.IX Item "http://www.stunnel.org/"
|
||
\&\fBstunnel\fR homepage
|
||
.IP "\fIhttp://www.openssl.org/\fR" 4
|
||
.IX Item "http://www.openssl.org/"
|
||
OpenSSL project website
|
||
.SH "AUTHOR"
|
||
.IX Header "AUTHOR"
|
||
.IP "Michał Trojnara" 4
|
||
.IX Item "Michał Trojnara"
|
||
<\fIMichal.Trojnara@mirt.net\fR>
|