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
343 A colon-delimited list of the ciphers to allow in the TLS
345 connection, for example DES-CBC3-SHA:IDEA-CBC-MD5.
346 client = yes | no
348 client mode (remote service uses TLS)
349 default: no (server mode)
351 config = COMMAND[:PARAMETER]
353 OpenSSL configuration command
354 The OpenSSL configuration command is executed with the specified
356 parameter. This allows any configuration commands to be invoked
357 from the stunnel configuration file. Supported commands are
358 described on the SSL_CONF_cmd(3ssl) manual page.
359 Several config lines can be used to specify multiple configuration
361 commands.
362 This option requires OpenSSL 1.0.2 or later.
364 connect = [HOST:]PORT
366 connect to a remote address
367 If no host is specified, the host defaults to localhost.
369 Multiple connect options are allowed in a single service section.
371 If host resolves to multiple addresses and/or if multiple connect
373 options are specified, then the remote address is chosen using a
374 round-robin algorithm.
375 CRLpath = DIRECTORY
377 Certificate Revocation Lists directory
378 This is the directory in which stunnel will look for CRLs when
380 using the verifyChain and verifyPeer options. Note that the CRLs in
381 this directory should be named XXXXXXXX.r0 where XXXXXXXX is the
382 hash value of the CRL.
383 The hash algorithm has been changed in OpenSSL 1.0.0. It is
385 required to c_rehash the directory on upgrade from OpenSSL 0.x.x to
386 OpenSSL 1.x.x.
387 CRLpath path is relative to the chroot directory if specified.
389 CRLfile = CRL_FILE
391 Certificate Revocation Lists file
392 This file contains multiple CRLs, used with the verifyChain and
394 verifyPeer options.
395 curve = NID
397 specify ECDH curve name
398 To get a list of supported curves use:
400 openssl ecparam -list_curves
402 default: prime256v1
404 logId = TYPE
406 connection identifier type
407 This identifier allows you to distinguish log entries generated for
409 each of the connections.
410 Currently supported types:
412 sequential
414 The numeric sequential identifier is only unique within a
415 single instance of stunnel, but very compact. It is most
416 useful for manual log analysis.
417 unique
419 This alphanumeric identifier is globally unique, but longer
420 than the sequential number. It is most useful for automated
421 log analysis.
422 thread
424 The operating system thread identifier is neither unique (even
425 within a single instance of stunnel) nor short. It is most
426 useful for debugging software or configuration issues.
427 process
429 The operating system process identifier (PID) may be useful in
430 the inetd mode.
431 default: sequential
433 debug = LEVEL
435 debugging level
436 Level is a one of the syslog level names or numbers emerg (0),
438 alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
439 debug (7). All logs for the specified level and all levels
440 numerically less than it will be shown. Use debug = debug or debug
441 = 7 for greatest debugging output. The default is notice (5).
442 delay = yes | no
444 delay DNS lookup for the connect option
445 This option is useful for dynamic DNS, or when DNS is not available
447 during stunnel startup (road warrior VPN, dial-up configurations).
448 Delayed resolver mode is automatically engaged when stunnel fails
450 to resolve on startup any of the connect targets for a service.
451 Delayed resolver inflicts failover = prio.
453 default: no
455 engineId = ENGINE_ID
457 select engine ID for the service
458 engineNum = ENGINE_NUMBER
460 select engine number for the service
461 The engines are numbered starting from 1.
463 exec = EXECUTABLE_PATH
465 execute a local inetd-type program
466 exec path is relative to the chroot directory if specified.
468 The following environmental variables are set on Unix platforms:
470 REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.
471 execArgs = $0 $1 $2 ...
473 arguments for exec including the program name ($0)
474 Quoting is currently not supported. Arguments are separated with
476 an arbitrary amount of whitespace.
477 failover = rr | prio
479 Failover strategy for multiple "connect" targets.
480 rr round robin - fair load distribution
482 prio
484 priority - use the order specified in config file
485 default: prio
487 ident = USERNAME
489 use IDENT (RFC 1413) username checking
490 include = DIRECTORY
492 include all configuration file parts located in DIRECTORY
493 The files are included in the ascending alphabetical order of their
495 names. The recommended filename convention is
496 for global options:
498 00-global.conf
500 for local service-level options:
502 01-service.conf
504 02-service.conf
506 key = KEY_FILE
508 private key for the certificate specified with cert option
509 A private key is needed to authenticate the certificate owner.
511 Since this file should be kept secret it should only be readable by
512 its owner. On Unix systems you can use the following command:
513 chmod 600 keyfile
515 This parameter is also used as the private key identifier when a
517 hardware engine is enabled.
518 default: the value of the cert option
520 libwrap = yes | no
522 Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
523 default: no (since version 5.00)
525 local = HOST
527 By default, the IP address of the outgoing interface is used as the
528 source for remote connections. Use this option to bind a static
529 local IP address instead.
530 OCSP = URL
532 select OCSP responder for certificate verification
533 OCSPaia = yes | no
535 validate certificates with their AIA OCSP responders
536 This option enables stunnel to validate certificates with the list
538 of OCSP responder URLs retrieved from their AIA (Authority
539 Information Access) extension.
540 OCSPflag = OCSP_FLAG
542 specify OCSP responder flag
543 Several OCSPflag can be used to specify multiple flags.
545 currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN,
547 NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
548 RESPID_KEY, NOTIME
549 OCSPnonce = yes | no
551 send and verify the OCSP nonce extension
552 This option protects the OCSP protocol against replay attacks. Due
554 to its computational overhead, the nonce extension is usually only
555 supported on internal (e.g. corporate) responders, and not on
556 public OCSP responders.
557 options = SSL_OPTIONS
559 OpenSSL library options
560 The parameter is the OpenSSL option name as described in the
562 SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix.
563 stunnel -options lists the options found to be allowed in the
564 current combination of stunnel and the OpenSSL library used to
565 build it.
566 Several option lines can be used to specify multiple options. An
568 option name can be prepended with a dash ("-") to disable the
569 option.
570 For example, for compatibility with the erroneous Eudora TLS
572 implementation, the following option can be used:
573 options = DONT_INSERT_EMPTY_FRAGMENTS
575 default:
577 options = NO_SSLv2
579 options = NO_SSLv3
580 Use sslVersionMax or sslVersionMin option instead of disabling
582 specific TLS protocol versions when compiled with OpenSSL 1.1.0 or
583 later.
584 protocol = PROTO
586 application protocol to negotiate TLS
587 This option enables initial, protocol-specific negotiation of the
589 TLS encryption. The protocol option should not be used with TLS
590 encryption on a separate port.
591 Currently supported protocols:
593 cifs
595 Proprietary (undocummented) extension of CIFS protocol
596 implemented in Samba. Support for this extension was dropped
597 in Samba 3.0.0.
598 connect
600 Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section
601 5.2 - Requesting a Tunnel with CONNECT
602 This protocol is only supported in client mode.
604 imap
606 Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP
607 nntp
609 Based on RFC 4642 - Using Transport Layer Security (TLS) with
610 Network News Transfer Protocol (NNTP)
611 This protocol is only supported in client mode.
613 pgsql
615 Based on
616 http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
617 pop3
619 Based on RFC 2449 - POP3 Extension Mechanism
620 proxy
622 Haproxy client IP address
623 http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
624 smtp
626 Based on RFC 2487 - SMTP Service Extension for Secure SMTP over
627 TLS
628 socks
630 SOCKS versions 4, 4a, and 5 are supported. The SOCKS protocol
631 itself is encapsulated within TLS encryption layer to protect
632 the final destination address.
633 http://www.openssh.com/txt/socks4.protocol
635 http://www.openssh.com/txt/socks4a.protocol
637 The BIND command of the SOCKS protocol is not supported. The
639 USERID parameter is ignored.
640 See Examples section for sample configuration files for VPN
642 based on SOCKS encryption.
643 protocolAuthentication = AUTHENTICATION
645 authentication type for the protocol negotiations
646 Currently, this option is only supported in the client-side
648 'connect' and 'smtp' protocols.
649 Supported authentication types for the 'connect' protocol are
651 'basic' or 'ntlm'. The default 'connect' authentication type is
652 'basic'.
653 Supported authentication types for the 'smtp' protocol are 'plain'
655 or 'login'. The default 'smtp' authentication type is 'plain'.
656 protocolDomain = DOMAIN
658 domain for the protocol negotiations
659 Currently, this option is only supported in the client-side
661 'connect' protocol.
662 protocolHost = HOST:PORT
664 destination address for the protocol negotiations
665 protocolHost specifies the final TLS server to be connected to by
667 the proxy, and not the proxy server directly connected by stunnel.
668 The proxy server should be specified with the 'connect' option.
669 Currently the protocol destination address only applies to the
671 'connect' protocol.
672 protocolPassword = PASSWORD
674 password for the protocol negotiations
675 Currently, this option is only supported in the client-side
677 'connect' and 'smtp' protocols.
678 protocolUsername = USERNAME
680 username for the protocol negotiations
681 Currently, this option is only supported in the client-side
683 'connect' and 'smtp' protocols.
684 PSKidentity = IDENTITY
686 PSK identity for the PSK client
687 PSKidentity can be used on stunnel clients to select the PSK
689 identity used for authentication. This option is ignored in server
690 sections.
691 default: the first identity specified in the PSKsecrets file.
693 PSKsecrets = FILE
695 file with PSK identities and corresponding keys
696 Each line of the file in the following format:
698 IDENTITY:KEY
700 The key is required to be at least 20 characters long. The file
702 should not be world-readable nor world-writable.
703 pty = yes | no (Unix only)
705 allocate a pseudoterminal for 'exec' option
706 redirect = [HOST:]PORT
708 redirect TLS client connections on certificate-based authentication
709 failures
710 This option only works in server mode. Some protocol negotiations
712 are also incompatible with the redirect option.
713 renegotiation = yes | no
715 support TLS renegotiation
716 Applications of the TLS renegotiation include some authentication
718 scenarios, or re-keying long lasting connections.
719 On the other hand this feature can facilitate a trivial CPU-
721 exhaustion DoS attack:
722 http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
724 Please note that disabling TLS renegotiation does not fully
726 mitigate this issue.
727 default: yes (if supported by OpenSSL)
729 reset = yes | no
731 attempt to use the TCP RST flag to indicate an error
732 This option is not supported on some platforms.
734 default: yes
736 retry = yes | no
738 reconnect a connect+exec section after it was disconnected
739 default: no
741 requireCert = yes | no
743 require a client certificate for verifyChain or verifyPeer
744 With requireCert set to no, the stunnel server accepts client
746 connections that did not present a certificate.
747 Both verifyChain = yes and verifyPeer = yes imply requireCert =
749 yes.
750 default: no
752 setgid = GROUP (Unix only)
754 Unix group id
755 As a global option: setgid() to the specified group in daemon mode
757 and clear all other groups.
758 As a service-level option: set the group of the Unix socket
760 specified with "accept".
761 setuid = USER (Unix only)
763 Unix user id
764 As a global option: setuid() to the specified user in daemon mode.
766 As a service-level option: set the owner of the Unix socket
768 specified with "accept".
769 sessionCacheSize = NUM_ENTRIES
771 session cache size
772 sessionCacheSize specifies the maximum number of the internal
774 session cache entries.
775 The value of 0 can be used for unlimited size. It is not
777 recommended for production use due to the risk of a memory
778 exhaustion DoS attack.
779 sessionCacheTimeout = TIMEOUT
781 session cache timeout
782 This is the number of seconds to keep cached TLS sessions.
784 sessiond = HOST:PORT
786 address of sessiond TLS cache server
787 sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)
789 Use the service as a slave service (a name-based virtual server)
790 for Server Name Indication TLS extension (RFC 3546).
791 SERVICE_NAME specifies the master service that accepts client
793 connections with the accept option. SERVER_NAME_PATTERN specifies
794 the host name to be redirected. The pattern may start with the '*'
795 character, e.g. '*.example.com'. Multiple slave services are
796 normally specified for a single master service. The sni option can
797 also be specified more than once within a single slave service.
798 This service, as well as the master service, may not be configured
800 in client mode.
801 The connect option of the slave service is ignored when the
803 protocol option is specified, as protocol connects to the remote
804 host before TLS handshake.
805 Libwrap checks (Unix only) are performed twice: with the master
807 service name after TCP connection is accepted, and with the slave
808 service name during the TLS handshake.
809 The sni option is only available when compiled with OpenSSL 1.0.0
811 and later.
812 sni = SERVER_NAME (client mode)
814 Use the parameter as the value of TLS Server Name Indication (RFC
815 3546) extension.
816 Empty SERVER_NAME disables sending the SNI extension.
818 The sni option is only available when compiled with OpenSSL 1.0.0
820 and later.
821 socket = a|l|r:OPTION=VALUE[:VALUE]
823 Set an option on the accept/local/remote socket
824 The values for the linger option are l_onof:l_linger. The values
826 for the time are tv_sec:tv_usec.
827 Examples:
829 socket = l:SO_LINGER=1:60
831 set one minute timeout for closing local socket
832 socket = r:SO_OOBINLINE=yes
833 place out-of-band data directly into the
834 receive data stream for remote sockets
835 socket = a:SO_REUSEADDR=no
836 disable address reuse (enabled by default)
837 socket = a:SO_BINDTODEVICE=lo
838 only accept connections on loopback interface
839 sslVersion = SSL_VERSION
841 select the TLS protocol version
842 Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2,
844 TLSv1.3
845 Availability of specific protocols depends on the linked OpenSSL
847 library. Older versions of OpenSSL do not support TLSv1.1, TLSv1.2
848 and TLSv1.3. Newer versions of OpenSSL do not support SSLv2.
849 Obsolete SSLv2 and SSLv3 are currently disabled by default.
851 Setting the option
853 sslVersion = SSL_VERSION
855 is equivalent to options
857 sslVersionMax = SSL_VERSION
859 sslVersionMin = SSL_VERSION
860 when compiled with OpenSSL 1.1.0 and later.
862 sslVersionMax = SSL_VERSION
864 maximum supported protocol versions
865 Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
867 all enable protocol versions up to the highest version supported by
869 the linked OpenSSL library.
870 Availability of specific protocols depends on the linked OpenSSL
872 library.
873 The sslVersionMax option is only available when compiled with
875 OpenSSL 1.1.0 and later.
876 default: all
878 sslVersionMin = SSL_VERSION
880 minimum supported protocol versions
881 Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
883 all enable protocol versions down to the lowest version supported
885 by the linked OpenSSL library.
886 Availability of specific protocols depends on the linked OpenSSL
888 library.
889 The sslVersionMin option is only available when compiled with
891 OpenSSL 1.1.0 and later.
892 default: TLSv1
894 stack = BYTES (except for FORK model)
896 CPU stack size of created threads
897 Excessive thread stack size increases virtual memory usage.
899 Insufficient thread stack size may cause application crashes.
900 default: 65536 bytes (sufficient for all platforms we tested)
902 TIMEOUTbusy = SECONDS
904 time to wait for expected data
905 TIMEOUTclose = SECONDS
907 time to wait for close_notify (set to 0 for buggy MSIE)
908 TIMEOUTconnect = SECONDS
910 time to wait to connect to a remote host
911 TIMEOUTidle = SECONDS
913 time to keep an idle connection
914 transparent = none | source | destination | both (Unix only)
916 enable transparent proxy support on selected platforms
917 Supported values:
919 none
921 Disable transparent proxy support. This is the default.
922 source
924 Re-write the address to appear as if a wrapped daemon is
925 connecting from the TLS client machine instead of the machine
926 running stunnel.
927 This option is currently available in:
929 Remote mode (connect option) on Linux >=2.6.28
931 This configuration requires stunnel to be executed as root
932 and without the setuid option.
933 This configuration requires the following setup for
935 iptables and routing (possibly in /etc/rc.local or
936 equivalent file):
937 iptables -t mangle -N DIVERT
939 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
940 iptables -t mangle -A DIVERT -j MARK --set-mark 1
941 iptables -t mangle -A DIVERT -j ACCEPT
942 ip rule add fwmark 1 lookup 100
943 ip route add local 0.0.0.0/0 dev lo table 100
944 echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter
945 stunnel must also to be executed as root and without the
947 setuid option.
948 Remote mode (connect option) on Linux 2.2.x
950 This configuration requires the kernel to be compiled with
951 the transparent proxy option. Connected service must be
952 installed on a separate host. Routing towards the clients
953 has to go through the stunnel box.
954 stunnel must also to be executed as root and without the
956 setuid option.
957 Remote mode (connect option) on FreeBSD >=8.0
959 This configuration requires additional firewall and routing
960 setup. stunnel must also to be executed as root and
961 without the setuid option.
962 Local mode (exec option)
964 This configuration works by pre-loading the libstunnel.so
965 shared library. _RLD_LIST environment variable is used on
966 Tru64, and LD_PRELOAD variable on other platforms.
967 destination
969 The original destination is used instead of the connect option.
970 A service section for transparent destination may look like
972 this:
973 [transparent]
975 client = yes
976 accept = <stunnel_port>
977 transparent = destination
978 This configuration requires iptables setup to work, possibly in
980 /etc/rc.local or equivalent file.
981 For a connect target installed on the same host:
983 /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \
985 -m ! --uid-owner <stunnel_user_id> \
986 -j DNAT --to-destination <local_ip>:<stunnel_port>
987 For a connect target installed on a remote host:
989 /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT
991 /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \
992 -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port>
993 The transparent destination option is currently only supported
995 on Linux.
996 both
998 Use both source and destination transparent proxy.
999 Two legacy options are also supported for backward compatibility:
1001 yes This option has been renamed to source.
1003 no This option has been renamed to none.
1005 verify = LEVEL
1007 verify the peer certificate
1008 This option is obsolete and should be replaced with the verifyChain
1010 and verifyPeer options.
1011 level 0
1013 Request and ignore the peer certificate.
1014 level 1
1016 Verify the peer certificate if present.
1017 level 2
1019 Verify the peer certificate.
1020 level 3
1022 Verify the peer against a locally installed certificate.
1023 level 4
1025 Ignore the chain and only verify the peer certificate.
1026 default
1028 No verify.
1029 verifyChain = yes | no
1031 verify the peer certificate chain starting from the root CA
1032 For server certificate verification it is essential to also require
1034 a specific certificate with checkHost or checkIP.
1035 The self-signed root CA certificate needs to be stored either in
1037 the file specified with CAfile, or in the directory specified with
1038 CApath.
1039 default: no
1041 verifyPeer = yes | no
1043 verify the peer certificate
1044 The peer certificate needs to be stored either in the file
1046 specified with CAfile, or in the directory specified with CApath.
1047 default: no
1049
1051 stunnel returns zero on success, non-zero on error.
1052
1054 The following signals can be used to control stunnel in Unix
1055 environment:
1056 SIGHUP
1058 Force a reload of the configuration file.
1059 Some global options will not be reloaded:
1061 · chroot
1063 · foreground
1065 · pid
1067 · setgid
1069 · setuid
1071 The use of the 'setuid' option will also prevent stunnel from
1073 binding to privileged (<1024) ports during configuration reloading.
1074 When the 'chroot' option is used, stunnel will look for all its
1076 files (including the configuration file, certificates, the log file
1077 and the pid file) within the chroot jail.
1078 SIGUSR1
1080 Close and reopen the stunnel log file. This function can be used
1081 for log rotation.
1082 SIGTERM, SIGQUIT, SIGINT
1084 Shut stunnel down.
1085 The result of sending any other signals to the server is undefined.
1087
1089 In order to provide TLS encapsulation to your local imapd service, use:
1090 [imapd]
1092 accept = 993
1093 exec = /usr/sbin/imapd
1094 execArgs = imapd
1095 or in remote mode:
1097 [imapd]
1099 accept = 993
1100 connect = 143
1101 In order to let your local e-mail client connect to a TLS-enabled imapd
1103 service on another server, configure the e-mail client to connect to
1104 localhost on port 119 and use:
1105 [imap]
1107 client = yes
1108 accept = 143
1109 connect = servername:993
1110 If you want to provide tunneling to your pppd daemon on port 2020, use
1112 something like:
1113 [vpn]
1115 accept = 2020
1116 exec = /usr/sbin/pppd
1117 execArgs = pppd local
1118 pty = yes
1119 If you want to use stunnel in inetd mode to launch your imapd process,
1121 you'd use this stunnel.conf. Note there must be no [service_name]
1122 section.
1123 exec = /usr/sbin/imapd
1125 execArgs = imapd
1126 To setup SOCKS VPN configure the following client service:
1128 [socks_client]
1130 client = yes
1131 accept = 127.0.0.1:1080
1132 connect = vpn_server:9080
1133 verifyPeer = yes
1134 CAfile = stunnel.pem
1135 The corresponding configuration on the vpn_server host:
1137 [socks_server]
1139 protocol = socks
1140 accept = 9080
1141 cert = stunnel.pem
1142 key = stunnel.key
1143 Now test your configuration on the client machine with:
1145 curl --socks4a localhost http://www.example.com/
1147 An example server mode SNI configuration:
1149 [virtual]
1151 ; master service
1152 accept = 443
1153 cert = default.pem
1154 connect = default.internal.mydomain.com:8080
1155 [sni1]
1157 ; slave service 1
1158 sni = virtual:server1.mydomain.com
1159 cert = server1.pem
1160 connect = server1.internal.mydomain.com:8081
1161 [sni2]
1163 ; slave service 2
1164 sni = virtual:server2.mydomain.com
1165 cert = server2.pem
1166 connect = server2.internal.mydomain.com:8082
1167 verifyPeer = yes
1168 CAfile = server2-allowed-clients.pem
1169 An example of advanced engine configuration allows for authentication
1171 with private keys stored in the Windows certificate store (Windows
1172 only). With the CAPI engine you don't need to manually select the
1173 client key to use. The client key is automatically selected based on
1174 the list of CAs trusted by the server.
1175 engine = capi
1177 [service]
1179 engineId = capi
1180 client = yes
1181 accept = 127.0.0.1:8080
1182 connect = example.com:8443
1183 An example of advanced engine configuration to use the certificate and
1185 the corresponding private key from a pkcs11 engine:
1186 engine = pkcs11
1188 engineCtrl = MODULE_PATH:opensc-pkcs11.so
1189 engineCtrl = PIN:123456
1190 [service]
1192 engineId = pkcs11
1193 client = yes
1194 accept = 127.0.0.1:8080
1195 connect = example.com:843
1196 cert = pkcs11:token=MyToken;object=MyCert
1197 key = pkcs11:token=MyToken;object=MyKey
1198 An example of advanced engine configuration to use the certificate and
1200 the corresponding private key from a SoftHSM token:
1201 engine = pkcs11
1203 engineCtrl = MODULE_PATH:softhsm2.dll
1204 engineCtrl = PIN:12345
1205 [service]
1207 engineId = pkcs11
1208 client = yes
1209 accept = 127.0.0.1:8080
1210 connect = example.com:843
1211 cert = pkcs11:token=MyToken;object=KeyCert
1212
1214 RESTRICTIONS
1215 stunnel cannot be used for the FTP daemon because of the nature of the
1216 FTP protocol which utilizes multiple ports for data transfers. There
1217 are available TLS-enabled versions of FTP and telnet daemons, however.
1218 INETD MODE
1220 The most common use of stunnel is to listen on a network port and
1221 establish communication with either a new port via the connect option,
1222 or a new program via the exec option. However there is a special case
1223 when you wish to have some other program accept incoming connections
1224 and launch stunnel, for example with inetd, xinetd, or tcpserver.
1225 For example, if you have the following line in inetd.conf:
1227 imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
1229 In these cases, the inetd-style program is responsible for binding a
1231 network socket (imaps above) and handing it to stunnel when a
1232 connection is received. Thus you do not want stunnel to have any
1233 accept option. All the Service Level Options should be placed in the
1234 global options section, and no [service_name] section will be present.
1235 See the EXAMPLES section for example configurations.
1236 CERTIFICATES
1238 Each TLS-enabled daemon needs to present a valid X.509 certificate to
1239 the peer. It also needs a private key to decrypt the incoming data. The
1240 easiest way to obtain a certificate and a key is to generate them with
1241 the free OpenSSL package. You can find more information on certificates
1242 generation on pages listed below.
1243 The .pem file should contain the unencrypted private key and a signed
1245 certificate (not certificate request). So the file should look like
1246 this:
1247 -----BEGIN RSA PRIVATE KEY-----
1249 [encoded key]
1250 -----END RSA PRIVATE KEY-----
1251 -----BEGIN CERTIFICATE-----
1252 [encoded certificate]
1253 -----END CERTIFICATE-----
1254 RANDOMNESS
1256 stunnel needs to seed the PRNG (pseudo-random number generator) in
1257 order for TLS to use good randomness. The following sources are loaded
1258 in order until sufficient random data has been gathered:
1259 · The file specified with the RNDfile flag.
1261 · The file specified by the RANDFILE environment variable, if set.
1263 · The file .rnd in your home directory, if RANDFILE not set.
1265 · The file specified with '--with-random' at compile time.
1267 · The contents of the screen if running on Windows.
1269 · The egd socket specified with the EGD flag.
1271 · The egd socket specified with '--with-egd-sock' at compile time.
1273 · The /dev/urandom device.
1275 Note that on Windows machines that do not have console user interaction
1277 (mouse movements, creating windows, etc.) the screen contents are not
1278 variable enough to be sufficient, and you should provide a random file
1279 for use with the RNDfile flag.
1280 Note that the file specified with the RNDfile flag should contain
1282 random data -- that means it should contain different information each
1283 time stunnel is run. This is handled automatically unless the
1284 RNDoverwrite flag is used. If you wish to update this file manually,
1285 the openssl rand command in recent versions of OpenSSL, would be
1286 useful.
1287 Important note: If /dev/urandom is available, OpenSSL often seeds the
1289 PRNG with it while checking the random state. On systems with
1290 /dev/urandom OpenSSL is likely to use it even though it is listed at
1291 the very bottom of the list above. This is the behaviour of OpenSSL
1292 and not stunnel.
1293 DH PARAMETERS
1295 stunnel 4.40 and later contains hardcoded 2048-bit DH parameters.
1296 Starting with stunnel 5.18, these hardcoded DH parameters are replaced
1297 every 24 hours with autogenerated temporary DH parameters. DH
1298 parameter generation may take several minutes.
1299 Alternatively, it is possible to specify static DH parameters in the
1301 certificate file, which disables generating temporary DH parameters:
1302 openssl dhparam 2048 >> stunnel.pem
1304
1306 @sysconfdir@/stunnel/stunnel.conf
1307 stunnel configuration file
1308
1310 The execArgs option and the Win32 command line do not support quoting.
1311
1313 tcpd(8)
1314 access control facility for internet services
1315 inetd(8)
1317 internet 'super-server'
1318 http://www.stunnel.org/
1320 stunnel homepage
1321 http://www.openssl.org/
1323 OpenSSL project website
1324
1326 Michał Trojnara
1327 <Michal.Trojnara@stunnel.org>
13285.50 2019.01.14 stunnel(8)