| .\" 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 "2015.07.27" "5.22" "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-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, 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-1SSL\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 |
| .Sp |
| zlib compression of \fBOpenSSL 0.9.8\fR or above is not backward compatible with |
| \&\fBOpenSSL 0.9.7\fR. |
| .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. (Available only if compiled with \fBOpenSSL 0.9.5a\fR or higher) |
| .IP "\fBengine\fR = auto | \s-1ENGINE_ID\s0" 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 the 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\*(R"\s0 and \*(L"\s-1INIT\*(R"\s0 can be used to load and initialize the |
| engine cryptogaphic module. |
| .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 | 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 "\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 |
| .Sp |
| Number of bytes of data read from random seed files. With \s-1SSL\s0 versions less |
| than \fB0.9.5a\fR, also determines how many bytes of data are considered |
| sufficient to seed the \s-1PRNG. \s0 More recent \fBOpenSSL\fR versions have a builtin |
| function to determine when sufficient randomness is available. |
| .IP "\fBRNDfile\fR = \s-1FILE\s0" 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 = \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 "\fBsetgid\fR = \s-1GROUP \s0(Unix only)" 4 |
| .IX Item "setgid = GROUP (Unix only)" |
| \&\fIsetgid()\fR to the specified group in daemon mode and clear all other groups |
| .IP "\fBsetuid\fR = \s-1USER \s0(Unix only)" 4 |
| .IX Item "setuid = USER (Unix only)" |
| \&\fIsetuid()\fR to the specified user 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 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 \fIverify\fR option. 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-1CERT_FILE\s0" 4 |
| .IX Item "CAfile = CERT_FILE" |
| Certificate Authority file |
| .Sp |
| This file contains multiple \s-1CA\s0 certificates, used with the \fIverify\fR option. |
| .IP "\fBcert\fR = \s-1PEM_FILE\s0" 4 |
| .IX Item "cert = PEM_FILE" |
| certificate chain \s-1PEM\s0 file name |
| .Sp |
| The certificates must be in \s-1PEM\s0 format, and must be from the |
| actual server/client certificate to the self-signed root \s-1CA\s0 certificate. |
| .Sp |
| A certificate is required in server mode, and optional in client mode. |
| .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. |
| .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. |
| .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. |
| .IP "\fBciphers\fR = \s-1CIPHER_LIST\s0" 4 |
| .IX Item "ciphers = CIPHER_LIST" |
| 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 = [\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 \fIverify\fR option. 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-1CERT_FILE\s0" 4 |
| .IX Item "CRLfile = CERT_FILE" |
| Certificate Revocation Lists file |
| .Sp |
| This file contains multiple CRLs, used with the \fIverify\fR option. |
| .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. |
| .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. |
| .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 = \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 |
| 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 "\fBsni\fR = \s-1SERVICE:SERVER_PATTERN \s0(server mode)" 4 |
| .IX Item "sni = SERVICE:SERVER_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 |
| \&\fIservice_name\fR specifies the master service that accepts client connections |
| with the \fIaccept\fR option. \fIserver_name_pattern\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 \s0(client mode)" 4 |
| .IX Item "sni = SERVER (client mode)" |
| Use the parameter as the value of \s-1TLS\s0 Server Name Indication (\s-1RFC 3546\s0) |
| extension. |
| .Sp |
| The \fIsni\fR option is only available when compiled with \fBOpenSSL 1.0.0\fR and later. |
| .IP "\fB\s-1OCSP\s0\fR = \s-1URL\s0" 4 |
| .IX Item "OCSP = URL" |
| select \s-1OCSP\s0 server 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 server 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 "\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 \fIoptions\fR 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-1SSL\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-1SSL\s0 |
| .Sp |
| This option enables initial, protocol-specific negotiation of the \s-1SSL/TLS\s0 |
| encryption. |
| The \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 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-1SSL/TLS\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 = basic | ntlm" 4 |
| .IX Item "protocolAuthentication = basic | ntlm" |
| authentication type for protocol negotiations |
| .Sp |
| Currently the authentication type only applies to the 'connect' protocol. |
| .Sp |
| default: basic |
| .IP "\fBprotocolHost\fR = \s-1HOST:PORT\s0" 4 |
| .IX Item "protocolHost = HOST:PORT" |
| destination address for protocol negotiations |
| .Sp |
| \&\fIprotocolHost\fR specifies the final \s-1SSL\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 'connect' protocol. |
| .IP "\fBprotocolPassword\fR = \s-1PASSWORD\s0" 4 |
| .IX Item "protocolPassword = PASSWORD" |
| password for protocol negotiations |
| .IP "\fBprotocolUsername\fR = \s-1USERNAME\s0" 4 |
| .IX Item "protocolUsername = USERNAME" |
| username for protocol negotiations |
| .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-1SSL\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-1SSL\s0 renegotiation |
| .Sp |
| Applications of the \s-1SSL\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-1SSL\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's disconnected |
| .Sp |
| default: no |
| .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-1SSL\s0 sessions. |
| .IP "\fBsessiond\fR = \s-1HOST:PORT\s0" 4 |
| .IX Item "sessiond = HOST:PORT" |
| address of sessiond \s-1SSL\s0 cache server |
| .IP "\fBsslVersion\fR = \s-1SSL_VERSION\s0" 4 |
| .IX Item "sslVersion = SSL_VERSION" |
| select the \s-1SSL\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-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 \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 |
| .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 with locally installed certificate. |
| .IP "level 4" 4 |
| .IX Item "level 4" |
| Ignore the \s-1CA\s0 chain and only verify the peer certificate. |
| .IP "default" 4 |
| .IX Item "default" |
| No verify. |
| .RE |
| .RS 4 |
| .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 \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-1SSL\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 an SSL-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 |
| \& verify = 4 |
| \& 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 |
| .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 SSL-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 SSL-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-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 (\fBOpenSSL 0.9.5a\fR or later) 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 \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@mirt.net\fR> |