1stunnel(8)                     stunnel TLS Proxy                    stunnel(8)
2
3
4

NAME

6       stunnel - TLS offloading and load-balancing proxy
7

SYNOPSIS

9       Unix:
10           stunnel [FILE] | -fd N | -help | -version | -sockets | -options
11
12       WIN32:
13           stunnel [ [ -install | -uninstall | -start | -stop |
14               -reload | -reopen | -exit ] [-quiet] [FILE] ] |
15               -help | -version | -sockets | -options
16

DESCRIPTION

18       The stunnel program is designed to work as TLS encryption wrapper
19       between remote clients and local (inetd-startable) or remote servers.
20       The concept is that having non-TLS aware daemons running on your system
21       you can easily set them up to communicate with clients over secure TLS
22       channels.
23
24       stunnel can be used to add TLS functionality to commonly used Inetd
25       daemons like POP-2, POP-3, and IMAP servers, to standalone daemons like
26       NNTP, SMTP and HTTP, and in tunneling PPP over network sockets without
27       changes to the source code.
28
29       This product includes cryptographic software written by Eric Young
30       (eay@cryptsoft.com)
31

OPTIONS

33       FILE
34           Use specified configuration file
35
36       -fd N (Unix only)
37           Read the config file from specified file descriptor
38
39       -help
40           Print stunnel help menu
41
42       -version
43           Print stunnel version and compile time defaults
44
45       -sockets
46           Print default socket options
47
48       -options
49           Print supported TLS options
50
51       -install (Windows NT and later only)
52           Install NT Service
53
54       -uninstall (Windows NT and later only)
55           Uninstall NT Service
56
57       -start (Windows NT and later only)
58           Start NT Service
59
60       -stop (Windows NT and later only)
61           Stop NT Service
62
63       -reload (Windows NT and later only)
64           Reload the configuration file of the running NT Service
65
66       -reopen (Windows NT and later only)
67           Reopen the log file of the running NT Service
68
69       -exit (Win32 only)
70           Exit an already started stunnel
71
72       -quiet (Win32 only)
73           Don't display any message boxes
74

CONFIGURATION FILE

