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       protocol = PROTO
582           application protocol to negotiate TLS
583
584           This option enables initial, protocol-specific negotiation of the
585           TLS encryption.  The protocol option should not be used with TLS
586           encryption on a separate port.
587
588           Currently supported protocols:
589
590           cifs
591               Proprietary (undocummented) extension of CIFS protocol
592               implemented in Samba.  Support for this extension was dropped
593               in Samba 3.0.0.
594
595           connect
596               Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section
597               5.2 - Requesting a Tunnel with CONNECT
598
599               This protocol is only supported in client mode.
600
601           imap
602               Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP
603
604           nntp
605               Based on RFC 4642 - Using Transport Layer Security (TLS) with
606               Network News Transfer Protocol (NNTP)
607
608               This protocol is only supported in client mode.
609
610           pgsql
611               Based on
612               http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
613
614           pop3
615               Based on RFC 2449 - POP3 Extension Mechanism
616
617           proxy
618               Haproxy client IP address
619               http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
620
621           smtp
622               Based on RFC 2487 - SMTP Service Extension for Secure SMTP over
623               TLS
624
625           socks
626               SOCKS versions 4, 4a, and 5 are supported.  The SOCKS protocol
627               itself is encapsulated within TLS encryption layer to protect
628               the final destination address.
629
630               http://www.openssh.com/txt/socks4.protocol
631
632               http://www.openssh.com/txt/socks4a.protocol
633
634               The BIND command of the SOCKS protocol is not supported.  The
635               USERID parameter is ignored.
636
637               See Examples section for sample configuration files for VPN
638               based on SOCKS encryption.
639
640       protocolAuthentication = AUTHENTICATION
641           authentication type for the protocol negotiations
642
643           Currently, this option is only supported in the client-side
644           'connect' and 'smtp' protocols.
645
646           Supported authentication types for the 'connect' protocol are
647           'basic' or 'ntlm'.  The default 'connect' authentication type is
648           'basic'.
649
650           Supported authentication types for the 'smtp' protocol are 'plain'
651           or 'login'.  The default 'smtp' authentication type is 'plain'.
652
653       protocolDomain = DOMAIN
654           domain for the protocol negotiations
655
656           Currently, this option is only supported in the client-side
657           'connect' protocol.
658
659       protocolHost = HOST:PORT
660           destination address for the protocol negotiations
661
662           protocolHost specifies the final TLS server to be connected to by
663           the proxy, and not the proxy server directly connected by stunnel.
664           The proxy server should be specified with the 'connect' option.
665
666           Currently the protocol destination address only applies to the
667           'connect' protocol.
668
669       protocolPassword = PASSWORD
670           password for the protocol negotiations
671
672           Currently, this option is only supported in the client-side
673           'connect' and 'smtp' protocols.
674
675       protocolUsername = USERNAME
676           username for the protocol negotiations
677
678           Currently, this option is only supported in the client-side
679           'connect' and 'smtp' protocols.
680
681       PSKidentity = IDENTITY
682           PSK identity for the PSK client
683
684           PSKidentity can be used on stunnel clients to select the PSK
685           identity used for authentication.  This option is ignored in server
686           sections.
687
688           default: the first identity specified in the PSKsecrets file.
689
690       PSKsecrets = FILE
691           file with PSK identities and corresponding keys
692
693           Each line of the file in the following format:
694
695               IDENTITY:KEY
696
697           The key is required to be at least 20 characters long.  The file
698           should not be world-readable nor world-writable.
699
700       pty = yes | no (Unix only)
701           allocate a pseudoterminal for 'exec' option
702
703       redirect = [HOST:]PORT
704           redirect TLS client connections on certificate-based authentication
705           failures
706
707           This option only works in server mode.  Some protocol negotiations
708           are also incompatible with the redirect option.
709
710       renegotiation = yes | no
711           support TLS renegotiation
712
713           Applications of the TLS renegotiation include some authentication
714           scenarios, or re-keying long lasting connections.
715
716           On the other hand this feature can facilitate a trivial CPU-
717           exhaustion DoS attack:
718
719           http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
720
721           Please note that disabling TLS renegotiation does not fully
722           mitigate this issue.
723
724           default: yes (if supported by OpenSSL)
725
726       reset = yes | no
727           attempt to use the TCP RST flag to indicate an error
728
729           This option is not supported on some platforms.
730
731           default: yes
732
733       retry = yes | no
734           reconnect a connect+exec section after it was disconnected
735
736           default: no
737
738       requireCert = yes | no
739           require a client certificate for verifyChain or verifyPeer
740
741           With requireCert set to no, the stunnel server accepts client
742           connections that did not present a certificate.
743
744           Both verifyChain = yes and verifyPeer = yes imply requireCert =
745           yes.
746
747           default: no
748
749       setgid = GROUP (Unix only)
750           Unix group id
751
752           As a global option: setgid() to the specified group in daemon mode
753           and clear all other groups.
754
755           As a service-level option: set the group of the Unix socket
756           specified with "accept".
757
758       setuid = USER (Unix only)
759           Unix user id
760
761           As a global option: setuid() to the specified user in daemon mode.
762
763           As a service-level option: set the owner of the Unix socket
764           specified with "accept".
765
766       sessionCacheSize = NUM_ENTRIES
767           session cache size
768
769           sessionCacheSize specifies the maximum number of the internal
770           session cache entries.
771
772           The value of 0 can be used for unlimited size.  It is not
773           recommended for production use due to the risk of a memory
774           exhaustion DoS attack.
775
776       sessionCacheTimeout = TIMEOUT
777           session cache timeout
778
779           This is the number of seconds to keep cached TLS sessions.
780
781       sessiond = HOST:PORT
782           address of sessiond TLS cache server
783
784       sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)
785           Use the service as a slave service (a name-based virtual server)
786           for Server Name Indication TLS extension (RFC 3546).
787
788           SERVICE_NAME specifies the master service that accepts client
789           connections with the accept option.  SERVER_NAME_PATTERN specifies
790           the host name to be redirected.  The pattern may start with the '*'
791           character, e.g.  '*.example.com'.  Multiple slave services are
792           normally specified for a single master service.  The sni option can
793           also be specified more than once within a single slave service.
794
795           This service, as well as the master service, may not be configured
796           in client mode.
797
798           The connect option of the slave service is ignored when the
799           protocol option is specified, as protocol connects to the remote
800           host before TLS handshake.
801
802           Libwrap checks (Unix only) are performed twice: with the master
803           service name after TCP connection is accepted, and with the slave
804           service name during the TLS handshake.
805
806           The sni option is only available when compiled with OpenSSL 1.0.0
807           and later.
808
809       sni = SERVER_NAME (client mode)
810           Use the parameter as the value of TLS Server Name Indication (RFC
811           3546) extension.
812
813           Empty SERVER_NAME disables sending the SNI extension.
814
815           The sni option is only available when compiled with OpenSSL 1.0.0
816           and later.
817
818       socket = a|l|r:OPTION=VALUE[:VALUE]
819           Set an option on the accept/local/remote socket
820
821           The values for the linger option are l_onof:l_linger.  The values
822           for the time are tv_sec:tv_usec.
823
824           Examples:
825
826               socket = l:SO_LINGER=1:60
827                   set one minute timeout for closing local socket
828               socket = r:SO_OOBINLINE=yes
829                   place out-of-band data directly into the
830                   receive data stream for remote sockets
831               socket = a:SO_REUSEADDR=no
832                   disable address reuse (enabled by default)
833               socket = a:SO_BINDTODEVICE=lo
834                   only accept connections on loopback interface
835
836       sslVersion = SSL_VERSION
837           select the TLS protocol version
838
839           Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2
840
841           sslVersion is obsolete and it will be removed in future releases of
842           stunnel.  Use the following options instead:
843
844               options = NO_SSLv2
845               options = NO_SSLv3
846               options = NO_TLSv1
847               options = NO_TLSv1.1
848               options = NO_TLSv1.2
849               options = NO_TLSv1.3
850
851           Availability of specific protocols depends on the linked OpenSSL
852           library.  Older versions of OpenSSL do not support TLSv1.1 and
853           TLSv1.2.  Newer versions of OpenSSL do not support SSLv2.
854
855           Obsolete SSLv2 and SSLv3 are currently disabled by default.  See
856           the options option documentation for details.
857
858       stack = BYTES (except for FORK model)
859           thread stack size
860
861       TIMEOUTbusy = SECONDS
862           time to wait for expected data
863
864       TIMEOUTclose = SECONDS
865           time to wait for close_notify (set to 0 for buggy MSIE)
866
867       TIMEOUTconnect = SECONDS
868           time to wait to connect to a remote host
869
870       TIMEOUTidle = SECONDS
871           time to keep an idle connection
872
873       transparent = none | source | destination | both (Unix only)
874           enable transparent proxy support on selected platforms
875
876           Supported values:
877
878           none
879               Disable transparent proxy support.  This is the default.
880
881           source
882               Re-write the address to appear as if a wrapped daemon is
883               connecting from the TLS client machine instead of the machine
884               running stunnel.
885
886               This option is currently available in:
887
888               Remote mode (connect option) on Linux >=2.6.28
889                   This configuration requires stunnel to be executed as root
890                   and without the setuid option.
891
892                   This configuration requires the following setup for
893                   iptables and routing (possibly in /etc/rc.local or
894                   equivalent file):
895
896                       iptables -t mangle -N DIVERT
897                       iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
898                       iptables -t mangle -A DIVERT -j MARK --set-mark 1
899                       iptables -t mangle -A DIVERT -j ACCEPT
900                       ip rule add fwmark 1 lookup 100
901                       ip route add local 0.0.0.0/0 dev lo table 100
902                       echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter
903
904                   stunnel must also to be executed as root and without the
905                   setuid option.
906
907               Remote mode (connect option) on Linux 2.2.x
908                   This configuration requires the kernel to be compiled with
909                   the transparent proxy option.  Connected service must be
910                   installed on a separate host.  Routing towards the clients
911                   has to go through the stunnel box.
912
913                   stunnel must also to be executed as root and without the
914                   setuid option.
915
916               Remote mode (connect option) on FreeBSD >=8.0
917                   This configuration requires additional firewall and routing
918                   setup.  stunnel must also to be executed as root and
919                   without the setuid option.
920
921               Local mode (exec option)
922                   This configuration works by pre-loading the libstunnel.so
923                   shared library.  _RLD_LIST environment variable is used on
924                   Tru64, and LD_PRELOAD variable on other platforms.
925
926           destination
927               The original destination is used instead of the connect option.
928
929               A service section for transparent destination may look like
930               this:
931
932                   [transparent]
933                   client = yes
934                   accept = <stunnel_port>
935                   transparent = destination
936
937               This configuration requires iptables setup to work, possibly in
938               /etc/rc.local or equivalent file.
939
940               For a connect target installed on the same host:
941
942                   /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \
943                       -m ! --uid-owner <stunnel_user_id> \
944                       -j DNAT --to-destination <local_ip>:<stunnel_port>
945
946               For a connect target installed on a remote host:
947
948                   /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT
949                   /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \
950                       -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port>
951
952               The transparent destination option is currently only supported
953               on Linux.
954
955           both
956               Use both source and destination transparent proxy.
957
958           Two legacy options are also supported for backward compatibility:
959
960           yes This option has been renamed to source.
961
962           no  This option has been renamed to none.
963
964       verify = LEVEL
965           verify the peer certificate
966
967           This option is obsolete and should be replaced with the verifyChain
968           and verifyPeer options.
969
970           level 0
971               Request and ignore the peer certificate.
972
973           level 1
974               Verify the peer certificate if present.
975
976           level 2
977               Verify the peer certificate.
978
979           level 3
980               Verify the peer against a locally installed certificate.
981
982           level 4
983               Ignore the chain and only verify the peer certificate.
984
985           default
986               No verify.
987
988       verifyChain = yes | no
989           verify the peer certificate chain starting from the root CA
990
991           For server certificate verification it is essential to also require
992           a specific certificate with checkHost or checkIP.
993
994           The self-signed root CA certificate needs to be stored either in
995           the file specified with CAfile, or in the directory specified with
996           CApath.
997
998           default: no
999
1000       verifyPeer = yes | no
1001           verify the peer certificate
1002
1003           The peer certificate needs to be stored either in the file
1004           specified with CAfile, or in the directory specified with CApath.
1005
1006           default: no
1007

