These are the arguments available to Stunnel as of
version 3.26. Older versions may not support all these
arguments.
- -c
- Client mode.
stunnel will connect to the machine/port specified as an
SSL client. This naturally requires that the remote end
is speaking SSL.
On unix, you will be able to send input directly
to the remote end, and receieve it's output. Very
useful for debugging connections.
On Windows you cannot interactively use this to communicate
to the remote machine. This is due to the way communication
is handled in the OpenSSL library, and is not something
stunnel can fix.
- -T
- 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 operating systems (Linux only, we believe)
and then only in server mode. Note that this option will not combine
with proxy mode (-r)
unless the client's default route to the target machine lies through
the host running stunnel, which cannot be localhost.
- -p file
- Location of your SSL Certificate/Certificate Chain
Allows you to specify the location of the SSL
Key/Certificate/Certificate Chain
to use for this connection.
See the certs section for
more info about this file.
See the stunnel -V output for defaults.
No cert is used by default in client mode. A key/cert is
always needed in server mode.
When a certificate chain, rather than a single certificate
is present in this file, the file must be sorted
starting with the certificate to the highest level (root CA).
This file must have all keys and certs in PEM format.
- -v #
- Certificate verification level
How should stunnel verify the certificate presented by
the other end of the SSL connection:
- Level 0: peer certificate is requested, but not verified.
- Level 1: verify peer certificate if present.
- Level 2: verify peer certificate.
- Level 3: verify peer with localy installed certificate.
See the certs section section for more detail.
Default: don't verify.
- -a directory
- The directory in which you have your locally installed
certificates.
This is the location in which stunnel will look to verify the
peer certificate when using -v 3. See
the certs section for a more detailed
description. Certificates in this directory are stored as
files where the filename is of the form XXXXXXXX.0
where XXXXXXXX is the hash value of the certificate.
See the stunnel -V output for defaults.
- -A certfice
- Certificate Authority File
This file contains multiple CA certificates, which is used with
the -v options.
- -S #
- Certificate source defaults
Both stunnel and the SSL library used to compile stunnel have default
locations to look for your certificate file (-A option)
and certificate directories (-a option). The -S flag allows you
to control which of these default sources, if any, should be
used.
- = ignore all default sources
- = use only ssl library defaults
- = use only stunnel defaults
- = use all defaults
See stunnel -V output for the default.
Note that the -A and -a flags overwrite, not supliment,
the stunnel defaults, whereas the ssl library defaults,
if enabled, are used in addition to the other sources.
In general, to avoid hurting one's brain, use -S 0
and explicitly set -A and/or -a as desired.
- -t seconds
- Session cache timeout
How long session IDs will be cached by stunnel.
SSL has a rather lengthy handshake to determine ciphers
used, verify peer identity, etc. Using
Session IDs allow a faster SSL handshake for the subsequent
SSL connections between that client and server. The timeout
defines how long said Session ID's should be cached.
See the stunnel -V output for defaults,
typically 300 seconds (5 minutes).
Note: the session cache has nothing to do with 'idle timeout'
which is determined at compile time, generally 1 minute.
- -u username
- Remote user name
This option uses the IDENT protocol
(RCF1413)
to determine the user who is initiating the SSL connection. It
relies on the remote (client) end to return the information
about the user.
Because the username is being given by the remote end, to be
using this feature securely you should be limiting access
to your stunnel server to a list of specific trusted hosts.
You can do this with the tcp wrapper support built into stunnel,
or other methods. It is trivial for a hacker to provide false
IDENT information.
- -N servicename
- Service name to use for TCP wrappers. If not specified then
a TCP wrapper service name will be generated automatically for
you. This will also be used when auto-generating pid filenames.
- -n protocol
- Negotiate SSL with the specified protocol
Some protocols have SSL as a negotiated option, not simply as
a handshake before the connection itself. This traditionally
has been difficult for SSL front-ends to support.
Note this is not the same as selecting permitted SSL
ciphers. See -C below for that.
Currently supported options are: smtp,
nntp, and pop.
- -E socket
- Location of the EGD (Entropy Gathering Daemon) or PRNGD (Pseudo Random
Number Generating Daemon) socket used to feed the OpenSSL random number
generator. (Available only if compiled with OpenSSL 0.9.5a or higher.)
- -R filename
- File containing random input. The SSL library will use data from this
file first to seed the random number generator. Note this file will
be overwritten with new random data unless the -W argument
is not specified.
- -W
- Do not overwritethe random seed files (specified with the -R filename
argument) with new random data.
- -B bytes
- 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 randomness is available.
- -P { dir/ | file | none }
- Pid file location
If the argument is a pathname ending in a slash, then
a pid file named "stunnel.servicename.pid" will
be created in the specified directory. If the argument
is a filename (no trailing slash), then that filename
will be used for the pid. If the argument is 'none',
then no pid file will be created.
- -I host
- If you have multiple interfaces and need Stunnel to use a
specific one for outbound (
-r) connections,
you can specify that IP/hostname here.
- -d [host:]port
- Run stunnel in daemon mode
This option allows you to run stunnel in daemon mode. It tells
stunnel to listen on the port port. Port may be a well
known port (ie listed in /etc/services) or be a numeric
port.
If your machine has multiple IP addresses, you may wish to restrict
stunnel to listen on onle one of the available IP addresses.
host may be either a machine name or IP address.
host defaults to all local IP addresses unless specified.
Examples:
-d 443 listen on port 443 on all IP addresses.
-d www:443 listen on port 443 only on the local IP address
associated with the machine 'www'
- -r [host:]port
- Connect to a 'remote' service
This option allows to to connect to a specific service.
As with the -d flag above, the host can be
an IP or hostname, and the port can me a well-known port or
an actual port number.
The meaning of the -r flag differs depending
on if you are acting as
a server (daemon/inetd) or a client (-c).
- In daemon mode:
- The daemon, after establishing SSL with the client application,
will pass the traffic along (unencrypted) to the remote end
(
[host:]port). Thus the connection to the client is
secure, whereas the connection to the remote end is insecure.
This remote end is typically a local port on the server machine,
or a port on a separate machine on a trusted network.
Example: -r www:http
Send the encrypted SSL traffic from the
clients to the http port of the machine
www. (A poor man's https:// front end)
- In client mode:
- The client will establish an SSL connection to the remote
(
[host:]port) machine. This connection is fully encrypted.
Example: -r mail:pop3s
Contact the pop3s (SSL pop3) port
on the machine mail. (A very difficult way
to read mail securely. I'd try a mail client first if I were
you...)
- -f
- Foreground
When in daemon mode, stay in the foreground, rather than detaching
from your terminal, and log to STDERR. Very useful for debugging.
- -l program [ -- args ]
- Execute local inetd-type program
Once establishing an SSL connection, have stunnel launch
the specified program, encrypting all traffic between
it and the client. It's best to use a full pathname.
If your program takes arguments, list them after a double dash.
make sure that your -l is the last stunnel
argument you use in this case.
Example: -l /bin/cat -- cat /etc/motd
Allow clients to connect with SSL and read the Message of the Day.
See the examples section for more detail.
In version 3.21 and later, if you are running
in server mode (-d, but not -c or -n are used) then the
environment variables SSL_CLIENT_DN and SSL_CLIENT_I_DN are
set from the certificate of the peer.
- -L program [ -- args ]
- Execute local inetd-type program on a local PTY
-L does the same thing as -l
except that it additionally opens a local PTY (pseudo-terminal)
on the machine and runs he program on that PTY. This is needed
for certain programs, notably PPP.
- -s username
- setuid to username in daemon mode
This flag allows you to select a different user as which
the stunnel daemon should run. The daemon must often start by
running as root in order to bind low port numbers
( <1024 )
however it may be desirable for it to become a different user before
performing service, for example running the program
specified by the -l or -L arguments.
username must be a username, not a numeric user id.
- -g groupname
- setgid to groupname in daemon mode
This flag allows you to select a different group as which
the stunnel daemon should run. The daemon must often start by
running as root in order to bind low port numbers
( <1024 )
however it may be desirable for it to become a different group before
performing service, for example running the program
specified by the -l or -L arguments.
groupname must be a group name, not a numeric group id.
You are limited to running as one group only, you cannot initialize
multiple groups (ala setgroups)
- -O a|l|r:option=value[:value]
- Set an option on accept/local/remote socket
There are more TCP options than you can shake a stick at. If you find
that some things are not working as you might expect (hung connections that
should have closed, nasty protocols like Oracle dying due to OOB (Out Of
Band data) then you can tweek TCP options to fix (some of) these problems.
These options are not for the newbie, nor the timid. We heartily suggest
you get a copy of W. Richard Steven's excellent TCP/networking books
if you want to learn what this is all about.
The 'a|l|r' section of the option is used to dictate
to which type of socket this option should be applied. aspecifies
an accept (inbound), l specifies a local (-l or -L)
and r specifies a remote (outbound TCP) socket.
The acceptible values and their meanings are dictated by the option
itself. It should be noted that the values for the SO_LINGER option
are l_onof:l_linger, and the values for time are tv_sec:tv_usec.
If you're still with us, here are some example arguments:
| -O l:SO_LINGER=1:60 | Set one minute timeout for closing local socket |
|---|
| -O r:TCP_NODELAY=1 | Turn off the Nagle algorithm for
remote sockets |
|---|
| -O r:SO_OOBINLINE=1 | Place out-of-band data
directly into the receive data stream for remote sockets |
|---|
| -O a:SO_REUSEADDR=0 | Disable address reuse (enabled
by default) |
|---|
| -O a:SO_BINDTODEVICE=lo | Only accept connections on
loopback interface |
|---|
See the output of 'stunnel -V' for options supported on your system and
their default values.
- -o filename
- Log to a file
Instead of sending output to stderr or syslog, output
the log to the specified filename, which is opened in
append mode.
- -C list
- Set permitted SSL ciphers
This flag allows you to specify exactly which ciphers to allow
for the SSL connection. The ciphers supported must, naturally,
be available in the underlying SSLeay or OpenSSL libraries with
which you used to compile stunnel.
The format of this list is dependent on the underlying library.
OpenSSL allows you to use any of comma, colon, semicolon, and
space as legal separators.
If there are not compatible ciphers available on both ends
(client and server) then the connection is dropped.
Example: -C DES-CBC3-SHA:DES-CBC-MD5:IDEA-CBC-MD5:DES-CBC-SHA
Allow only those four ciphers for SSL.
- -D [facility.]level
- Debug Level
The debug level for the logging to syslog,
or STDERR when -f
is used. By selecting a level you will log all messages of that
level or
less (ie all those messages and those even more important.)
The levels are your standard syslog levels, as outlined
in the following table:
| 0 | EMERG | system is unusable |
|---|
| 1 | ALERT | action must be taken immediately |
|---|
| 2 | CRIT | critical conditions |
|---|
| 3 | ERR | error conditions |
|---|
| 4 | WARNING | warning conditions |
|---|
| 5 | NOTICE | normal but significant condition |
|---|
| 6 | INFO | informational |
|---|
| 7 | DEBUG | debug-level messages |
|---|
You can specify the level as either the number (0 through 7) or the name
(emerg through debug) which is
case insensitive.
Facility (not available on windows) is the syslog
facility to use, such as mail, uucp, local2, etc. The
default is daemon. See
'man syslog' for the supported facilities on your system.
Default: level 5 (notice)
- -h
- Stunnel help screen
Don't do anything, just print out a help screen giving a brief
overview of the arguments it accepts. Like this page, just
more brief. Lets you see the defaults it assumes as well.
- -V
- Stunnel version
Don't do anything, just print out the version of stunnel,
and show the compile-time defaults.
Example output:
stunnel 3.X on i686-pc-linux-gnu PTHREAD+LIBWRAP
Default behaviour:
run in inetd mode (unless -d used)
run in background (unless -f used)
run in ssl server mode (unless -c used)
Compile time defaults:
-v level no verify
-a directory (none)
-A file (none)
-S sources 2
-t timeout 300 seconds
-B bytes 64
-D level 5
-P pid dir /opt/pkgs/stunnel-3.9/var/stunnel/
-p pemfile in server mode: stunnel.pem
in client mode: none
