stunnel(8) - version 4




SYNOPSIS

       stunnel [filename] | -help | -version | -sockets


DESCRIPTION

       The stunnel program is designed to work as SSL encryption
       wrapper between remote clients and local (inetd-startable)
       or remote servers. The concept is that having non-SSL
       aware daemons running on your system you can easily set
       them up to communicate with clients over secure SSL chan-
       nels.

       stunnel can be used to add SSL functionality to commonly
       used inetd daemons like POP-2, POP-3, and IMAP servers, to
       standalone daemons like NNTP, SMTP and HTTP, and in tun-
       neling PPP over network sockets without changes to the
       source code.

       This product includes cryptographic software written by
       Eric Young (eay@cryptsoft.com)


OPTIONS

       [filename]
	   Use specified configuration file

       -help
	   Print stunnel help menu

       -version
	   Print stunnel version and compile time defaults

       -sockets
	   Print default socket options


CONFIGURATION FILE

       GLOBAL OPTIONS


       CApath = directory
	   Certificate Authority directory

	   This is the directory in which stunnel will look for
	   certificates when using the verify. Note that the cer-
	   tificates in this directory should be named XXXXXXXX.0
	   where XXXXXXXX is the hash value of the cert.

       CAfile = certfile
	   Certificate Authority file

	   This file contains multiple CA certificates, used with
	   the verify.

       cert = pemfile

	   have to be relative to the directory specified with
	   chroot.

       ciphers = cipherlist
	   Select permitted SSL ciphers

	   A colon delimited list of the ciphers to allow in the
	   SSL connection.  For example DES-CBC3-SHA:IDEA-CBC-MD5

       client = yes | no
	   client mode (remote service uses SSL)

	   default: no (server mode)

       debug = level[.facility]
	   debugging level

	   Level is a one of the syslog level names or numbers
	   emerg (0), alert (1), crit (2), err (3), warning (4),
	   notice (5), info (6), or debug (7).	All logs for the
	   specified level and all levels numerically less than
	   it will be shown.  Use debug = debug or debug = 7 for
	   greatest debugging output.  The default is notice (5).

	   The syslog facility 'daemon' will be used unless a
	   facility name is supplied.  (Facilities are not sup-
	   ported on Win32.)

	   Case is ignored for both facilities and levels.

       EGD = egd path
	   path to Entropy Gathering Daemon socket

	   Entropy Gathering Daemon socket to use to feed OpenSSL
	   random number generator.  (Available only if compiled
	   with OpenSSL 0.9.5a or higher)

       foreground = yes | no
	   foreground mode

	   Stay in foreground (don't fork) and log to stderr
	   instead of via syslog (unless output is specified).

	   default: background in daemon mode

       key = keyfile
	   private key for certificate specified with cert option

	   Private key is needed to authenticate certificate
	   owner.  Since this file should be kept secret it
	   should only be readable to its owner.  On Unix systems
	   you can use the following command:
       RNDbytes = bytes
	   bytes to read from random seed files

	   Number of bytes of data read from random seed files.
	   With SSL versions less than 0.9.5a, also determines
	   how many bytes of data are considered sufficient to
	   seed the PRNG.  More recent OpenSSL versions have a
	   builtin function to determine when sufficient random-
	   ness is available.

       RNDfile = file
	   path to file with random seed data

	   The SSL library will use data from this file first to
	   seed the random number generator.

       RNDoverwrite = yes | no
	   overwrite the random seed files with new random data

	   default: yes

       timeout = timeout
	   session cache timeout

       setgid = groupname
	   setgid() to groupname in daemon mode and clears all
	   other groups

       setuid = username
	   setuid() to username in daemon mode

       socket = a|l|r:option=value[:value]
	   Set an option on accept/local/remote socket

	   The values for linger option are l_onof:l_linger.  The
	   values for time are tv_sec:tv_usec.

	   Examples:

	       socket = l:SO_LINGER=1:60
		   set one minute timeout for closing local socket
	       socket = r:TCP_NODELAY=1
		   turn off the Nagle algorithm for remote sockets
	       socket = r:SO_OOBINLINE=1
		   place out-of-band data directly into the
		   receive data stream for remote sockets
	       socket = a:SO_REUSEADDR=0
		   disable address reuse (enabled by default)
	       socket = a:SO_BINDTODEVICE=lo
		   only accept connections on loopback interface


       services in your log files.

       accept = [host:]port
	   accept connections on specified host:port

	   If no host specified, defaults to all IP addresses for
	   the local host.

       connect = [host:]port
	   connect to remote host:port

	   If no host specified, defaults to localhost.

       delay = yes | no
	   delay DNS lookup for 'connect' option

       exec = executable_path
	   execute local inetd-type program

       execargs = $0 $1 $2 ...
	   arguments for exec including program name ($0)

	   Quoting is currently not supported.	Arguments are
	   speparated with arbitrary number of whitespaces.

       ident = username
	   use IDENT (RFC 1413) username checking

       local = host
	   IP of the outgoing interface is used as source for
	   remote connections.	Use this option to bind a static
	   local IP address, instead.

       protocol = proto
	   Negotiate SSL with specified protocol

	   currently supported: smtp, pop3, nntp

       pty = yes | no
	   allocate pseudo terminal for 'exec' option

       transparent = yes | no
	   transparent proxy mode

	   Re-write address to appear as if wrapped daemon is
	   connecting from the SSL client machine instead of the
	   machine running stunnel.  Available only on some oper-
	   ating systems (Linux 2.2 only) and then only in server
	   mode. Note that this option will not combine with
	   proxy mode (connect) unless the client's default route
	   to the target machine lies through the host running
	   stunnel, which cannot be localhost.
       port 2020, use something like

	   [vpn]
	   accept = 2020
	   exec = /usr/sbin/pppd
	   execargs = pppd local
	   pty = yes



FILES

       stunnel.conf
	   stunnel configuration file

       stunnel.pem
	   stunnel certificate and private key


BUGS

       Shared library to be LD_PRELOADed with transparent option
       is not too portable.  stunnel should support creating
       shared libraries on non-gcc compilers.


RESTRICTIONS

       stunnel cannot be used for the FTP daemon because of the
       nature of the FTP protocol which utilizes multiple ports
       for data transfers.  There are available SSL enabled ver-
       sions of FTP and telnet daemons, however.


NOTES

       CERTIFICATES

       Each SSL enabled daemon needs to present a valid X.509
       certificate to the peer. It also needs a private key to
       decrypt the incoming data. The easiest way to obtain a
       certificate and a key is to generate them with the free
       openssl package. You can find more information on certifi-
       cates generation on pages listed below.

       Two things are important when generating certificate-key
       pairs for stunnel. The private key cannot be encrypted,
       because the server has no way to obtain the password from
       the user. To produce an unencrypted key add the -nodes
       option when running the req command from the openssl kit.

       The order of contents of the .pem file is also important.
       It should contain the unencrypted private key first, then
       a signed certificate (not certificate request).	There
       should be also empty lines after certificate and private
       key.  Plaintext certificate information appended on the
       top of generated certificate should be discarded. So the
       file should look like this:

	   -----BEGIN RSA PRIVATE KEY-----
       data has been gathered:

       o   The file specified with the RNDfile flag.

       o   The file specified by the RANDFILE environment vari-
	   able, if set.

       o   The file .rnd in your home directory, if RANDFILE not
	   set.

       o   The file specified with '--with-random' at compile
	   time.

       o   The contents of the screen if running on Windows.

       o   The egd socket specified with the EGD flag.

       o   The egd socket specified with '--with-egd-sock' at
	   compile time.

       o   The /dev/urandom device.

       With recent (>=OpenSSL 0.9.5a) version of SSL it will stop
       loading random data automatically when sufficient entropy
       has been gathered.  With previous versions it will con-
       tinue to gather from all the above sources since no SSL
       function exists to tell when enough data is available.

       Note that on Windows machines that do not have console
       user interaction (mouse movements, creating windows, etc)
       the screen contents are not variable enough to be suffi-
       cient, and you should provide a random file for use with
       the RNDfile flag.

       Note that the file specified with the RNDfile flag should
       contain random data -- that means it should contain dif-
       ferent information each time stunnel is run.  This is han-
       dled automatically unless the RNDoverwrite flag is used.
       If you wish to update this file manually, the openssl rand
       command in recent versions of OpenSSL, would be useful.

       One important note -- if /dev/urandom is available,
       OpenSSL has a habit of seeding the PRNG with it even when
       checking the random state, so on systems with /dev/urandom
       you're likely to use it even though it's listed at the
       very bottom of the list above.  This isn't stunnel's
       behaviour, it's OpenSSLs.


SEE ALSO

       tcpd(8)
	   access control facility for internet services

	   <Michal.Trojnara@mirt.net>



3rd Berkeley Distribution   2002.08.30		       STUNNEL(8)

Man(1) output converted with man2html