SPEY V1.0.pre2
                                  ==============

                                  Beta release
                              (C) 2011 David Given
                                   2011-08-26

INTRODUCTION
============

Spey is a smart SMTP proxy whose main function in life is to block spam by
implementing greylisting. Greylisting is a really simple but effective way of
determining which messages are real and which aren't by relying on the fact
that spammers can't usually afford to run real mail servers; see:

	http://projects.puremagic.com/greylisting/

...for more information.

Spey uses the Sqlite library to keep track of which addresses its seen before,
so you'll need that before you can use it.


IF YOU'VE USED SPEY BEFORE
==========================

The database files used by 1.0 are NOT compatible with those used by 0.4. If
you're upgrading from 0.4 or earlier, you will have to delete the database
and recreate it using speyctl (the new speyctl that comes with 1.0, of course).
If you try to run spey with an old configuration file... well, on your own
head be it.


INSTALLATION
============

spey uses Prime Mover (http://primemover.sf.net) as its build system. You will
need to configure the pmfile. Load it into an editor and follow the
instructions; there is very little that will need changing (nothing, if you're
 on Debian).
  
Then, simply do:

  ./pm install
  
spey will build and install to the location you specified in the pmfile.
(If you specified a location that needs to be written to as root,
you will need to use sudo. If you don't like building things as root, you can
build and install in two stages by doing "./pm; ./pm install").

It is now ready to use.

If you want to start spey from init, the install procedure will have placed
an LSB-compliant script in $IPREFIX/share/doc/spey/init.d/spey; you can copy
this into /etc/init.d. (If you're not on an LSB system and can't use the
script, let me know and I'll put back the old, non-LSB one. I don't know of
any inits these days which use init scripts like this which *aren't* LSB, but
that doesn't mean there aren't any.)

All the code should, ideally, use standard Posix and C++ features. There might
be some Linuxisms or gccisms that have crept in; if you find any, these are
bugs, so please inform me.


REQUIREMENTS
============

- IPv4. Due to the way spey handles IP address internally, it will *only*
  work on 32-bit IPv4 addresses. I currently have no intention of changing
  this (as it would require totally changing all the code and starting again
  from scratch). Sorry.
  
- sqlite, version 2.8.13 or compatible.  Note that libsqlite 3.0 is
  *unsupported*. If you can get it to work, great (and please tell me). But I
  recommend staying with 2.8. Note that 2.4 *does not work*.

- GNUTLS, version 1.4.4 or thereabouts (OPTIONAL). This is needed to make TLS
  connections work. If you don't care about TLS, then set the GNUTLS setting
  to false in the makefile and spey will be built without it.

Links:

    sqlite:   http://sqlite.org/
    gnutls:   http://www.gnu.org/software/gnutls/
    
Debian has all of these in the right versions (because that's where I do my
development).


CONFIGURATION
=============

Spey works by listening on one port, normally your conventional SMTP port, and
forwarding the connections to another port, where your real mail server is
listening.  If you like you can run the mail server on another machine than you
run Spey; Spey itself doesn't care.

I'm assuming that you've reconfigured your mail server to listen on the address
localhost:2525 and that it's happy to receive mail from localhost.

Step 0
------

By default, spey drops root privileges after startup. To do this, you need
to create a user and group called "spey" and "spey". You don't have to do
this, but these instructions assume that you are (because it's a good idea).
If you're happy with running as root, then see "runtime-user-id" in the
spey(8) man page to switch this feature off.

Step 1
------

You need to configure Spey. Spey stores all its configuration information in
its database, which by default lives in /var/lib/spey/spey.db. You need to
create this before you can do anything. You can do this with these commands:

	mkdir -p /var/lib/spey
	chown spey.spey /var/lib/spey
	speyctl init

There are two things you need to do at minimum to configure spey. Firstly, you
need to tell spey who to announce itself as in the SMTP banner. (In practice
this isn't necessary, but the RFC requires it, and it's considered polite.) You
do it like this:

	speyctl set identity 'mydomain.com'

Secondly, you need to tell spey who it is going to be receiving mail from. Most
users will want to do this:

	speyctl recipient add '@mydomain.com'
	speyctl trust add '127.0.0.1/32'

This tells spey to accept all mail to any address at mydomain.com; and to relay
any mail being sent from the local machine. See the spey(8) man page for more
information.

Step 2
------

Now all you need to do is to run Spey itself. As superuser, do this:

	spey -f 0.0.0.0:25 -t localhost:2525 -v 999

Spey will start up, with maximum logging to syslog's 'mail' channel, listening
on all interfaces on port 25 and connecting to localhost:2525 (your real
mail server).

Step 3
------

Test it!

Try sending some mail to your machine. If your machine is connected to the
'net, you'll probably be getting spam coming in. You should see copious amounts
of tracing appear detailing exactly what's happening.

After it's been running for a while, you can do:

	speyctl showdb
or	speyctl stats

...to show information about the database.

Step 4
------

You need to set up a cron job or some other way of periodically running the
command:

	speyctl purge

This will clear out stale entries from the database. If you don't do this, then
the database will grow unboundedly as Spey keeps track of every single piece of
spam you ever retrieve from a billion and one throwaway email addresses... and
while this won't do any harm, and indeed you might want to keep it as a record
(and it won't even slow Spey down much thanks to the magic of Sqlite), it is a
bit of a waste of space.

If you want to do this from cron, the install procedure will have placed
a suitable script in $IPREFIX/share/doc/spey/cron.d/spey; you can copy this
into /etc/cron.daily.



DOCUMENTATION
=============

Man pages are provided; see spey(8) and speyctl(8). They contain useful
information. While I'm completely happy to answer any queries people may have,
it might be noted that most of my replies usually end in 'see the spey man
page for more information'...


BUGS
====

What, you want to know about them *all*? That's a big job...

These are the ones I know about and think are significant:

* If spey cannot write to its database, it has a tendency to crash. The fix for
  this could well just be to refuse to start up if the database is read only.
  
* If the database schema changes, for example if you add or remove a table,
  spey will crash cleanly (i.e. unexpectedly shut down). Playing with the
  schema is not recommended.
  
* If you change a configuration setting, it will take effect when the next
  client connects to spey; but when this happens, the changes will affect all
  existing connections. This is sub-optimal and potentially confusing.


DISCLAIMER
==========

Spey is FREE SOFTWARE!

It is NOT RELIABLE!

DO NOT USE IT for mission-critical data because IT WILL LOST YOUR MAIL!

If it goes wrong DO NOT BLAME ME because YOU HAVE BEEN WARNED!

(It hasn't yet for me, but that's no guarantee.)

I have attempted to write it with robustness and security in mind --- for
example, there is exactly one place where it does explicit dynamic memory
allocation, which means it has no buffers to overflow --- but I'm new at this,
okay?


LEGAL STUFF
===========

Spey is (C) 2004-2011 David Given. It is distributable under the conditions
laid out by the GNU Public License, version 2 only (and explicitly not version
3). You can find a copy of this license in the file COPYING.


REVISION HISTORY
================

Spey 1.0.pre2: 2011-08-45: Fixed a bug where on some versions of GNUTLS the
connection would hang immediately after handshake. Also, now if TLS is compiled
in but not enabled the STARTTLS command is rejected rather than being passed
to the downstream server (which doesn't work).

Spey 1.0.pre1: 2011-01-25: Reengineered speyctl to be part of the spey binary
to avoid the nasty mawk dependency. Fix serious bug where dropping root
privileges wasn't working properly (thanks to Achim Latz for this). Corrected
bugs in TLS certificate handling and compilation on 64-bit systems. Several
documentation updates and improvements. Added the LSB init script and cron
script.

Spey 0.5.pre1: 2008-11-09: Added external auth support. Switched build system
to Prime Mover because make was getting just too annoying. Fixed a few nasty
race condition issues. Assorted rearrangement, tidying and bugfixing.

Spey 0.4.2.1: 2007-11-06: Added a missing file to the 0.4.2 distribution that
was preventing it from building.

Spey 0.4.2: 2007-10-24: Finally fixed that horrible random-lockup-on-startup-
problem that was manifesting itself on some libc/pthread combinations. Thanks
go to Wojtek Swiatek for helping test this. Domain verification now no longer
happens on trusted or authenticated sessions (which means it will now accept
submissions from Outlook and Outlook Express, which are buggy). SSL sessions
are no longer considered automatically authenticated.

Spey 0.4.1: 2007-04-18: Fixed yet *another* random-crash-at-infrequent-
intervals (this one related to the new TLS support). Fixed an SQL injection
issue; thanks to Frederic Vander Elst for pointing this out. Fixed a number
of minor documentation issues. Fixed a race condition on threadlet destruction
that could have led to yet more random crashes. REUSEADDR is now used
correctly, so the 'connection in use' errors when restarting spey should have
gone. A few other minor tweaks.

Spey 0.4.0: 2006-10-10: Lots of new features! SMTP AUTH proxying, TLS support,
greet-pause support, RBL lookups. Lots of bugfixes and tweaks, including a
complete rewrite of the threadlet code to now use pthreads instead of ucontext,
which should make it a whole lot more portable.

Spey 0.3.3: 2005-11-08: Fixed the untraceable scheduler bug that was causing
Spey to very occasionally crash silently --- thanks to Markus Madlener for
help with this one. Fixed some other embarassing security holes; thanks to
Joshua Drake for pointing these out. Also added support for dropping root
privileges. Fixed an issue with using qmail as the internal mail server.
Documented the incompatibility with Linux 2.4 glibc.

Spey 0.3.2: 2004-11-21: Tracing now works correctly on gcc 3.3 and thereabouts;
Spey should now work on, hopefully, all versions of gcc that support a modern
iostreams implementation. Also fixed a problem where SIGPIPE would occasionally
be received, causing spey to silently shut down.

Spey 0.3.1: 2004-06-30: No longer shuts down prematurely if the downstream SMTP
server can't be contacted; added hardening against DoS attacks by flooding spey
with incoming connections. This also has the side effect of making spey a bit
more efficient in dealing with erroneous (or malicious) connections from
non-SMTP devices.

Spey 0.3.0: 2004-06-22: Added whitelist and blacklist support. Now compiles
under gcc 3.3. Several minor bugfixes.

Spey 0.2.9: 2004-05-30: Major internal rearrangements to support processing of
multiple connections at once. It should now be far more usable when dealing
with heavy loads.

Spey 0.2.1: 2004-05-19. Maintenance releasing fixing a small bug in 0.2's
speyctl.

Spey 0.2: 2004-05-15. Bug fixes, feature enhancements. Lots of stability and
performance tweaks; inetd mode; proper daemon support; decent relay checking;
rewrote speyctl in a real language.

Spey 0.1: 2004-04-28. First release.