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