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.
129 The debug = debug (or the equivalent <debug = 7>) level produces
131 for the most verbose log output. This logging level is only meant
132 to be understood by stunnel developers, and not by users. Please
133 either use the debug level when requested to do so by an stunnel
134 developer, or when you intend to get confused.
135 The default logging level is notice (5).
137 The syslog 'authpriv' facility will be used unless a facility name
139 is supplied. (Facilities are not supported on Win32.)
140 Case is ignored for both facilities and levels.
142 EGD = EGD_PATH (Unix only)
144 path to Entropy Gathering Daemon socket
145 Entropy Gathering Daemon socket to use to feed the OpenSSL random
147 number generator.
148 engine = auto | ENGINE_ID
150 select hardware or software cryptographic engine
151 default: software-only cryptography
153 See Examples section for an engine configuration to use the
155 certificate and the corresponding private key from a cryptographic
156 device.
157 engineCtrl = COMMAND[:PARAMETER]
159 control hardware engine
160 engineDefault = TASK_LIST
162 set OpenSSL tasks delegated to the current engine
163 The parameter specifies a comma-separated list of task to be
165 delegated to the current engine.
166 The following tasks may be available, if supported by the engine:
168 ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY,
169 PKEY_CRYPTO, PKEY_ASN1.
170 fips = yes | no
172 enable or disable FIPS 140-2 mode.
173 This option allows you to disable entering FIPS mode if stunnel was
175 compiled with FIPS 140-2 support.
176 default: no (since version 5.00)
178 foreground = yes | quiet | no (Unix only)
180 foreground mode
181 Stay in foreground (don't fork).
183 With the yes parameter it also logs to stderr in addition to the
185 destinations specified with syslog and output.
186 default: background in daemon mode
188 iconActive = ICON_FILE (GUI only)
190 GUI icon to be displayed when there are established connections
191 On Windows platform the parameter should be an .ico file containing
193 a 16x16 pixel image.
194 iconError = ICON_FILE (GUI only)
196 GUI icon to be displayed when no valid configuration is loaded
197 On Windows platform the parameter should be an .ico file containing
199 a 16x16 pixel image.
200 iconIdle = ICON_FILE (GUI only)
202 GUI icon to be displayed when there are no established connections
203 On Windows platform the parameter should be an .ico file containing
205 a 16x16 pixel image.
206 log = append | overwrite
208 log file handling
209 This option allows you to choose whether the log file (specified
211 with the output option) is appended or overwritten when opened or
212 re-opened.
213 default: append
215 output = FILE
217 append log messages to a file
218 /dev/stdout device can be used to send log messages to the standard
220 output (for example to log them with daemontools splogger).
221 pid = FILE (Unix only)
223 pid file location
224 If the argument is empty, then no pid file will be created.
226 pid path is relative to the chroot directory if specified.
228 RNDbytes = BYTES
230 bytes to read from random seed files
231 RNDfile = FILE
233 path to file with random seed data
234 The OpenSSL library will use data from this file first to seed the
236 random number generator.
237 RNDoverwrite = yes | no
239 overwrite the random seed files with new random data
240 default: yes
242 service = SERVICE (Unix only)
244 stunnel service name
245 The specified service name is used for syslog and as the inetd mode
247 service name for TCP Wrappers. While this option can technically
248 be specified in the service sections, it is only useful in global
249 options.
250 default: stunnel
252 syslog = yes | no (Unix only)
254 enable logging via syslog
255 default: yes
257 taskbar = yes | no (WIN32 only)
259 enable the taskbar icon
260 default: yes
262 SERVICE-LEVEL OPTIONS
264 Each configuration section begins with a service name in square
265 brackets. The service name is used for libwrap (TCP Wrappers) access
266 control and lets you distinguish stunnel services in your log files.
267 Note that if you wish to run stunnel in inetd mode (where it is
269 provided a network socket by a server such as inetd, xinetd, or
270 tcpserver) then you should read the section entitled INETD MODE below.
271 accept = [HOST:]PORT
273 accept connections on specified address
274 If no host specified, defaults to all IPv4 addresses for the local
276 host.
277 To listen on all IPv6 addresses use:
279 accept = :::PORT
281 CAengine = ENGINE-SPECIFIC_CA_CERTIFICATE_IDENTIFIER
283 load a trusted CA certificate from an engine
284 The loaded CA certificates will be used with the verifyChain and
286 verifyPeer options.
287 Multiple CAengine options are allowed in a single service section.
289 Currently supported engines: pkcs11, cng.
291 CApath = CA_DIRECTORY
293 load trusted CA certificates from a directory
294 The loaded CA certificates will be used with the verifyChain and
296 verifyPeer options. Note that the certificates in this directory
297 should be named XXXXXXXX.0 where XXXXXXXX is the hash value of the
298 DER encoded subject of the cert.
299 The hash algorithm has been changed in OpenSSL 1.0.0. It is
301 required to c_rehash the directory on upgrade from OpenSSL 0.x.x to
302 OpenSSL 1.x.x or later.
303 CApath path is relative to the chroot directory if specified.
305 CAfile = CA_FILE
307 load trusted CA certificates from a file
308 The loaded CA certificates will be used with the verifyChain and
310 verifyPeer options.
311 cert = CERT_FILE
313 certificate chain file name
314 The parameter specifies the file containing certificates used by
316 stunnel to authenticate itself against the remote client or server.
317 The file should contain the whole certificate chain starting from
318 the actual server/client certificate, and ending with the self-
319 signed root CA certificate. The file must be either in PEM or P12
320 format.
321 A certificate chain is required in server mode, and optional in
323 client mode.
324 This parameter is also used as the certificate identifier when a
326 hardware engine is enabled.
327 checkEmail = EMAIL
329 verify the email address of the end-entity (leaf) peer certificate
330 subject
331 Certificates are accepted if no subject checks were specified, or
333 the email address of the end-entity (leaf) peer certificate matches
334 any of the email addresses specified with checkEmail.
335 Multiple checkEmail options are allowed in a single service
337 section.
338 This option requires OpenSSL 1.0.2 or later.
340 checkHost = HOST
342 verify the host of the end-entity (leaf) peer certificate subject
343 Certificates are accepted if no subject checks were specified, or
345 the host name of the end-entity (leaf) peer certificate matches any
346 of the hosts specified with checkHost.
347 Multiple checkHost options are allowed in a single service section.
349 This option requires OpenSSL 1.0.2 or later.
351 checkIP = IP
353 verify the IP address of the end-entity (leaf) peer certificate
354 subject
355 Certificates are accepted if no subject checks were specified, or
357 the IP address of the end-entity (leaf) peer certificate matches
358 any of the IP addresses specified with checkIP.
359 Multiple checkIP options are allowed in a single service section.
361 This option requires OpenSSL 1.0.2 or later.
363 ciphers = CIPHER_LIST
365 select permitted TLS ciphers (TLSv1.2 and below)
366 This option does not impact TLSv1.3 ciphersuites.
368 A colon-delimited list of the ciphers to allow in the TLS
370 connection, for example DES-CBC3-SHA:IDEA-CBC-MD5.
371 ciphersuites = CIPHERSUITES_LIST
373 select permitted TLSv1.3 ciphersuites
374 A colon-delimited list of TLSv1.3 ciphersuites names in order of
376 preference.
377 This option requires OpenSSL 1.1.1 or later.
379 default:
381 TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256
382 client = yes | no
384 client mode (remote service uses TLS)
385 default: no (server mode)
387 config = COMMAND[:PARAMETER]
389 OpenSSL configuration command
390 The OpenSSL configuration command is executed with the specified
392 parameter. This allows any configuration commands to be invoked
393 from the stunnel configuration file. Supported commands are
394 described on the SSL_CONF_cmd(3ssl) manual page.
395 Several config lines can be used to specify multiple configuration
397 commands.
398 Use curves option instead of enabling config = Curves:list_curves
400 to support elliptic curves.
401 This option requires OpenSSL 1.0.2 or later.
403 connect = [HOST:]PORT
405 connect to a remote address
406 If no host is specified, the host defaults to localhost.
408 Multiple connect options are allowed in a single service section.
410 If host resolves to multiple addresses and/or if multiple connect
411 options are specified, then the remote address is chosen using a
412 round-robin algorithm.
413 CRLpath = DIRECTORY
415 Certificate Revocation Lists directory
416 This is the directory in which stunnel will look for CRLs when
418 using the verifyChain and verifyPeer options. Note that the CRLs in
419 this directory should be named XXXXXXXX.r0 where XXXXXXXX is the
420 hash value of the CRL.
421 The hash algorithm has been changed in OpenSSL 1.0.0. It is
423 required to c_rehash the directory on upgrade from OpenSSL 0.x.x to
424 OpenSSL 1.x.x.
425 CRLpath path is relative to the chroot directory if specified.
427 CRLfile = CRL_FILE
429 Certificate Revocation Lists file
430 This file contains multiple CRLs, used with the verifyChain and
432 verifyPeer options.
433 curves = list
435 ECDH curves separated with ':'
436 Note: This option is supported for server mode sockets only.
438 Only a single curve name is allowed for OpenSSL older than 1.1.1.
440 To get a list of supported curves use:
442 openssl ecparam -list_curves
444 default:
446 X25519:P-256:X448:P-521:P-384 (OpenSSL 1.1.1 or later)
448 prime256v1 (OpenSSL older than 1.1.1)
450 logId = TYPE
452 connection identifier type
453 This identifier allows you to distinguish log entries generated for
455 each of the connections.
456 Currently supported types:
458 sequential
460 The numeric sequential identifier is only unique within a
461 single instance of stunnel, but very compact. It is most
462 useful for manual log analysis.
463 unique
465 This alphanumeric identifier is globally unique, but longer
466 than the sequential number. It is most useful for automated
467 log analysis.
468 thread
470 The operating system thread identifier is neither unique (even
471 within a single instance of stunnel) nor short. It is most
472 useful for debugging software or configuration issues.
473 process
475 The operating system process identifier (PID) may be useful in
476 the inetd mode.
477 default: sequential
479 debug = LEVEL
481 debugging level
482 Level is a one of the syslog level names or numbers emerg (0),
484 alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
485 debug (7). All logs for the specified level and all levels
486 numerically less than it will be shown. The default is notice (5).
487 While the debug = debug or debug = 7 level generates the most
489 verbose output, it is only intended to be used by stunnel
490 developers. Please only use this value if you are a developer, or
491 you intend to send your logs to our technical support. Otherwise,
492 the generated logs will be confusing.
493 delay = yes | no
495 delay DNS lookup for the connect option
496 This option is useful for dynamic DNS, or when DNS is not available
498 during stunnel startup (road warrior VPN, dial-up configurations).
499 Delayed resolver mode is automatically engaged when stunnel fails
501 to resolve on startup any of the connect targets for a service.
502 Delayed resolver inflicts failover = prio.
504 default: no
506 engineId = ENGINE_ID
508 select engine ID for the service
509 engineNum = ENGINE_NUMBER
511 select engine number for the service
512 The engines are numbered starting from 1.
514 exec = EXECUTABLE_PATH
516 execute a local inetd-type program
517 exec path is relative to the chroot directory if specified.
519 The following environmental variables are set on Unix platforms:
521 REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.
522 execArgs = $0 $1 $2 ...
524 arguments for exec including the program name ($0)
525 Quoting is currently not supported. Arguments are separated with
527 an arbitrary amount of whitespace.
528 failover = rr | prio
530 Failover strategy for multiple "connect" targets.
531 rr round robin - fair load distribution
533 prio
535 priority - use the order specified in config file
536 default: prio
538 ident = USERNAME
540 use IDENT (RFC 1413) username checking
541 include = DIRECTORY
543 include all configuration file parts located in DIRECTORY
544 The files are included in the ascending alphabetical order of their
546 names. The recommended filename convention is
547 for global options:
549 00-global.conf
551 for local service-level options:
553 01-service.conf
555 02-service.conf
557 key = KEY_FILE
559 private key for the certificate specified with cert option
560 A private key is needed to authenticate the certificate owner.
562 Since this file should be kept secret it should only be readable by
563 its owner. On Unix systems you can use the following command:
564 chmod 600 keyfile
566 This parameter is also used as the private key identifier when a
568 hardware engine is enabled.
569 default: the value of the cert option
571 libwrap = yes | no
573 Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
574 default: no (since version 5.00)
576 local = HOST
578 By default, the IP address of the outgoing interface is used as the
579 source for remote connections. Use this option to bind a static
580 local IP address instead.
581 OCSP = URL
583 select OCSP responder for the end-entity (leaf) peer certificate
584 verification
585 OCSPaia = yes | no
587 validate certificates with their AIA OCSP responders
588 This option enables stunnel to validate certificates with the list
590 of OCSP responder URLs retrieved from their AIA (Authority
591 Information Access) extension.
592 OCSPflag = OCSP_FLAG
594 specify OCSP responder flag
595 Several OCSPflag can be used to specify multiple flags.
597 currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN,
599 NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
600 RESPID_KEY, NOTIME
601 OCSPnonce = yes | no
603 send and verify the OCSP nonce extension
604 This option protects the OCSP protocol against replay attacks. Due
606 to its computational overhead, the nonce extension is usually only
607 supported on internal (e.g. corporate) responders, and not on
608 public OCSP responders.
609 OCSPrequire = yes | no
611 require a conclusive OCSP response
612 Disable this option to allow a connection even though no conclusive
614 OCSP response was retrieved from stapling and a direct request to
615 the OCSP responder.
616 default: yes
618 options = SSL_OPTIONS
620 OpenSSL library options
621 The parameter is the OpenSSL option name as described in the
623 SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix.
624 stunnel -options lists the options found to be allowed in the
625 current combination of stunnel and the OpenSSL library used to
626 build it.
627 Several option lines can be used to specify multiple options. An
629 option name can be prepended with a dash ("-") to disable the
630 option.
631 For example, for compatibility with the erroneous Eudora TLS
633 implementation, the following option can be used:
634 options = DONT_INSERT_EMPTY_FRAGMENTS
636 default:
638 options = NO_SSLv2
640 options = NO_SSLv3
641 Use sslVersionMax or sslVersionMin option instead of disabling
643 specific TLS protocol versions when compiled with OpenSSL 1.1.0 or
644 later.
645 protocol = PROTO
647 application protocol to negotiate TLS
648 This option enables initial, protocol-specific negotiation of the
650 TLS encryption. The protocol option should not be used with TLS
651 encryption on a separate port.
652 Currently supported protocols:
654 cifs
656 Proprietary (undocummented) extension of CIFS protocol
657 implemented in Samba. Support for this extension was dropped
658 in Samba 3.0.0.
659 capwin
661 http://www.capwin.org/ application support
662 capwinctrl
664 http://www.capwin.org/ application support
665 This protocol is only supported in client mode.
667 connect
669 Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section
670 5.2 - Requesting a Tunnel with CONNECT
671 This protocol is only supported in client mode.
673 imap
675 Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP
676 ldap
678 Based on RFC 2830 - Lightweight Directory Access Protocol (v3):
679 Extension for Transport Layer Security
680 nntp
682 Based on RFC 4642 - Using Transport Layer Security (TLS) with
683 Network News Transfer Protocol (NNTP)
684 This protocol is only supported in client mode.
686 pgsql
688 Based on
689 http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
690 pop3
692 Based on RFC 2449 - POP3 Extension Mechanism
693 proxy
695 Passing of the original client IP address with HAProxy PROXY
696 protocol version 1
697 https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
698 smtp
700 Based on RFC 2487 - SMTP Service Extension for Secure SMTP over
701 TLS
702 socks
704 SOCKS versions 4, 4a, and 5 are supported. The SOCKS protocol
705 itself is encapsulated within TLS encryption layer to protect
706 the final destination address.
707 http://www.openssh.com/txt/socks4.protocol
709 http://www.openssh.com/txt/socks4a.protocol
711 The BIND command of the SOCKS protocol is not supported. The
713 USERID parameter is ignored.
714 See Examples section for sample configuration files for VPN
716 based on SOCKS encryption.
717 protocolAuthentication = AUTHENTICATION
719 authentication type for the protocol negotiations
720 Currently, this option is only supported in the client-side
722 'connect' and 'smtp' protocols.
723 Supported authentication types for the 'connect' protocol are
725 'basic' or 'ntlm'. The default 'connect' authentication type is
726 'basic'.
727 Supported authentication types for the 'smtp' protocol are 'plain'
729 or 'login'. The default 'smtp' authentication type is 'plain'.
730 protocolDomain = DOMAIN
732 domain for the protocol negotiations
733 Currently, this option is only supported in the client-side
735 'connect' protocol.
736 protocolHeader = HEADER
738 header for the protocol negotiations
739 Currently, this option is only supported in the client-side
741 'connect' protocol.
742 protocolHost = ADDRESS
744 host address for the protocol negotiations
745 For the 'connect' protocol negotiations, protocolHost specifies
747 HOST:PORT of the final TLS server to be connected to by the proxy.
748 The proxy server directly connected by stunnel must be specified
749 with the connect option.
750 For the 'smtp' protocol negotiations, protocolHost controls the
752 client SMTP HELO/EHLO value.
753 protocolPassword = PASSWORD
755 password for the protocol negotiations
756 Currently, this option is only supported in the client-side
758 'connect' and 'smtp' protocols.
759 protocolUsername = USERNAME
761 username for the protocol negotiations
762 Currently, this option is only supported in the client-side
764 'connect' and 'smtp' protocols.
765 PSKidentity = IDENTITY
767 PSK identity for the PSK client
768 PSKidentity can be used on stunnel clients to select the PSK
770 identity used for authentication. This option is ignored in server
771 sections.
772 default: the first identity specified in the PSKsecrets file.
774 PSKsecrets = FILE
776 file with PSK identities and corresponding keys
777 Each line of the file in the following format:
779 IDENTITY:KEY
781 Hexadecimal keys are automatically converted to binary form. Keys
783 are required to be at least 16 bytes long, which implies at least
784 32 characters for hexadecimal keys. The file should neither be
785 world-readable nor world-writable.
786 pty = yes | no (Unix only)
788 allocate a pseudoterminal for 'exec' option
789 redirect = [HOST:]PORT
791 redirect TLS client connections on certificate-based authentication
792 failures
793 This option only works in server mode. Some protocol negotiations
795 are also incompatible with the redirect option.
796 renegotiation = yes | no
798 support TLS renegotiation
799 Applications of the TLS renegotiation include some authentication
801 scenarios, or re-keying long lasting connections.
802 On the other hand this feature can facilitate a trivial CPU-
804 exhaustion DoS attack:
805 http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
807 Please note that disabling TLS renegotiation does not fully
809 mitigate this issue.
810 default: yes (if supported by OpenSSL)
812 reset = yes | no
814 attempt to use the TCP RST flag to indicate an error
815 This option is not supported on some platforms.
817 default: yes
819 retry = yes | no | DELAY
821 reconnect a connect+exec section after it was disconnected
822 The DELAY value specifies the number of milliseconds before
824 retrying. "retry = yes" has the same effect as "retry = 1000".
825 default: no
827 securityLevel = LEVEL
829 set the security level
830 The meaning of each level is described below:
832 level 0
834 Everything is permitted.
835 level 1
837 The security level corresponds to a minimum of 80 bits of
838 security. Any parameters offering below 80 bits of security are
839 excluded. As a result RSA, DSA and DH keys shorter than 1024
840 bits and ECC keys shorter than 160 bits are prohibited. All
841 export cipher suites are prohibited since they all offer less
842 than 80 bits of security. SSL version 2 is prohibited. Any
843 cipher suite using MD5 for the MAC is also prohibited.
844 level 2
846 Security level set to 112 bits of security. As a result RSA,
847 DSA and DH keys shorter than 2048 bits and ECC keys shorter
848 than 224 bits are prohibited. In addition to the level 1
849 exclusions any cipher suite using RC4 is also prohibited. SSL
850 version 3 is also not allowed. Compression is disabled.
851 level 3
853 Security level set to 128 bits of security. As a result RSA,
854 DSA and DH keys shorter than 3072 bits and ECC keys shorter
855 than 256 bits are prohibited. In addition to the level 2
856 exclusions cipher suites not offering forward secrecy are
857 prohibited. TLS versions below 1.1 are not permitted. Session
858 tickets are disabled.
859 level 4
861 Security level set to 192 bits of security. As a result RSA,
862 DSA and DH keys shorter than 7680 bits and ECC keys shorter
863 than 384 bits are prohibited. Cipher suites using SHA1 for the
864 MAC are prohibited. TLS versions below 1.2 are not permitted.
865 level 5
867 Security level set to 256 bits of security. As a result RSA,
868 DSA and DH keys shorter than 15360 bits and ECC keys shorter
869 than 512 bits are prohibited.
870 default: 2
872 The securityLevel option is only available when compiled with
874 OpenSSL 1.1.0 and later.
875 requireCert = yes | no
877 require a client certificate for verifyChain or verifyPeer
878 With requireCert set to no, the stunnel server accepts client
880 connections that did not present a certificate.
881 Both verifyChain = yes and verifyPeer = yes imply requireCert =
883 yes.
884 default: no
886 setgid = GROUP (Unix only)
888 Unix group id
889 As a global option: setgid() to the specified group in daemon mode
891 and clear all other groups.
892 As a service-level option: set the group of the Unix socket
894 specified with "accept".
895 setuid = USER (Unix only)
897 Unix user id
898 As a global option: setuid() to the specified user in daemon mode.
900 As a service-level option: set the owner of the Unix socket
902 specified with "accept".
903 sessionCacheSize = NUM_ENTRIES
905 session cache size
906 sessionCacheSize specifies the maximum number of the internal
908 session cache entries.
909 The value of 0 can be used for unlimited size. It is not
911 recommended for production use due to the risk of a memory
912 exhaustion DoS attack.
913 sessionCacheTimeout = TIMEOUT
915 session cache timeout
916 This is the number of seconds to keep cached TLS sessions.
918 sessionResume = yes | no
920 allow or disallow session resumption
921 default: yes
923 sessiond = HOST:PORT
925 address of sessiond TLS cache server
926 sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)
928 Use the service as a secondary service (a name-based virtual
929 server) for Server Name Indication TLS extension (RFC 3546).
930 SERVICE_NAME specifies the primary service that accepts client
932 connections with the accept option. SERVER_NAME_PATTERN specifies
933 the host name to be redirected. The pattern may start with the '*'
934 character, e.g. '*.example.com'. Multiple secondary services are
935 normally specified for a single primary service. The sni option
936 can also be specified more than once within a single secondary
937 service.
938 This service, as well as the primary service, may not be configured
940 in client mode.
941 The connect option of the secondary service is ignored when the
943 protocol option is specified, as protocol connects to the remote
944 host before TLS handshake.
945 Libwrap checks (Unix only) are performed twice: with the primary
947 service name after TCP connection is accepted, and with the
948 secondary service name during the TLS handshake.
949 The sni option is only available when compiled with OpenSSL 1.0.0
951 and later.
952 sni = SERVER_NAME (client mode)
954 Use the parameter as the value of TLS Server Name Indication (RFC
955 3546) extension.
956 Empty SERVER_NAME disables sending the SNI extension.
958 The sni option is only available when compiled with OpenSSL 1.0.0
960 and later.
961 socket = a|l|r:OPTION=VALUE[:VALUE]
963 Set an option on the accept/local/remote socket
964 The values for the linger option are l_onof:l_linger. The values
966 for the time are tv_sec:tv_usec.
967 Examples:
969 socket = l:SO_LINGER=1:60
971 set one minute timeout for closing local socket
972 socket = r:SO_OOBINLINE=yes
973 place out-of-band data directly into the
974 receive data stream for remote sockets
975 socket = a:SO_REUSEADDR=no
976 disable address reuse (enabled by default)
977 socket = a:SO_BINDTODEVICE=lo
978 only accept connections on loopback interface
979 sslVersion = SSL_VERSION
981 select the TLS protocol version
982 Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2,
984 TLSv1.3
985 Availability of specific protocols depends on the linked OpenSSL
987 library. Older versions of OpenSSL do not support TLSv1.1, TLSv1.2
988 and TLSv1.3. Newer versions of OpenSSL do not support SSLv2.
989 Obsolete SSLv2 and SSLv3 are currently disabled by default.
991 Setting the option
993 sslVersion = SSL_VERSION
995 is equivalent to options
997 sslVersionMax = SSL_VERSION
999 sslVersionMin = SSL_VERSION
1000 when compiled with OpenSSL 1.1.0 and later.
1002 sslVersionMax = SSL_VERSION
1004 maximum supported protocol versions
1005 Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
1007 all enable protocol versions up to the highest version supported by
1009 the linked OpenSSL library.
1010 Availability of specific protocols depends on the linked OpenSSL
1012 library.
1013 The sslVersionMax option is only available when compiled with
1015 OpenSSL 1.1.0 and later.
1016 default: all
1018 sslVersionMin = SSL_VERSION
1020 minimum supported protocol versions
1021 Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
1023 all enable protocol versions down to the lowest version supported
1025 by the linked OpenSSL library.
1026 Availability of specific protocols depends on the linked OpenSSL
1028 library.
1029 The sslVersionMin option is only available when compiled with
1031 OpenSSL 1.1.0 and later.
1032 default: TLSv1
1034 stack = BYTES (except for FORK model)
1036 CPU stack size of created threads
1037 Excessive thread stack size increases virtual memory usage.
1039 Insufficient thread stack size may cause application crashes.
1040 default: 65536 bytes (sufficient for all platforms we tested)
1042 ticketKeySecret = SECRET
1044 hexadecimal symmetric key used for session ticket confidentiality
1045 protection
1046 Session tickets defined in RFC 5077 provide an enhanced session
1048 resumption capability, where the server-side caching is not
1049 required to maintain per session state.
1050 Combining ticketKeySecret and ticketMacSecret options allow to
1052 resume a negotiated session on other cluster nodes, or to resume a
1053 negotiated session after server restart.
1054 The key is required to be either 16 or 32 bytes long, which implies
1056 exactly 32 or 64 hexadecimal digits. Colons may optionally be used
1057 between two-character hexadecimal bytes.
1058 This option only works in server mode.
1060 The ticketKeySecret option is only available when compiled with
1062 OpenSSL 1.0.0 and later.
1063 Disabling NO_TICKET option is required for the ticket support in
1065 OpenSSL older than 1.1.1, but note that this option is incompatible
1066 with the redirect option.
1067 ticketMacSecret = SECRET
1069 hexadecimal symmetric key used for session ticket integrity
1070 protection
1071 The key is required to be either 16 or 32 bytes long, which implies
1073 exactly 32 or 64 hexadecimal digits. Colons may optionally be used
1074 between two-character hexadecimal bytes.
1075 This option only works in server mode.
1077 The ticketMacSecret option is only available when compiled with
1079 OpenSSL 1.0.0 and later.
1080 TIMEOUTbusy = SECONDS
1082 time to wait for expected data
1083 TIMEOUTclose = SECONDS
1085 time to wait for close_notify (set to 0 for buggy MSIE)
1086 TIMEOUTconnect = SECONDS
1088 time to wait to connect a remote host
1089 TIMEOUTidle = SECONDS
1091 time to keep an idle connection
1092 TIMEOUTocsp = SECONDS
1094 time to wait to connect an OCSP responder
1095 transparent = none | source | destination | both (Unix only)
1097 enable transparent proxy support on selected platforms
1098 Supported values:
1100 none
1102 Disable transparent proxy support. This is the default.
1103 source
1105 Re-write the address to appear as if a wrapped daemon is
1106 connecting from the TLS client machine instead of the machine
1107 running stunnel.
1108 This option is currently available in:
1110 Remote mode (connect option) on Linux >=2.6.28
1112 This configuration requires stunnel to be executed as root
1113 and without the setuid option.
1114 This configuration requires the following setup for
1116 iptables and routing (possibly in /etc/rc.local or
1117 equivalent file):
1118 iptables -t mangle -N DIVERT
1120 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
1121 iptables -t mangle -A DIVERT -j MARK --set-mark 1
1122 iptables -t mangle -A DIVERT -j ACCEPT
1123 ip rule add fwmark 1 lookup 100
1124 ip route add local 0.0.0.0/0 dev lo table 100
1125 echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter
1126 stunnel must also to be executed as root and without the
1128 setuid option.
1129 Remote mode (connect option) on Linux 2.2.x
1131 This configuration requires the kernel to be compiled with
1132 the transparent proxy option. Connected service must be
1133 installed on a separate host. Routing towards the clients
1134 has to go through the stunnel box.
1135 stunnel must also to be executed as root and without the
1137 setuid option.
1138 Remote mode (connect option) on FreeBSD >=8.0
1140 This configuration requires additional firewall and routing
1141 setup. stunnel must also to be executed as root and
1142 without the setuid option.
1143 Local mode (exec option)
1145 This configuration works by pre-loading the libstunnel.so
1146 shared library. _RLD_LIST environment variable is used on
1147 Tru64, and LD_PRELOAD variable on other platforms.
1148 destination
1150 The original destination is used instead of the connect option.
1151 A service section for transparent destination may look like
1153 this:
1154 [transparent]
1156 client = yes
1157 accept = <stunnel_port>
1158 transparent = destination
1159 This configuration requires iptables setup to work, possibly in
1161 /etc/rc.local or equivalent file.
1162 For a connect target installed on the same host:
1164 /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \
1166 -m ! --uid-owner <stunnel_user_id> \
1167 -j DNAT --to-destination <local_ip>:<stunnel_port>
1168 For a connect target installed on a remote host:
1170 /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT
1172 /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \
1173 -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port>
1174 The transparent destination option is currently only supported
1176 on Linux.
1177 both
1179 Use both source and destination transparent proxy.
1180 Two legacy options are also supported for backward compatibility:
1182 yes This option has been renamed to source.
1184 no This option has been renamed to none.
1186 verify = LEVEL
1188 verify the peer certificate
1189 This option is obsolete and should be replaced with the verifyChain
1191 and verifyPeer options.
1192 level 0
1194 Request and ignore the peer certificate chain.
1195 level 1
1197 Verify the peer certificate chain if present.
1198 level 2
1200 Verify the peer certificate chain.
1201 level 3
1203 Verify the peer certificate chain and the end-entity (leaf)
1204 peer certificate against a locally installed certificate.
1205 level 4
1207 Ignore the peer certificate chain and only verify the end-
1208 entity (leaf) peer certificate against a locally installed
1209 certificate.
1210 default
1212 No verify.
1213 verifyChain = yes | no
1215 verify the peer certificate chain starting from the root CA
1216 For server certificate verification it is essential to also require
1218 a specific certificate with checkHost or checkIP.
1219 The self-signed root CA certificate needs to be stored either in
1221 the file specified with CAfile, or in the directory specified with
1222 CApath.
1223 default: no
1225 verifyPeer = yes | no
1227 verify the end-entity (leaf) peer certificate
1228 The end-entity (leaf) peer certificate needs to be stored either in
1230 the file specified with CAfile, or in the directory specified with
1231 CApath.
1232 default: no
1234
1236 stunnel returns zero on success, non-zero on error.
1237
1239 The following signals can be used to control stunnel in Unix
1240 environment:
1241 SIGHUP
1243 Force a reload of the configuration file.
1244 Some global options will not be reloaded:
1246 • chroot
1248 • foreground
1250 • pid
1252 • setgid
1254 • setuid
1256 The use of the 'setuid' option will also prevent stunnel from
1258 binding to privileged (<1024) ports during configuration reloading.
1259 When the 'chroot' option is used, stunnel will look for all its
1261 files (including the configuration file, certificates, the log file
1262 and the pid file) within the chroot jail.
1263 SIGUSR1
1265 Close and reopen the stunnel log file. This function can be used
1266 for log rotation.
1267 SIGUSR2
1269 Log the list of active connections.
1270 SIGTERM, SIGQUIT, SIGINT
1272 Shut stunnel down.
1273 The result of sending any other signals to the server is undefined.
1275
1277 In order to provide TLS encapsulation to your local imapd service, use:
1278 [imapd]
1280 accept = 993
1281 exec = /usr/sbin/imapd
1282 execArgs = imapd
1283 or in remote mode:
1285 [imapd]
1287 accept = 993
1288 connect = 143
1289 In order to let your local e-mail client connect to a TLS-enabled imapd
1291 service on another server, configure the e-mail client to connect to
1292 localhost on port 119 and use:
1293 [imap]
1295 client = yes
1296 accept = 143
1297 connect = servername:993
1298 If you want to provide tunneling to your pppd daemon on port 2020, use
1300 something like:
1301 [vpn]
1303 accept = 2020
1304 exec = /usr/sbin/pppd
1305 execArgs = pppd local
1306 pty = yes
1307 If you want to use stunnel in inetd mode to launch your imapd process,
1309 you'd use this stunnel.conf. Note there must be no [service_name]
1310 section.
1311 exec = /usr/sbin/imapd
1313 execArgs = imapd
1314 To setup SOCKS VPN configure the following client service:
1316 [socks_client]
1318 client = yes
1319 accept = 127.0.0.1:1080
1320 connect = vpn_server:9080
1321 verifyPeer = yes
1322 CAfile = stunnel.pem
1323 The corresponding configuration on the vpn_server host:
1325 [socks_server]
1327 protocol = socks
1328 accept = 9080
1329 cert = stunnel.pem
1330 key = stunnel.key
1331 Now test your configuration on the client machine with:
1333 curl --socks4a localhost http://www.example.com/
1335 An example server mode SNI configuration:
1337 [virtual]
1339 ; primary service
1340 accept = 443
1341 cert = default.pem
1342 connect = default.internal.mydomain.com:8080
1343 [sni1]
1345 ; secondary service 1
1346 sni = virtual:server1.mydomain.com
1347 cert = server1.pem
1348 connect = server1.internal.mydomain.com:8081
1349 [sni2]
1351 ; secondary service 2
1352 sni = virtual:server2.mydomain.com
1353 cert = server2.pem
1354 connect = server2.internal.mydomain.com:8082
1355 verifyPeer = yes
1356 CAfile = server2-allowed-clients.pem
1357 An example of advanced engine configuration allows for authentication
1359 with private keys stored in the Windows certificate store (Windows
1360 only). With the CAPI engine you don't need to manually select the
1361 client key to use. The client key is automatically selected based on
1362 the list of CAs trusted by the server.
1363 engine = capi
1365 [service]
1367 engineId = capi
1368 client = yes
1369 accept = 127.0.0.1:8080
1370 connect = example.com:8443
1371 An example of advanced engine configuration to use the certificate and
1373 the corresponding private key from a pkcs11 engine:
1374 engine = pkcs11
1376 engineCtrl = MODULE_PATH:opensc-pkcs11.so
1377 engineCtrl = PIN:123456
1378 [service]
1380 engineId = pkcs11
1381 client = yes
1382 accept = 127.0.0.1:8080
1383 connect = example.com:843
1384 cert = pkcs11:token=MyToken;object=MyCert
1385 key = pkcs11:token=MyToken;object=MyKey
1386 An example of advanced engine configuration to use the certificate and
1388 the corresponding private key from a SoftHSM token:
1389 engine = pkcs11
1391 engineCtrl = MODULE_PATH:softhsm2.dll
1392 engineCtrl = PIN:12345
1393 [service]
1395 engineId = pkcs11
1396 client = yes
1397 accept = 127.0.0.1:8080
1398 connect = example.com:843
1399 cert = pkcs11:token=MyToken;object=KeyCert
1400
1402 RESTRICTIONS
1403 stunnel cannot be used for the FTP daemon because of the nature of the
1404 FTP protocol which utilizes multiple ports for data transfers. There
1405 are available TLS-enabled versions of FTP and telnet daemons, however.
1406 INETD MODE
1408 The most common use of stunnel is to listen on a network port and
1409 establish communication with either a new port via the connect option,
1410 or a new program via the exec option. However there is a special case
1411 when you wish to have some other program accept incoming connections
1412 and launch stunnel, for example with inetd, xinetd, or tcpserver.
1413 For example, if you have the following line in inetd.conf:
1415 imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
1417 In these cases, the inetd-style program is responsible for binding a
1419 network socket (imaps above) and handing it to stunnel when a
1420 connection is received. Thus you do not want stunnel to have any
1421 accept option. All the Service Level Options should be placed in the
1422 global options section, and no [service_name] section will be present.
1423 See the EXAMPLES section for example configurations.
1424 CERTIFICATES
1426 Each TLS-enabled daemon needs to present a valid X.509 certificate to
1427 the peer. It also needs a private key to decrypt the incoming data. The
1428 easiest way to obtain a certificate and a key is to generate them with
1429 the free OpenSSL package. You can find more information on certificates
1430 generation on pages listed below.
1431 The .pem file should contain the unencrypted private key and a signed
1433 certificate (not certificate request). So the file should look like
1434 this:
1435 -----BEGIN RSA PRIVATE KEY-----
1437 [encoded key]
1438 -----END RSA PRIVATE KEY-----
1439 -----BEGIN CERTIFICATE-----
1440 [encoded certificate]
1441 -----END CERTIFICATE-----
1442 RANDOMNESS
1444 stunnel needs to seed the PRNG (pseudo-random number generator) in
1445 order for TLS to use good randomness. The following sources are loaded
1446 in order until sufficient random data has been gathered:
1447 • The file specified with the RNDfile flag.
1449 • The file specified by the RANDFILE environment variable, if set.
1451 • The file .rnd in your home directory, if RANDFILE not set.
1453 • The file specified with '--with-random' at compile time.
1455 • The contents of the screen if running on Windows.
1457 • The egd socket specified with the EGD flag.
1459 • The egd socket specified with '--with-egd-sock' at compile time.
1461 • The /dev/urandom device.
1463 Note that on Windows machines that do not have console user interaction
1465 (mouse movements, creating windows, etc.) the screen contents are not
1466 variable enough to be sufficient, and you should provide a random file
1467 for use with the RNDfile flag.
1468 Note that the file specified with the RNDfile flag should contain
1470 random data -- that means it should contain different information each
1471 time stunnel is run. This is handled automatically unless the
1472 RNDoverwrite flag is used. If you wish to update this file manually,
1473 the openssl rand command in recent versions of OpenSSL, would be
1474 useful.
1475 Important note: If /dev/urandom is available, OpenSSL often seeds the
1477 PRNG with it while checking the random state. On systems with
1478 /dev/urandom OpenSSL is likely to use it even though it is listed at
1479 the very bottom of the list above. This is the behaviour of OpenSSL
1480 and not stunnel.
1481 DH PARAMETERS
1483 stunnel 4.40 and later contains hardcoded 2048-bit DH parameters.
1484 Starting with stunnel 5.18, these hardcoded DH parameters are replaced
1485 every 24 hours with autogenerated temporary DH parameters. DH
1486 parameter generation may take several minutes.
1487 Alternatively, it is possible to specify static DH parameters in the
1489 certificate file, which disables generating temporary DH parameters:
1490 openssl dhparam 2048 >> stunnel.pem
1492
1494 @sysconfdir@/stunnel/stunnel.conf
1495 stunnel configuration file
1496
1498 The execArgs option and the Win32 command line do not support quoting.
1499
1501 tcpd(8)
1502 access control facility for internet services
1503 inetd(8)
1505 internet 'super-server'
1506 http://www.stunnel.org/
1508 stunnel homepage
1509 http://www.openssl.org/
1511 OpenSSL project website
1512
1514 Michał Trojnara
1515 <Michal.Trojnara@stunnel.org>
15165.71 2023.10.05 stunnel(8)