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 (TLSv1.2 and below)
343
344           This option does not impact TLSv1.3 ciphersuites.
345
346           A colon-delimited list of the ciphers to allow in the TLS
347           connection, for example DES-CBC3-SHA:IDEA-CBC-MD5.
348
349       ciphersuites = CIPHERSUITES_LIST
350           select permitted TLSv1.3 ciphersuites
351
352           A colon-delimited list of TLSv1.3 ciphersuites names in order of
353           preference.
354
355           This option requires OpenSSL 1.1.1 or later.
356
357           default:
358           TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256
359
360       client = yes | no
361           client mode (remote service uses TLS)
362
363           default: no (server mode)
364
365       config = COMMAND[:PARAMETER]
366           OpenSSL configuration command
367
368           The OpenSSL configuration command is executed with the specified
369           parameter.  This allows any configuration commands to be invoked
370           from the stunnel configuration file.  Supported commands are
371           described on the SSL_CONF_cmd(3ssl) manual page.
372
373           Several config lines can be used to specify multiple configuration
374           commands.
375
376           Use curves option instead of enabling config = Curves:list_curves
377           to support elliptic curves.
378
379           This option requires OpenSSL 1.0.2 or later.
380
381       connect = [HOST:]PORT
382           connect to a remote address
383
384           If no host is specified, the host defaults to localhost.
385
386           Multiple connect options are allowed in a single service section.
387
388           If host resolves to multiple addresses and/or if multiple connect
389           options are specified, then the remote address is chosen using a
390           round-robin algorithm.
391
392       CRLpath = DIRECTORY
393           Certificate Revocation Lists directory
394
395           This is the directory in which stunnel will look for CRLs when
396           using the verifyChain and verifyPeer options. Note that the CRLs in
397           this directory should be named XXXXXXXX.r0 where XXXXXXXX is the
398           hash value of the CRL.
399
400           The hash algorithm has been changed in OpenSSL 1.0.0.  It is
401           required to c_rehash the directory on upgrade from OpenSSL 0.x.x to
402           OpenSSL 1.x.x.
403
404           CRLpath path is relative to the chroot directory if specified.
405
406       CRLfile = CRL_FILE
407           Certificate Revocation Lists file
408
409           This file contains multiple CRLs, used with the verifyChain and
410           verifyPeer options.
411
412       curves = list
413           ECDH curves separated with ':'
414
415           Note: This option is supported for server mode sockets only.
416
417           Only a single curve name is allowed for OpenSSL older than 1.1.1.
418
419           To get a list of supported curves use:
420
421               openssl ecparam -list_curves
422
423           default:
424
425               X25519:P-256:X448:P-521:P-384 (OpenSSL 1.1.1 or later)
426
427               prime256v1 (OpenSSL older than 1.1.1)
428
429       logId = TYPE
430           connection identifier type
431
432           This identifier allows you to distinguish log entries generated for
433           each of the connections.
434
435           Currently supported types:
436
437           sequential
438               The numeric sequential identifier is only unique within a
439               single instance of stunnel, but very compact.  It is most
440               useful for manual log analysis.
441
442           unique
443               This alphanumeric identifier is globally unique, but longer
444               than the sequential number.  It is most useful for automated
445               log analysis.
446
447           thread
448               The operating system thread identifier is neither unique (even
449               within a single instance of stunnel) nor short.  It is most
450               useful for debugging software or configuration issues.
451
452           process
453               The operating system process identifier (PID) may be useful in
454               the inetd mode.
455
456           default: sequential
457
458       debug = LEVEL
459           debugging level
460
461           Level is a one of the syslog level names or numbers emerg (0),
462           alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
463           debug (7).  All logs for the specified level and all levels
464           numerically less than it will be shown.  The default is notice (5).
465
466           While the debug = debug or debug = 7 level generates the most
467           verbose output, it is only intended to be used by stunnel
468           developers.  Please only use this value if you are a developer, or
469           you intend to send your logs to our technical support.  Otherwise,
470           the generated logs will be confusing.
471
472       delay = yes | no
473           delay DNS lookup for the connect option
474
475           This option is useful for dynamic DNS, or when DNS is not available
476           during stunnel startup (road warrior VPN, dial-up configurations).
477
478           Delayed resolver mode is automatically engaged when stunnel fails
479           to resolve on startup any of the connect targets for a service.
480
481           Delayed resolver inflicts failover = prio.
482
483           default: no
484
485       engineId = ENGINE_ID
486           select engine ID for the service
487
488       engineNum = ENGINE_NUMBER
489           select engine number for the service
490
491           The engines are numbered starting from 1.
492
493       exec = EXECUTABLE_PATH
494           execute a local inetd-type program
495
496           exec path is relative to the chroot directory if specified.
497
498           The following environmental variables are set on Unix platforms:
499           REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.
500
501       execArgs = $0 $1 $2 ...
502           arguments for exec including the program name ($0)
503
504           Quoting is currently not supported.  Arguments are separated with
505           an arbitrary amount of whitespace.
506
507       failover = rr | prio
508           Failover strategy for multiple "connect" targets.
509
510           rr  round robin - fair load distribution
511
512           prio
513               priority - use the order specified in config file
514
515           default: prio
516
517       ident = USERNAME
518           use IDENT (RFC 1413) username checking
519
520       include = DIRECTORY
521           include all configuration file parts located in DIRECTORY
522
523           The files are included in the ascending alphabetical order of their
524           names. The recommended filename convention is
525
526           for global options:
527
528                   00-global.conf
529
530           for local service-level options:
531
532                   01-service.conf
533
534                   02-service.conf
535
536       key = KEY_FILE
537           private key for the certificate specified with cert option
538
539           A private key is needed to authenticate the certificate owner.
540           Since this file should be kept secret it should only be readable by
541           its owner.  On Unix systems you can use the following command:
542
543               chmod 600 keyfile
544
545           This parameter is also used as the private key identifier when a
546           hardware engine is enabled.
547
548           default: the value of the cert option
549
550       libwrap = yes | no
551           Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
552
553           default: no (since version 5.00)
554
555       local = HOST
556           By default, the IP address of the outgoing interface is used as the
557           source for remote connections.  Use this option to bind a static
558           local IP address instead.
559
560       OCSP = URL
561           select OCSP responder for certificate verification
562
563       OCSPaia = yes | no
564           validate certificates with their AIA OCSP responders
565
566           This option enables stunnel to validate certificates with the list
567           of OCSP responder URLs retrieved from their AIA (Authority
568           Information Access) extension.
569
570       OCSPflag = OCSP_FLAG
571           specify OCSP responder flag
572
573           Several OCSPflag can be used to specify multiple flags.
574
575           currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN,
576           NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
577           RESPID_KEY, NOTIME
578
579       OCSPnonce = yes | no
580           send and verify the OCSP nonce extension
581
582           This option protects the OCSP protocol against replay attacks.  Due
583           to its computational overhead, the nonce extension is usually only
584           supported on internal (e.g. corporate) responders, and not on
585           public OCSP responders.
586
587       options = SSL_OPTIONS
588           OpenSSL library options
589
590           The parameter is the OpenSSL option name as described in the
591           SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix.
592           stunnel -options lists the options found to be allowed in the
593           current combination of stunnel and the OpenSSL library used to
594           build it.
595
596           Several option lines can be used to specify multiple options.  An
597           option name can be prepended with a dash ("-") to disable the
598           option.
599
600           For example, for compatibility with the erroneous Eudora TLS
601           implementation, the following option can be used:
602
603               options = DONT_INSERT_EMPTY_FRAGMENTS
604
605           default:
606
607               options = NO_SSLv2
608               options = NO_SSLv3
609
610           Use sslVersionMax or sslVersionMin option instead of disabling
611           specific TLS protocol versions when compiled with OpenSSL 1.1.0 or
612           later.
613
614       protocol = PROTO
615           application protocol to negotiate TLS
616
617           This option enables initial, protocol-specific negotiation of the
618           TLS encryption.  The protocol option should not be used with TLS
619           encryption on a separate port.
620
621           Currently supported protocols:
622
623           cifs
624               Proprietary (undocummented) extension of CIFS protocol
625               implemented in Samba.  Support for this extension was dropped
626               in Samba 3.0.0.
627
628           capwin
629               http://www.capwin.org/ application support
630
631           capwinctrl
632               http://www.capwin.org/ application support
633
634               This protocol is only supported in client mode.
635
636           connect
637               Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section
638               5.2 - Requesting a Tunnel with CONNECT
639
640               This protocol is only supported in client mode.
641
642           imap
643               Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP
644
645           ldap
646               Based on RFC 2830 - Lightweight Directory Access Protocol (v3):
647               Extension for Transport Layer Security
648
649           nntp
650               Based on RFC 4642 - Using Transport Layer Security (TLS) with
651               Network News Transfer Protocol (NNTP)
652
653               This protocol is only supported in client mode.
654
655           pgsql
656               Based on
657               http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
658
659           pop3
660               Based on RFC 2449 - POP3 Extension Mechanism
661
662           proxy
663               Passing of the original client IP address with HAProxy PROXY
664               protocol version 1
665               https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
666
667           smtp
668               Based on RFC 2487 - SMTP Service Extension for Secure SMTP over
669               TLS
670
671           socks
672               SOCKS versions 4, 4a, and 5 are supported.  The SOCKS protocol
673               itself is encapsulated within TLS encryption layer to protect
674               the final destination address.
675
676               http://www.openssh.com/txt/socks4.protocol
677
678               http://www.openssh.com/txt/socks4a.protocol
679
680               The BIND command of the SOCKS protocol is not supported.  The
681               USERID parameter is ignored.
682
683               See Examples section for sample configuration files for VPN
684               based on SOCKS encryption.
685
686       protocolAuthentication = AUTHENTICATION
687           authentication type for the protocol negotiations
688
689           Currently, this option is only supported in the client-side
690           'connect' and 'smtp' protocols.
691
692           Supported authentication types for the 'connect' protocol are
693           'basic' or 'ntlm'.  The default 'connect' authentication type is
694           'basic'.
695
696           Supported authentication types for the 'smtp' protocol are 'plain'
697           or 'login'.  The default 'smtp' authentication type is 'plain'.
698
699       protocolDomain = DOMAIN
700           domain for the protocol negotiations
701
702           Currently, this option is only supported in the client-side
703           'connect' protocol.
704
705       protocolHeader = HEADER
706           header for the protocol negotiations
707
708           Currently, this option is only supported in the client-side
709           'connect' protocol.
710
711       protocolHost = ADDRESS
712           host address for the protocol negotiations
713
714           For the 'connect' protocol negotiations, protocolHost specifies
715           HOST:PORT of the final TLS server to be connected to by the proxy.
716           The proxy server directly connected by stunnel must be specified
717           with the connect option.
718
719           For the 'smtp' protocol negotiations, protocolHost controls the
720           client SMTP HELO/EHLO value.
721
722       protocolPassword = PASSWORD
723           password for the protocol negotiations
724
725           Currently, this option is only supported in the client-side
726           'connect' and 'smtp' protocols.
727
728       protocolUsername = USERNAME
729           username for the protocol negotiations
730
731           Currently, this option is only supported in the client-side
732           'connect' and 'smtp' protocols.
733
734       PSKidentity = IDENTITY
735           PSK identity for the PSK client
736
737           PSKidentity can be used on stunnel clients to select the PSK
738           identity used for authentication.  This option is ignored in server
739           sections.
740
741           default: the first identity specified in the PSKsecrets file.
742
743       PSKsecrets = FILE
744           file with PSK identities and corresponding keys
745
746           Each line of the file in the following format:
747
748               IDENTITY:KEY
749
750           Hexadecimal keys are automatically converted to binary form.  Keys
751           are required to be at least 16 bytes long, which implies at least
752           32 characters for hexadecimal keys.  The file should neither be
753           world-readable nor world-writable.
754
755       pty = yes | no (Unix only)
756           allocate a pseudoterminal for 'exec' option
757
758       redirect = [HOST:]PORT
759           redirect TLS client connections on certificate-based authentication
760           failures
761
762           This option only works in server mode.  Some protocol negotiations
763           are also incompatible with the redirect option.
764
765       renegotiation = yes | no
766           support TLS renegotiation
767
768           Applications of the TLS renegotiation include some authentication
769           scenarios, or re-keying long lasting connections.
770
771           On the other hand this feature can facilitate a trivial CPU-
772           exhaustion DoS attack:
773
774           http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
775
776           Please note that disabling TLS renegotiation does not fully
777           mitigate this issue.
778
779           default: yes (if supported by OpenSSL)
780
781       reset = yes | no
782           attempt to use the TCP RST flag to indicate an error
783
784           This option is not supported on some platforms.
785
786           default: yes
787
788       retry = yes | no
789           reconnect a connect+exec section after it was disconnected
790
791           default: no
792
793       securityLevel = LEVEL
794           set the security level
795
796           The meaning of each level is described below:
797
798           level 0
799               Everything is permitted.
800
801           level 1
802               The security level corresponds to a minimum of 80 bits of
803               security. Any parameters offering below 80 bits of security are
804               excluded. As a result RSA, DSA and DH keys shorter than 1024
805               bits and ECC keys shorter than 160 bits are prohibited. All
806               export cipher suites are prohibited since they all offer less
807               than 80 bits of security. SSL version 2 is prohibited. Any
808               cipher suite using MD5 for the MAC is also prohibited.
809
810           level 2
811               Security level set to 112 bits of security. As a result RSA,
812               DSA and DH keys shorter than 2048 bits and ECC keys shorter
813               than 224 bits are prohibited. In addition to the level 1
814               exclusions any cipher suite using RC4 is also prohibited. SSL
815               version 3 is also not allowed. Compression is disabled.
816
817           level 3
818               Security level set to 128 bits of security. As a result RSA,
819               DSA and DH keys shorter than 3072 bits and ECC keys shorter
820               than 256 bits are prohibited. In addition to the level 2
821               exclusions cipher suites not offering forward secrecy are
822               prohibited. TLS versions below 1.1 are not permitted. Session
823               tickets are disabled.
824
825           level 4
826               Security level set to 192 bits of security. As a result RSA,
827               DSA and DH keys shorter than 7680 bits and ECC keys shorter
828               than 384 bits are prohibited. Cipher suites using SHA1 for the
829               MAC are prohibited. TLS versions below 1.2 are not permitted.
830
831           level 5
832               Security level set to 256 bits of security. As a result RSA,
833               DSA and DH keys shorter than 15360 bits and ECC keys shorter
834               than 512 bits are prohibited.
835
836           default: 2
837
838           The securityLevel option is only available when compiled with
839           OpenSSL 1.1.0 and later.
840
841       requireCert = yes | no
842           require a client certificate for verifyChain or verifyPeer
843
844           With requireCert set to no, the stunnel server accepts client
845           connections that did not present a certificate.
846
847           Both verifyChain = yes and verifyPeer = yes imply requireCert =
848           yes.
849
850           default: no
851
852       setgid = GROUP (Unix only)
853           Unix group id
854
855           As a global option: setgid() to the specified group in daemon mode
856           and clear all other groups.
857
858           As a service-level option: set the group of the Unix socket
859           specified with "accept".
860
861       setuid = USER (Unix only)
862           Unix user id
863
864           As a global option: setuid() to the specified user in daemon mode.
865
866           As a service-level option: set the owner of the Unix socket
867           specified with "accept".
868
869       sessionCacheSize = NUM_ENTRIES
870           session cache size
871
872           sessionCacheSize specifies the maximum number of the internal
873           session cache entries.
874
875           The value of 0 can be used for unlimited size.  It is not
876           recommended for production use due to the risk of a memory
877           exhaustion DoS attack.
878
879       sessionCacheTimeout = TIMEOUT
880           session cache timeout
881
882           This is the number of seconds to keep cached TLS sessions.
883
884       sessionResume = yes | no
885           allow or disallow session resumption
886
887           default: yes
888
889       sessiond = HOST:PORT
890           address of sessiond TLS cache server
891
892       sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)
893           Use the service as a slave service (a name-based virtual server)
894           for Server Name Indication TLS extension (RFC 3546).
895
896           SERVICE_NAME specifies the master service that accepts client
897           connections with the accept option.  SERVER_NAME_PATTERN specifies
898           the host name to be redirected.  The pattern may start with the '*'
899           character, e.g.  '*.example.com'.  Multiple slave services are
900           normally specified for a single master service.  The sni option can
901           also be specified more than once within a single slave service.
902
903           This service, as well as the master service, may not be configured
904           in client mode.
905
906           The connect option of the slave service is ignored when the
907           protocol option is specified, as protocol connects to the remote
908           host before TLS handshake.
909
910           Libwrap checks (Unix only) are performed twice: with the master
911           service name after TCP connection is accepted, and with the slave
912           service name during the TLS handshake.
913
914           The sni option is only available when compiled with OpenSSL 1.0.0
915           and later.
916
917       sni = SERVER_NAME (client mode)
918           Use the parameter as the value of TLS Server Name Indication (RFC
919           3546) extension.
920
921           Empty SERVER_NAME disables sending the SNI extension.
922
923           The sni option is only available when compiled with OpenSSL 1.0.0
924           and later.
925
926       socket = a|l|r:OPTION=VALUE[:VALUE]
927           Set an option on the accept/local/remote socket
928
929           The values for the linger option are l_onof:l_linger.  The values
930           for the time are tv_sec:tv_usec.
931
932           Examples:
933
934               socket = l:SO_LINGER=1:60
935                   set one minute timeout for closing local socket
936               socket = r:SO_OOBINLINE=yes
937                   place out-of-band data directly into the
938                   receive data stream for remote sockets
939               socket = a:SO_REUSEADDR=no
940                   disable address reuse (enabled by default)
941               socket = a:SO_BINDTODEVICE=lo
942                   only accept connections on loopback interface
943
944       sslVersion = SSL_VERSION
945           select the TLS protocol version
946
947           Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2,
948           TLSv1.3
949
950           Availability of specific protocols depends on the linked OpenSSL
951           library.  Older versions of OpenSSL do not support TLSv1.1, TLSv1.2
952           and TLSv1.3.  Newer versions of OpenSSL do not support SSLv2.
953
954           Obsolete SSLv2 and SSLv3 are currently disabled by default.
955
956           Setting the option
957
958               sslVersion = SSL_VERSION
959
960           is equivalent to options
961
962               sslVersionMax = SSL_VERSION
963               sslVersionMin = SSL_VERSION
964
965           when compiled with OpenSSL 1.1.0 and later.
966
967       sslVersionMax = SSL_VERSION
968           maximum supported protocol versions
969
970           Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
971
972           all enable protocol versions up to the highest version supported by
973           the linked OpenSSL library.
974
975           Availability of specific protocols depends on the linked OpenSSL
976           library.
977
978           The sslVersionMax option is only available when compiled with
979           OpenSSL 1.1.0 and later.
980
981           default: all
982
983       sslVersionMin = SSL_VERSION
984           minimum supported protocol versions
985
986           Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
987
988           all enable protocol versions down to the lowest version supported
989           by the linked OpenSSL library.
990
991           Availability of specific protocols depends on the linked OpenSSL
992           library.
993
994           The sslVersionMin option is only available when compiled with
995           OpenSSL 1.1.0 and later.
996
997           default: TLSv1
998
999       stack = BYTES (except for FORK model)
1000           CPU stack size of created threads
1001
1002           Excessive thread stack size increases virtual memory usage.
1003           Insufficient thread stack size may cause application crashes.
1004
1005           default: 65536 bytes (sufficient for all platforms we tested)
1006
1007       ticketKeySecret = SECRET
1008           hexadecimal symmetric key used for session ticket confidentiality
1009           protection
1010
1011           Session tickets defined in RFC 5077 provide an enhanced session
1012           resumption capability, where the server-side caching is not
1013           required to maintain per session state.
1014
1015           Combining ticketKeySecret and ticketMacSecret options allow to
1016           resume a negotiated session on other cluster nodes, or to resume a
1017           negotiated session after server restart.
1018
1019           The key is required to be either 16 or 32 bytes long, which implies
1020           exactly 32 or 64 hexadecimal digits.  Colons may optionally be used
1021           between two-character hexadecimal bytes.
1022
1023           This option only works in server mode.
1024
1025           The ticketKeySecret option is only available when compiled with
1026           OpenSSL 1.0.0 and later.
1027
1028           Disabling NO_TICKET option is required for the ticket support in
1029           OpenSSL older than 1.1.1, but note that this option is incompatible
1030           with the redirect option.
1031
1032       ticketMacSecret = SECRET
1033           hexadecimal symmetric key used for session ticket integrity
1034           protection
1035
1036           The key is required to be either 16 or 32 bytes long, which implies
1037           exactly 32 or 64 hexadecimal digits.  Colons may optionally be used
1038           between two-character hexadecimal bytes.
1039
1040           This option only works in server mode.
1041
1042           The ticketMacSecret option is only available when compiled with
1043           OpenSSL 1.0.0 and later.
1044
1045       TIMEOUTbusy = SECONDS
1046           time to wait for expected data
1047
1048       TIMEOUTclose = SECONDS
1049           time to wait for close_notify (set to 0 for buggy MSIE)
1050
1051       TIMEOUTconnect = SECONDS
1052           time to wait to connect to a remote host
1053
1054       TIMEOUTidle = SECONDS
1055           time to keep an idle connection
1056
1057       transparent = none | source | destination | both (Unix only)
1058           enable transparent proxy support on selected platforms
1059
1060           Supported values:
1061
1062           none
1063               Disable transparent proxy support.  This is the default.
1064
1065           source
1066               Re-write the address to appear as if a wrapped daemon is
1067               connecting from the TLS client machine instead of the machine
1068               running stunnel.
1069
1070               This option is currently available in:
1071
1072               Remote mode (connect option) on Linux >=2.6.28
1073                   This configuration requires stunnel to be executed as root
1074                   and without the setuid option.
1075
1076                   This configuration requires the following setup for
1077                   iptables and routing (possibly in /etc/rc.local or
1078                   equivalent file):
1079
1080                       iptables -t mangle -N DIVERT
1081                       iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
1082                       iptables -t mangle -A DIVERT -j MARK --set-mark 1
1083                       iptables -t mangle -A DIVERT -j ACCEPT
1084                       ip rule add fwmark 1 lookup 100
1085                       ip route add local 0.0.0.0/0 dev lo table 100
1086                       echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter
1087
1088                   stunnel must also to be executed as root and without the
1089                   setuid option.
1090
1091               Remote mode (connect option) on Linux 2.2.x
1092                   This configuration requires the kernel to be compiled with
1093                   the transparent proxy option.  Connected service must be
1094                   installed on a separate host.  Routing towards the clients
1095                   has to go through the stunnel box.
1096
1097                   stunnel must also to be executed as root and without the
1098                   setuid option.
1099
1100               Remote mode (connect option) on FreeBSD >=8.0
1101                   This configuration requires additional firewall and routing
1102                   setup.  stunnel must also to be executed as root and
1103                   without the setuid option.
1104
1105               Local mode (exec option)
1106                   This configuration works by pre-loading the libstunnel.so
1107                   shared library.  _RLD_LIST environment variable is used on
1108                   Tru64, and LD_PRELOAD variable on other platforms.
1109
1110           destination
1111               The original destination is used instead of the connect option.
1112
1113               A service section for transparent destination may look like
1114               this:
1115
1116                   [transparent]
1117                   client = yes
1118                   accept = <stunnel_port>
1119                   transparent = destination
1120
1121               This configuration requires iptables setup to work, possibly in
1122               /etc/rc.local or equivalent file.
1123
1124               For a connect target installed on the same host:
1125
1126                   /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \
1127                       -m ! --uid-owner <stunnel_user_id> \
1128                       -j DNAT --to-destination <local_ip>:<stunnel_port>
1129
1130               For a connect target installed on a remote host:
1131
1132                   /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT
1133                   /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \
1134                       -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port>
1135
1136               The transparent destination option is currently only supported
1137               on Linux.
1138
1139           both
1140               Use both source and destination transparent proxy.
1141
1142           Two legacy options are also supported for backward compatibility:
1143
1144           yes This option has been renamed to source.
1145
1146           no  This option has been renamed to none.
1147
1148       verify = LEVEL
1149           verify the peer certificate
1150
1151           This option is obsolete and should be replaced with the verifyChain
1152           and verifyPeer options.
1153
1154           level 0
1155               Request and ignore the peer certificate.
1156
1157           level 1
1158               Verify the peer certificate if present.
1159
1160           level 2
1161               Verify the peer certificate.
1162
1163           level 3
1164               Verify the peer against a locally installed certificate.
1165
1166           level 4
1167               Ignore the chain and only verify the peer certificate.
1168
1169           default
1170               No verify.
1171
1172       verifyChain = yes | no
1173           verify the peer certificate chain starting from the root CA
1174
1175           For server certificate verification it is essential to also require
1176           a specific certificate with checkHost or checkIP.
1177
1178           The self-signed root CA certificate needs to be stored either in
1179           the file specified with CAfile, or in the directory specified with
1180           CApath.
1181
1182           default: no
1183
1184       verifyPeer = yes | no
1185           verify the peer certificate
1186
1187           The peer certificate needs to be stored either in the file
1188           specified with CAfile, or in the directory specified with CApath.
1189
1190           default: no
1191