76       Each line of the configuration file can be either:
77
78       ·   An empty line (ignored).
79
80       ·   A comment starting with ';' (ignored).
81
82       ·   An 'option_name = option_value' pair.
83
84       ·   '[service_name]' indicating a start of a service definition.
85
86       An address parameter of an option may be either:
87
88       ·   A port number.
89
90       ·   A colon-separated pair of IP address (either IPv4, IPv6, or domain
91           name) and port number.
92
93       ·   A Unix socket path (Unix only).
94
95   GLOBAL OPTIONS
96       chroot = DIRECTORY (Unix only)
97           directory to chroot stunnel process
98
99           chroot keeps stunnel in a chrooted jail.  CApath, CRLpath, pid and
100           exec are located inside the jail and the patches have to be
101           relative to the directory specified with chroot.
102
103           Several functions of the operating system also need their files to
104           be located within the chroot jail, e.g.:
105
106           ·   Delayed resolver typically needs /etc/nsswitch.conf and
107               /etc/resolv.conf.
108
109           ·   Local time in log files needs /etc/timezone.
110
111           ·   Some other functions may need devices, e.g. /dev/zero or
112               /dev/null.
113
114       compression = deflate | zlib
115           select data compression algorithm
116
117           default: no compression
118
119           Deflate is the standard compression method as described in RFC
120           1951.
121
122       debug = [FACILITY.]LEVEL
123           debugging level
124
125           Level is one of the syslog level names or numbers emerg (0), alert
126           (1), crit (2), err (3), warning (4), notice (5), info (6), or debug
127           (7).  All logs for the specified level and all levels numerically
128           less than it will be shown.  Use debug = debug or debug = 7 for
129           greatest debugging output.  The default is notice (5).
130
131           The syslog facility 'authpriv' will be used unless a facility name
132           is supplied.  (Facilities are not supported on Win32.)
133
134           Case is ignored for both facilities and levels.
135
136       EGD = EGD_PATH (Unix only)
137           path to Entropy Gathering Daemon socket
138
139           Entropy Gathering Daemon socket to use to feed the OpenSSL random
140           number generator.
141
142       engine = auto | ENGINE_ID
143           select hardware or software cryptographic engine
144
145           default: software-only cryptography
146
147           See Examples section for an engine configuration to use the
148           certificate and the corresponding private key from a cryptographic
149           device.
150
151       engineCtrl = COMMAND[:PARAMETER]
152           control hardware engine
153
154       engineDefault = TASK_LIST
155           set OpenSSL tasks delegated to the current engine
156
157           The parameter specifies a comma-separated list of task to be
158           delegated to the current engine.
159
160           The following tasks may be available, if supported by the engine:
161           ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY,
162           PKEY_CRYPTO, PKEY_ASN1.
163
164       fips = yes | no
165           enable or disable FIPS 140-2 mode.
166
167           This option allows you to disable entering FIPS mode if stunnel was
168           compiled with FIPS 140-2 support.
169
170           default: no (since version 5.00)
171
172       foreground = yes | quiet | no (Unix only)
173           foreground mode
174
175           Stay in foreground (don't fork).
176
177           With the yes parameter it also logs to stderr in addition to the
178           destinations specified with syslog and output.
179
180           default: background in daemon mode
181
182       iconActive = ICON_FILE (GUI only)
183           GUI icon to be displayed when there are established connections
184
185           On Windows platform the parameter should be an .ico file containing
186           a 16x16 pixel image.
187
188       iconError = ICON_FILE (GUI only)
189           GUI icon to be displayed when no valid configuration is loaded
190
191           On Windows platform the parameter should be an .ico file containing
192           a 16x16 pixel image.
193
194       iconIdle = ICON_FILE (GUI only)
195           GUI icon to be displayed when there are no established connections
196
197           On Windows platform the parameter should be an .ico file containing
198           a 16x16 pixel image.
199
200       log = append | overwrite
201           log file handling
202
203           This option allows you to choose whether the log file (specified
204           with the output option) is appended or overwritten when opened or
205           re-opened.
206
207           default: append
208
209       output = FILE
210           append log messages to a file
211
212           /dev/stdout device can be used to send log messages to the standard
213           output (for example to log them with daemontools splogger).
214
215       pid = FILE (Unix only)
216           pid file location
217
218           If the argument is empty, then no pid file will be created.
219
220           pid path is relative to the chroot directory if specified.
221
222       RNDbytes = BYTES
223           bytes to read from random seed files
224
225       RNDfile = FILE
226           path to file with random seed data
227
228           The OpenSSL library will use data from this file first to seed the
229           random number generator.
230
231       RNDoverwrite = yes | no
232           overwrite the random seed files with new random data
233
234           default: yes
235
236       service = SERVICE (Unix only)
237           stunnel service name
238
239           The specified service name is used for syslog and as the inetd mode
240           service name for TCP Wrappers.  While this option can technically
241           be specified in the service sections, it is only useful in global
242           options.
243
244           default: stunnel
245
246       syslog = yes | no (Unix only)
247           enable logging via syslog
248
249           default: yes
250
251       taskbar = yes | no (WIN32 only)
252           enable the taskbar icon
253
254           default: yes
255
256   SERVICE-LEVEL OPTIONS
257       Each configuration section begins with a service name in square
258       brackets.  The service name is used for libwrap (TCP Wrappers) access
259       control and lets you distinguish stunnel services in your log files.
260
261       Note that if you wish to run stunnel in inetd mode (where it is
262       provided a network socket by a server such as inetd, xinetd, or
263       tcpserver) then you should read the section entitled INETD MODE below.
264
265       accept = [HOST:]PORT
266           accept connections on specified address
267
268           If no host specified, defaults to all IPv4 addresses for the local
269           host.
270
271           To listen on all IPv6 addresses use:
272
273               accept = :::PORT
274
275       CApath = DIRECTORY
276           Certificate Authority directory
277
278           This is the directory in which stunnel will look for certificates
279           when using the verifyChain or verifyPeer options.  Note that the
280           certificates in this directory should be named XXXXXXXX.0 where
281           XXXXXXXX is the hash value of the DER encoded subject of the cert.
282
283           The hash algorithm has been changed in OpenSSL 1.0.0.  It is
284           required to c_rehash the directory on upgrade from OpenSSL 0.x.x to
285           OpenSSL 1.x.x.
286
287           CApath path is relative to the chroot directory if specified.
288
289       CAfile = CA_FILE
290           Certificate Authority file
291
292           This file contains multiple CA certificates, to be used with the
293           verifyChain and verifyPeer options.
294
295       cert = CERT_FILE
296           certificate chain file name
297
298           The parameter specifies the file containing certificates used by
299           stunnel to authenticate itself against the remote client or server.
300           The file should contain the whole certificate chain starting from
301           the actual server/client certificate, and ending with the self-
302           signed root CA certificate.  The file must be either in PEM or P12
303           format.
304
305           A certificate chain is required in server mode, and optional in
306           client mode.
307
308           This parameter is also used as the certificate identifier when a
309           hardware engine is enabled.
310
311       checkEmail = EMAIL
312           email address of the peer certificate subject
313
314           Multiple checkEmail options are allowed in a single service
315           section.  Certificates are accepted if no subject checks were
316           specified, or the email address of the peer certificate matches any
317           of the email addresses specified with checkEmail.
318
319           This option requires OpenSSL 1.0.2 or later.
320
321       checkHost = HOST
322           host of the peer certificate subject
323
324           Multiple checkHost options are allowed in a single service section.
325           Certificates are accepted if no subject checks were specified, or
326           the host name of the peer certificate matches any of the hosts
327           specified with checkHost.
328
329           This option requires OpenSSL 1.0.2 or later.
330
331       checkIP = IP
332           IP address of the peer certificate subject
333
334           Multiple checkIP options are allowed in a single service section.
335           Certificates are accepted if no subject checks were specified, or
336           the IP address of the peer certificate matches any of the IP
337           addresses specified with checkIP.
338
339           This option requires OpenSSL 1.0.2 or later.
340
341       ciphers = CIPHER_LIST
342           Select permitted TLS ciphers
343
344           A colon-delimited list of the ciphers to allow in the TLS
345           connection, for example DES-CBC3-SHA:IDEA-CBC-MD5.
346
347       client = yes | no
348           client mode (remote service uses TLS)
349
350           default: no (server mode)
351
352       config = COMMAND[:PARAMETER]
353           OpenSSL configuration command
354
355           The OpenSSL configuration command is executed with the specified
356           parameter.  This allows any configuration commands to be invoked
357           from the stunnel configuration file.  Supported commands are
358           described on the SSL_CONF_cmd(3ssl) manual page.
359
360           Several config lines can be used to specify multiple configuration
361           commands.
362
363           This option requires OpenSSL 1.0.2 or later.
364
365       connect = [HOST:]PORT
366           connect to a remote address
367
368           If no host is specified, the host defaults to localhost.
369
370           Multiple connect options are allowed in a single service section.
371
372           If host resolves to multiple addresses and/or if multiple connect
373           options are specified, then the remote address is chosen using a
374           round-robin algorithm.
375
376       CRLpath = DIRECTORY
377           Certificate Revocation Lists directory
378
379           This is the directory in which stunnel will look for CRLs when
380           using the verifyChain and verifyPeer options. Note that the CRLs in
381           this directory should be named XXXXXXXX.r0 where XXXXXXXX is the
382           hash value of the CRL.
383
384           The hash algorithm has been changed in OpenSSL 1.0.0.  It is
385           required to c_rehash the directory on upgrade from OpenSSL 0.x.x to
386           OpenSSL 1.x.x.
387
388           CRLpath path is relative to the chroot directory if specified.
389
390       CRLfile = CRL_FILE
391           Certificate Revocation Lists file
392
393           This file contains multiple CRLs, used with the verifyChain and
394           verifyPeer options.
395
396       curve = NID
397           specify ECDH curve name
398
399           To get a list of supported curves use:
400
401               openssl ecparam -list_curves
402
403           default: prime256v1
404
405       logId = TYPE
406           connection identifier type
407
408           This identifier allows you to distinguish log entries generated for
409           each of the connections.
410
411           Currently supported types:
412
413           sequential
414               The numeric sequential identifier is only unique within a
415               single instance of stunnel, but very compact.  It is most
416               useful for manual log analysis.
417
418           unique
419               This alphanumeric identifier is globally unique, but longer
420               than the sequential number.  It is most useful for automated
421               log analysis.
422
423           thread
424               The operating system thread identifier is neither unique (even
425               within a single instance of stunnel) nor short.  It is most
426               useful for debugging software or configuration issues.
427
428           process
429               The operating system process identifier (PID) may be useful in
430               the inetd mode.
431
432           default: sequential
433
434       debug = LEVEL
435           debugging level
436
437           Level is a one of the syslog level names or numbers emerg (0),
438           alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
439           debug (7).  All logs for the specified level and all levels
440           numerically less than it will be shown.  Use debug = debug or debug
441           = 7 for greatest debugging output.  The default is notice (5).
442
443       delay = yes | no
444           delay DNS lookup for the connect option
445
446           This option is useful for dynamic DNS, or when DNS is not available
447           during stunnel startup (road warrior VPN, dial-up configurations).
448
449           Delayed resolver mode is automatically engaged when stunnel fails
450           to resolve on startup any of the connect targets for a service.
451
452           Delayed resolver inflicts failover = prio.
453
454           default: no
455
456       engineId = ENGINE_ID
457           select engine ID for the service
458
459       engineNum = ENGINE_NUMBER
460           select engine number for the service
461
462           The engines are numbered starting from 1.
463
464       exec = EXECUTABLE_PATH
465           execute a local inetd-type program
466
467           exec path is relative to the chroot directory if specified.
468
469           The following environmental variables are set on Unix platforms:
470           REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.
471
472       execArgs = $0 $1 $2 ...
473           arguments for exec including the program name ($0)
474
475           Quoting is currently not supported.  Arguments are separated with
476           an arbitrary amount of whitespace.
477
478       failover = rr | prio
479           Failover strategy for multiple "connect" targets.
480
481           rr  round robin - fair load distribution
482
483           prio
484               priority - use the order specified in config file
485
486           default: prio
487
488       ident = USERNAME
489           use IDENT (RFC 1413) username checking
490
491       include = DIRECTORY
492           include all configuration file parts located in DIRECTORY
493
494           The files are included in the ascending alphabetical order of their
495           names. The recommended filename convention is
496
497           for global options:
498
499                   00-global.conf
500
501           for local service-level options:
502
503                   01-service.conf
504
505                   02-service.conf
506
507       key = KEY_FILE
508           private key for the certificate specified with cert option
509
510           A private key is needed to authenticate the certificate owner.
511           Since this file should be kept secret it should only be readable by
512           its owner.  On Unix systems you can use the following command:
513
514               chmod 600 keyfile
515
516           This parameter is also used as the private key identifier when a
517           hardware engine is enabled.
518
519           default: the value of the cert option
520
521       libwrap = yes | no
522           Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
523
524           default: no (since version 5.00)
525
526       local = HOST
527           By default, the IP address of the outgoing interface is used as the
528           source for remote connections.  Use this option to bind a static
529           local IP address instead.
530
531       OCSP = URL
532           select OCSP responder for certificate verification
533
534       OCSPaia = yes | no
535           validate certificates with their AIA OCSP responders
536
537           This option enables stunnel to validate certificates with the list
538           of OCSP responder URLs retrieved from their AIA (Authority
539           Information Access) extension.
540
541       OCSPflag = OCSP_FLAG
542           specify OCSP responder flag
543
544           Several OCSPflag can be used to specify multiple flags.
545
546           currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN,
547           NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
548           RESPID_KEY, NOTIME
549
550       OCSPnonce = yes | no
551           send and verify the OCSP nonce extension
552
553           This option protects the OCSP protocol against replay attacks.  Due
554           to its computational overhead, the nonce extension is usually only
555           supported on internal (e.g. corporate) responders, and not on
556           public OCSP responders.
557
558       options = SSL_OPTIONS
559           OpenSSL library options
560
561           The parameter is the OpenSSL option name as described in the
562           SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix.
563           stunnel -options lists the options found to be allowed in the
564           current combination of stunnel and the OpenSSL library used to
565           build it.
566
567           Several option lines can be used to specify multiple options.  An
568           option name can be prepended with a dash ("-") to disable the
569           option.
570
571           For example, for compatibility with the erroneous Eudora TLS
572           implementation, the following option can be used:
573
574               options = DONT_INSERT_EMPTY_FRAGMENTS
575
576           default:
577
578               options = NO_SSLv2
579               options = NO_SSLv3
580
581           Use sslVersionMax or sslVersionMin option instead of disabling
582           specific TLS protocol versions when compiled with OpenSSL 1.1.0 or
583           later.
584
585       protocol = PROTO
586           application protocol to negotiate TLS
587
588           This option enables initial, protocol-specific negotiation of the
589           TLS encryption.  The protocol option should not be used with TLS
590           encryption on a separate port.
591
592           Currently supported protocols:
593
594           cifs
595               Proprietary (undocummented) extension of CIFS protocol
596               implemented in Samba.  Support for this extension was dropped
597               in Samba 3.0.0.
598
599           connect
600               Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section
601               5.2 - Requesting a Tunnel with CONNECT
602
603               This protocol is only supported in client mode.
604
605           imap
606               Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP
607
608           nntp
609               Based on RFC 4642 - Using Transport Layer Security (TLS) with
610               Network News Transfer Protocol (NNTP)
611
612               This protocol is only supported in client mode.
613
614           pgsql
615               Based on
616               http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
617
618           pop3
619               Based on RFC 2449 - POP3 Extension Mechanism
620
621           proxy
622               Haproxy client IP address
623               http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
624
625           smtp
626               Based on RFC 2487 - SMTP Service Extension for Secure SMTP over
627               TLS
628
629           socks
630               SOCKS versions 4, 4a, and 5 are supported.  The SOCKS protocol
631               itself is encapsulated within TLS encryption layer to protect
632               the final destination address.
633
634               http://www.openssh.com/txt/socks4.protocol
635
636               http://www.openssh.com/txt/socks4a.protocol
637
638               The BIND command of the SOCKS protocol is not supported.  The
639               USERID parameter is ignored.
640
641               See Examples section for sample configuration files for VPN
642               based on SOCKS encryption.
643
644       protocolAuthentication = AUTHENTICATION
645           authentication type for the protocol negotiations
646
647           Currently, this option is only supported in the client-side
648           'connect' and 'smtp' protocols.
649
650           Supported authentication types for the 'connect' protocol are
651           'basic' or 'ntlm'.  The default 'connect' authentication type is
652           'basic'.
653
654           Supported authentication types for the 'smtp' protocol are 'plain'
655           or 'login'.  The default 'smtp' authentication type is 'plain'.
656
657       protocolDomain = DOMAIN
658           domain for the protocol negotiations
659
660           Currently, this option is only supported in the client-side
661           'connect' protocol.
662
663       protocolHost = HOST:PORT
664           destination address for the protocol negotiations
665
666           protocolHost specifies the final TLS server to be connected to by
667           the proxy, and not the proxy server directly connected by stunnel.
668           The proxy server should be specified with the 'connect' option.
669
670           Currently the protocol destination address only applies to the
671           'connect' protocol.
672
673       protocolPassword = PASSWORD
674           password for the protocol negotiations
675
676           Currently, this option is only supported in the client-side
677           'connect' and 'smtp' protocols.
678
679       protocolUsername = USERNAME
680           username for the protocol negotiations
681
682           Currently, this option is only supported in the client-side
683           'connect' and 'smtp' protocols.
684
685       PSKidentity = IDENTITY
686           PSK identity for the PSK client
687
688           PSKidentity can be used on stunnel clients to select the PSK
689           identity used for authentication.  This option is ignored in server
690           sections.
691
692           default: the first identity specified in the PSKsecrets file.
693
694       PSKsecrets = FILE
695           file with PSK identities and corresponding keys
696
697           Each line of the file in the following format:
698
699               IDENTITY:KEY
700
701           The key is required to be at least 20 characters long.  The file
702           should not be world-readable nor world-writable.
703
704       pty = yes | no (Unix only)
705           allocate a pseudoterminal for 'exec' option
706
707       redirect = [HOST:]PORT
708           redirect TLS client connections on certificate-based authentication
709           failures
710
711           This option only works in server mode.  Some protocol negotiations
712           are also incompatible with the redirect option.
713
714       renegotiation = yes | no
715           support TLS renegotiation
716
717           Applications of the TLS renegotiation include some authentication
718           scenarios, or re-keying long lasting connections.
719
720           On the other hand this feature can facilitate a trivial CPU-
721           exhaustion DoS attack:
722
723           http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
724
725           Please note that disabling TLS renegotiation does not fully
726           mitigate this issue.
727
728           default: yes (if supported by OpenSSL)
729
730       reset = yes | no
731           attempt to use the TCP RST flag to indicate an error
732
733           This option is not supported on some platforms.
734
735           default: yes
736
737       retry = yes | no
738           reconnect a connect+exec section after it was disconnected
739
740           default: no
741
742       requireCert = yes | no
743           require a client certificate for verifyChain or verifyPeer
744
745           With requireCert set to no, the stunnel server accepts client
746           connections that did not present a certificate.
747
748           Both verifyChain = yes and verifyPeer = yes imply requireCert =
749           yes.
750
751           default: no
752
753       setgid = GROUP (Unix only)
754           Unix group id
755
756           As a global option: setgid() to the specified group in daemon mode
757           and clear all other groups.
758
759           As a service-level option: set the group of the Unix socket
760           specified with "accept".
761
762       setuid = USER (Unix only)
763           Unix user id
764
765           As a global option: setuid() to the specified user in daemon mode.
766
767           As a service-level option: set the owner of the Unix socket
768           specified with "accept".
769
770       sessionCacheSize = NUM_ENTRIES
771           session cache size
772
773           sessionCacheSize specifies the maximum number of the internal
774           session cache entries.
775
776           The value of 0 can be used for unlimited size.  It is not
777           recommended for production use due to the risk of a memory
778           exhaustion DoS attack.
779
780       sessionCacheTimeout = TIMEOUT
781           session cache timeout
782
783           This is the number of seconds to keep cached TLS sessions.
784
785       sessiond = HOST:PORT
786           address of sessiond TLS cache server
787
788       sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)
789           Use the service as a slave service (a name-based virtual server)
790           for Server Name Indication TLS extension (RFC 3546).
791
792           SERVICE_NAME specifies the master service that accepts client
793           connections with the accept option.  SERVER_NAME_PATTERN specifies
794           the host name to be redirected.  The pattern may start with the '*'
795           character, e.g.  '*.example.com'.  Multiple slave services are
796           normally specified for a single master service.  The sni option can
797           also be specified more than once within a single slave service.
798
799           This service, as well as the master service, may not be configured
800           in client mode.
801
802           The connect option of the slave service is ignored when the
803           protocol option is specified, as protocol connects to the remote
804           host before TLS handshake.
805
806           Libwrap checks (Unix only) are performed twice: with the master
807           service name after TCP connection is accepted, and with the slave
808           service name during the TLS handshake.
809
810           The sni option is only available when compiled with OpenSSL 1.0.0
811           and later.
812
813       sni = SERVER_NAME (client mode)
814           Use the parameter as the value of TLS Server Name Indication (RFC
815           3546) extension.
816
817           Empty SERVER_NAME disables sending the SNI extension.
818
819           The sni option is only available when compiled with OpenSSL 1.0.0
820           and later.
821
822       socket = a|l|r:OPTION=VALUE[:VALUE]
823           Set an option on the accept/local/remote socket
824
825           The values for the linger option are l_onof:l_linger.  The values
826           for the time are tv_sec:tv_usec.
827
828           Examples:
829
830               socket = l:SO_LINGER=1:60
831                   set one minute timeout for closing local socket
832               socket = r:SO_OOBINLINE=yes
833                   place out-of-band data directly into the
834                   receive data stream for remote sockets
835               socket = a:SO_REUSEADDR=no
836                   disable address reuse (enabled by default)
837               socket = a:SO_BINDTODEVICE=lo
838                   only accept connections on loopback interface
839
840       sslVersion = SSL_VERSION
841           select the TLS protocol version
842
843           Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2,
844           TLSv1.3
845
846           Availability of specific protocols depends on the linked OpenSSL
847           library.  Older versions of OpenSSL do not support TLSv1.1, TLSv1.2
848           and TLSv1.3.  Newer versions of OpenSSL do not support SSLv2.
849
850           Obsolete SSLv2 and SSLv3 are currently disabled by default.
851
852           Setting the option
853
854               sslVersion = SSL_VERSION
855
856           is equivalent to options
857
858               sslVersionMax = SSL_VERSION
859               sslVersionMin = SSL_VERSION
860
861           when compiled with OpenSSL 1.1.0 and later.
862
863       sslVersionMax = SSL_VERSION
864           maximum supported protocol versions
865
866           Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
867
868           all enable protocol versions up to the highest version supported by
869           the linked OpenSSL library.
870
871           Availability of specific protocols depends on the linked OpenSSL
872           library.
873
874           The sslVersionMax option is only available when compiled with
875           OpenSSL 1.1.0 and later.
876
877           default: all
878
879       sslVersionMin = SSL_VERSION
880           minimum supported protocol versions
881
882           Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
883
884           all enable protocol versions down to the lowest version supported
885           by the linked OpenSSL library.
886
887           Availability of specific protocols depends on the linked OpenSSL
888           library.
889
890           The sslVersionMin option is only available when compiled with
891           OpenSSL 1.1.0 and later.
892
893           default: TLSv1
894
895       stack = BYTES (except for FORK model)
896           CPU stack size of created threads
897
898           Excessive thread stack size increases virtual memory usage.
899           Insufficient thread stack size may cause application crashes.
900
901           default: 65536 bytes (sufficient for all platforms we tested)
902
903       TIMEOUTbusy = SECONDS
904           time to wait for expected data
905
906       TIMEOUTclose = SECONDS
907           time to wait for close_notify (set to 0 for buggy MSIE)
908
909       TIMEOUTconnect = SECONDS
910           time to wait to connect to a remote host
911
912       TIMEOUTidle = SECONDS
913           time to keep an idle connection
914
915       transparent = none | source | destination | both (Unix only)
916           enable transparent proxy support on selected platforms
917
918           Supported values:
919
920           none
921               Disable transparent proxy support.  This is the default.
922
923           source
924               Re-write the address to appear as if a wrapped daemon is
925               connecting from the TLS client machine instead of the machine
926               running stunnel.
927
928               This option is currently available in:
929
930               Remote mode (connect option) on Linux >=2.6.28
931                   This configuration requires stunnel to be executed as root
932                   and without the setuid option.
933
934                   This configuration requires the following setup for
935                   iptables and routing (possibly in /etc/rc.local or
936                   equivalent file):
937
938                       iptables -t mangle -N DIVERT
939                       iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
940                       iptables -t mangle -A DIVERT -j MARK --set-mark 1
941                       iptables -t mangle -A DIVERT -j ACCEPT
942                       ip rule add fwmark 1 lookup 100
943                       ip route add local 0.0.0.0/0 dev lo table 100
944                       echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter
945
946                   stunnel must also to be executed as root and without the
947                   setuid option.
948
949               Remote mode (connect option) on Linux 2.2.x
950                   This configuration requires the kernel to be compiled with
951                   the transparent proxy option.  Connected service must be
952                   installed on a separate host.  Routing towards the clients
953                   has to go through the stunnel box.
954
955                   stunnel must also to be executed as root and without the
956                   setuid option.
957
958               Remote mode (connect option) on FreeBSD >=8.0
959                   This configuration requires additional firewall and routing
960                   setup.  stunnel must also to be executed as root and
961                   without the setuid option.
962
963               Local mode (exec option)
964                   This configuration works by pre-loading the libstunnel.so
965                   shared library.  _RLD_LIST environment variable is used on
966                   Tru64, and LD_PRELOAD variable on other platforms.
967
968           destination
969               The original destination is used instead of the connect option.
970
971               A service section for transparent destination may look like
972               this:
973
974                   [transparent]
975                   client = yes
976                   accept = <stunnel_port>
977                   transparent = destination
978
979               This configuration requires iptables setup to work, possibly in
980               /etc/rc.local or equivalent file.
981
982               For a connect target installed on the same host:
983
984                   /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \
985                       -m ! --uid-owner <stunnel_user_id> \
986                       -j DNAT --to-destination <local_ip>:<stunnel_port>
987
988               For a connect target installed on a remote host:
989
990                   /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT
991                   /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \
992                       -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port>
993
994               The transparent destination option is currently only supported
995               on Linux.
996
997           both
998               Use both source and destination transparent proxy.
999
1000           Two legacy options are also supported for backward compatibility:
1001
1002           yes This option has been renamed to source.
1003
1004           no  This option has been renamed to none.
1005
1006       verify = LEVEL
1007           verify the peer certificate
1008
1009           This option is obsolete and should be replaced with the verifyChain
1010           and verifyPeer options.
1011
1012           level 0
1013               Request and ignore the peer certificate.
1014
1015           level 1
1016               Verify the peer certificate if present.
1017
1018           level 2
1019               Verify the peer certificate.
1020
1021           level 3
1022               Verify the peer against a locally installed certificate.
1023
1024           level 4
1025               Ignore the chain and only verify the peer certificate.
1026
1027           default
1028               No verify.
1029
1030       verifyChain = yes | no
1031           verify the peer certificate chain starting from the root CA
1032
1033           For server certificate verification it is essential to also require
1034           a specific certificate with checkHost or checkIP.
1035
1036           The self-signed root CA certificate needs to be stored either in
1037           the file specified with CAfile, or in the directory specified with
1038           CApath.
1039
1040           default: no
1041
1042       verifyPeer = yes | no
1043           verify the peer certificate
1044
1045           The peer certificate needs to be stored either in the file
1046           specified with CAfile, or in the directory specified with CApath.
1047
1048           default: no
1049