RETURN VALUE

1009       stunnel returns zero on success, non-zero on error.
1010

SIGNALS

1012       The following signals can be used to control stunnel in Unix
1013       environment:
1014
1015       SIGHUP
1016           Force a reload of the configuration file.
1017
1018           Some global options will not be reloaded:
1019
1020           ·   chroot
1021
1022           ·   foreground
1023
1024           ·   pid
1025
1026           ·   setgid
1027
1028           ·   setuid
1029
1030           The use of the 'setuid' option will also prevent stunnel from
1031           binding to privileged (<1024) ports during configuration reloading.
1032
1033           When the 'chroot' option is used, stunnel will look for all its
1034           files (including the configuration file, certificates, the log file
1035           and the pid file) within the chroot jail.
1036
1037       SIGUSR1
1038           Close and reopen the stunnel log file.  This function can be used
1039           for log rotation.
1040
1041       SIGTERM, SIGQUIT, SIGINT
1042           Shut stunnel down.
1043
1044       The result of sending any other signals to the server is undefined.
1045

EXAMPLES

1047       In order to provide TLS encapsulation to your local imapd service, use:
1048
1049           [imapd]
1050           accept = 993
1051           exec = /usr/sbin/imapd
1052           execArgs = imapd
1053
1054       or in remote mode:
1055
1056           [imapd]
1057           accept = 993
1058           connect = 143
1059
1060       In order to let your local e-mail client connect to a TLS-enabled imapd
1061       service on another server, configure the e-mail client to connect to
1062       localhost on port 119 and use:
1063
1064           [imap]
1065           client = yes
1066           accept = 143
1067           connect = servername:993
1068
1069       If you want to provide tunneling to your pppd daemon on port 2020, use
1070       something like:
1071
1072           [vpn]
1073           accept = 2020
1074           exec = /usr/sbin/pppd
1075           execArgs = pppd local
1076           pty = yes
1077
1078       If you want to use stunnel in inetd mode to launch your imapd process,
1079       you'd use this stunnel.conf.  Note there must be no [service_name]
1080       section.
1081
1082           exec = /usr/sbin/imapd
1083           execArgs = imapd
1084
1085       To setup SOCKS VPN configure the following client service:
1086
1087           [socks_client]
1088           client = yes
1089           accept = 127.0.0.1:1080
1090           connect = vpn_server:9080
1091           verifyPeer = yes
1092           CAfile = stunnel.pem
1093
1094       The corresponding configuration on the vpn_server host:
1095
1096           [socks_server]
1097           protocol = socks
1098           accept = 9080
1099           cert = stunnel.pem
1100           key = stunnel.key
1101
1102       Now test your configuration on the client machine with:
1103
1104           curl --socks4a localhost http://www.example.com/
1105
1106       An example server mode SNI configuration:
1107
1108           [virtual]
1109           ; master service
1110           accept = 443
1111           cert =  default.pem
1112           connect = default.internal.mydomain.com:8080
1113
1114           [sni1]
1115           ; slave service 1
1116           sni = virtual:server1.mydomain.com
1117           cert = server1.pem
1118           connect = server1.internal.mydomain.com:8081
1119
1120           [sni2]
1121           ; slave service 2
1122           sni = virtual:server2.mydomain.com
1123           cert = server2.pem
1124           connect = server2.internal.mydomain.com:8082
1125           verifyPeer = yes
1126           CAfile = server2-allowed-clients.pem
1127
1128       An example of advanced engine configuration allows for authentication
1129       with private keys stored in the Windows certificate store (Windows
1130       only).  With the CAPI engine you don't need to manually select the
1131       client key to use.  The client key is automatically selected based on
1132       the list of CAs trusted by the server.
1133
1134           engine = capi
1135
1136           [service]
1137           engineId = capi
1138           client = yes
1139           accept = 127.0.0.1:8080
1140           connect = example.com:8443
1141
1142       An example of advanced engine configuration to use the certificate and
1143       the corresponding private key from a pkcs11 engine:
1144
1145           engine = pkcs11
1146           engineCtrl = MODULE_PATH:opensc-pkcs11.so
1147           engineCtrl = PIN:123456
1148
1149           [service]
1150           engineId = pkcs11
1151           client = yes
1152           accept = 127.0.0.1:8080
1153           connect = example.com:843
1154           cert = pkcs11:token=MyToken;object=MyCert
1155           key = pkcs11:token=MyToken;object=MyKey
1156
1157       An example of advanced engine configuration to use the certificate and
1158       the corresponding private key from a SoftHSM token:
1159
1160           engine = pkcs11
1161           engineCtrl = MODULE_PATH:softhsm2.dll
1162           engineCtrl = PIN:12345
1163
1164           [service]
1165           engineId = pkcs11
1166           client = yes
1167           accept = 127.0.0.1:8080
1168           connect = example.com:843
1169           cert = pkcs11:token=MyToken;object=KeyCert
1170

