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

RETURN VALUE

1171       stunnel returns zero on success, non-zero on error.
1172

SIGNALS

1174       The following signals can be used to control stunnel in Unix
1175       environment:
1176
1177       SIGHUP
1178           Force a reload of the configuration file.
1179
1180           Some global options will not be reloaded:
1181
1182           •   chroot
1183
1184           •   foreground
1185
1186           •   pid
1187
1188           •   setgid
1189
1190           •   setuid
1191
1192           The use of the 'setuid' option will also prevent stunnel from
1193           binding to privileged (<1024) ports during configuration reloading.
1194
1195           When the 'chroot' option is used, stunnel will look for all its
1196           files (including the configuration file, certificates, the log file
1197           and the pid file) within the chroot jail.
1198
1199       SIGUSR1
1200           Close and reopen the stunnel log file.  This function can be used
1201           for log rotation.
1202
1203       SIGUSR2
1204           Log the list of active connections.
1205
1206       SIGTERM, SIGQUIT, SIGINT
1207           Shut stunnel down.
1208
1209       The result of sending any other signals to the server is undefined.
1210

EXAMPLES

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

NOTES

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

FILES

1429       @sysconfdir@/stunnel/stunnel.conf
1430           stunnel configuration file
1431

BUGS

1433       The execArgs option and the Win32 command line do not support quoting.
1434

SEE ALSO

1436       tcpd(8)
1437           access control facility for internet services
1438
1439       inetd(8)
1440           internet 'super-server'
1441
1442       http://www.stunnel.org/
1443           stunnel homepage
1444
1445       http://www.openssl.org/
1446           OpenSSL project website
1447

AUTHOR

1449       Michał Trojnara
1450           <Michal.Trojnara@stunnel.org>
1451
1452
1453
14545.58                              2021.03.02                        stunnel(8)
Impressum