1396 lines
48 KiB
Groff
1396 lines
48 KiB
Groff
.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
|
||
.\"
|
||
.\" 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" ''
|
||
. ds C`
|
||
. ds C'
|
||
'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.
|
||
.\"
|
||
.\" Avoid warning from groff about undefined register 'F'.
|
||
.de IX
|
||
..
|
||
.nr rF 0
|
||
.if \n(.g .if rF .nr rF 1
|
||
.if (\n(rF:(\n(.g==0)) \{
|
||
. if \nF \{
|
||
. de IX
|
||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
..
|
||
. if !\nF==2 \{
|
||
. nr % 0
|
||
. nr F 2
|
||
. \}
|
||
. \}
|
||
.\}
|
||
.rr rF
|
||
.\" ========================================================================
|
||
.\"
|
||
.IX Title "stunnel 8"
|
||
.TH stunnel 8 "2017.04.01" "5.42" "stunnel TLS Proxy"
|
||
.\" 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 \- TLS offloading and load\-balancing proxy
|
||
.SH "SYNOPSIS"
|
||
.IX Header "SYNOPSIS"
|
||
.IP "\fBUnix:\fR" 4
|
||
.IX Item "Unix:"
|
||
\&\fBstunnel\fR [\s-1FILE\s0] | \-fd N | \-help | \-version | \-sockets | \-options
|
||
.IP "\fB\s-1WIN32:\s0\fR" 4
|
||
.IX Item "WIN32:"
|
||
\&\fBstunnel\fR [ [ \-install | \-uninstall | \-start | \-stop |
|
||
\-reload | \-reopen | \-exit ] [\-quiet] [\s-1FILE\s0] ] |
|
||
\-help | \-version | \-sockets | \-options
|
||
.SH "DESCRIPTION"
|
||
.IX Header "DESCRIPTION"
|
||
The \fBstunnel\fR program is designed to work as \fI\s-1TLS\s0\fR encryption wrapper
|
||
between remote clients and local (\fIinetd\fR\-startable) or remote
|
||
servers. The concept is that having non-TLS aware daemons running on
|
||
your system you can easily set them up to communicate with clients over
|
||
secure \fI\s-1TLS\s0\fR channels.
|
||
.PP
|
||
\&\fBstunnel\fR can be used to add \fI\s-1TLS\s0\fR functionality to commonly used \fIInetd\fR
|
||
daemons like \s-1POP\-2, POP\-3,\s0 and \s-1IMAP\s0 servers, to standalone daemons like
|
||
\&\s-1NNTP, SMTP\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 "\fB\s-1FILE\s0\fR" 4
|
||
.IX Item "FILE"
|
||
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\-options\fR" 4
|
||
.IX Item "-options"
|
||
Print supported \s-1TLS\s0 options
|
||
.IP "\fB\-install\fR (Windows \s-1NT\s0 and later only)" 4
|
||
.IX Item "-install (Windows NT and later only)"
|
||
Install \s-1NT\s0 Service
|
||
.IP "\fB\-uninstall\fR (Windows \s-1NT\s0 and later only)" 4
|
||
.IX Item "-uninstall (Windows NT and later only)"
|
||
Uninstall \s-1NT\s0 Service
|
||
.IP "\fB\-start\fR (Windows \s-1NT\s0 and later only)" 4
|
||
.IX Item "-start (Windows NT and later only)"
|
||
Start \s-1NT\s0 Service
|
||
.IP "\fB\-stop\fR (Windows \s-1NT\s0 and later only)" 4
|
||
.IX Item "-stop (Windows NT and later only)"
|
||
Stop \s-1NT\s0 Service
|
||
.IP "\fB\-reload\fR (Windows \s-1NT\s0 and later only)" 4
|
||
.IX Item "-reload (Windows NT and later only)"
|
||
Reload the configuration file of the running \s-1NT\s0 Service
|
||
.IP "\fB\-reopen\fR (Windows \s-1NT\s0 and later only)" 4
|
||
.IX Item "-reopen (Windows NT and later only)"
|
||
Reopen the log file of the running \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 (Win32 only)" 4
|
||
.IX Item "-quiet (Win32 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 OPTIONS\s0"
|
||
.IX Subsection "GLOBAL OPTIONS"
|
||
.IP "\fBchroot\fR = \s-1DIRECTORY \s0(Unix only)" 4
|
||
.IX Item "chroot = DIRECTORY (Unix only)"
|
||
directory to chroot \fBstunnel\fR process
|
||
.Sp
|
||
\&\fBchroot\fR keeps \fBstunnel\fR in a 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.
|
||
.Sp
|
||
Several functions of the operating system also need their files to be located within the chroot jail, e.g.:
|
||
.RS 4
|
||
.IP "\(bu" 4
|
||
Delayed resolver typically needs /etc/nsswitch.conf and /etc/resolv.conf.
|
||
.IP "\(bu" 4
|
||
Local time in log files needs /etc/timezone.
|
||
.IP "\(bu" 4
|
||
Some other functions may need devices, e.g. /dev/zero or /dev/null.
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fBcompression\fR = deflate | zlib" 4
|
||
.IX Item "compression = deflate | zlib"
|
||
select data compression algorithm
|
||
.Sp
|
||
default: no compression
|
||
.Sp
|
||
Deflate is the standard compression method as described in \s-1RFC 1951.\s0
|
||
.IP "\fBdebug\fR = [\s-1FACILITY.\s0]LEVEL" 4
|
||
.IX Item "debug = [FACILITY.]LEVEL"
|
||
debugging level
|
||
.Sp
|
||
Level is 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 = \s-1EGD_PATH \s0(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 the \fBOpenSSL\fR random number
|
||
generator.
|
||
.IP "\fBengine\fR = auto | \s-1ENGINE_ID\s0" 4
|
||
.IX Item "engine = auto | ENGINE_ID"
|
||
select hardware or software cryptographic engine
|
||
.Sp
|
||
default: software-only cryptography
|
||
.Sp
|
||
See Examples section for an engine configuration to use the certificate and the corresponding private key from a cryptographic device.
|
||
.IP "\fBengineCtrl\fR = COMMAND[:PARAMETER]" 4
|
||
.IX Item "engineCtrl = COMMAND[:PARAMETER]"
|
||
control hardware engine
|
||
.IP "\fBengineDefault\fR = \s-1TASK_LIST\s0" 4
|
||
.IX Item "engineDefault = TASK_LIST"
|
||
set OpenSSL tasks delegated to the current engine
|
||
.Sp
|
||
The parameter specifies a comma-separated list of task to be delegated to the
|
||
current engine.
|
||
.Sp
|
||
The following tasks may be available, if supported by the engine: \s-1ALL, RSA,
|
||
DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1.\s0
|
||
.IP "\fBfips\fR = yes | no" 4
|
||
.IX Item "fips = yes | no"
|
||
enable or disable \s-1FIPS 140\-2\s0 mode.
|
||
.Sp
|
||
This option allows you to disable entering \s-1FIPS\s0 mode if \fBstunnel\fR was compiled
|
||
with \s-1FIPS 140\-2\s0 support.
|
||
.Sp
|
||
default: no (since version 5.00)
|
||
.IP "\fBforeground\fR = yes | quiet | no (Unix only)" 4
|
||
.IX Item "foreground = yes | quiet | no (Unix only)"
|
||
foreground mode
|
||
.Sp
|
||
Stay in foreground (don't fork).
|
||
.Sp
|
||
With the \fIyes\fR parameter it also logs to stderr in addition to
|
||
the destinations specified with \fIsyslog\fR and \fIoutput\fR.
|
||
.Sp
|
||
default: background in daemon mode
|
||
.IP "\fBiconActive\fR = \s-1ICON_FILE \s0(\s-1GUI\s0 only)" 4
|
||
.IX Item "iconActive = ICON_FILE (GUI only)"
|
||
\&\s-1GUI\s0 icon to be displayed when there are established connections
|
||
.Sp
|
||
On Windows platform the parameter should be an .ico file containing a 16x16
|
||
pixel image.
|
||
.IP "\fBiconError\fR = \s-1ICON_FILE \s0(\s-1GUI\s0 only)" 4
|
||
.IX Item "iconError = ICON_FILE (GUI only)"
|
||
\&\s-1GUI\s0 icon to be displayed when no valid configuration is loaded
|
||
.Sp
|
||
On Windows platform the parameter should be an .ico file containing a 16x16
|
||
pixel image.
|
||
.IP "\fBiconIdle\fR = \s-1ICON_FILE \s0(\s-1GUI\s0 only)" 4
|
||
.IX Item "iconIdle = ICON_FILE (GUI only)"
|
||
\&\s-1GUI\s0 icon to be displayed when there are no established connections
|
||
.Sp
|
||
On Windows platform the parameter should be an .ico file containing a 16x16
|
||
pixel image.
|
||
.IP "\fBlog\fR = append | overwrite" 4
|
||
.IX Item "log = append | overwrite"
|
||
log file handling
|
||
.Sp
|
||
This option allows you to choose whether the log file (specified with the \fIoutput\fR
|
||
option) is appended or overwritten when opened or re-opened.
|
||
.Sp
|
||
default: append
|
||
.IP "\fBoutput\fR = \s-1FILE\s0" 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 = \s-1FILE \s0(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 the \fIchroot\fR directory if specified.
|
||
.IP "\fBRNDbytes\fR = \s-1BYTES\s0" 4
|
||
.IX Item "RNDbytes = BYTES"
|
||
bytes to read from random seed files
|
||
.IP "\fBRNDfile\fR = \s-1FILE\s0" 4
|
||
.IX Item "RNDfile = FILE"
|
||
path to file with random seed data
|
||
.Sp
|
||
The OpenSSL 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 = \s-1SERVICE \s0(Unix only)" 4
|
||
.IX Item "service = SERVICE (Unix only)"
|
||
stunnel service name
|
||
.Sp
|
||
The specified service name is used for syslog and as the \fIinetd\fR mode service
|
||
name for \s-1TCP\s0 Wrappers. While this option can technically be specified in the
|
||
service sections, it is only useful in global options.
|
||
.Sp
|
||
default: stunnel
|
||
.IP "\fBsocket\fR = a|l|r:OPTION=VALUE[:VALUE]" 4
|
||
.IX Item "socket = a|l|r:OPTION=VALUE[:VALUE]"
|
||
Set an option on the accept/local/remote socket
|
||
.Sp
|
||
The values for the linger option are l_onof:l_linger.
|
||
The values for the 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 a 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 MODE\s0\fR
|
||
below.
|
||
.IP "\fBaccept\fR = [\s-1HOST:\s0]PORT" 4
|
||
.IX Item "accept = [HOST:]PORT"
|
||
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
|
||
\& accept = :::PORT
|
||
.Ve
|
||
.IP "\fBCApath\fR = \s-1DIRECTORY\s0" 4
|
||
.IX Item "CApath = DIRECTORY"
|
||
Certificate Authority directory
|
||
.Sp
|
||
This is the directory in which \fBstunnel\fR will look for certificates when using
|
||
the \fIverifyChain\fR or \fIverifyPeer\fR options. Note that the certificates in
|
||
this directory should be named \s-1XXXXXXXX.0\s0 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 \fBOpenSSL 1.0.0\fR. It is required to
|
||
c_rehash the directory on upgrade from \fBOpenSSL 0.x.x\fR to \fBOpenSSL 1.x.x\fR.
|
||
.Sp
|
||
\&\fICApath\fR path is relative to the \fIchroot\fR directory if specified.
|
||
.IP "\fBCAfile\fR = \s-1CA_FILE\s0" 4
|
||
.IX Item "CAfile = CA_FILE"
|
||
Certificate Authority file
|
||
.Sp
|
||
This file contains multiple \s-1CA\s0 certificates, to be used with the \fIverifyChain\fR
|
||
and \fIverifyPeer\fR options.
|
||
.IP "\fBcert\fR = \s-1CERT_FILE\s0" 4
|
||
.IX Item "cert = CERT_FILE"
|
||
certificate chain file name
|
||
.Sp
|
||
The parameter specifies the file containing certificates used by \fBstunnel\fR
|
||
to authenticate itself against the remote client or server.
|
||
The file should contain the whole certificate chain starting from the actual
|
||
server/client certificate, and ending with the self-signed root \s-1CA\s0 certificate.
|
||
The file must be either in \s-1PEM\s0 or P12 format.
|
||
.Sp
|
||
A certificate chain is required in server mode, and optional in client mode.
|
||
.Sp
|
||
This parameter is also used as the certificate identifier when a hardware
|
||
engine is enabled.
|
||
.IP "\fBcheckEmail\fR = \s-1EMAIL\s0" 4
|
||
.IX Item "checkEmail = EMAIL"
|
||
email address of the peer certificate subject
|
||
.Sp
|
||
Multiple \fIcheckEmail\fR options are allowed in a single service section.
|
||
Certificates are accepted if no \fIcheckEmail\fR option was specified, or the
|
||
email address of the peer certificate matches any of the email addresses
|
||
specified with \fIcheckEmail\fR.
|
||
.Sp
|
||
This option requires OpenSSL 1.0.2 or later.
|
||
.IP "\fBcheckHost\fR = \s-1HOST\s0" 4
|
||
.IX Item "checkHost = HOST"
|
||
host of the peer certificate subject
|
||
.Sp
|
||
Multiple \fIcheckHost\fR options are allowed in a single service section.
|
||
Certificates are accepted if no \fIcheckHost\fR option was specified, or the host
|
||
name of the peer certificate matches any of the hosts specified with
|
||
\&\fIcheckHost\fR.
|
||
.Sp
|
||
This option requires OpenSSL 1.0.2 or later.
|
||
.IP "\fBcheckIP\fR = \s-1IP\s0" 4
|
||
.IX Item "checkIP = IP"
|
||
\&\s-1IP\s0 address of the peer certificate subject
|
||
.Sp
|
||
Multiple \fIcheckIP\fR options are allowed in a single service section.
|
||
Certificates are accepted if no \fIcheckIP\fR option was specified, or the \s-1IP\s0
|
||
address of the peer certificate matches any of the \s-1IP\s0 addresses specified with
|
||
\&\fIcheckIP\fR.
|
||
.Sp
|
||
This option requires OpenSSL 1.0.2 or later.
|
||
.IP "\fBciphers\fR = \s-1CIPHER_LIST\s0" 4
|
||
.IX Item "ciphers = CIPHER_LIST"
|
||
Select permitted \s-1TLS\s0 ciphers
|
||
.Sp
|
||
A colon-delimited list of the ciphers to allow in the \s-1TLS\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-1TLS\s0)
|
||
.Sp
|
||
default: no (server mode)
|
||
.IP "\fBconfig\fR = COMMAND[:PARAMETER]" 4
|
||
.IX Item "config = COMMAND[:PARAMETER]"
|
||
\&\fBOpenSSL\fR configuration command
|
||
.Sp
|
||
The \fBOpenSSL\fR configuration command is executed with the specified parameter.
|
||
This allows any configuration commands to be invoked from the stunnel
|
||
configuration file. Supported commands are described on the
|
||
\&\fI\fISSL_CONF_cmd\fI\|(3ssl)\fR manual page.
|
||
.Sp
|
||
Several \fIconfig\fR lines can be used to specify multiple configuration commands.
|
||
.Sp
|
||
This option requires OpenSSL 1.0.2 or later.
|
||
.IP "\fBconnect\fR = [\s-1HOST:\s0]PORT" 4
|
||
.IX Item "connect = [HOST:]PORT"
|
||
connect to a remote address
|
||
.Sp
|
||
If no host is specified, the host defaults to localhost.
|
||
.Sp
|
||
Multiple \fIconnect\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 = \s-1DIRECTORY\s0" 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
|
||
\&\fIverifyChain\fR and \fIverifyPeer\fR options. 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 \fBOpenSSL 1.0.0\fR. It is required to
|
||
c_rehash the directory on upgrade from \fBOpenSSL 0.x.x\fR to \fBOpenSSL 1.x.x\fR.
|
||
.Sp
|
||
\&\fICRLpath\fR path is relative to the \fIchroot\fR directory if specified.
|
||
.IP "\fBCRLfile\fR = \s-1CRL_FILE\s0" 4
|
||
.IX Item "CRLfile = CRL_FILE"
|
||
Certificate Revocation Lists file
|
||
.Sp
|
||
This file contains multiple CRLs, used with the \fIverifyChain\fR and
|
||
\&\fIverifyPeer\fR options.
|
||
.IP "\fBcurve\fR = \s-1NID\s0" 4
|
||
.IX Item "curve = NID"
|
||
specify \s-1ECDH\s0 curve name
|
||
.Sp
|
||
To get a list of supported curves use:
|
||
.Sp
|
||
.Vb 1
|
||
\& openssl ecparam \-list_curves
|
||
.Ve
|
||
.Sp
|
||
default: prime256v1
|
||
.IP "\fBlogId\fR = \s-1TYPE\s0" 4
|
||
.IX Item "logId = TYPE"
|
||
connection identifier type
|
||
.Sp
|
||
This identifier allows you to distinguish log entries generated for each of the
|
||
connections.
|
||
.Sp
|
||
Currently supported types:
|
||
.RS 4
|
||
.IP "\fIsequential\fR" 4
|
||
.IX Item "sequential"
|
||
The numeric sequential identifier is only unique within a single instance of
|
||
\&\fBstunnel\fR, but very compact. It is most useful for manual log analysis.
|
||
.IP "\fIunique\fR" 4
|
||
.IX Item "unique"
|
||
This alphanumeric identifier is globally unique, but longer than the sequential
|
||
number. It is most useful for automated log analysis.
|
||
.IP "\fIthread\fR" 4
|
||
.IX Item "thread"
|
||
The operating system thread identifier is neither unique (even within a single
|
||
instance of \fBstunnel\fR) nor short. It is most useful for debugging software
|
||
or configuration issues.
|
||
.IP "\fIprocess\fR" 4
|
||
.IX Item "process"
|
||
The operating system process identifier (\s-1PID\s0) may be useful in the inetd mode.
|
||
.RE
|
||
.RS 4
|
||
.Sp
|
||
default: sequential
|
||
.RE
|
||
.IP "\fBdebug\fR = \s-1LEVEL\s0" 4
|
||
.IX Item "debug = 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).
|
||
.IP "\fBdelay\fR = yes | no" 4
|
||
.IX Item "delay = yes | no"
|
||
delay \s-1DNS\s0 lookup for the \fIconnect\fR option
|
||
.Sp
|
||
This option is useful for dynamic \s-1DNS,\s0 or when \s-1DNS\s0 is not available during
|
||
\&\fBstunnel\fR startup (road warrior \s-1VPN,\s0 dial-up configurations).
|
||
.Sp
|
||
Delayed resolver mode is automatically engaged when stunnel fails to resolve on
|
||
startup any of the \fIconnect\fR targets for a service.
|
||
.Sp
|
||
Delayed resolver inflicts \fIfailover = prio\fR.
|
||
.Sp
|
||
default: no
|
||
.IP "\fBengineId\fR = \s-1ENGINE_ID\s0" 4
|
||
.IX Item "engineId = ENGINE_ID"
|
||
select engine \s-1ID\s0 for the service
|
||
.IP "\fBengineNum\fR = \s-1ENGINE_NUMBER\s0" 4
|
||
.IX Item "engineNum = ENGINE_NUMBER"
|
||
select engine number for the service
|
||
.Sp
|
||
The engines are numbered starting from 1.
|
||
.IP "\fBexec\fR = \s-1EXECUTABLE_PATH\s0" 4
|
||
.IX Item "exec = EXECUTABLE_PATH"
|
||
execute a local inetd-type program
|
||
.Sp
|
||
\&\fIexec\fR path is relative to the \fIchroot\fR directory if specified.
|
||
.Sp
|
||
The following environmental variables are set on Unix platforms:
|
||
\&\s-1REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.\s0
|
||
.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 the program name ($0)
|
||
.Sp
|
||
Quoting is currently not supported.
|
||
Arguments are separated with an arbitrary amount of whitespace.
|
||
.IP "\fBfailover\fR = rr | prio" 4
|
||
.IX Item "failover = rr | prio"
|
||
Failover strategy for multiple \*(L"connect\*(R" targets.
|
||
.RS 4
|
||
.IP "\fIrr\fR" 4
|
||
.IX Item "rr"
|
||
round robin \- fair load distribution
|
||
.IP "\fIprio\fR" 4
|
||
.IX Item "prio"
|
||
priority \- use the order specified in config file
|
||
.RE
|
||
.RS 4
|
||
.Sp
|
||
default: rr
|
||
.RE
|
||
.IP "\fBident\fR = \s-1USERNAME\s0" 4
|
||
.IX Item "ident = USERNAME"
|
||
use \s-1IDENT \s0(\s-1RFC 1413\s0) username checking
|
||
.IP "\fBinclude\fR = \s-1DIRECTORY\s0" 4
|
||
.IX Item "include = DIRECTORY"
|
||
include all configuration file parts located in \s-1DIRECTORY\s0
|
||
.Sp
|
||
The files are included in the ascending alphabetical order of their names.
|
||
.IP "\fBkey\fR = \s-1KEY_FILE\s0" 4
|
||
.IX Item "key = KEY_FILE"
|
||
private key for the certificate specified with \fIcert\fR option
|
||
.Sp
|
||
A private key is needed to authenticate the certificate owner.
|
||
Since this file should be kept secret it should only be readable
|
||
by its owner. On Unix systems you can use the following command:
|
||
.Sp
|
||
.Vb 1
|
||
\& chmod 600 keyfile
|
||
.Ve
|
||
.Sp
|
||
This parameter is also used as the private key identifier when a hardware
|
||
engine is enabled.
|
||
.Sp
|
||
default: the value of the \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: no (since version 5.00)
|
||
.IP "\fBlocal\fR = \s-1HOST\s0" 4
|
||
.IX Item "local = HOST"
|
||
By default, the \s-1IP\s0 address of the outgoing interface is used as the source for
|
||
remote connections. Use this option to bind a static local \s-1IP\s0 address instead.
|
||
.IP "\fB\s-1OCSP\s0\fR = \s-1URL\s0" 4
|
||
.IX Item "OCSP = URL"
|
||
select \s-1OCSP\s0 responder for certificate verification
|
||
.IP "\fBOCSPaia\fR = yes | no" 4
|
||
.IX Item "OCSPaia = yes | no"
|
||
validate certificates with their \s-1AIA OCSP\s0 responders
|
||
.Sp
|
||
This option enables \fIstunnel\fR to validate certificates with the list of
|
||
\&\s-1OCSP\s0 responder URLs retrieved from their \s-1AIA \s0(Authority Information Access)
|
||
extension.
|
||
.IP "\fBOCSPflag\fR = \s-1OCSP_FLAG\s0" 4
|
||
.IX Item "OCSPflag = OCSP_FLAG"
|
||
specify \s-1OCSP\s0 responder flag
|
||
.Sp
|
||
Several \fIOCSPflag\fR can be used to specify multiple flags.
|
||
.Sp
|
||
currently supported flags: \s-1NOCERTS, NOINTERN, NOSIGS, NOCHAIN, NOVERIFY,
|
||
NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER, RESPID_KEY, NOTIME\s0
|
||
.IP "\fBOCSPnonce\fR = yes | no" 4
|
||
.IX Item "OCSPnonce = yes | no"
|
||
send and verify the \s-1OCSP\s0 nonce extension
|
||
.Sp
|
||
This option protects the \s-1OCSP\s0 protocol against replay attacks. Due to its
|
||
computational overhead, the nonce extension is usually only supported on
|
||
internal (e.g. corporate) responders, and not on public \s-1OCSP\s0 responders.
|
||
.IP "\fBoptions\fR = \s-1SSL_OPTIONS\s0" 4
|
||
.IX Item "options = SSL_OPTIONS"
|
||
\&\fBOpenSSL\fR library options
|
||
.Sp
|
||
The parameter is the \fBOpenSSL\fR option name as described in the
|
||
\&\fI\fISSL_CTX_set_options\fI\|(3ssl)\fR manual, but without \fI\s-1SSL_OP_\s0\fR prefix.
|
||
\&\fIstunnel \-options\fR lists the options found to be allowed in the
|
||
current combination of \fIstunnel\fR and the \fIOpenSSL\fR library used
|
||
to build it.
|
||
.Sp
|
||
Several \fIoption\fR lines can be used to specify multiple options.
|
||
An option name can be prepended with a dash (\*(L"\-\*(R") to disable the option.
|
||
.Sp
|
||
For example, for compatibility with the erroneous Eudora \s-1TLS\s0
|
||
implementation, the following option can be used:
|
||
.Sp
|
||
.Vb 1
|
||
\& options = DONT_INSERT_EMPTY_FRAGMENTS
|
||
.Ve
|
||
.Sp
|
||
default:
|
||
.Sp
|
||
.Vb 2
|
||
\& options = NO_SSLv2
|
||
\& options = NO_SSLv3
|
||
.Ve
|
||
.IP "\fBprotocol\fR = \s-1PROTO\s0" 4
|
||
.IX Item "protocol = PROTO"
|
||
application protocol to negotiate \s-1TLS\s0
|
||
.Sp
|
||
This option enables initial, protocol-specific negotiation of the \s-1TLS\s0
|
||
encryption.
|
||
The \fIprotocol\fR option should not be used with \s-1TLS\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 2817 \- \s0\fIUpgrading to \s-1TLS\s0 Within \s-1HTTP/1.1\s0\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 2595 \- \s0\fIUsing \s-1TLS\s0 with \s-1IMAP, POP3\s0 and \s-1ACAP\s0\fR
|
||
.IP "\fInntp\fR" 4
|
||
.IX Item "nntp"
|
||
Based on \s-1RFC 4642 \- \s0\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
|
||
\&\fIhttp://www.postgresql.org/docs/8.3/static/protocol\-flow.html#AEN73982\fR
|
||
.IP "\fIpop3\fR" 4
|
||
.IX Item "pop3"
|
||
Based on \s-1RFC 2449 \- \s0\fI\s-1POP3\s0 Extension Mechanism\fR
|
||
.IP "\fIproxy\fR" 4
|
||
.IX Item "proxy"
|
||
Haproxy client \s-1IP\s0 address
|
||
\&\fIhttp://haproxy.1wt.eu/download/1.5/doc/proxy\-protocol.txt\fR
|
||
.IP "\fIsmtp\fR" 4
|
||
.IX Item "smtp"
|
||
Based on \s-1RFC 2487 \- \s0\fI\s-1SMTP\s0 Service Extension for Secure \s-1SMTP\s0 over \s-1TLS\s0\fR
|
||
.IP "\fIsocks\fR" 4
|
||
.IX Item "socks"
|
||
\&\s-1SOCKS\s0 versions 4, 4a, and 5 are supported. The \s-1SOCKS\s0 protocol itself
|
||
is encapsulated within \s-1TLS\s0 encryption layer to protect the final
|
||
destination address.
|
||
.Sp
|
||
\&\fIhttp://www.openssh.com/txt/socks4.protocol\fR
|
||
.Sp
|
||
\&\fIhttp://www.openssh.com/txt/socks4a.protocol\fR
|
||
.Sp
|
||
The \s-1BIND\s0 command of the \s-1SOCKS\s0 protocol is not supported.
|
||
The \s-1USERID\s0 parameter is ignored.
|
||
.Sp
|
||
See Examples section for sample configuration files for \s-1VPN\s0 based on \s-1SOCKS\s0
|
||
encryption.
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fBprotocolAuthentication\fR = \s-1AUTHENTICATION\s0" 4
|
||
.IX Item "protocolAuthentication = AUTHENTICATION"
|
||
authentication type for the protocol negotiations
|
||
.Sp
|
||
Currently, this option is only supported in the client-side 'connect' and
|
||
\&'smtp' protocols.
|
||
.Sp
|
||
Supported authentication types for the 'connect' protocol are 'basic' or
|
||
\&'ntlm'. The default 'connect' authentication type is 'basic'.
|
||
.Sp
|
||
Supported authentication types for the 'smtp' protocol are 'plain' or 'login'.
|
||
The default 'smtp' authentication type is 'plain'.
|
||
.IP "\fBprotocolDomain\fR = \s-1DOMAIN\s0" 4
|
||
.IX Item "protocolDomain = DOMAIN"
|
||
domain for the protocol negotiations
|
||
.Sp
|
||
Currently, this option is only supported in the client-side 'connect' protocol.
|
||
.IP "\fBprotocolHost\fR = \s-1HOST:PORT\s0" 4
|
||
.IX Item "protocolHost = HOST:PORT"
|
||
destination address for the protocol negotiations
|
||
.Sp
|
||
\&\fIprotocolHost\fR specifies the final \s-1TLS\s0 server to be connected to by the proxy,
|
||
and not the proxy server directly connected by \fBstunnel\fR.
|
||
The proxy server should be specified with the 'connect' option.
|
||
.Sp
|
||
Currently the protocol destination address only applies to the 'connect'
|
||
protocol.
|
||
.IP "\fBprotocolPassword\fR = \s-1PASSWORD\s0" 4
|
||
.IX Item "protocolPassword = PASSWORD"
|
||
password for the protocol negotiations
|
||
.Sp
|
||
Currently, this option is only supported in the client-side 'connect' and
|
||
\&'smtp' protocols.
|
||
.IP "\fBprotocolUsername\fR = \s-1USERNAME\s0" 4
|
||
.IX Item "protocolUsername = USERNAME"
|
||
username for the protocol negotiations
|
||
.Sp
|
||
Currently, this option is only supported in the client-side 'connect' and
|
||
\&'smtp' protocols.
|
||
.IP "\fBPSKidentity\fR = \s-1IDENTITY\s0" 4
|
||
.IX Item "PSKidentity = IDENTITY"
|
||
\&\s-1PSK\s0 identity for the \s-1PSK\s0 client
|
||
.Sp
|
||
\&\fIPSKidentity\fR can be used on \fBstunnel\fR clients to select the \s-1PSK\s0 identity
|
||
used for authentication. This option is ignored in server sections.
|
||
.Sp
|
||
default: the first identity specified in the \fIPSKsecrets\fR file.
|
||
.IP "\fBPSKsecrets\fR = \s-1FILE\s0" 4
|
||
.IX Item "PSKsecrets = FILE"
|
||
file with \s-1PSK\s0 identities and corresponding keys
|
||
.Sp
|
||
Each line of the file in the following format:
|
||
.Sp
|
||
.Vb 1
|
||
\& IDENTITY:KEY
|
||
.Ve
|
||
.Sp
|
||
The key is required to be at least 20 characters long.
|
||
The file should not be world-readable nor world-writable.
|
||
.IP "\fBpty\fR = yes | no (Unix only)" 4
|
||
.IX Item "pty = yes | no (Unix only)"
|
||
allocate a pseudoterminal for 'exec' option
|
||
.IP "\fBredirect\fR = [\s-1HOST:\s0]PORT" 4
|
||
.IX Item "redirect = [HOST:]PORT"
|
||
redirect \s-1TLS\s0 client connections on certificate-based authentication failures
|
||
.Sp
|
||
This option only works in server mode.
|
||
Some protocol negotiations are also incompatible with the \fIredirect\fR option.
|
||
.IP "\fBrenegotiation\fR = yes | no" 4
|
||
.IX Item "renegotiation = yes | no"
|
||
support \s-1TLS\s0 renegotiation
|
||
.Sp
|
||
Applications of the \s-1TLS\s0 renegotiation include some authentication scenarios,
|
||
or re-keying long lasting connections.
|
||
.Sp
|
||
On the other hand this feature can facilitate a trivial CPU-exhaustion
|
||
DoS attack:
|
||
.Sp
|
||
\&\fIhttp://vincent.bernat.im/en/blog/2011\-ssl\-dos\-mitigation.html\fR
|
||
.Sp
|
||
Please note that disabling \s-1TLS\s0 renegotiation does not fully mitigate
|
||
this issue.
|
||
.Sp
|
||
default: yes (if supported by \fBOpenSSL\fR)
|
||
.IP "\fBreset\fR = yes | no" 4
|
||
.IX Item "reset = yes | no"
|
||
attempt to use the \s-1TCP RST\s0 flag to indicate an error
|
||
.Sp
|
||
This option is not supported on some platforms.
|
||
.Sp
|
||
default: yes
|
||
.IP "\fBretry\fR = yes | no" 4
|
||
.IX Item "retry = yes | no"
|
||
reconnect a connect+exec section after it was disconnected
|
||
.Sp
|
||
default: no
|
||
.IP "\fBrequireCert\fR = yes | no" 4
|
||
.IX Item "requireCert = yes | no"
|
||
require a client certificate for \fIverifyChain\fR or \fIverifyPeer\fR
|
||
.Sp
|
||
With \fIrequireCert\fR set to \fIno\fR, the \fBstunnel\fR server accepts client
|
||
connections that did not present a certificate.
|
||
.Sp
|
||
Both \fIverifyChain = yes\fR and \fIverifyPeer = yes\fR imply \fIrequireCert = yes\fR.
|
||
.Sp
|
||
default: no
|
||
.IP "\fBsetgid\fR = \s-1GROUP \s0(Unix only)" 4
|
||
.IX Item "setgid = GROUP (Unix only)"
|
||
Unix group id
|
||
.Sp
|
||
As a global option: \fIsetgid()\fR to the specified group in daemon mode and clear all other groups.
|
||
.Sp
|
||
As a service-level option: set the group of the Unix socket specified with \*(L"accept\*(R".
|
||
.IP "\fBsetuid\fR = \s-1USER \s0(Unix only)" 4
|
||
.IX Item "setuid = USER (Unix only)"
|
||
Unix user id
|
||
.Sp
|
||
As a global option: \fIsetuid()\fR to the specified user in daemon mode.
|
||
.Sp
|
||
As a service-level option: set the owner of the Unix socket specified with \*(L"accept\*(R".
|
||
.IP "\fBsessionCacheSize\fR = \s-1NUM_ENTRIES\s0" 4
|
||
.IX Item "sessionCacheSize = NUM_ENTRIES"
|
||
session cache size
|
||
.Sp
|
||
\&\fIsessionCacheSize\fR specifies the maximum number of the internal session cache
|
||
entries.
|
||
.Sp
|
||
The value of 0 can be used for unlimited size. It is not recommended
|
||
for production use due to the risk of a memory exhaustion DoS attack.
|
||
.IP "\fBsessionCacheTimeout\fR = \s-1TIMEOUT\s0" 4
|
||
.IX Item "sessionCacheTimeout = TIMEOUT"
|
||
session cache timeout
|
||
.Sp
|
||
This is the number of seconds to keep cached \s-1TLS\s0 sessions.
|
||
.IP "\fBsessiond\fR = \s-1HOST:PORT\s0" 4
|
||
.IX Item "sessiond = HOST:PORT"
|
||
address of sessiond \s-1TLS\s0 cache server
|
||
.IP "\fBsni\fR = \s-1SERVICE_NAME:SERVER_NAME_PATTERN \s0(server mode)" 4
|
||
.IX Item "sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)"
|
||
Use the service as a slave service (a name-based virtual server) for Server
|
||
Name Indication \s-1TLS\s0 extension (\s-1RFC 3546\s0).
|
||
.Sp
|
||
\&\fI\s-1SERVICE_NAME\s0\fR specifies the master service that accepts client connections
|
||
with the \fIaccept\fR option. \fI\s-1SERVER_NAME_PATTERN\s0\fR specifies the host name to
|
||
be redirected. The pattern may start with the '*' character, e.g.
|
||
\&'*.example.com'. Multiple slave services are normally specified for a single
|
||
master service. The \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.
|
||
.Sp
|
||
The \fIconnect\fR option of the slave service is ignored when the \fIprotocol\fR
|
||
option is specified, as \fIprotocol\fR connects to the remote host before \s-1TLS\s0
|
||
handshake.
|
||
.Sp
|
||
Libwrap checks (Unix only) are performed twice: with the master service name
|
||
after \s-1TCP\s0 connection is accepted, and with the slave service name during the
|
||
\&\s-1TLS\s0 handshake.
|
||
.Sp
|
||
The \fIsni\fR option is only available when compiled with \fBOpenSSL 1.0.0\fR and
|
||
later.
|
||
.IP "\fBsni\fR = \s-1SERVER_NAME \s0(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 3546\s0)
|
||
extension.
|
||
.Sp
|
||
Empty \s-1SERVER_NAME\s0 disables sending the \s-1SNI\s0 extension.
|
||
.Sp
|
||
The \fIsni\fR option is only available when compiled with \fBOpenSSL 1.0.0\fR and
|
||
later.
|
||
.IP "\fBsslVersion\fR = \s-1SSL_VERSION\s0" 4
|
||
.IX Item "sslVersion = SSL_VERSION"
|
||
select the \s-1TLS\s0 protocol version
|
||
.Sp
|
||
Supported values: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2
|
||
.Sp
|
||
Availability of specific protocols depends on the linked OpenSSL library.
|
||
Older versions of OpenSSL do not support TLSv1.1 and TLSv1.2.
|
||
Newer versions of OpenSSL do not support SSLv2.
|
||
.Sp
|
||
Obsolete SSLv2 and SSLv3 are currently disabled by default.
|
||
See the \fBoptions\fR option documentation for details.
|
||
.IP "\fBstack\fR = \s-1BYTES \s0(except for \s-1FORK\s0 model)" 4
|
||
.IX Item "stack = BYTES (except for FORK model)"
|
||
thread stack size
|
||
.IP "\fBTIMEOUTbusy\fR = \s-1SECONDS\s0" 4
|
||
.IX Item "TIMEOUTbusy = SECONDS"
|
||
time to wait for expected data
|
||
.IP "\fBTIMEOUTclose\fR = \s-1SECONDS\s0" 4
|
||
.IX Item "TIMEOUTclose = SECONDS"
|
||
time to wait for close_notify (set to 0 for buggy \s-1MSIE\s0)
|
||
.IP "\fBTIMEOUTconnect\fR = \s-1SECONDS\s0" 4
|
||
.IX Item "TIMEOUTconnect = SECONDS"
|
||
time to wait to connect to a remote host
|
||
.IP "\fBTIMEOUTidle\fR = \s-1SECONDS\s0" 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 the address to appear as if a wrapped daemon is connecting
|
||
from the \s-1TLS\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 \fBstunnel\fR to be executed as root and without
|
||
the \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 the \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 the kernel to be compiled with the \fItransparent proxy\fR
|
||
option.
|
||
Connected service must be installed on a separate host.
|
||
Routing towards the clients has to go through the \fBstunnel\fR box.
|
||
.Sp
|
||
\&\fBstunnel\fR must also to be executed as root and without the \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 the \fIsetuid\fR option.
|
||
.IP "Local mode (\fIexec\fR option)" 4
|
||
.IX Item "Local mode (exec option)"
|
||
This configuration works by pre-loading the \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"
|
||
The original destination is used instead of the \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 iptables setup to work,
|
||
possibly in /etc/rc.local or equivalent file.
|
||
.Sp
|
||
For a connect target installed on the same host:
|
||
.Sp
|
||
.Vb 3
|
||
\& /sbin/iptables \-t nat \-I OUTPUT \-p tcp \-\-dport <redirected_port> \e
|
||
\& \-m ! \-\-uid\-owner <stunnel_user_id> \e
|
||
\& \-j DNAT \-\-to\-destination <local_ip>:<stunnel_port>
|
||
.Ve
|
||
.Sp
|
||
For a connect target installed on a remote host:
|
||
.Sp
|
||
.Vb 3
|
||
\& /sbin/iptables \-I INPUT \-i eth0 \-p tcp \-\-dport <stunnel_port> \-j ACCEPT
|
||
\& /sbin/iptables \-t nat \-I PREROUTING \-p tcp \-\-dport <redirected_port> \e
|
||
\& \-i eth0 \-j DNAT \-\-to\-destination <local_ip>:<stunnel_port>
|
||
.Ve
|
||
.Sp
|
||
The 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 option has been renamed to \fIsource\fR.
|
||
.IP "\fIno\fR" 4
|
||
.IX Item "no"
|
||
This option has been renamed to \fInone\fR.
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fBverify\fR = \s-1LEVEL\s0" 4
|
||
.IX Item "verify = LEVEL"
|
||
verify the peer certificate
|
||
.Sp
|
||
This option is obsolete and should be replaced with the \fIverifyChain\fR
|
||
and \fIverifyPeer\fR options.
|
||
.RS 4
|
||
.IP "level 0" 4
|
||
.IX Item "level 0"
|
||
Request and ignore the peer certificate.
|
||
.IP "level 1" 4
|
||
.IX Item "level 1"
|
||
Verify the peer certificate if present.
|
||
.IP "level 2" 4
|
||
.IX Item "level 2"
|
||
Verify the peer certificate.
|
||
.IP "level 3" 4
|
||
.IX Item "level 3"
|
||
Verify the peer against a locally installed certificate.
|
||
.IP "level 4" 4
|
||
.IX Item "level 4"
|
||
Ignore the chain and only verify the peer certificate.
|
||
.IP "default" 4
|
||
.IX Item "default"
|
||
No verify.
|
||
.RE
|
||
.RS 4
|
||
.RE
|
||
.IP "\fBverifyChain\fR = yes | no" 4
|
||
.IX Item "verifyChain = yes | no"
|
||
verify the peer certificate chain starting from the root \s-1CA\s0
|
||
.Sp
|
||
For server certificate verification it is essential to also require a specific
|
||
certificate with \fIcheckHost\fR or \fIcheckIP\fR.
|
||
.Sp
|
||
The self-signed root \s-1CA\s0 certificate needs to be stored either in the file
|
||
specified with \fICAfile\fR, or in the directory specified with \fICApath\fR.
|
||
.Sp
|
||
default: no
|
||
.IP "\fBverifyPeer\fR = yes | no" 4
|
||
.IX Item "verifyPeer = yes | no"
|
||
verify the peer certificate
|
||
.Sp
|
||
The peer certificate needs to be stored either in the file
|
||
specified with \fICAfile\fR, or in the directory specified with \fICApath\fR.
|
||
.Sp
|
||
default: no
|
||
.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 \fBstunnel\fR 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 the 'setuid' option will also prevent \fBstunnel\fR from binding to privileged
|
||
(<1024) ports during configuration reloading.
|
||
.Sp
|
||
When the 'chroot' option is used, \fBstunnel\fR will look for all its files (including
|
||
the configuration file, certificates, the log file and the pid file) within the chroot
|
||
jail.
|
||
.RE
|
||
.IP "\s-1SIGUSR1\s0" 4
|
||
.IX Item "SIGUSR1"
|
||
Close and reopen the \fBstunnel\fR log file.
|
||
This function can be used for log rotation.
|
||
.IP "\s-1SIGTERM, SIGQUIT, SIGINT\s0" 4
|
||
.IX Item "SIGTERM, SIGQUIT, SIGINT"
|
||
Shut \fBstunnel\fR down.
|
||
.PP
|
||
The result of sending any other signals to the server is undefined.
|
||
.SH "EXAMPLES"
|
||
.IX Header "EXAMPLES"
|
||
In order to provide \s-1TLS\s0 encapsulation to your local \fIimapd\fR service, use:
|
||
.PP
|
||
.Vb 4
|
||
\& [imapd]
|
||
\& accept = 993
|
||
\& exec = /usr/sbin/imapd
|
||
\& execArgs = imapd
|
||
.Ve
|
||
.PP
|
||
or in remote mode:
|
||
.PP
|
||
.Vb 3
|
||
\& [imapd]
|
||
\& accept = 993
|
||
\& connect = 143
|
||
.Ve
|
||
.PP
|
||
In order to let your local e\-mail client connect to a TLS-enabled \fIimapd\fR
|
||
service on another server, configure the e\-mail client to connect to localhost
|
||
on port 119 and use:
|
||
.PP
|
||
.Vb 4
|
||
\& [imap]
|
||
\& client = yes
|
||
\& accept = 143
|
||
\& connect = servername:993
|
||
.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
|
||
.PP
|
||
To setup \s-1SOCKS VPN\s0 configure the following client service:
|
||
.PP
|
||
.Vb 6
|
||
\& [socks_client]
|
||
\& client = yes
|
||
\& accept = 127.0.0.1:1080
|
||
\& connect = vpn_server:9080
|
||
\& verifyPeer = yes
|
||
\& CAfile = stunnel.pem
|
||
.Ve
|
||
.PP
|
||
The corresponding configuration on the vpn_server host:
|
||
.PP
|
||
.Vb 5
|
||
\& [socks_server]
|
||
\& protocol = socks
|
||
\& accept = 9080
|
||
\& cert = stunnel.pem
|
||
\& key = stunnel.key
|
||
.Ve
|
||
.PP
|
||
Now test your configuration on the client machine with:
|
||
.PP
|
||
.Vb 1
|
||
\& curl \-\-socks4a localhost http://www.example.com/
|
||
.Ve
|
||
.PP
|
||
An example server mode \s-1SNI\s0 configuration:
|
||
.PP
|
||
.Vb 5
|
||
\& [virtual]
|
||
\& ; master service
|
||
\& accept = 443
|
||
\& cert = default.pem
|
||
\& connect = default.internal.mydomain.com:8080
|
||
\&
|
||
\& [sni1]
|
||
\& ; slave service 1
|
||
\& sni = virtual:server1.mydomain.com
|
||
\& cert = server1.pem
|
||
\& connect = server1.internal.mydomain.com:8081
|
||
\&
|
||
\& [sni2]
|
||
\& ; slave service 2
|
||
\& sni = virtual:server2.mydomain.com
|
||
\& cert = server2.pem
|
||
\& connect = server2.internal.mydomain.com:8082
|
||
\& verifyPeer = yes
|
||
\& CAfile = server2\-allowed\-clients.pem
|
||
.Ve
|
||
.PP
|
||
An example of advanced engine configuration allows for authentication with private keys
|
||
stored in the Windows certificate store (Windows only).
|
||
With the \s-1CAPI\s0 engine you don't need to manually select the client key to use.
|
||
The client key is automatically selected based on the list of CAs trusted by the server.
|
||
.PP
|
||
.Vb 1
|
||
\& engine = capi
|
||
\&
|
||
\& [service]
|
||
\& engineId = capi
|
||
\& client = yes
|
||
\& accept = 127.0.0.1:8080
|
||
\& connect = example.com:8443
|
||
.Ve
|
||
.PP
|
||
An example of advanced engine configuration to use the certificate and the corresponding private key from a pkcs11 engine:
|
||
.PP
|
||
.Vb 3
|
||
\& 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
|
||
.Ve
|
||
.PP
|
||
An example of advanced engine configuration to use the certificate and the corresponding private key from a SoftHSM token:
|
||
.PP
|
||
.Vb 3
|
||
\& 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
|
||
.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 TLS-enabled versions of \s-1FTP\s0 and telnet daemons, however.
|
||
.SS "\s-1INETD MODE\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 @bindir@/stunnel stunnel @sysconfdir@/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 TLS-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 \fBOpenSSL\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 also be empty lines after the certificate and the private key.
|
||
Any 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-1TLS\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
|
||
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 \fBOpenSSL\fR,
|
||
would be useful.
|
||
.PP
|
||
Important note: If /dev/urandom is available, \fBOpenSSL\fR often seeds the \s-1PRNG\s0
|
||
with it while checking the random state. On systems with /dev/urandom
|
||
\&\fBOpenSSL\fR is likely to use it even though it is listed at the very bottom of
|
||
the list above. This is the behaviour of \fBOpenSSL\fR and not \fBstunnel\fR.
|
||
.SS "\s-1DH PARAMETERS\s0"
|
||
.IX Subsection "DH PARAMETERS"
|
||
\&\fBstunnel\fR 4.40 and later contains hardcoded 2048\-bit \s-1DH\s0 parameters. Starting
|
||
with \fBstunnel\fR 5.18, these hardcoded \s-1DH\s0 parameters are replaced every 24 hours
|
||
with autogenerated temporary \s-1DH\s0 parameters. \s-1DH\s0 parameter generation may take
|
||
several minutes.
|
||
.PP
|
||
Alternatively, it is possible to specify static \s-1DH\s0 parameters in the
|
||
certificate file, which disables generating temporary \s-1DH\s0 parameters:
|
||
.PP
|
||
.Vb 1
|
||
\& openssl dhparam 2048 >> stunnel.pem
|
||
.Ve
|
||
.SH "FILES"
|
||
.IX Header "FILES"
|
||
.ie n .IP "\fI\fI@sysconfdir\fI@/stunnel/stunnel.conf\fR" 4
|
||
.el .IP "\fI\f(CI@sysconfdir\fI@/stunnel/stunnel.conf\fR" 4
|
||
.IX Item "@sysconfdir@/stunnel/stunnel.conf"
|
||
\&\fBstunnel\fR configuration file
|
||
.SH "BUGS"
|
||
.IX Header "BUGS"
|
||
The \fIexecArgs\fR option and the Win32 command line do 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/"
|
||
\&\fBOpenSSL\fR project website
|
||
.SH "AUTHOR"
|
||
.IX Header "AUTHOR"
|
||
.IP "Michał Trojnara" 4
|
||
.IX Item "Michał Trojnara"
|
||
<\fIMichal.Trojnara@stunnel.org\fR>
|