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 To have libwrap (TCP Wrappers) control effective in a chrooted
83 environment you also have to copy its configuration files
84 (/etc/hosts.allow and /etc/hosts.deny) there.
85 compression = zlib | rle
87 select data compression algorithm
88 default: no compression
90 zlib compression of OpenSSL 0.9.8 or above is not backward
92 compatible with OpenSSL 0.9.7.
93 rle compression is currently not implemented by the OpenSSL
95 library.
96 debug = [facility.]level
98 debugging level
99 Level is a one of the syslog level names or numbers emerg (0),
101 alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
102 debug (7). All logs for the specified level and all levels
103 numerically less than it will be shown. Use debug = debug or debug
104 = 7 for greatest debugging output. The default is notice (5).
105 The syslog facility 'authpriv' will be used unless a facility name
107 is supplied. (Facilities are not supported on Win32.)
108 Case is ignored for both facilities and levels.
110 EGD = egd path (Unix only)
112 path to Entropy Gathering Daemon socket
113 Entropy Gathering Daemon socket to use to feed OpenSSL random
115 number generator. (Available only if compiled with OpenSSL 0.9.5a
116 or higher)
117 engine = auto | <engine id>
119 select hardware engine
120 default: software-only cryptography
122 There's an example in 'EXAMPLES' section.
124 engineCtrl = command[:parameter]
126 control hardware engine
127 Special commands "LOAD" and "INIT" can be used to load and
129 initialize the engine cryptogaphic module.
130 fips = yes | no
132 Enable or disable FIPS 140-2 mode.
133 This option allows to disable entering FIPS mode if stunnel was
135 compiled with FIPS 140-2 support.
136 default: no
138 foreground = yes | no (Unix only)
140 foreground mode
141 Stay in foreground (don't fork) and log to stderr instead of via
143 syslog (unless output is specified).
144 default: background in daemon mode
146 output = file
148 append log messages to a file instead of using syslog
149 /dev/stdout device can be used to redirect log messages to the
151 standard output (for example to log them with daemontools
152 splogger).
153 pid = file (Unix only)
155 pid file location
156 If the argument is empty, then no pid file will be created.
158 pid path is relative to chroot directory if specified.
160 RNDbytes = bytes
162 bytes to read from random seed files
163 Number of bytes of data read from random seed files. With SSL
165 versions less than 0.9.5a, also determines how many bytes of data
166 are considered sufficient to seed the PRNG. More recent OpenSSL
167 versions have a builtin function to determine when sufficient
168 randomness is available.
169 RNDfile = file
171 path to file with random seed data
172 The SSL library will use data from this file first to seed the
174 random number generator.
175 RNDoverwrite = yes | no
177 overwrite the random seed files with new random data
178 default: yes
180 service = servicename
182 use specified string as the service name
183 On Unix: inetd mode service name for TCP Wrapper library.
185 On NT/2000/XP: NT service name in the Control Panel.
187 default: stunnel
189 setgid = groupname (Unix only)
191 setgid() to groupname in daemon mode and clears all other groups
192 setuid = username (Unix only)
194 setuid() to username in daemon mode
195 socket = a|l|r:option=value[:value]
197 Set an option on accept/local/remote socket
198 The values for linger option are l_onof:l_linger. The values for
200 time are tv_sec:tv_usec.
201 Examples:
203 socket = l:SO_LINGER=1:60
205 set one minute timeout for closing local socket
206 socket = r:TCP_NODELAY=1
207 turn off the Nagle algorithm for remote sockets
208 socket = r:SO_OOBINLINE=1
209 place out-of-band data directly into the
210 receive data stream for remote sockets
211 socket = a:SO_REUSEADDR=0
212 disable address reuse (enabled by default)
213 socket = a:SO_BINDTODEVICE=lo
214 only accept connections on loopback interface
215 syslog = yes | no (Unix only)
217 enable logging via syslog
218 default: yes
220 taskbar = yes | no (WIN32 only)
222 enable the taskbar icon
223 default: yes
225 SERVICE-LEVEL OPTIONS
227 Each configuration section begins with service name in square brackets.
228 The service name is used for libwrap (TCP Wrappers) access control and
229 lets you distinguish stunnel services in your log files.
230 Note that if you wish to run stunnel in inetd mode (where it is
232 provided a network socket by a server such as inetd, xinetd, or
233 tcpserver) then you should read the section entitled INETD MODE below.
234 accept = [host:]port
236 accept connections on specified host:port
237 If no host specified, defaults to all IP addresses for the local
239 host.
240 CApath = directory
242 Certificate Authority directory
243 This is the directory in which stunnel will look for certificates
245 when using the verify. Note that the certificates in this directory
246 should be named XXXXXXXX.0 where XXXXXXXX is the hash value of the
247 DER encoded subject of the cert (the first 4 bytes of the MD5 hash
248 in least significant byte order).
249 CApath path is relative to chroot directory if specified.
251 CAfile = certfile
253 Certificate Authority file
254 This file contains multiple CA certificates, used with the verify.
256 cert = pemfile
258 certificate chain PEM file name
259 A PEM is always needed in server mode. Specifying this flag in
261 client mode will use this certificate chain as a client side
262 certificate chain. Using client side certs is optional. The
263 certificates must be in PEM format and must be sorted starting with
264 the certificate to the highest level (root CA).
265 ciphers = cipherlist
267 Select permitted SSL ciphers
268 A colon delimited list of the ciphers to allow in the SSL
270 connection. For example DES-CBC3-SHA:IDEA-CBC-MD5
271 client = yes | no
273 client mode (remote service uses SSL)
274 default: no (server mode)
276 connect = [host:]port
278 connect to a remote host:port
279 If no host is specified, the host defaults to localhost.
281 Multiple connect options are allowed in a single service section.
283 If host resolves to multiple addresses and/or if multiple connect
285 options are specified, then the remote address is chosen using a
286 round-robin algorithm.
287 CRLpath = directory
289 Certificate Revocation Lists directory
290 This is the directory in which stunnel will look for CRLs when
292 using the verify. Note that the CRLs in this directory should be
293 named XXXXXXXX.0 where XXXXXXXX is the hash value of the CRL.
294 CRLpath path is relative to chroot directory if specified.
296 CRLfile = certfile
298 Certificate Revocation Lists file
299 This file contains multiple CRLs, used with the verify.
301 curve = nid
303 specify ECDH curve name for server
304 To get a list of supported curves use:
306 openssl ecparam -list_curves
308 default: prime256v1
310 delay = yes | no
312 delay DNS lookup for 'connect' option
313 engineNum = engine number
315 select engine number to read private key
316 The engines are numbered starting from 1.
318 exec = executable_path (Unix only)
320 execute local inetd-type program
321 exec path is relative to chroot directory if specified.
323 execargs = $0 $1 $2 ... (Unix only)
325 arguments for exec including program name ($0)
326 Quoting is currently not supported. Arguments are separated with
328 arbitrary number of whitespaces.
329 failover = rr | prio
331 Failover strategy for multiple "connect" targets.
332 rr (round robin) - fair load distribution
334 prio (priority) - use the order specified in config file
335 default: rr
337 ident = username
339 use IDENT (RFC 1413) username checking
340 key = keyfile
342 private key for certificate specified with cert option
343 Private key is needed to authenticate certificate owner. Since
345 this file should be kept secret it should only be readable to its
346 owner. On Unix systems you can use the following command:
347 chmod 600 keyfile
349 default: value of cert option
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 currently supported: cifs, connect, imap, nntp, pop3, smtp, pgsql
385 protocolAuthentication = auth_type
387 authentication type for protocol negotiations
388 currently supported: basic, NTLM
390 Currently authentication type only applies to 'connect' protocol.
392 default: basic
394 protocolHost = host:port
396 destination address for protocol negotiations
397 protocolPassword = password
399 password for protocol negotiations
400 protocolUsername = username
402 username for protocol negotiations
403 pty = yes | no (Unix only)
405 allocate pseudo terminal for 'exec' option
406 retry = yes | no (Unix only)
408 reconnect a connect+exec section after it's disconnected
409 default: no
411 session = timeout
413 session cache timeout
414 sessiond = host:port
416 address of sessiond SSL cache server
417 sslVersion = version
419 select version of SSL protocol
420 Allowed options: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2
422 default: all
424 stack = bytes (except for FORK model)
426 thread stack size
427 TIMEOUTbusy = seconds
429 time to wait for expected data
430 TIMEOUTclose = seconds
432 time to wait for close_notify (set to 0 for buggy MSIE)
433 TIMEOUTconnect = seconds
435 time to wait to connect a remote host
436 TIMEOUTidle = seconds
438 time to keep an idle connection
439 transparent = yes | no (Unix only)
441 transparent proxy mode
442 Re-write address to appear as if wrapped daemon is connecting from
444 the SSL client machine instead of the machine running stunnel.
445 This option is currently available in:
447 remote mode (I<connect> option) on Linux >=2.6.28
449 remote mode (I<connect> option) 2.2.x
450 local mode (I<exec> option)
451 Remote mode (either 2.2.x and >=2.6.28) requires stunnel to be
453 executed as root. setuid option will also break this
454 functionality.
455 Linux >=2.6.28 requires the following setup for iptables and
457 routing (possibly in /etc/rc.local or equivalent file):
458 iptables -t mangle -N DIVERT
460 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
461 iptables -t mangle -A DIVERT -j MARK --set-mark 1
462 iptables -t mangle -A DIVERT -j ACCEPT
463 ip rule add fwmark 1 lookup 100
464 ip route add local 0.0.0.0/0 dev lo table 100
465 Linux 2.2.x requires kernel to be compiled with transparent proxy
467 option. Connected service must be installed on a separate host.
468 Routing towards the clients has to go through the stunnel box.
469 Local mode works by LD_PRELOADing env.so shared library.
471 verify = level
473 verify peer certificate
474 level 1 - verify peer certificate if present
476 level 2 - verify peer certificate
477 level 3 - verify peer with locally installed certificate
478 default - no verify
479 It is important to understand, that this option was solely designed
481 for access control and not for authorization. Specifically for
482 level 2 every non-revoked certificate is accepted regardless of its
483 Common Name. For this reason a dedicated CA should be used with
484 level 2, and not a generic CA commonly used for webservers. Level
485 3 is preferred for point-to-point connections.
486
488 stunnel returns zero on success, non-zero on error.
489
491 In order to provide SSL encapsulation to your local imapd service, use
492 [imapd]
494 accept = 993
495 exec = /usr/sbin/imapd
496 execargs = imapd
497 If you want to provide tunneling to your pppd daemon on port 2020, use
499 something like
500 [vpn]
502 accept = 2020
503 exec = /usr/sbin/pppd
504 execargs = pppd local
505 pty = yes
506 If you want to use stunnel in inetd mode to launch your imapd process,
508 you'd use this stunnel.conf. Note there must be no [service_name]
509 section.
510 exec = /usr/sbin/imapd
512 execargs = imapd
513 Here is an example of advanced engine configuration to read private key
515 from an OpenSC engine
516 engine=dynamic
518 engineCtrl=SO_PATH:/usr/lib/opensc/engine_pkcs11.so
519 engineCtrl=ID:pkcs11
520 engineCtrl=LIST_ADD:1
521 engineCtrl=LOAD
522 engineCtrl=MODULE_PATH:/usr/lib/pkcs11/opensc-pkcs11.so
523 engineCtrl=INIT
524 [service]
526 engineNum=1
527 key=id_45
528
530 stunnel.conf
531 stunnel configuration file
532 stunnel.pem
534 stunnel certificate and private key
535
537 Option execargs does not support quoting.
538
540 stunnel cannot be used for the FTP daemon because of the nature of the
541 FTP protocol which utilizes multiple ports for data transfers. There
542 are available SSL enabled versions of FTP and telnet daemons, however.
543
545 INETD MODE
546 The most common use of stunnel is to listen on a network port and
547 establish communication with either a new port via the connect option,
548 or a new program via the exec option. However there is a special case
549 when you wish to have some other program accept incoming connections
550 and launch stunnel, for example with inetd, xinetd, or tcpserver.
551 For example, if you have the following line in inetd.conf:
553 imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
555 In these cases, the inetd-style program is responsible for binding a
557 network socket (imaps above) and handing it to stunnel when a
558 connection is received. Thus you do not want stunnel to have any
559 accept option. All the Service Level Options should be placed in the
560 global options section, and no [service_name] section will be present.
561 See the EXAMPLES section for example configurations.
562 CERTIFICATES
564 Each SSL enabled daemon needs to present a valid X.509 certificate to
565 the peer. It also needs a private key to decrypt the incoming data. The
566 easiest way to obtain a certificate and a key is to generate them with
567 the free OpenSSL package. You can find more information on certificates
568 generation on pages listed below.
569 The order of contents of the .pem file is important. It should contain
571 the unencrypted private key first, then a signed certificate (not
572 certificate request). There should be also empty lines after
573 certificate and private key. Plaintext certificate information
574 appended on the top of generated certificate should be discarded. So
575 the file should look like this:
576 -----BEGIN RSA PRIVATE KEY-----
578 [encoded key]
579 -----END RSA PRIVATE KEY-----
580 [empty line]
581 -----BEGIN CERTIFICATE-----
582 [encoded certificate]
583 -----END CERTIFICATE-----
584 [empty line]
585 RANDOMNESS
587 stunnel needs to seed the PRNG (pseudo random number generator) in
588 order for SSL to use good randomness. The following sources are loaded
589 in order until sufficient random data has been gathered:
590 · The file specified with the RNDfile flag.
592 · The file specified by the RANDFILE environment variable, if set.
594 · The file .rnd in your home directory, if RANDFILE not set.
596 · The file specified with '--with-random' at compile time.
598 · The contents of the screen if running on Windows.
600 · The egd socket specified with the EGD flag.
602 · The egd socket specified with '--with-egd-sock' at compile time.
604 · The /dev/urandom device.
606 With recent (>=OpenSSL 0.9.5a) version of SSL it will stop loading
608 random data automatically when sufficient entropy has been gathered.
609 With previous versions it will continue to gather from all the above
610 sources since no SSL function exists to tell when enough data is
611 available.
612 Note that on Windows machines that do not have console user interaction
614 (mouse movements, creating windows, etc) the screen contents are not
615 variable enough to be sufficient, and you should provide a random file
616 for use with the RNDfile flag.
617 Note that the file specified with the RNDfile flag should contain
619 random data -- that means it should contain different information each
620 time stunnel is run. This is handled automatically unless the
621 RNDoverwrite flag is used. If you wish to update this file manually,
622 the openssl rand command in recent versions of OpenSSL, would be
623 useful.
624 One important note -- if /dev/urandom is available, OpenSSL has a habit
626 of seeding the PRNG with it even when checking the random state, so on
627 systems with /dev/urandom you're likely to use it even though it's
628 listed at the very bottom of the list above. This isn't stunnel's
629 behaviour, it's OpenSSLs.
630
632 tcpd(8)
633 access control facility for internet services
634 inetd(8)
636 internet 'super-server'
637 http://stunnel.mirt.net/
639 stunnel homepage
640 http://www.stunnel.org/
642 stunnel Frequently Asked Questions
643 http://www.openssl.org/
645 OpenSSL project website
646
648 Michal Trojnara
649 <Michal.Trojnara@mirt.net>
6504.29 2009.11.20 STUNNEL(8)