1STUNNEL(8) stunnel STUNNEL(8)
2
6 stunnel - universal SSL tunnel
7
9 Unix:
10 stunnel [<filename>] | -fd n | -help | -version | -sockets
11 WIN32:
13 stunnel [ [-install | -uninstall | -start | -stop]
14 [-quiet] [<filename>] ] | -help | -version | -sockets
15
17 The stunnel program is designed to work as SSL encryption wrapper
18 between remote clients and local (inetd-startable) or remote servers.
19 The concept is that having non-SSL aware daemons running on your system
20 you can easily set them up to communicate with clients over secure SSL
21 channels.
22 stunnel can be used to add SSL functionality to commonly used Inetd
24 daemons like POP-2, POP-3, and IMAP servers, to standalone daemons like
25 NNTP, SMTP and HTTP, and in tunneling PPP over network sockets without
26 changes to the source code.
27 This product includes cryptographic software written by Eric Young
29 (eay@cryptsoft.com)
30
32 <filename>
33 Use specified configuration file
34 -fd n (Unix only)
36 Read the config file from specified file descriptor
37 -help
39 Print stunnel help menu
40 -version
42 Print stunnel version and compile time defaults
43 -sockets
45 Print default socket options
46 -install (NT/2000/XP only)
48 Install NT Service
49 -uninstall (NT/2000/XP only)
51 Uninstall NT Service
52 -start (NT/2000/XP only)
54 Start NT Service
55 -stop (NT/2000/XP only)
57 Stop NT Service
58 -quiet (NT/2000/XP only)
60 Don't display a message box when successfully installed or
61 uninstalled NT service
62
64 Each line of the configuration file can be either:
65 · an empty line (ignored)
67 · a comment starting with ';' (ignored)
69 · an 'option_name = option_value' pair
71 · '[service_name]' indicating a start of a service definition
73 GLOBAL OPTIONS
75 chroot = directory (Unix only)
76 directory to chroot stunnel process
77 chroot keeps stunnel in chrooted jail. CApath, CRLpath, pid and
79 exec are located inside the jail and the patches have to be
80 relative to the directory specified with chroot.
81 compression = zlib | rle
83 select data compression algorithm
84 default: no compression
86 zlib compression of OpenSSL 0.9.8 or above is not backward
88 compatible with OpenSSL 0.9.7.
89 rle compression is currently not implemented by the OpenSSL
91 library.
92 debug = [facility.]level
94 debugging level
95 Level is a one of the syslog level names or numbers emerg (0),
97 alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
98 debug (7). All logs for the specified level and all levels
99 numerically less than it will be shown. Use debug = debug or debug
100 = 7 for greatest debugging output. The default is notice (5).
101 The syslog facility 'authpriv' will be used unless a facility name
103 is supplied. (Facilities are not supported on Win32.)
104 Case is ignored for both facilities and levels.
106 EGD = egd path (Unix only)
108 path to Entropy Gathering Daemon socket
109 Entropy Gathering Daemon socket to use to feed OpenSSL random
111 number generator. (Available only if compiled with OpenSSL 0.9.5a
112 or higher)
113 engine = auto | <engine id>
115 select hardware engine
116 default: software-only cryptography
118 There's an example in 'EXAMPLES' section.
120 engineCtrl = command[:parameter]
122 control hardware engine
123 Special commands "LOAD" and "INIT" can be used to load and
125 initialize the engine cryptogaphic module.
126 fips = yes | no
128 Enable or disable FIPS 140-2 mode.
129 This option allows to disable entering FIPS mode if stunnel was
131 compiled with FIPS 140-2 support.
132 default: yes
134 foreground = yes | no (Unix only)
136 foreground mode
137 Stay in foreground (don't fork) and log to stderr instead of via
139 syslog (unless output is specified).
140 default: background in daemon mode
142 output = file
144 append log messages to a file instead of using syslog
145 /dev/stdout device can be used to redirect log messages to the
147 standard output (for example to log them with daemontools
148 splogger).
149 pid = file (Unix only)
151 pid file location
152 If the argument is empty, then no pid file will be created.
154 pid path is relative to chroot directory if specified.
156 RNDbytes = bytes
158 bytes to read from random seed files
159 Number of bytes of data read from random seed files. With SSL
161 versions less than 0.9.5a, also determines how many bytes of data
162 are considered sufficient to seed the PRNG. More recent OpenSSL
163 versions have a builtin function to determine when sufficient
164 randomness is available.
165 RNDfile = file
167 path to file with random seed data
168 The SSL library will use data from this file first to seed the
170 random number generator.
171 RNDoverwrite = yes | no
173 overwrite the random seed files with new random data
174 default: yes
176 service = servicename
178 use specified string as the service name
179 On Unix: inetd mode service name for TCP Wrapper library.
181 On NT/2000/XP: NT service name in the Control Panel.
183 default: stunnel
185 setgid = groupname (Unix only)
187 setgid() to groupname in daemon mode and clears all other groups
188 setuid = username (Unix only)
190 setuid() to username in daemon mode
191 socket = a|l|r:option=value[:value]
193 Set an option on accept/local/remote socket
194 The values for linger option are l_onof:l_linger. The values for
196 time are tv_sec:tv_usec.
197 Examples:
199 socket = l:SO_LINGER=1:60
201 set one minute timeout for closing local socket
202 socket = r:TCP_NODELAY=1
203 turn off the Nagle algorithm for remote sockets
204 socket = r:SO_OOBINLINE=1
205 place out-of-band data directly into the
206 receive data stream for remote sockets
207 socket = a:SO_REUSEADDR=0
208 disable address reuse (enabled by default)
209 socket = a:SO_BINDTODEVICE=lo
210 only accept connections on loopback interface
211 syslog = yes | no (Unix only)
213 enable logging via syslog
214 default: yes
216 taskbar = yes | no (WIN32 only)
218 enable the taskbar icon
219 default: yes
221 SERVICE-LEVEL OPTIONS
223 Each configuration section begins with service name in square brackets.
224 The service name is used for libwrap (TCP Wrappers) access control and
225 lets you distinguish stunnel services in your log files.
226 Note that if you wish to run stunnel in inetd mode (where it is
228 provided a network socket by a server such as inetd, xinetd, or
229 tcpserver) then you should read the section entitled INETD MODE below.
230 accept = [host:]port
232 accept connections on specified host:port
233 If no host specified, defaults to all IP addresses for the local
235 host.
236 CApath = directory
238 Certificate Authority directory
239 This is the directory in which stunnel will look for certificates
241 when using the verify. Note that the certificates in this directory
242 should be named XXXXXXXX.0 where XXXXXXXX is the hash value of the
243 DER encoded subject of the cert (the first 4 bytes of the MD5 hash
244 in least significant byte order).
245 CApath path is relative to chroot directory if specified.
247 CAfile = certfile
249 Certificate Authority file
250 This file contains multiple CA certificates, used with the verify.
252 cert = pemfile
254 certificate chain PEM file name
255 A PEM is always needed in server mode. Specifying this flag in
257 client mode will use this certificate chain as a client side
258 certificate chain. Using client side certs is optional. The
259 certificates must be in PEM format and must be sorted starting with
260 the certificate to the highest level (root CA).
261 ciphers = cipherlist
263 Select permitted SSL ciphers
264 A colon delimited list of the ciphers to allow in the SSL
266 connection. For example DES-CBC3-SHA:IDEA-CBC-MD5
267 client = yes | no
269 client mode (remote service uses SSL)
270 default: no (server mode)
272 connect = [host:]port
274 connect to a remote host:port
275 If no host is specified, the host defaults to localhost.
277 Multiple connect options are allowed in a single service section.
279 If host resolves to multiple addresses and/or if multiple connect
281 options are specified, then the remote address is chosen using a
282 round-robin algorithm.
283 CRLpath = directory
285 Certificate Revocation Lists directory
286 This is the directory in which stunnel will look for CRLs when
288 using the verify. Note that the CRLs in this directory should be
289 named XXXXXXXX.0 where XXXXXXXX is the hash value of the CRL.
290 CRLpath path is relative to chroot directory if specified.
292 CRLfile = certfile
294 Certificate Revocation Lists file
295 This file contains multiple CRLs, used with the verify.
297 curve = nid
299 specify ECDH curve name
300 default: sect163r2
302 delay = yes | no
304 delay DNS lookup for 'connect' option
305 This option is useful for dynamic DNS, or when DNS is not available
307 during stunnel startup (road warrior VPN, dial-up configurations).
308 engineNum = engine number
310 select engine number to read private key
311 The engines are numbered starting from 1.
313 exec = executable_path
315 execute local inetd-type program
316 exec path is relative to chroot directory if specified.
318 execargs = $0 $1 $2 ...
320 arguments for exec including program name ($0)
321 Quoting is currently not supported. Arguments are separated with
323 arbitrary number of whitespaces.
324 failover = rr | prio
326 Failover strategy for multiple "connect" targets.
327 rr (round robin) - fair load distribution
329 prio (priority) - use the order specified in config file
330 default: rr
332 ident = username
334 use IDENT (RFC 1413) username checking
335 key = keyfile
337 private key for certificate specified with cert option
338 Private key is needed to authenticate certificate owner. Since
340 this file should be kept secret it should only be readable to its
341 owner. On Unix systems you can use the following command:
342 chmod 600 keyfile
344 default: value of cert option
346 libwrap = yes | no
348 Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.
349 default: yes
351 local = host
353 IP of the outgoing interface is used as source for remote
354 connections. Use this option to bind a static local IP address,
355 instead.
356 OCSP = url
358 select OCSP server for certificate verification
359 OCSPflag = flag
361 specify OCSP server flag
362 Several OCSPflag can be used to specify multiple flags.
364 currently supported flags: NOCERTS, NOINTERN NOSIGS, NOCHAIN,
366 NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
367 RESPID_KEY, NOTIME
368 options = SSL_options
370 OpenSSL library options
371 The parameter is the OpenSSL option name as described in the
373 SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix.
374 Several options can be used to specify multiple options.
375 For example for compatibility with erroneous Eudora SSL
377 implementation the following option can be used:
378 options = DONT_INSERT_EMPTY_FRAGMENTS
380 protocol = proto
382 application protocol to negotiate SSL
383 Specifically "connect" protocol is used in client mode to establish
385 SSL connections via HTTP proxy.
386 currently supported: cifs, connect, imap, nntp, pop3, smtp, pgsql
388 protocolAuthentication = auth_type
390 authentication type for protocol negotiations
391 currently supported: basic, NTLM
393 Currently authentication type only applies to 'connect' protocol.
395 default: basic
397 protocolHost = host:port
399 destination address for protocol negotiations
400 protocolPassword = password
402 password for protocol negotiations
403 protocolUsername = username
405 username for protocol negotiations
406 pty = yes | no (Unix only)
408 allocate pseudo terminal for 'exec' option
409 retry = yes | no (Unix only)
411 reconnect a connect+exec section after it's disconnected
412 default: no
414 session = timeout
416 session cache timeout
417 sessiond = host:port
419 address of sessiond SSL cache server
420 sslVersion = version
422 select version of SSL protocol
423 Allowed options: all, SSLv2, SSLv3, TLSv1
425 stack = bytes (except for FORK model)
427 thread stack size
428 TIMEOUTbusy = seconds
430 time to wait for expected data
431 TIMEOUTclose = seconds
433 time to wait for close_notify (set to 0 for buggy MSIE)
434 TIMEOUTconnect = seconds
436 time to wait to connect a remote host
437 TIMEOUTidle = seconds
439 time to keep an idle connection
440 transparent = yes | no (Unix only)
442 transparent proxy mode
443 Re-write address to appear as if wrapped daemon is connecting from
445 the SSL client machine instead of the machine running stunnel.
446 This option is currently available in:
448 remote mode (I<connect> option) on Linux >=2.6.28
450 remote mode (I<connect> option) 2.2.x
451 local mode (I<exec> option)
452 Remote mode (either 2.2.x and >=2.6.28) requires stunnel to be
454 executed as root. setuid option will also break this
455 functionality.
456 Linux >=2.6.28 requires the following setup for iptables and
458 routing (possibly in /etc/rc.local or equivalent file):
459 iptables -t mangle -N DIVERT
461 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
462 iptables -t mangle -A DIVERT -j MARK --set-mark 1
463 iptables -t mangle -A DIVERT -j ACCEPT
464 ip rule add fwmark 1 lookup 100
465 ip route add local 0.0.0.0/0 dev lo table 100
466 Linux 2.2.x requires kernel to be compiled with transparent proxy
468 option. Connected service must be installed on a separate host.
469 Routing towards the clients has to go through the stunnel box.
470 Local mode works by LD_PRELOADing env.so shared library.
472 verify = level
474 verify peer certificate
475 level 1 - verify peer certificate if present
477 level 2 - verify peer certificate
478 level 3 - verify peer with locally installed certificate
479 default - no verify
480 It is important to understand, that this option was solely designed
482 for access control and not for authorization. Specifically for
483 level 2 every non-revoked certificate is accepted regardless of its
484 Common Name. For this reason a dedicated CA should be used with
485 level 2, and not a generic CA commonly used for webservers. Level
486 3 is preferred for point-to-point connections.
487
489 stunnel returns zero on success, non-zero on error.
490
492 The following signals can be used to control stunnel in Unix
493 environment:
494 SIGHUP
496 Force a reload of the configuration file.
497 Some global options will not be reloaded:
499 · chroot
501 · fips
503 · foreground
505 · pid
507 · setgid
509 · setuid
511 The use of 'setuid' option will also prevent stunnel from binding
513 privileged (<1024) ports during configuration reloading.
514 When 'chroot' option is used, stunnel will look for all its files
516 (including configuration file, certificates, log file and pid file)
517 within the chroot jail.
518 SIGUSR1
520 Close and reopen stunnel log file. This function can be used for
521 log rotation.
522 SIGTERM, SIGQUIT, SIGINT
524 Shut stunnel down.
525 The result of sending any other signals to the server is undefined.
527
529 In order to provide SSL encapsulation to your local imapd service, use
530 [imapd]
532 accept = 993
533 exec = /usr/sbin/imapd
534 execargs = imapd
535 If you want to provide tunneling to your pppd daemon on port 2020, use
537 something like
538 [vpn]
540 accept = 2020
541 exec = /usr/sbin/pppd
542 execargs = pppd local
543 pty = yes
544 If you want to use stunnel in inetd mode to launch your imapd process,
546 you'd use this stunnel.conf. Note there must be no [service_name]
547 section.
548 exec = /usr/sbin/imapd
550 execargs = imapd
551 Here is an example of advanced engine configuration to read private key
553 from an OpenSC engine
554 engine=dynamic
556 engineCtrl=SO_PATH:/usr/lib/opensc/engine_pkcs11.so
557 engineCtrl=ID:pkcs11
558 engineCtrl=LIST_ADD:1
559 engineCtrl=LOAD
560 engineCtrl=MODULE_PATH:/usr/lib/pkcs11/opensc-pkcs11.so
561 engineCtrl=INIT
562 [service]
564 engineNum=1
565 key=id_45
566
568 RESTRICTIONS
569 stunnel cannot be used for the FTP daemon because of the nature of the
570 FTP protocol which utilizes multiple ports for data transfers. There
571 are available SSL enabled versions of FTP and telnet daemons, however.
572 INETD MODE
574 The most common use of stunnel is to listen on a network port and
575 establish communication with either a new port via the connect option,
576 or a new program via the exec option. However there is a special case
577 when you wish to have some other program accept incoming connections
578 and launch stunnel, for example with inetd, xinetd, or tcpserver.
579 For example, if you have the following line in inetd.conf:
581 imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
583 In these cases, the inetd-style program is responsible for binding a
585 network socket (imaps above) and handing it to stunnel when a
586 connection is received. Thus you do not want stunnel to have any
587 accept option. All the Service Level Options should be placed in the
588 global options section, and no [service_name] section will be present.
589 See the EXAMPLES section for example configurations.
590 CERTIFICATES
592 Each SSL enabled daemon needs to present a valid X.509 certificate to
593 the peer. It also needs a private key to decrypt the incoming data. The
594 easiest way to obtain a certificate and a key is to generate them with
595 the free OpenSSL package. You can find more information on certificates
596 generation on pages listed below.
597 The order of contents of the .pem file is important. It should contain
599 the unencrypted private key first, then a signed certificate (not
600 certificate request). There should be also empty lines after
601 certificate and private key. Plaintext certificate information
602 appended on the top of generated certificate should be discarded. So
603 the file should look like this:
604 -----BEGIN RSA PRIVATE KEY-----
606 [encoded key]
607 -----END RSA PRIVATE KEY-----
608 [empty line]
609 -----BEGIN CERTIFICATE-----
610 [encoded certificate]
611 -----END CERTIFICATE-----
612 [empty line]
613 RANDOMNESS
615 stunnel needs to seed the PRNG (pseudo random number generator) in
616 order for SSL to use good randomness. The following sources are loaded
617 in order until sufficient random data has been gathered:
618 · The file specified with the RNDfile flag.
620 · The file specified by the RANDFILE environment variable, if set.
622 · The file .rnd in your home directory, if RANDFILE not set.
624 · The file specified with '--with-random' at compile time.
626 · The contents of the screen if running on Windows.
628 · The egd socket specified with the EGD flag.
630 · The egd socket specified with '--with-egd-sock' at compile time.
632 · The /dev/urandom device.
634 With recent (>=OpenSSL 0.9.5a) version of SSL it will stop loading
636 random data automatically when sufficient entropy has been gathered.
637 With previous versions it will continue to gather from all the above
638 sources since no SSL function exists to tell when enough data is
639 available.
640 Note that on Windows machines that do not have console user interaction
642 (mouse movements, creating windows, etc.) the screen contents are not
643 variable enough to be sufficient, and you should provide a random file
644 for use with the RNDfile flag.
645 Note that the file specified with the RNDfile flag should contain
647 random data -- that means it should contain different information each
648 time stunnel is run. This is handled automatically unless the
649 RNDoverwrite flag is used. If you wish to update this file manually,
650 the openssl rand command in recent versions of OpenSSL, would be
651 useful.
652 One important note -- if /dev/urandom is available, OpenSSL has a habit
654 of seeding the PRNG with it even when checking the random state, so on
655 systems with /dev/urandom you're likely to use it even though it's
656 listed at the very bottom of the list above. This isn't stunnel's
657 behaviour, it's OpenSSLs.
658
660 stunnel.conf
661 stunnel configuration file
662
664 Option execargs does not support quoting.
665
667 tcpd(8)
668 access control facility for internet services
669 inetd(8)
671 internet 'super-server'
672 http://stunnel.mirt.net/
674 stunnel homepage
675 http://www.stunnel.org/
677 stunnel Frequently Asked Questions
678 http://www.openssl.org/
680 OpenSSL project website
681
683 Michal Trojnara
684 <Michal.Trojnara@mirt.net>
6854.34 2010.10.04 STUNNEL(8)