This page depreciated

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

Running stunnel

This section gives you basic information on how to run the stunnel program in client and server mode.

Running stunnel in inetd mode

(This does not apply to Windows machines)

You can invoke stunnel from inetd. Inetd is the unix 'super server' that allows you to launch a program (for example the telnet daemon) whenever a connection is established to a specified port.

Lets say we want to have stunnel listen on our machine on port 9999 to support a fictious protocol called foobar. We'd add the following line to the file /etc/inetd.conf

   foobar stream tcp nowait root  /usr/local/sbin/stunnel stunnel args

(if you installed stunnel in a different location than /usr/local/sbin, use that path instead) and add the following line to /etc/services

   foobar	9999/tcp		# The foobar service

You must then send the inetd process a SIGHUP. Find the process id for the inetd process by one of the following commands:

   ps -ef|grep inetd
   ps -axj|grep inetd

and then type kill -HUP process_id.

You may be able to use killall -HUP inetd on some Unix versions (for example linux, *BSD, IRIX) to save yourself from looking up the process id. Note that some unix variants have a killall command that kills all processes on the machine. That's not the killall you're looking for...

For examples of the args you'd wish to use, see the next chapter, and the examples in chapter 6.

Notes:
Running in daemon mode is much prefered to running in inetd mode. Why?

SSL needs to be initialized for every connection.
No session cache is possible.
inetd mode requires forking, which causes additional overhead. Daemon mode will not fork if you have stunnel compiled with threads.

Running stunnel in daemon mode

Lets say we want to have stunnel listen on our machine on port 9999 to support a fictious protocol called foobar. We'd add the following line to /etc/services

   foobar       9999/tcp                # The foobar service

Then we launch stunnel from the command line (or a script) as follows:

   /usr/local/sbin/stunnel -d foobar args

For examples of the args you'd wish to use, see the next chapter, and the examples in chapter 6.

Running stunnel with tcp wrappers

You do not need to use the tcpd binary to wrap stunnel (although you could). You can can compile in support for tcp wrappers when you compile stunnel itself.

The configure program should be able to determine if the libwrap library (-lwrap) and headers are available in standard locations.

You must put entries in /etc/hosts.allow to specify which machines should be allowed access to stunnel. These are of the form

   service1: goodhost.example.com .trusteddomain.example.com
   service2: otherhost.example.com 192.168.0.1

Since you could be running more than one copy of stunnel, and on various ports and IPs, stunnel uses the following rules to determine what service name to use in the hosts.allow file:

If the are some arguments (after options) the first one (argv[0] for the local service) is used.
Else in remote mode - remote hostname is used, but ':' is changed to '.'.
Else in local mode - the execname (w/o path) is used.

If you are having difficulty determining what service name stunnel will look for, try running it in debug mode (-D 7) and look for a line similar to the following:

	LOG7[XXXX:XXXX]: http bound to X.X.X.X:XXXX

In the example above, stunnel will check the hosts.allow file for service entries for http.

There are more examples in chapter 6.

Stopping stunnel

If stunnel is running in daemon mode, you can stop it simply by killing it. Stunnel accepts the following signals, all of which tell it to log the signal and terminate: TERM, QUIT, INT.