RETURN VALUE

1051       stunnel returns zero on success, non-zero on error.
1052

SIGNALS

1054       The following signals can be used to control stunnel in Unix
1055       environment:
1056
1057       SIGHUP
1058           Force a reload of the configuration file.
1059
1060           Some global options will not be reloaded:
1061
1062           ·   chroot
1063
1064           ·   foreground
1065
1066           ·   pid
1067
1068           ·   setgid
1069
1070           ·   setuid
1071
1072           The use of the 'setuid' option will also prevent stunnel from
1073           binding to privileged (<1024) ports during configuration reloading.
1074
1075           When the 'chroot' option is used, stunnel will look for all its
1076           files (including the configuration file, certificates, the log file
1077           and the pid file) within the chroot jail.
1078
1079       SIGUSR1
1080           Close and reopen the stunnel log file.  This function can be used
1081           for log rotation.
1082
1083       SIGTERM, SIGQUIT, SIGINT
1084           Shut stunnel down.
1085
1086       The result of sending any other signals to the server is undefined.
1087

EXAMPLES

1089       In order to provide TLS encapsulation to your local imapd service, use:
1090
1091           [imapd]
1092           accept = 993
1093           exec = /usr/sbin/imapd
1094           execArgs = imapd
1095
1096       or in remote mode:
1097
1098           [imapd]
1099           accept = 993
1100           connect = 143
1101
1102       In order to let your local e-mail client connect to a TLS-enabled imapd
1103       service on another server, configure the e-mail client to connect to
1104       localhost on port 119 and use:
1105
1106           [imap]
1107           client = yes
1108           accept = 143
1109           connect = servername:993
1110
1111       If you want to provide tunneling to your pppd daemon on port 2020, use
1112       something like:
1113
1114           [vpn]
1115           accept = 2020
1116           exec = /usr/sbin/pppd
1117           execArgs = pppd local
1118           pty = yes
1119
1120       If you want to use stunnel in inetd mode to launch your imapd process,
1121       you'd use this stunnel.conf.  Note there must be no [service_name]
1122       section.
1123
1124           exec = /usr/sbin/imapd
1125           execArgs = imapd
1126
1127       To setup SOCKS VPN configure the following client service:
1128
1129           [socks_client]
1130           client = yes
1131           accept = 127.0.0.1:1080
1132           connect = vpn_server:9080
1133           verifyPeer = yes
1134           CAfile = stunnel.pem
1135
1136       The corresponding configuration on the vpn_server host:
1137
1138           [socks_server]
1139           protocol = socks
1140           accept = 9080
1141           cert = stunnel.pem
1142           key = stunnel.key
1143
1144       Now test your configuration on the client machine with:
1145
1146           curl --socks4a localhost http://www.example.com/
1147
1148       An example server mode SNI configuration:
1149
1150           [virtual]
1151           ; master service
1152           accept = 443
1153           cert =  default.pem
1154           connect = default.internal.mydomain.com:8080
1155
1156           [sni1]
1157           ; slave service 1
1158           sni = virtual:server1.mydomain.com
1159           cert = server1.pem
1160           connect = server1.internal.mydomain.com:8081
1161
1162           [sni2]
1163           ; slave service 2
1164           sni = virtual:server2.mydomain.com
1165           cert = server2.pem
1166           connect = server2.internal.mydomain.com:8082
1167           verifyPeer = yes
1168           CAfile = server2-allowed-clients.pem
1169
1170       An example of advanced engine configuration allows for authentication
1171       with private keys stored in the Windows certificate store (Windows
1172       only).  With the CAPI engine you don't need to manually select the
1173       client key to use.  The client key is automatically selected based on
1174       the list of CAs trusted by the server.
1175
1176           engine = capi
1177
1178           [service]
1179           engineId = capi
1180           client = yes
1181           accept = 127.0.0.1:8080
1182           connect = example.com:8443
1183
1184       An example of advanced engine configuration to use the certificate and
1185       the corresponding private key from a pkcs11 engine:
1186
1187           engine = pkcs11
1188           engineCtrl = MODULE_PATH:opensc-pkcs11.so
1189           engineCtrl = PIN:123456
1190
1191           [service]
1192           engineId = pkcs11
1193           client = yes
1194           accept = 127.0.0.1:8080
1195           connect = example.com:843
1196           cert = pkcs11:token=MyToken;object=MyCert
1197           key = pkcs11:token=MyToken;object=MyKey
1198
1199       An example of advanced engine configuration to use the certificate and
1200       the corresponding private key from a SoftHSM token:
1201
1202           engine = pkcs11
1203           engineCtrl = MODULE_PATH:softhsm2.dll
1204           engineCtrl = PIN:12345
1205
1206           [service]
1207           engineId = pkcs11
1208           client = yes
1209           accept = 127.0.0.1:8080
1210           connect = example.com:843
1211           cert = pkcs11:token=MyToken;object=KeyCert
1212