RETURN VALUE

1193       stunnel returns zero on success, non-zero on error.
1194

SIGNALS

1196       The following signals can be used to control stunnel in Unix
1197       environment:
1198
1199       SIGHUP
1200           Force a reload of the configuration file.
1201
1202           Some global options will not be reloaded:
1203
1204           •   chroot
1205
1206           •   foreground
1207
1208           •   pid
1209
1210           •   setgid
1211
1212           •   setuid
1213
1214           The use of the 'setuid' option will also prevent stunnel from
1215           binding to privileged (<1024) ports during configuration reloading.
1216
1217           When the 'chroot' option is used, stunnel will look for all its
1218           files (including the configuration file, certificates, the log file
1219           and the pid file) within the chroot jail.
1220
1221       SIGUSR1
1222           Close and reopen the stunnel log file.  This function can be used
1223           for log rotation.
1224
1225       SIGUSR2
1226           Log the list of active connections.
1227
1228       SIGTERM, SIGQUIT, SIGINT
1229           Shut stunnel down.
1230
1231       The result of sending any other signals to the server is undefined.
1232

EXAMPLES

1234       In order to provide TLS encapsulation to your local imapd service, use:
1235
1236           [imapd]
1237           accept = 993
1238           exec = /usr/sbin/imapd
1239           execArgs = imapd
1240
1241       or in remote mode:
1242
1243           [imapd]
1244           accept = 993
1245           connect = 143
1246
1247       In order to let your local e-mail client connect to a TLS-enabled imapd
1248       service on another server, configure the e-mail client to connect to
1249       localhost on port 119 and use:
1250
1251           [imap]
1252           client = yes
1253           accept = 143
1254           connect = servername:993
1255
1256       If you want to provide tunneling to your pppd daemon on port 2020, use
1257       something like:
1258
1259           [vpn]
1260           accept = 2020
1261           exec = /usr/sbin/pppd
1262           execArgs = pppd local
1263           pty = yes
1264
1265       If you want to use stunnel in inetd mode to launch your imapd process,
1266       you'd use this stunnel.conf.  Note there must be no [service_name]
1267       section.
1268
1269           exec = /usr/sbin/imapd
1270           execArgs = imapd
1271
1272       To setup SOCKS VPN configure the following client service:
1273
1274           [socks_client]
1275           client = yes
1276           accept = 127.0.0.1:1080
1277           connect = vpn_server:9080
1278           verifyPeer = yes
1279           CAfile = stunnel.pem
1280
1281       The corresponding configuration on the vpn_server host:
1282
1283           [socks_server]
1284           protocol = socks
1285           accept = 9080
1286           cert = stunnel.pem
1287           key = stunnel.key
1288
1289       Now test your configuration on the client machine with:
1290
1291           curl --socks4a localhost http://www.example.com/
1292
1293       An example server mode SNI configuration:
1294
1295           [virtual]
1296           ; master service
1297           accept = 443
1298           cert =  default.pem
1299           connect = default.internal.mydomain.com:8080
1300
1301           [sni1]
1302           ; slave service 1
1303           sni = virtual:server1.mydomain.com
1304           cert = server1.pem
1305           connect = server1.internal.mydomain.com:8081
1306
1307           [sni2]
1308           ; slave service 2
1309           sni = virtual:server2.mydomain.com
1310           cert = server2.pem
1311           connect = server2.internal.mydomain.com:8082
1312           verifyPeer = yes
1313           CAfile = server2-allowed-clients.pem
1314
1315       An example of advanced engine configuration allows for authentication
1316       with private keys stored in the Windows certificate store (Windows
1317       only).  With the CAPI engine you don't need to manually select the
1318       client key to use.  The client key is automatically selected based on
1319       the list of CAs trusted by the server.
1320
1321           engine = capi
1322
1323           [service]
1324           engineId = capi
1325           client = yes
1326           accept = 127.0.0.1:8080
1327           connect = example.com:8443
1328
1329       An example of advanced engine configuration to use the certificate and
1330       the corresponding private key from a pkcs11 engine:
1331
1332           engine = pkcs11
1333           engineCtrl = MODULE_PATH:opensc-pkcs11.so
1334           engineCtrl = PIN:123456
1335
1336           [service]
1337           engineId = pkcs11
1338           client = yes
1339           accept = 127.0.0.1:8080
1340           connect = example.com:843
1341           cert = pkcs11:token=MyToken;object=MyCert
1342           key = pkcs11:token=MyToken;object=MyKey
1343
1344       An example of advanced engine configuration to use the certificate and
1345       the corresponding private key from a SoftHSM token:
1346
1347           engine = pkcs11
1348           engineCtrl = MODULE_PATH:softhsm2.dll
1349           engineCtrl = PIN:12345
1350
1351           [service]
1352           engineId = pkcs11
1353           client = yes
1354           accept = 127.0.0.1:8080
1355           connect = example.com:843
1356           cert = pkcs11:token=MyToken;object=KeyCert
1357