NOTES

1172   RESTRICTIONS
1173       stunnel cannot be used for the FTP daemon because of the nature of the
1174       FTP protocol which utilizes multiple ports for data transfers.  There
1175       are available TLS-enabled versions of FTP and telnet daemons, however.
1176
1177   INETD MODE
1178       The most common use of stunnel is to listen on a network port and
1179       establish communication with either a new port via the connect option,
1180       or a new program via the exec option.  However there is a special case
1181       when you wish to have some other program accept incoming connections
1182       and launch stunnel, for example with inetd, xinetd, or tcpserver.
1183
1184       For example, if you have the following line in inetd.conf:
1185
1186           imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
1187
1188       In these cases, the inetd-style program is responsible for binding a
1189       network socket (imaps above) and handing it to stunnel when a
1190       connection is received.  Thus you do not want stunnel to have any
1191       accept option.  All the Service Level Options should be placed in the
1192       global options section, and no [service_name] section will be present.
1193       See the EXAMPLES section for example configurations.
1194
1195   CERTIFICATES
1196       Each TLS-enabled daemon needs to present a valid X.509 certificate to
1197       the peer. It also needs a private key to decrypt the incoming data. The
1198       easiest way to obtain a certificate and a key is to generate them with
1199       the free OpenSSL package. You can find more information on certificates
1200       generation on pages listed below.
1201
1202       The order of contents of the .pem file is important.  It should contain
1203       the unencrypted private key first, then a signed certificate (not
1204       certificate request).  There should also be empty lines after the
1205       certificate and the private key.  Any plaintext certificate information
1206       appended on the top of generated certificate should be discarded. So
1207       the file should look like this:
1208
1209           -----BEGIN RSA PRIVATE KEY-----
1210           [encoded key]
1211           -----END RSA PRIVATE KEY-----
1212           [empty line]
1213           -----BEGIN CERTIFICATE-----
1214           [encoded certificate]
1215           -----END CERTIFICATE-----
1216           [empty line]
1217
1218   RANDOMNESS
1219       stunnel needs to seed the PRNG (pseudo-random number generator) in
1220       order for TLS to use good randomness.  The following sources are loaded
1221       in order until sufficient random data has been gathered:
1222
1223       ·   The file specified with the RNDfile flag.
1224
1225       ·   The file specified by the RANDFILE environment variable, if set.
1226
1227       ·   The file .rnd in your home directory, if RANDFILE not set.
1228
1229       ·   The file specified with '--with-random' at compile time.
1230
1231       ·   The contents of the screen if running on Windows.
1232
1233       ·   The egd socket specified with the EGD flag.
1234
1235       ·   The egd socket specified with '--with-egd-sock' at compile time.
1236
1237       ·   The /dev/urandom device.
1238
1239       Note that on Windows machines that do not have console user interaction
1240       (mouse movements, creating windows, etc.) the screen contents are not
1241       variable enough to be sufficient, and you should provide a random file
1242       for use with the RNDfile flag.
1243
1244       Note that the file specified with the RNDfile flag should contain
1245       random data -- that means it should contain different information each
1246       time stunnel is run.  This is handled automatically unless the
1247       RNDoverwrite flag is used.  If you wish to update this file manually,
1248       the openssl rand command in recent versions of OpenSSL, would be
1249       useful.
1250
1251       Important note: If /dev/urandom is available, OpenSSL often seeds the
1252       PRNG with it while checking the random state.  On systems with
1253       /dev/urandom OpenSSL is likely to use it even though it is listed at
1254       the very bottom of the list above.  This is the behaviour of OpenSSL
1255       and not stunnel.
1256
1257   DH PARAMETERS
1258       stunnel 4.40 and later contains hardcoded 2048-bit DH parameters.
1259       Starting with stunnel 5.18, these hardcoded DH parameters are replaced
1260       every 24 hours with autogenerated temporary DH parameters.  DH
1261       parameter generation may take several minutes.
1262
1263       Alternatively, it is possible to specify static DH parameters in the
1264       certificate file, which disables generating temporary DH parameters:
1265
1266           openssl dhparam 2048 >> stunnel.pem
1267

FILES

1269       @sysconfdir@/stunnel/stunnel.conf
1270           stunnel configuration file
1271

BUGS

1273       The execArgs option and the Win32 command line do not support quoting.
1274

SEE ALSO

1276       tcpd(8)
1277           access control facility for internet services
1278
1279       inetd(8)
1280           internet 'super-server'
1281
1282       http://www.stunnel.org/
1283           stunnel homepage
1284
1285       http://www.openssl.org/
1286           OpenSSL project website
1287

AUTHOR

1289       Michał Trojnara
1290           <Michal.Trojnara@stunnel.org>
1291
1292
1293
12945.48                              2018.07.02                        stunnel(8)
Impressum