This page depreciated

This FAQ for stunnel is no longer being updated. Please go to the FAQ section on www.stunnel.org instead.






Stunnel command arguments

This section gives you a breakdown of the arguments accepted by stunnel.

You may also look at the man page


Important Note

Some of the defaults listed below are different depending on how you compiled stunnel. Please see the stunnel -h output to see if your defaults vary from those listed below.

These are the arguments available to stunnel as of version 3.8. Older versions may not support all these arguments.


Stunnel 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) You will be able to type to the remote end, and see it's output. Very useful for debugging connections.

Not available on Windows machines.

-T
Transparent proxy mode.

If your machine supports it, stunnel will operate in transparent proxy mode. Thus it will connect to the destination machine as if it were the remote/client. In other words, the service to which you're connecting will see the actual source IP address, rather than the machine upon which this stunnel daemon is running. Helpful to maintain good logs.

-p file
Location of your SSL Certificate

Allows you to specify the location of the SSL Key/Certificate to use for this connection. See Chapter A for more info about this file.

Default: /usr/local/stunnel/certs/stunnel.pem in server mode.
No cert is used by default in client mode.

-v #
Certificate verification level

How should stunnel verify the certificate presented by the other end of the SSL connection:

See Chapter A section for more detail.

Default: don't verify.

-a dir
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 Chapter A for a more detailed description.

Default: /usr/local/stunnel/certs/trusted.

-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.

Default: 300 seconds (5 minutes)

-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 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.
See the examples section for how to use this option. (not there yet)

-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.

-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)

-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 num
Debug Level, 0-7

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

Default: level 5

-V
Stunnel version

Don't do anything, just print out the version of stunnel. Tells you a bit about how it was compiled as well.
Example output: stunnel 3.8 on i686-pc-linux-gnu PTHREAD+LIBWRAP

-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.


| Previous Chapter | |Table of contents | | Next Chapter |