This page depreciated

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

Stunnel Examples

This section gives you some examples of running stunnel to support various services.

Setting up PPP over stunnel (Make your own VPN)

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 FAQ Maintainer and I'll make them available.

Examples of launching programs from an stunnel daemon

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

Examples of encrypting existing services

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.

Examples of tcp wrapper service names for stunnel

First, read the description about running stunnel with tcp wrappers in chapter 4.

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

Forwarding an insecure port securely from one machine to another

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