README for in.pop3gwd ( $Revision: 1.2 $ )
-------------------------------------------------------------------------------


	Copyright (C) 1997 Andrea Borgia

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.



Abstract:
---------

This program is an application-level gateway, or proxy, designed to allow
mail retrieval from POP3 servers by systems that either:

	(a) are behind a firewall or screening router OR
	(b) do not have an assigned IP number OR
	(c) must share a SLIP/PPP connection on another system

It connects to the POP3 server on behalf of the client, performs the login
and then passes data both ways until either the client or the server shut
down the connection. In the meanwhile, the connection will appear to have
originated on the host running the proxy.



How it all began:
-----------------


As is the case with most free software, I wrote it out of necessity. At
home, I have two PCs, a P133 running Linux and NT and an old 486sx running
W95. When I connected to my ISP using NT, everything was fine because I
already had a nifty program that did the magic (in case you ask, it's
WinGate 1.x) and relayed mail (both smtp and pop3), nntp, ftp and http
coming from my other PC to my ISP, thus allowing me to use both systems
freely. If I used Linux, my brother and my father were not able to get their
mail using the other PC, because Linux lacked a program to relay POP3
connections (for other protocols, I use TIS' FWTK).

To make a long story short, I decided that I could do it and in about two
weeks I put this little creature together. I now use it quite regularly and
it seems to be even faster than its NT counterpart (no wonder, you say? ;-)



Compiling the proxy:
--------------------

Running 'make'with no parameters will build the executable and nothing else;
running 'make install' will also copy the program to /usr/sbin and the docs
to /usr/doc/pop3wgd. Different directories may be specified by editing the
Makefile.

The program is known to compile and run on the following OS:
- Linux/i386 2.0.30
- FreeBSD 2.2.1R



INSTALLATION:		(READ CAREFULLY)
-------------

First of all, you must be root to be able to install this software, since it
runs directly off inetd. VERY BIG WARNING: it will not run in stand-alone
mode, it really needs inetd, so do not even try to do that.

To tell inetd about this proxy, add a line like:

	pop-3   stream   tcp   nowait   nobody   /usr/sbin/tcpd in.pop3gwd

to /etc/inetd.conf, then signal it to reread the setup with:

kill -HUP `cat /var/run/inetd.pid`
(or find out the pid with ps, then use kill)

If you also run a real POP3 server on the same host, than you must choose a
different port for the proxy, this way, for example:

	pop-3gw   stream   tcp   nowait   nobody   /usr/sbin/tcpd in.pop3gwd

in /etc/inetd.conf and

	pop-3gw   1110/tcp

in /etc/services; it is not relevant whether you call the new service
'pop3-gw' or 'foobar', so long as you use the same name consistently in both
files. It is better to avoid changing the server's port number, as this is
quite likely to wreck havoc with many a user's setup.

The program currently recognizes the following command-line options:

	- the letter 'd' and a punctuation character, such as '#' or '@';
	this is the delimiter used by the proxy to parse the mangled
	username/hostname string. See later for details.

	- the letter 't' and an integer; sets the timeout for all network
	read/write operations (value is in seconds).

	- the letter 'p' and an integer; sets the port number the proxy
	will use when connecting to the POP3 server. You only need this
	option if your server does not use the standard POP3 port, 110.

No blanks are allowed between the option identifier and its value; this
program makes ample use of KISS(tm) technology, so please bear with me for
the way command-line options have to be formatted in order to be understood
by the option parser.



Setting up clients:
-------------------

For clients to be able to use the proxy, a few changes to their setups are
needed; let's assume the configuration is the following:

	POP3 username:	johndoe
	POP3 server:	fbi.gov

If the host running the proxy is called, for example, 'gatekeeper', then you
have to change the setup to read:

	POP3 username:	johndoe#fbi.gov
	POP3 server:	gatekeeper

Get the idea? The new username is a combination of the old username and
server name fields, with a special separator between them; it is possible,
should the need arise, to change the character used as a delimiter, but
great care should be taken in doing so, since all characters that may
legitimately appear in a username or in a hostname should not be used at all.
See the previous section for details on how to change the delimiter.

More advanced users may wish to know that this program supports the chaining of
proxies, by parsing the combined user/server string backwards; again, an
example should clarify the correct usage.

Assuming the same initial setup as before, now imagine that there are two
proxies that must be traversed, the second being 'keymaster'. In this case,
the new setup is:

	POP3 username:	johndoe#fbi.gov#keymaster
	POP3 server:	gatekeeper



Thanks to:
----------

- Trusted Information Systems, for producing FWTK, a great tool for 
	creating firewalls: it has served as an example of how to do 
	certain things (sometimes also how not to ;-).
- Valerio Paolini <paolini@cs.unibo.it>, for his many suggestions
	during design phase.
- Shun-Jee Liu <liu@hermes.com.tw>, for reporting the first buglet (see
	HISTORY for details)
- Adrian Pavlykevych <pam@polynet.lviv.ua>, for reporting the second one
	(again, see HISTORY) and for some BSD patches.



Reporting bugs...
-----------------

Every program, perhaps with the exception of "Hello, world", has a few bugs,
nobody can help it. If you happen to be so, ehr, lucky to spot one, please
try to get as much information as possible about it, including your setup,
and report it to me. See later for info on how to get in touch with me.

Great care, however, has been put in avoiding the infamous buffer overrun
problems that have plagued all security-related software almost since the
Epoch.

One thing I'm sure it is not adequate is this documentation and I'll try to
make it more complete in a future version.



Contacting the author:
----------------------

I have two addresses that I use regularly:

- bab0069@iperbole.bologna.it	(home)
- borgia@cs.unibo.it		(University)

Generally, I tend to read my home mail more often and answer more quickly
than on my university account, so please use the first one; in case of
trouble, sending your mail to both addresses should do the job.

You may download the latest version of this software from my home page, at
the following URL:
			http://caristudenti.cs.unibo.it/~borgia/


IMPORTANT: If you like this little program, please send me a postcard of
your city, I'd love that. My snail mail address is:

	Mr. Andrea Borgia
	via B. Marcello, 28/b
	40141 Bologna (BO)
	ITALY

