|
Stunnel FAQ: Running Stunnel
Chapter Contents:
This section gives you basic information on how to run
the stunnel program in client and server mode.
NOTE: This page is currently Stunnel 3.x specific. Any
additions welcome.
(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
argument descriptions,
and the examples in examples section.
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.
(This does not apply to Windows machines)
If you want to run Stunnel 4.x from inetd/xinetd/tcpserver/etc,
then you still set up the inetd.conf/xinetd.conf/etc files the
same way you would for 3.x. When creating your Stunnel 4.x
configuration file, do not include a [service]
line. For example
cert= ...
setuid = ...
setgid = ...
...
# Do not include
# [someservicename]
connect = logging:syslogs
If you have a [service] line, then Stunnel
will fork into the background to do it's job, and will
not work with inetd.
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
command line argument descriptions,
and the examples in examples section.
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.
(See the patches page
for patches that will allow you to turn off
the automatic inclusion of libwrap at compile time.)
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.
See also the examples section.
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.
Stunnel 4.x can run as a native service under Windows.
If you're running a 4.x version, then you can install as
a native service by running
stunnel -install
in the directory in which stunnel.conf is available.
The 3.x branch does not have the ability to run natively as
a service. However, here are some user-suplied suggestions:
- Rainer W. Gerling, suggests using
Manfred Spraul's service program available at
http://colorfullife.com/manfreds/Service/.
(He also notes to make the configuration files read only, lest
anyone be able to run any program as a service.)
- Jim Gilliver suggests creating a
batch file that runs stunnel using the START command as follows:
START /M stunnel - should run stunnel in the background.
If that doesn't work, you could definitely do it with a
batch file doing this:
START COMMAND /C STUNNEL options
But this way will open a new dos box for every instance of stunnel.
-
Miroslav Pragl suggests including registry entries for win9x in:
HKLM/Software/Microsoft/Windows/CurrentVersion/RunServices
or running stunnel with srvany.exe for Windows NT.
Under Win9x or NT you can use the Task Schedule, which is visible
in 'My Computer' if MSIE 4.0 or higher is installed. Add
Stunnel as a new task that is launched on startup.
- B. Busshardt wrote a web page describing
the start procedure of an Stunnel service using
srvany.exe of the resource kit. Find it
here.
(English translation via BabelFish.)
- Kirk Hinderberger points us to the following
Microsoft website on how to create an NT/2000 service:
Q137890 - HOWTO: Create a User-Defined Service
- Clemens Wittinger suggests FireDaemon,
available at http://www.firedaemon.com,
saying:
"Anyway it does, at least accoding to their website, what srvany.exe is supposed
to. It's free, well at least it resides in some part of the free
software spectrum... And it works. Nice tool as well."
- Ed Suominen suggest you use 'winhide.exe' to hide the
DOS window that is spawned by Stunnel. Download via
http://www.owt.com/users/rsavard/software.html and
http://www.savardsoftware.com/downloads/whide32.zip.
Execute winhide followed by the window title, e.g.:
winhide "Command Prompt - stunnel -d 5501 -r 5500"
In TCL, you can script this along with scripting the stunnel start as
follows:
set args [list stunnel -d $dport -r $rport]
exec cmd.exe /c $args
exec cmd.exe /c winhide {Command Prompt - } $args
The stunnel window disappears and it is running, for all practical
purposes, as a service.
- Mats Gefvert created an Stunnel service wrapper, which he
describes:
My program, which I in a moment of brilliant inspiration decided to call
"stunnelsvc", does just that: It contains a graphical configuration
interface, which, according to Win32 recommended practices, stores
information in the local registry, and has a service which installs
itself into the service manager and acts like a professional windows service.
The program can be found at
http://www.kristnet.org/~mats/software/stunnelsvc.zip.
I thought that you guys might be interested to have a look at it.
- Giuseppe Crisafulli provides another solution at
http://www.crisafulli.net/cygwin/running_stunnel_as_a_service.htm.
|