NOTES

1359   RESTRICTIONS
1360       stunnel cannot be used for the FTP daemon because of the nature of the
1361       FTP protocol which utilizes multiple ports for data transfers.  There
1362       are available TLS-enabled versions of FTP and telnet daemons, however.
1363
1364   INETD MODE
1365       The most common use of stunnel is to listen on a network port and
1366       establish communication with either a new port via the connect option,
1367       or a new program via the exec option.  However there is a special case
1368       when you wish to have some other program accept incoming connections
1369       and launch stunnel, for example with inetd, xinetd, or tcpserver.
1370
1371       For example, if you have the following line in inetd.conf:
1372
1373           imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
1374
1375       In these cases, the inetd-style program is responsible for binding a
1376       network socket (imaps above) and handing it to stunnel when a
1377       connection is received.  Thus you do not want stunnel to have any
1378       accept option.  All the Service Level Options should be placed in the
1379       global options section, and no [service_name] section will be present.
1380       See the EXAMPLES section for example configurations.
1381
1382   CERTIFICATES
1383       Each TLS-enabled daemon needs to present a valid X.509 certificate to
1384       the peer. It also needs a private key to decrypt the incoming data. The
1385       easiest way to obtain a certificate and a key is to generate them with
1386       the free OpenSSL package. You can find more information on certificates
1387       generation on pages listed below.
1388
1389       The .pem file should contain the unencrypted private key and a signed
1390       certificate (not certificate request).  So the file should look like
1391       this:
1392
1393           -----BEGIN RSA PRIVATE KEY-----
1394           [encoded key]
1395           -----END RSA PRIVATE KEY-----
1396           -----BEGIN CERTIFICATE-----
1397           [encoded certificate]
1398           -----END CERTIFICATE-----
1399
1400   RANDOMNESS
1401       stunnel needs to seed the PRNG (pseudo-random number generator) in
1402       order for TLS to use good randomness.  The following sources are loaded
1403       in order until sufficient random data has been gathered:
1404
1405       •   The file specified with the RNDfile flag.
1406
1407       •   The file specified by the RANDFILE environment variable, if set.
1408
1409       •   The file .rnd in your home directory, if RANDFILE not set.
1410
1411       •   The file specified with '--with-random' at compile time.
1412
1413       •   The contents of the screen if running on Windows.
1414
1415       •   The egd socket specified with the EGD flag.
1416
1417       •   The egd socket specified with '--with-egd-sock' at compile time.
1418
1419       •   The /dev/urandom device.
1420
1421       Note that on Windows machines that do not have console user interaction
1422       (mouse movements, creating windows, etc.) the screen contents are not
1423       variable enough to be sufficient, and you should provide a random file
1424       for use with the RNDfile flag.
1425
1426       Note that the file specified with the RNDfile flag should contain
1427       random data -- that means it should contain different information each
1428       time stunnel is run.  This is handled automatically unless the
1429       RNDoverwrite flag is used.  If you wish to update this file manually,
1430       the openssl rand command in recent versions of OpenSSL, would be
1431       useful.
1432
1433       Important note: If /dev/urandom is available, OpenSSL often seeds the
1434       PRNG with it while checking the random state.  On systems with
1435       /dev/urandom OpenSSL is likely to use it even though it is listed at
1436       the very bottom of the list above.  This is the behaviour of OpenSSL
1437       and not stunnel.
1438
1439   DH PARAMETERS
1440       stunnel 4.40 and later contains hardcoded 2048-bit DH parameters.
1441       Starting with stunnel 5.18, these hardcoded DH parameters are replaced
1442       every 24 hours with autogenerated temporary DH parameters.  DH
1443       parameter generation may take several minutes.
1444
1445       Alternatively, it is possible to specify static DH parameters in the
1446       certificate file, which disables generating temporary DH parameters:
1447
1448           openssl dhparam 2048 >> stunnel.pem
1449

FILES

1451       /etc/stunnel/stunnel.conf
1452           stunnel configuration file
1453

BUGS

1455       The execArgs option and the Win32 command line do not support quoting.
1456

SEE ALSO

1458       tcpd(8)
1459           access control facility for internet services
1460
1461       inetd(8)
1462           internet 'super-server'
1463
1464       http://www.stunnel.org/
1465           stunnel homepage
1466
1467       http://www.openssl.org/
1468           OpenSSL project website
1469

AUTHOR

1471       Michał Trojnara
1472           <Michal.Trojnara@stunnel.org>
1473
1474
1475
14765.62                              2022.02.07                        stunnel(8)
Impressum