NOTES

1214   RESTRICTIONS
1215       stunnel cannot be used for the FTP daemon because of the nature of the
1216       FTP protocol which utilizes multiple ports for data transfers.  There
1217       are available TLS-enabled versions of FTP and telnet daemons, however.
1218
1219   INETD MODE
1220       The most common use of stunnel is to listen on a network port and
1221       establish communication with either a new port via the connect option,
1222       or a new program via the exec option.  However there is a special case
1223       when you wish to have some other program accept incoming connections
1224       and launch stunnel, for example with inetd, xinetd, or tcpserver.
1225
1226       For example, if you have the following line in inetd.conf:
1227
1228           imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
1229
1230       In these cases, the inetd-style program is responsible for binding a
1231       network socket (imaps above) and handing it to stunnel when a
1232       connection is received.  Thus you do not want stunnel to have any
1233       accept option.  All the Service Level Options should be placed in the
1234       global options section, and no [service_name] section will be present.
1235       See the EXAMPLES section for example configurations.
1236
1237   CERTIFICATES
1238       Each TLS-enabled daemon needs to present a valid X.509 certificate to
1239       the peer. It also needs a private key to decrypt the incoming data. The
1240       easiest way to obtain a certificate and a key is to generate them with
1241       the free OpenSSL package. You can find more information on certificates
1242       generation on pages listed below.
1243
1244       The .pem file should contain the unencrypted private key and a signed
1245       certificate (not certificate request).  So the file should look like
1246       this:
1247
1248           -----BEGIN RSA PRIVATE KEY-----
1249           [encoded key]
1250           -----END RSA PRIVATE KEY-----
1251           -----BEGIN CERTIFICATE-----
1252           [encoded certificate]
1253           -----END CERTIFICATE-----
1254
1255   RANDOMNESS
1256       stunnel needs to seed the PRNG (pseudo-random number generator) in
1257       order for TLS to use good randomness.  The following sources are loaded
1258       in order until sufficient random data has been gathered:
1259
1260       ·   The file specified with the RNDfile flag.
1261
1262       ·   The file specified by the RANDFILE environment variable, if set.
1263
1264       ·   The file .rnd in your home directory, if RANDFILE not set.
1265
1266       ·   The file specified with '--with-random' at compile time.
1267
1268       ·   The contents of the screen if running on Windows.
1269
1270       ·   The egd socket specified with the EGD flag.
1271
1272       ·   The egd socket specified with '--with-egd-sock' at compile time.
1273
1274       ·   The /dev/urandom device.
1275
1276       Note that on Windows machines that do not have console user interaction
1277       (mouse movements, creating windows, etc.) the screen contents are not
1278       variable enough to be sufficient, and you should provide a random file
1279       for use with the RNDfile flag.
1280
1281       Note that the file specified with the RNDfile flag should contain
1282       random data -- that means it should contain different information each
1283       time stunnel is run.  This is handled automatically unless the
1284       RNDoverwrite flag is used.  If you wish to update this file manually,
1285       the openssl rand command in recent versions of OpenSSL, would be
1286       useful.
1287
1288       Important note: If /dev/urandom is available, OpenSSL often seeds the
1289       PRNG with it while checking the random state.  On systems with
1290       /dev/urandom OpenSSL is likely to use it even though it is listed at
1291       the very bottom of the list above.  This is the behaviour of OpenSSL
1292       and not stunnel.
1293
1294   DH PARAMETERS
1295       stunnel 4.40 and later contains hardcoded 2048-bit DH parameters.
1296       Starting with stunnel 5.18, these hardcoded DH parameters are replaced
1297       every 24 hours with autogenerated temporary DH parameters.  DH
1298       parameter generation may take several minutes.
1299
1300       Alternatively, it is possible to specify static DH parameters in the
1301       certificate file, which disables generating temporary DH parameters:
1302
1303           openssl dhparam 2048 >> stunnel.pem
1304

FILES

1306       @sysconfdir@/stunnel/stunnel.conf
1307           stunnel configuration file
1308

BUGS

1310       The execArgs option and the Win32 command line do not support quoting.
1311

SEE ALSO

1313       tcpd(8)
1314           access control facility for internet services
1315
1316       inetd(8)
1317           internet 'super-server'
1318
1319       http://www.stunnel.org/
1320           stunnel homepage
1321
1322       http://www.openssl.org/
1323           OpenSSL project website
1324

AUTHOR

1326       Michał Trojnara
1327           <Michal.Trojnara@stunnel.org>
1328
1329
1330
13315.50                              2019.01.14                        stunnel(8)
Impressum