Stunnel FAQ: Examples
Chapter Contents:
Examples
Setting up PPP over stunnel (Make your own VPN)
Examples of launching programs from an stunnel daemon
Examples of encrypting existing services
Examples of tcp wrapper service names for stunnel
Forwarding an insecure port securely from one machine to another
This section gives you some examples of running stunnel
to support various services.
- Set up your ppp configuration as you would if you were
just using a normal dialup connection, including
any passwords required.
There is no step-by-step description I can give for
you here, as this is different from OS to OS.
Working submissions encouraged.
- Read about setting up stunnel on the previous pages.
- Set up stunnel on the server in either daemon or inetd
mode with the following meta-arguments:
(stunnel) (stunnel args) -L /dir/to/pppd -- pppd local
for example
stunnel -d 5555 -v 1 -D 7 -L /usr/sbin/pppd -- pppd local
- Run stunnel on the client with the following meta-arguments:
(stunnel) (stunnel args) -L /dir/to/pppd -- pppd local
for example
stunnel -c -r remote:5555 -D 7 -L /usr/sbin/pppd -- pppd local
You could also look at
this URL which
describes setting up ppp over an ssh connection.
Setting up ppp over stunnel is similar.
If anyone specific implementations they'd like
to share, complete with how to set up pppd on your OS), please
inform the Webmaster
and I'll make them available.
The -l and -L arguments allow you to supply
the name of a program to launch from the stunnel Daemon.
Examples:
-l /usr/sbin/ipop3d
- Run the ipop3d (POP3 daemon).
-l /usr/sbin/swat -- swat -s /etc/smb.conf
- Run the
swat (Samba Web Administration Tool)
Here you see an example where the program
you are running (swat ) takes
additional arguments, here the -s /etc/smb.conf .
Note that you first supply the full path to the program
/usr/sbin/swat followed by two dashes, followed
by the program name (argv[0] or $0
for you C and perl programmers, respectively) and then
the arguments.
When using this form (the one with the double dash)
make sure the -l argument is your last stunnel
argument on the command line (or in the
inetd.conf file).
Lets say you want to protect the IMAP service, which
runs on port 143 . Normally (ie without any SSL)
you'd simply have a line like the following in
/etc/inetd.conf :
imap stream tcp nowait root /usr/sbin/tcpd imapd
However we wish to wrap it in SSL with stunnel.
Let's give two examples.
- Example 1: stunnel forwards traffic (after SSL decryption)
to the existing
imap service (port 143).
Start up stunnel as follows:
stunnel -d imaps -r localhost:imap
which says 'listen on port imaps, and
forward all traffic, after decryption, to port
imap (143) on localhost '.
Now if we're using tcp wrappers, we probably want to
do two things:
- If we want to force everyone to use the secure
imaps ,
deny access to all machines other than localhost
(127.0.0.1) to imap in /etc/hosts.allow .
- If we want to limit access to this
imaps
port, restrict it in /etc/hosts.allow .
Note that the service name, given the way we started
stunnel above, would be localhost.imap .
- Example 2: stunnel launches the
imapd program itself,
rather than just forwarding packets to the existing imap
port.
Start stunnel this way:
stunnel -d imaps -l /usr/sbin/imapd
which says 'listen on port imaps, and
launch the program /usr/sbin/imapd and
send it the unencrypted data from the remote end.'
Again, if we want to restrict access, we'll probably
do two things:
- If we don't need anyone using the
imap service
without SSL, simply remove the existing imap line in
/etc/inetd.conf and send inetd
a SIGHUP .
-
If we want to limit access to this
imaps port,
restrict it in /etc/hosts.allow .
Note that the service name, given the way we started
stunnel above, would be imapd .
One important thing to remember is that you must
have your client configured to use SSL. If it isn't,
then it will never attempt to use the stunnel wrapper
you've put in place. Make sure that your client has
SSL support. If it doesn't, you will get errors noticable
from the stunnel debugging output.
First, read the description about running Stunnel
with tcp wrappers in
this section.
Examples:
stunnel command | tcp wrapper service name |
---|
stunnel ... -r http | http |
stunnel ... -r www:http | www.http |
stunnel ... -l /usr/bin/ipop3d | ipop3d |
stunnel ... -l /bin/cat -- cat /etc/motd | cat |
stunnel ... -l /bin/cat -- motd /etc/motd | motd |
Stunnel will print out the tcpwrapper service name in the debugging
output. If you wish to select one rather than relying on stunnel's
built-in method of determining the service name, use the
-N servicename flag.
Lets say you want to use POP from your local machine to a remote
machine, but don't have an SSL aware email client. What you can
do is to have your machine
talk to stunnel on the local machine,
who then encrypts the packets and sends them another stunnel
running on the remote machine,
which forwards them in clear text to the POP server on that machine.
You must have some port on the remote machine that listens for
the encrypted connection. You can either pick some arbitrary
high port (for cases where you're not running as root this may be
the only option, for example) or if the protocol has a port reserved
for an ssl variant, you could use it. So, we could pick the port
50493 out of the air if we didn't want to use the actual
registered port for pop3s -- 995 . The example
below uses pop3s , but you could use your own port instead
as long as you are consistant.
So what we need is the following:
- foo
- The local machine.
Stunnel listens on foo:pop3, forwards to bar:pop3s.
- bar
- The remote mail machine.
Stunnel listens on bar:pop3s, forwards to bar:pop3.
So, we need to run the following on foo:
stunnel -c -d pop3 -r bar:pop3s
and on bar:
stunnel -p /path/to/stunnel.pem -d pop3s -r bar:pop3
Then configure your email client to think that your local machine, foo,
is actually your mail server. The traffic will be sent from one end to
the other encrypted, even though neither your email client nor your
pop server need speek SSL.
This works for anything, not just POP. If you have flexibility
in your ports, there's no reason that you'd have listen on your
local machine on the same port to which the packets end up on
the remote machine.
For those familiar with the program
ssh , this is similar to
running
ssh -L pop3:bar:pop3 bar
except that, since stunnel is running as it's own daemon, you can
use this port forward without first establishing the ssh
connection.
|