1stunnel(8) stunnel TLS Proxy stunnel(8)
2
6 stunnel - TLS offloading and load-balancing proxy
7
9 Unix:
10 stunnel [FILE] | -fd N | -help | -version | -sockets | -options
11 WIN32:
13 stunnel [ [ -install | -uninstall | -start | -stop |
14 -reload | -reopen | -exit ] [-quiet] [FILE] ] |
15 -help | -version | -sockets | -options
16
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 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 This product includes cryptographic software written by Eric Young
30 (eay@cryptsoft.com)
31
33 FILE
34 Use specified configuration file
35 -fd N (Unix only)
37 Read the config file from specified file descriptor
38 -help
40 Print stunnel help menu
41 -version
43 Print stunnel version and compile time defaults
44 -sockets
46 Print default socket options
47 -options
49 Print supported TLS options
50 -install (Windows NT and later only)
52 Install NT Service
53 -uninstall (Windows NT and later only)
55 Uninstall NT Service
56 -start (Windows NT and later only)
58 Start NT Service
59 -stop (Windows NT and later only)
61 Stop NT Service
62 -reload (Windows NT and later only)
64 Reload the configuration file of the running NT Service
65 -reopen (Windows NT and later only)
67 Reopen the log file of the running NT Service
68 -exit (Win32 only)
70 Exit an already started stunnel
71 -quiet (Win32 only)
73 Don't display any message boxes
74
76 Each line of the configuration file can be either:
77 • An empty line (ignored).
79 • A comment starting with ';' (ignored).
81 • An 'option_name = option_value' pair.
83 • '[service_name]' indicating a start of a service definition.
85 An address parameter of an option may be either:
87 • A port number.
89 • A colon-separated pair of IP address (either IPv4, IPv6, or domain
91 name) and port number.
92 • A Unix socket path (Unix only).
94 GLOBAL OPTIONS
96 chroot = DIRECTORY (Unix only)
97 directory to chroot stunnel process
98 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 Several functions of the operating system also need their files to
104 be located within the chroot jail, e.g.:
105 • Delayed resolver typically needs /etc/nsswitch.conf and
107 /etc/resolv.conf.
108 • Local time in log files needs /etc/timezone.
110 • Some other functions may need devices, e.g. /dev/zero or
112 /dev/null.
113 compression = deflate | zlib
115 select data compression algorithm
116 default: no compression
118 Deflate is the standard compression method as described in RFC
120 1951.
121 debug = [FACILITY.]LEVEL
123 debugging level
124 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 The syslog facility 'authpriv' will be used unless a facility name
132 is supplied. (Facilities are not supported on Win32.)
133 Case is ignored for both facilities and levels.
135 EGD = EGD_PATH (Unix only)
137 path to Entropy Gathering Daemon socket
138 Entropy Gathering Daemon socket to use to feed the OpenSSL random
140 number generator.
141 engine = auto | ENGINE_ID
143 select hardware or software cryptographic engine
144 default: software-only cryptography
146 See Examples section for an engine configuration to use the
148 certificate and the corresponding private key from a cryptographic
149 device.
150 engineCtrl = COMMAND[:PARAMETER]
152 control hardware engine
153 engineDefault = TASK_LIST
155 set OpenSSL tasks delegated to the current engine
156 The parameter specifies a comma-separated list of task to be
158 delegated to the current engine.
159 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 fips = yes | no
165 enable or disable FIPS 140-2 mode.
166 This option allows you to disable entering FIPS mode if stunnel was
168 compiled with FIPS 140-2 support.
169 default: no (since version 5.00)
171 foreground = yes | quiet | no (Unix only)
173 foreground mode
174 Stay in foreground (don't fork).
176 With the yes parameter it also logs to stderr in addition to the
178 destinations specified with syslog and output.
179 default: background in daemon mode
181 iconActive = ICON_FILE (GUI only)
183 GUI icon to be displayed when there are established connections
184 On Windows platform the parameter should be an .ico file containing
186 a 16x16 pixel image.
187 iconError = ICON_FILE (GUI only)
189 GUI icon to be displayed when no valid configuration is loaded
190 On Windows platform the parameter should be an .ico file containing
192 a 16x16 pixel image.
193 iconIdle = ICON_FILE (GUI only)
195 GUI icon to be displayed when there are no established connections
196 On Windows platform the parameter should be an .ico file containing
198 a 16x16 pixel image.
199 log = append | overwrite
201 log file handling
202 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 default: append
208 output = FILE
210 append log messages to a file
211 /dev/stdout device can be used to send log messages to the standard
213 output (for example to log them with daemontools splogger).
214 pid = FILE (Unix only)
216 pid file location
217 If the argument is empty, then no pid file will be created.
219 pid path is relative to the chroot directory if specified.
221 RNDbytes = BYTES
223 bytes to read from random seed files
224 RNDfile = FILE
226 path to file with random seed data
227 The OpenSSL library will use data from this file first to seed the
229 random number generator.
230 RNDoverwrite = yes | no
232 overwrite the random seed files with new random data
233 default: yes
235 service = SERVICE (Unix only)
237 stunnel service name
238 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 default: stunnel
245 syslog = yes | no (Unix only)
247 enable logging via syslog
248 default: yes
250 taskbar = yes | no (WIN32 only)
252 enable the taskbar icon
253 default: yes
255 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 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 accept = [HOST:]PORT
266 accept connections on specified address
267 If no host specified, defaults to all IPv4 addresses for the local
269 host.
270 To listen on all IPv6 addresses use:
272 accept = :::PORT
274 CApath = DIRECTORY
276 Certificate Authority directory
277 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 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 CApath path is relative to the chroot directory if specified.
288 CAfile = CA_FILE
290 Certificate Authority file
291 This file contains multiple CA certificates, to be used with the
293 verifyChain and verifyPeer options.
294 cert = CERT_FILE
296 certificate chain file name
297 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 A certificate chain is required in server mode, and optional in
306 client mode.
307 This parameter is also used as the certificate identifier when a
309 hardware engine is enabled.
310 checkEmail = EMAIL
312 email address of the peer certificate subject
313 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 This option requires OpenSSL 1.0.2 or later.
320 checkHost = HOST
322 host of the peer certificate subject
323 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 This option requires OpenSSL 1.0.2 or later.
330 checkIP = IP
332 IP address of the peer certificate subject
333 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 This option requires OpenSSL 1.0.2 or later.
340 ciphers = CIPHER_LIST
342 select permitted TLS ciphers (TLSv1.2 and below)
343 This option does not impact TLSv1.3 ciphersuites.
345 A colon-delimited list of the ciphers to allow in the TLS
347 connection, for example DES-CBC3-SHA:IDEA-CBC-MD5.
348 ciphersuites = CIPHERSUITES_LIST
350 select permitted TLSv1.3 ciphersuites
351 A colon-delimited list of TLSv1.3 ciphersuites names in order of
353 preference.
354 This option requires OpenSSL 1.1.1 or later.
356 default:
358 TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256
359 client = yes | no
361 client mode (remote service uses TLS)
362 default: no (server mode)
364 config = COMMAND[:PARAMETER]
366 OpenSSL configuration command
367 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 Several config lines can be used to specify multiple configuration
374 commands.
375 Use curves option instead of enabling config = Curves:list_curves
377 to support elliptic curves.
378 This option requires OpenSSL 1.0.2 or later.
380 connect = [HOST:]PORT
382 connect to a remote address
383 If no host is specified, the host defaults to localhost.
385 Multiple connect options are allowed in a single service section.
387 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 CRLpath = DIRECTORY
393 Certificate Revocation Lists directory
394 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 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 CRLpath path is relative to the chroot directory if specified.
405 CRLfile = CRL_FILE
407 Certificate Revocation Lists file
408 This file contains multiple CRLs, used with the verifyChain and
410 verifyPeer options.
411 curves = list
413 ECDH curves separated with ':'
414 Note: This option is supported for server mode sockets only.
416 Only a single curve name is allowed for OpenSSL older than 1.1.1.
418 To get a list of supported curves use:
420 openssl ecparam -list_curves
422 default:
424 X25519:P-256:X448:P-521:P-384 (OpenSSL 1.1.1 or later)
426 prime256v1 (OpenSSL older than 1.1.1)
428 logId = TYPE
430 connection identifier type
431 This identifier allows you to distinguish log entries generated for
433 each of the connections.
434 Currently supported types:
436 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 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 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 process
453 The operating system process identifier (PID) may be useful in
454 the inetd mode.
455 default: sequential
457 debug = LEVEL
459 debugging level
460 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 delay = yes | no
468 delay DNS lookup for the connect option
469 This option is useful for dynamic DNS, or when DNS is not available
471 during stunnel startup (road warrior VPN, dial-up configurations).
472 Delayed resolver mode is automatically engaged when stunnel fails
474 to resolve on startup any of the connect targets for a service.
475 Delayed resolver inflicts failover = prio.
477 default: no
479 engineId = ENGINE_ID
481 select engine ID for the service
482 engineNum = ENGINE_NUMBER
484 select engine number for the service
485 The engines are numbered starting from 1.
487 exec = EXECUTABLE_PATH
489 execute a local inetd-type program
490 exec path is relative to the chroot directory if specified.
492 The following environmental variables are set on Unix platforms:
494 REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.
495 execArgs = $0 $1 $2 ...
497 arguments for exec including the program name ($0)
498 Quoting is currently not supported. Arguments are separated with
500 an arbitrary amount of whitespace.
501 failover = rr | prio
503 Failover strategy for multiple "connect" targets.
504 rr round robin - fair load distribution
506 prio
508 priority - use the order specified in config file
509 default: prio
511 ident = USERNAME
513 use IDENT (RFC 1413) username checking
514 include = DIRECTORY
516 include all configuration file parts located in DIRECTORY
517 The files are included in the ascending alphabetical order of their
519 names. The recommended filename convention is
520 for global options:
522 00-global.conf
524 for local service-level options:
526 01-service.conf
528 02-service.conf
530 key = KEY_FILE
532 private key for the certificate specified with cert option
533 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 chmod 600 keyfile
539 This parameter is also used as the private key identifier when a
541 hardware engine is enabled.
542 default: the value of the cert option
544 libwrap = yes | no
546 Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
547 default: no (since version 5.00)
549 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 OCSP = URL
556 select OCSP responder for certificate verification
557 OCSPaia = yes | no
559 validate certificates with their AIA OCSP responders
560 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 OCSPflag = OCSP_FLAG
566 specify OCSP responder flag
567 Several OCSPflag can be used to specify multiple flags.
569 currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN,
571 NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
572 RESPID_KEY, NOTIME
573 OCSPnonce = yes | no
575 send and verify the OCSP nonce extension
576 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 options = SSL_OPTIONS
583 OpenSSL library options
584 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 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 For example, for compatibility with the erroneous Eudora TLS
596 implementation, the following option can be used:
597 options = DONT_INSERT_EMPTY_FRAGMENTS
599 default:
601 options = NO_SSLv2
603 options = NO_SSLv3
604 Use sslVersionMax or sslVersionMin option instead of disabling
606 specific TLS protocol versions when compiled with OpenSSL 1.1.0 or
607 later.
608 protocol = PROTO
610 application protocol to negotiate TLS
611 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 Currently supported protocols:
617 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 connect
624 Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section
625 5.2 - Requesting a Tunnel with CONNECT
626 This protocol is only supported in client mode.
628 imap
630 Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP
631 nntp
633 Based on RFC 4642 - Using Transport Layer Security (TLS) with
634 Network News Transfer Protocol (NNTP)
635 This protocol is only supported in client mode.
637 pgsql
639 Based on
640 http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
641 pop3
643 Based on RFC 2449 - POP3 Extension Mechanism
644 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 smtp
651 Based on RFC 2487 - SMTP Service Extension for Secure SMTP over
652 TLS
653 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 http://www.openssh.com/txt/socks4.protocol
660 http://www.openssh.com/txt/socks4a.protocol
662 The BIND command of the SOCKS protocol is not supported. The
664 USERID parameter is ignored.
665 See Examples section for sample configuration files for VPN
667 based on SOCKS encryption.
668 protocolAuthentication = AUTHENTICATION
670 authentication type for the protocol negotiations
671 Currently, this option is only supported in the client-side
673 'connect' and 'smtp' protocols.
674 Supported authentication types for the 'connect' protocol are
676 'basic' or 'ntlm'. The default 'connect' authentication type is
677 'basic'.
678 Supported authentication types for the 'smtp' protocol are 'plain'
680 or 'login'. The default 'smtp' authentication type is 'plain'.
681 protocolDomain = DOMAIN
683 domain for the protocol negotiations
684 Currently, this option is only supported in the client-side
686 'connect' protocol.
687 protocolHeader = HEADER
689 header for the protocol negotiations
690 Currently, this option is only supported in the client-side
692 'connect' protocol.
693 protocolHost = ADDRESS
695 host address for the protocol negotiations
696 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 For the 'smtp' protocol negotiations, protocolHost controls the
703 client SMTP HELO/EHLO value.
704 protocolPassword = PASSWORD
706 password for the protocol negotiations
707 Currently, this option is only supported in the client-side
709 'connect' and 'smtp' protocols.
710 protocolUsername = USERNAME
712 username for the protocol negotiations
713 Currently, this option is only supported in the client-side
715 'connect' and 'smtp' protocols.
716 PSKidentity = IDENTITY
718 PSK identity for the PSK client
719 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 default: the first identity specified in the PSKsecrets file.
725 PSKsecrets = FILE
727 file with PSK identities and corresponding keys
728 Each line of the file in the following format:
730 IDENTITY:KEY
732 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 pty = yes | no (Unix only)
739 allocate a pseudoterminal for 'exec' option
740 redirect = [HOST:]PORT
742 redirect TLS client connections on certificate-based authentication
743 failures
744 This option only works in server mode. Some protocol negotiations
746 are also incompatible with the redirect option.
747 renegotiation = yes | no
749 support TLS renegotiation
750 Applications of the TLS renegotiation include some authentication
752 scenarios, or re-keying long lasting connections.
753 On the other hand this feature can facilitate a trivial CPU-
755 exhaustion DoS attack:
756 http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
758 Please note that disabling TLS renegotiation does not fully
760 mitigate this issue.
761 default: yes (if supported by OpenSSL)
763 reset = yes | no
765 attempt to use the TCP RST flag to indicate an error
766 This option is not supported on some platforms.
768 default: yes
770 retry = yes | no
772 reconnect a connect+exec section after it was disconnected
773 default: no
775 securityLevel = LEVEL
777 set the security level
778 The meaning of each level is described below:
780 level 0
782 Everything is permitted.
783 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 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 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 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 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 default: 2
820 The securityLevel option is only available when compiled with
822 OpenSSL 1.1.0 and later.
823 requireCert = yes | no
825 require a client certificate for verifyChain or verifyPeer
826 With requireCert set to no, the stunnel server accepts client
828 connections that did not present a certificate.
829 Both verifyChain = yes and verifyPeer = yes imply requireCert =
831 yes.
832 default: no
834 setgid = GROUP (Unix only)
836 Unix group id
837 As a global option: setgid() to the specified group in daemon mode
839 and clear all other groups.
840 As a service-level option: set the group of the Unix socket
842 specified with "accept".
843 setuid = USER (Unix only)
845 Unix user id
846 As a global option: setuid() to the specified user in daemon mode.
848 As a service-level option: set the owner of the Unix socket
850 specified with "accept".
851 sessionCacheSize = NUM_ENTRIES
853 session cache size
854 sessionCacheSize specifies the maximum number of the internal
856 session cache entries.
857 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 sessionCacheTimeout = TIMEOUT
863 session cache timeout
864 This is the number of seconds to keep cached TLS sessions.
866 sessiond = HOST:PORT
868 address of sessiond TLS cache server
869 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 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 This service, as well as the master service, may not be configured
882 in client mode.
883 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 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 The sni option is only available when compiled with OpenSSL 1.0.0
893 and later.
894 sni = SERVER_NAME (client mode)
896 Use the parameter as the value of TLS Server Name Indication (RFC
897 3546) extension.
898 Empty SERVER_NAME disables sending the SNI extension.
900 The sni option is only available when compiled with OpenSSL 1.0.0
902 and later.
903 socket = a|l|r:OPTION=VALUE[:VALUE]
905 Set an option on the accept/local/remote socket
906 The values for the linger option are l_onof:l_linger. The values
908 for the time are tv_sec:tv_usec.
909 Examples:
911 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 sslVersion = SSL_VERSION
923 select the TLS protocol version
924 Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2,
926 TLSv1.3
927 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 Obsolete SSLv2 and SSLv3 are currently disabled by default.
933 Setting the option
935 sslVersion = SSL_VERSION
937 is equivalent to options
939 sslVersionMax = SSL_VERSION
941 sslVersionMin = SSL_VERSION
942 when compiled with OpenSSL 1.1.0 and later.
944 sslVersionMax = SSL_VERSION
946 maximum supported protocol versions
947 Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
949 all enable protocol versions up to the highest version supported by
951 the linked OpenSSL library.
952 Availability of specific protocols depends on the linked OpenSSL
954 library.
955 The sslVersionMax option is only available when compiled with
957 OpenSSL 1.1.0 and later.
958 default: all
960 sslVersionMin = SSL_VERSION
962 minimum supported protocol versions
963 Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
965 all enable protocol versions down to the lowest version supported
967 by the linked OpenSSL library.
968 Availability of specific protocols depends on the linked OpenSSL
970 library.
971 The sslVersionMin option is only available when compiled with
973 OpenSSL 1.1.0 and later.
974 default: TLSv1
976 stack = BYTES (except for FORK model)
978 CPU stack size of created threads
979 Excessive thread stack size increases virtual memory usage.
981 Insufficient thread stack size may cause application crashes.
982 default: 65536 bytes (sufficient for all platforms we tested)
984 ticketKeySecret = SECRET
986 hexadecimal symmetric key used for session ticket confidentiality
987 protection
988 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 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 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 This option only works in server mode.
1002 The ticketKeySecret option is only available when compiled with
1004 OpenSSL 1.0.0 and later.
1005 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 ticketMacSecret = SECRET
1011 hexadecimal symmetric key used for session ticket integrity
1012 protection
1013 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 This option only works in server mode.
1019 The ticketMacSecret option is only available when compiled with
1021 OpenSSL 1.0.0 and later.
1022 TIMEOUTbusy = SECONDS
1024 time to wait for expected data
1025 TIMEOUTclose = SECONDS
1027 time to wait for close_notify (set to 0 for buggy MSIE)
1028 TIMEOUTconnect = SECONDS
1030 time to wait to connect to a remote host
1031 TIMEOUTidle = SECONDS
1033 time to keep an idle connection
1034 transparent = none | source | destination | both (Unix only)
1036 enable transparent proxy support on selected platforms
1037 Supported values:
1039 none
1041 Disable transparent proxy support. This is the default.
1042 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 This option is currently available in:
1049 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 This configuration requires the following setup for
1055 iptables and routing (possibly in /etc/rc.local or
1056 equivalent file):
1057 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 stunnel must also to be executed as root and without the
1067 setuid option.
1068 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 stunnel must also to be executed as root and without the
1076 setuid option.
1077 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 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 destination
1089 The original destination is used instead of the connect option.
1090 A service section for transparent destination may look like
1092 this:
1093 [transparent]
1095 client = yes
1096 accept = <stunnel_port>
1097 transparent = destination
1098 This configuration requires iptables setup to work, possibly in
1100 /etc/rc.local or equivalent file.
1101 For a connect target installed on the same host:
1103 /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 For a connect target installed on a remote host:
1109 /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 The transparent destination option is currently only supported
1115 on Linux.
1116 both
1118 Use both source and destination transparent proxy.
1119 Two legacy options are also supported for backward compatibility:
1121 yes This option has been renamed to source.
1123 no This option has been renamed to none.
1125 verify = LEVEL
1127 verify the peer certificate
1128 This option is obsolete and should be replaced with the verifyChain
1130 and verifyPeer options.
1131 level 0
1133 Request and ignore the peer certificate.
1134 level 1
1136 Verify the peer certificate if present.
1137 level 2
1139 Verify the peer certificate.
1140 level 3
1142 Verify the peer against a locally installed certificate.
1143 level 4
1145 Ignore the chain and only verify the peer certificate.
1146 default
1148 No verify.
1149 verifyChain = yes | no
1151 verify the peer certificate chain starting from the root CA
1152 For server certificate verification it is essential to also require
1154 a specific certificate with checkHost or checkIP.
1155 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 default: no
1161 verifyPeer = yes | no
1163 verify the peer certificate
1164 The peer certificate needs to be stored either in the file
1166 specified with CAfile, or in the directory specified with CApath.
1167 default: no
1169
1171 stunnel returns zero on success, non-zero on error.
1172
1174 The following signals can be used to control stunnel in Unix
1175 environment:
1176 SIGHUP
1178 Force a reload of the configuration file.
1179 Some global options will not be reloaded:
1181 • chroot
1183 • foreground
1185 • pid
1187 • setgid
1189 • setuid
1191 The use of the 'setuid' option will also prevent stunnel from
1193 binding to privileged (<1024) ports during configuration reloading.
1194 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 SIGUSR1
1200 Close and reopen the stunnel log file. This function can be used
1201 for log rotation.
1202 SIGUSR2
1204 Log the list of active connections.
1205 SIGTERM, SIGQUIT, SIGINT
1207 Shut stunnel down.
1208 The result of sending any other signals to the server is undefined.
1210
1212 In order to provide TLS encapsulation to your local imapd service, use:
1213 [imapd]
1215 accept = 993
1216 exec = /usr/sbin/imapd
1217 execArgs = imapd
1218 or in remote mode:
1220 [imapd]
1222 accept = 993
1223 connect = 143
1224 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 [imap]
1230 client = yes
1231 accept = 143
1232 connect = servername:993
1233 If you want to provide tunneling to your pppd daemon on port 2020, use
1235 something like:
1236 [vpn]
1238 accept = 2020
1239 exec = /usr/sbin/pppd
1240 execArgs = pppd local
1241 pty = yes
1242 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 exec = /usr/sbin/imapd
1248 execArgs = imapd
1249 To setup SOCKS VPN configure the following client service:
1251 [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 The corresponding configuration on the vpn_server host:
1260 [socks_server]
1262 protocol = socks
1263 accept = 9080
1264 cert = stunnel.pem
1265 key = stunnel.key
1266 Now test your configuration on the client machine with:
1268 curl --socks4a localhost http://www.example.com/
1270 An example server mode SNI configuration:
1272 [virtual]
1274 ; master service
1275 accept = 443
1276 cert = default.pem
1277 connect = default.internal.mydomain.com:8080
1278 [sni1]
1280 ; slave service 1
1281 sni = virtual:server1.mydomain.com
1282 cert = server1.pem
1283 connect = server1.internal.mydomain.com:8081
1284 [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 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 engine = capi
1300 [service]
1302 engineId = capi
1303 client = yes
1304 accept = 127.0.0.1:8080
1305 connect = example.com:8443
1306 An example of advanced engine configuration to use the certificate and
1308 the corresponding private key from a pkcs11 engine:
1309 engine = pkcs11
1311 engineCtrl = MODULE_PATH:opensc-pkcs11.so
1312 engineCtrl = PIN:123456
1313 [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 An example of advanced engine configuration to use the certificate and
1323 the corresponding private key from a SoftHSM token:
1324 engine = pkcs11
1326 engineCtrl = MODULE_PATH:softhsm2.dll
1327 engineCtrl = PIN:12345
1328 [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
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 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 For example, if you have the following line in inetd.conf:
1350 imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
1352 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 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 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 -----BEGIN RSA PRIVATE KEY-----
1372 [encoded key]
1373 -----END RSA PRIVATE KEY-----
1374 -----BEGIN CERTIFICATE-----
1375 [encoded certificate]
1376 -----END CERTIFICATE-----
1377 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 • The file specified with the RNDfile flag.
1384 • The file specified by the RANDFILE environment variable, if set.
1386 • The file .rnd in your home directory, if RANDFILE not set.
1388 • The file specified with '--with-random' at compile time.
1390 • The contents of the screen if running on Windows.
1392 • The egd socket specified with the EGD flag.
1394 • The egd socket specified with '--with-egd-sock' at compile time.
1396 • The /dev/urandom device.
1398 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 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 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 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 Alternatively, it is possible to specify static DH parameters in the
1424 certificate file, which disables generating temporary DH parameters:
1425 openssl dhparam 2048 >> stunnel.pem
1427
1429 @sysconfdir@/stunnel/stunnel.conf
1430 stunnel configuration file
1431
1433 The execArgs option and the Win32 command line do not support quoting.
1434
1436 tcpd(8)
1437 access control facility for internet services
1438 inetd(8)
1440 internet 'super-server'
1441 http://www.stunnel.org/
1443 stunnel homepage
1444 http://www.openssl.org/
1446 OpenSSL project website
1447
1449 Michał Trojnara
1450 <Michal.Trojnara@stunnel.org>
14515.58 2021.03.02 stunnel(8)