emailrelay/doc/userguide.txt

E-MailRelay User Guide
======================

What is it?
-----------
E-MailRelay is a simple store-and-forward message transfer agent and proxy
server. It runs on Unix-like operating systems (including Linux), and on
Windows.

When used as proxy server the E-MailRelay program ("emailrelay") runs in the
background and accepts e-mail from local e-mail client programs (KMail, Outlook
etc.) or from the outside world, using the SMTP protocol. As soon as an e-mail
message is received it is forwarded on to the next SMTP server for onward
delivery. This becomes more useful when you add in your own message processing:
as each message is received it can be passed one of your programs for editing,
filtering, encrypting etc.

When used as a store-and-forward transfer agent E-MailRelay runs in two modes:
the storage daemon part, and the forwarding agent. The storage daemon
waits for incoming mail and stores anything it receives in a spool directory.
As a forwarding agent E-MailRelay pulls messages out of the spool directory
and passes them on to a remote server -- perhaps your ISP mail server.

E-MailRelay can also run as a POP3 server so that e-mail client programs can
read the spooled messages.

What it's not
-------------
E-MailRelay is not a routing MTA. It forwards e-mail to a pre-configured SMTP
server, regardless of any message addressing or DNS redirects.

E-MailRelay is not a delivery agent. Some programs like "fetchmail" send
locally-addressed e-mail to the local SMTP server in order to deliver them to
local system mailboxes. E-MailRelay will not normally do this.

Why use it?
-----------
E-MailRelay is a simple tool that does SMTP. For simple tasks it is likely
to be easier to understand and configure than a more general purpose MTA.

E-MailRelay is designed to be policy-free, so that you can implement your own
policies for message retries, bounces, local mailbox delivery, spam filtering
etc. through external scripts.

It has no dependencies on third-party libraries or run-time environments so it
is easy to build and install, and the single-threaded, event-driven design with
non-blocking i/o may provide better performance and resource usage than some of
the alternatives.

Typical applications of E-MailRelay include:
* spam filtering and virus checking incoming mail
* adding digital signatures or legal disclaimers to outgoing mail
* doing store-and-forward for outgoing mail across a dial-up Internet connection
* adding authentication where the existing infrastructure does not support it
* simple SMTP proxying on a firewall host or DMZ
* SMTP to POP gateway

Running E-MailRelay
-------------------
To use E-MailRelay in store-and-forward mode use the "--as-server" switch to
start the storage daemon in the background, and then trigger delivery of spooled
messages by running with the "--as-client" switch and the address of the target
host.

For example, to start a storage daemon listening on port 10025 use a command like
this:

	emailrelay --as-server --port 10025 --spool-dir /tmp

And then to forward the spooled mail to "smarthost" run something like this:

	emailrelay --as-client smarthost:smtp --spool-dir /tmp

To get behaviour more like a proxy you can add the "--poll" switch so that
messages are forwarded continuously rather than on-demand. This example starts a
store-and-forward server that forwards spooled-up e-mail every hour:

	emailrelay --as-server --poll 3600 --forward-to smarthost:smtp

For a proxy server that forwards each message as it is being received, without
any delay, you can use the "--as-proxy" mode:

	emailrelay --as-proxy smarthost:smtp

If you want to edit or filter e-mail as it passes through the proxy then specify
your pre-processor program with the "--filter" switch, something like this:

	emailrelay --as-proxy smarthost:smtp --filter /usr/local/bin/addsig

To run E-MailRelay as a POP server without SMTP use "--pop" and "--no-smtp":

	emailrelay --pop --no-smtp --log --close-stderr

The "emailrelay-submit" utility can be used to put messages straight into the
spool directory so that the POP clients can fetch them.

Note that by default E-MailRelay will always reject connections from remote
machines. To allow connections from anywhere use the "--remote-clients" switch,
but please consider the implications if your machine is connected to the
internet.

For more information on the command-line options refer to the reference guide
or run:

	emailrelay --help --verbose

Configuration
-------------
The "emailrelay" program itself is mostly configured through command-line
switches (such as "--port" and "--forward-to"), so there is no single
definitive configuration file.

However, in most installations on Unix-like system the E-MailRelay server will
be started up by the boot-time script called "emailrelay" in the "/etc/init.d"
directory, and this script uses the configuration file "/etc/emailrelay.conf" to
define the server command-line. Each entry in the configuration file corresponds
to an E-MailRelay command-line switch, so you can edit this file to add and
remove server switches. Refer to the reference guide for a complete list of
configuration switches.

On Windows the installation program creates a startup batch file called
"emailrelay-start.bat" that contains all the server command-line switches and
you can edit this file to tailor the server configuration. You can also set up
your own shortcuts to the E-MailRelay executable and add and remove command-line
switches using the shortcut properties tab.

If you are using authentication then you will have to create the text files
containing your authentication secrets (passwords and password hashes). The
"--server-auth", "--client-auth" and "--pop-auth" command-line switches are used
to point to these files.

There is also a graphical configuration program called "emailrelay-gui" that
may be available to help with configuring the system. This is intended to be
used once at installation time (and it is the basis of the self-extracting
installer on Windows) but it may also be used to do some simple reconfiguration
of an alreay-installed system.

Logging
-------
If the "--log" switch is used then E-MailRelay program issues warnings and error
messages to the "syslog" system using the "LOG_MAIL" facility. Under Windows it
writes to the "Application" event log.

The "syslog" system is configured through the "/etc/syslog.conf" file (try
"man syslog.conf"), and in most cases you will find that "LOG_MAIL" warnings and
errors are directed to an appropriate log file (perhaps "/var/log/messages").

For more verbose logging add the "--verbose" switch. If this becomes difficult
to read via the system log (especially on Windows) then try logging to the
standard error stream and redirect that to a file. Bear in mind that you will
need have to replace "--as-server" with "--log" and "--as-proxy" with
"--immediate --forward-to" since the "--as-server" and "--as-proxy" switches
implicitly close the standard error stream soon after startup.

	emailrelay --log --verbose > emailrelay.log 2>&1

Troubleshooting
---------------
A useful technique for troubleshooting SMTP problems is to telnet into the
remote server and drive the SMTP protocol manually. Telnet can be told to
connect to the remote SMTP port by putting the port number (25) on the command
line after the remote hostname, for example: "telnet smtp.myisp.net 25".

Once connected you should get a startup banner from the server, which may tell
you what server software you have connected to. From there you should type
something like "EHLO myhost.mydomain". The response to the EHLO command should
contain a list of SMTP extensions which the server software supports. If this
includes the AUTH extension then the set of supported authentication mechanisms
(such as LOGIN, CRAM-MD5 etc.) will be listed on the same line.

After the EHLO response you should type "MAIL FROM:<myhost.mydomain>", retaining
the angle brackets but substituting your own address. If this is accepted then
enter a "RCPT TO:<me@myhost.mydomain>" command to say where the e-mail is going.
(Again, retain the angle brackets but substitute an appropriate address.)

After one or more "RCPT TO" commands you should enter the "DATA" command,
followed by the message content. The message content should include an RFC822
header, followed by a blank line, followed by the message text. For testing
purposes you might get away without having any header/body structure at all, but
to do things properly you should have at least a "To:" line, a "From:" line and
a "Subject:" line in the header.

At the end of the message text type a "." on a line of its own. At that point
the message should get dispatched, and eventually end up in your in-box in the
usual way (assuming you put your own address in the "RCPT TO" command).

The following is an example SMTP dialogue, with ">>" and "<<" marks added to
show what was typed and what was received:
	>> telnet smtp.myisp.net 25
	<< Trying 12.34.56.78...
	<< Connected to smtp.myisp.net.
	<< Escape character is '^]'.
	<< 220 mail12.myisp.net ESMTP Exim 3.13 #0 Sat, 17 Nov 2001 16:22:39 +0000
	>> EHLO myhost.myisp.net
	<< 250-mail12.myisp.net Hello modem-185.myisp.net [12.34.56.78]
	<< 250-SIZE 104857600
	<< 250-PIPELINING
	<< 250 HELP
	>> MAIL FROM:<me@myhost.myisp.net>
	<< 250 <me@myhost.myisp.net> is syntactically correct
	>> RCPT TO:<me@myhost.myisp.net>
	<< 250 <me@myhost.myisp.net> verified
	>> DATA
	<< 354 Enter message, ending with "." on a line by itself
	>> To: me@myhost.myisp.net
	>> From: me@myhost.myisp.net
	>> Subject: test
	>>
	>> Test message.
	>> .
	<< 250 OK id=1658Fp-0000Il-00
	>> QUIT
	<< 221 mail12.myisp.net closing connection
	<< Connection closed by foreign host.

If you get some sort of "access denied" errors when talking to a server which
does not support the AUTH extension, then your ISP may be using POP-before-SMTP
authentication. In this scheme you are required to conduct an authenticated POP
or IMAP dialogue before you try to use SMTP. The POP/IMAP dialogue is done
separately from the SMTP connection, but bear in mind that there might be a time
limit so that your SMTP connection has to be made soon after the POP/IMAP
authentication. You should be able to use an e-mail client program, or something
like "fetchmail" to do the POP/IMAP authentication.

If you can send mail messages sucessfully using telnet, then you should look at
the E-MailRelay "--verbose" log output and compare what you do interactively
with what the program does.

Preventing open mail relay
--------------------------
If you are running E-MailRelay as a server with a permanent connection to the
Internet it is important to prevent open mail relay because this can be
exploited by spammers. By default open mail relaying is not possible because
E-MailRelay does not accept IP connections from remote clients. However, if you
use the "--remote-clients" switch then you need to be more careful.

If the only required access to the E-MailRelay server is from a local network
and not from the Internet then you can use the "--interface" switch to listen
for incoming connections only on the local network interface. You should also
use a firewall in this scenario.

Another option is to require all clients to authenticate by using the
"--server-auth" switch. If you then need local clients, such as your own e-mail
client program, to connect without authentication then you must put those
trusted IP addresses in the secrets file with an authentication mechanism of
"NONE". Refer to the reference guide for more information.

Taking it one stage further, you may want to allow connections from the Internet
without authentication but only allow them to send mail to local users. In other
words you want to allow anyone to deliver e-mail to your system but not allow
them to spam someone else. You can do this by requiring authentication with the
"--server-auth" switch, then exempt everyone from mandatory authentication with
"NONE server *.*.*.* x" line in the secrets file, and finally have an address
verifier script ("--verifier") which rejects remote recipient addresses if the
client has not authenticated. Again, refer to the reference guide for further
details.

Running as a POP server
-----------------------
E-MailRelay can run as a POP server so that e-mail client programs can retrieve
messages from the spool directory directly (although it is not a good idea to
run E-MailRelay as a POP server if also forwarding messages by SMTP).

To allow POP access to spooled messages use a command-line something like this:

	emailrelay --as-server --pop --pop-auth /etc/emailrelay.auth

You will need to create the authentication secrets file ("/etc/emailrelay.auth"
in this example) containing usernames and passwords. A simple example would look
like this:

	APOP server user1 password1
	APOP server user2 password2

If you need to serve up messages to more than one POP client consider using the
"--pop-by-name" option with a "--filter" script that moves messages into the
appropriate sub-directory. The "emailrelay-filter-copy" program is designed
to be used in this way: when a message is received over SMTP it copies it
into all available sub-directories for collection by multiple POP clients.

Refer to the reference guide for more information.

Triggering delivery over dial-up
--------------------------------
If you are using E-MailRelay to store and forward e-mail over a dial-up link to
the Internet, then you will need to set things up so that the dialler tells
E-MailRelay when to start forwarding.

In most Unix-like systems a "ppp" daemon calls the script "/etc/ppp/ip-up" when
it has successfully established a dial-up link to your ISP. This script will
probably set up IP routes, update the DNS configuration, initialise a firewall,
run "fetchmail" and "sendmail", etc. It may also call out to another script,
"ip-up.local" which is available for you to put stuff into without having to
edit "ip-up" itself.

The simplest approach for editing "ip-up" is to look for a "sendmail -q" line.
If you find "sendmail -q" then it should be sufficient to replace it with this:

	emailrelay --as-client <myisp>:smtp

where you substitute your ISP's SMTP server address for <myisp>.

Or if your "ip-up" calls out to "ip-up.local" then create a two-line
"/etc/ppp/ip-up.local" script like this:

	#!/bin/sh
	exec /usr/local/sbin/emailrelay --as-client <myisp>:smtp

If you create "ip-up.local" yourself remember to make it executable.

Notification of failed e-mails
------------------------------
If e-mail messages cannot be forwarded by the E-MailRelay system then the
envelope files in the spool directory are given a ".bad" suffix. The reason for
the failure will be recorded in the envelope file itself.

You should check for ".bad" envelope files in the E-MailRelay spool directory
from time to time.

If you want failed e-mails to be retried a few times you can run the
"emailrelay-resubmit.sh" script periodically, perhaps from "cron". This script
simply removes the ".bad" suffix from files in the spool directory, as long as
they have not been retried too many times already.

If you are using E-MailRelay to forward outgoing e-mails then you can also get
failed e-mails to bounce back to your in-tray by running the
"emailrelay-notify.sh" script periodically as "root", although this does require
"procmail" to act as a delivery agent.

Polling and timeouts
--------------------
In normal proxy mode, using "--immediate" or "--as-proxy", the E-MailRelay
server will try forward each message as soon as it is received and only then
will it acknowledge receipt of the message back to the submitting client. This
has the advantage that any problems with the forwarding process can be reported
back to the submitting client; any failures should be reported your e-mail
client program and the failed messages should stay in its "outbox".

However, some e-mail client programs are not always prepared to wait long enough
for the message to be forwarded and this can result in problems with timeouts. A
good fix for this is to use the "--poll" mechanism as a replacement for
"--immediate"/"--as-proxy". In this way the submitting e-mail client program
does not have to wait for the E-MailRelay server to forward each message and so
it should not time out. If you have timeout problems try replacing "--immediate"
with "--poll 0" so that forwarding is done as soon as the client has finished
submitting messages.

Usage patterns
--------------
The simplest ways of using E-MailRelay for SMTP are as a proxy or as a
store-and-forward MTA, but many other configurations are possible. For example,
multiple E-MailRelay servers can run in parallel sharing the same spool directory,
or they can be chained in series to that e-mail messages get transferred
from one to the next.

Remember that messages can be introduced directly into the E-MailRelay spool
directory using the "emailrelay-submit" utility, and they can be moved out again
at any time, as long as the envelope file is not locked (ie. with a special
filename extension). Your "--filter" program can edit messages in any way you
want, and it can even remove the current message from the spool directory.

When using E-MailRelay as a POP server the "--pop-by-name" feature can be used
to serve up different spooled messages according to the username that the client
authenticated with: each user's messages are taken from their own sub-directory
of the main spool directory. If messages are coming in over SMTP then you could
install an SMTP "--filter" script to move each new message into the relevant
sub-directory based on the message addressing.

For more ideas check out the "--client-filter" and "--poll" switches, and don't
overlook the administration and control interface ("--admin") which you can use
to receive notification of message arrival or force message forwarding at any
time.

SpamAssassin
------------
The E-MailRelay server can use *SpamAssassin* [http://spamassassin.apache.org]
to mark or reject potential spam.

To get E-MailRelay to reject spam outright you can just use "spamassassin -e" as
your E-MailRelay "--filter" program:

	emailrelay --as-server --filter "/usr/bin/spamassassin --exit-code"

Or on Windows:

	emailrelay --as-server --filter "c:/Program\ Files/perl/site/bin/spamassassin.bat --exit-code"

To get spam messages identified by SpamAssassin but still pass through the
E-MailRelay system you will have to have a small "--filter" script to collect
the output from the "spamassassin" program and write it back into the
E-MailRelay content file.

Your "--filter" shell script could look something like this:

	#!/bin/sh
	spamassassin "$1" > "$1.tmp"
	mv "$1.tmp" "$1"
	exit 0

Or an equivalent batch script on Windows:

	c:\Program Files\perl\site\bin\spamassassin.bat %1 > %1.tmp
	ren %1.tmp %1
	exit 0

You may need to set the "--filter-timeout" switch to control how long
E-MailRelay waits for the spam analysis to complete.

You could also consider doing spam filtering off-line, completely independent
of any SMTP activity, by having two E-MailRelay processes chained together
working off two spool directories:

	emailrelay --as-server --spool-dir /tmp/spool-in --poll 1 --forward-to localhost:10025
	emailrelay --as-server --spool-dir /tmp/spool-out --port 10025 --filter /tmp/myspamfilter

Here the first E-MailRelay server accepts incoming mail straight into its spool
directory and it uses a "--poll" timer to independently forward spooled messages
to the second server running on port 10025. The second server runs the spam
filter as each message is received.

There is also an experimental mechanism where E-MailRelay can talk direcly to
the SpamassAssin "spamd" network deamon using a special form of the "--filter"
switch:

	emailrelay --as-server --filter spam:localhost:783

This might be useful if spam filtering is creating a bottleneck in the
E-MailRelay server.

Google mail
-----------
To send mail via Google mail's SMTP gateway you will need to create a client
secrets file containing your account details and enable TLS support in
E-MailRelay by using the "--client-tls" switch.

The secrets file should contain one line of text something like this:

	login client myname@gmail.com mypassword

Reference this file using "--client-auth" on the E-MailRelay command-line and
also add in the "--client-tls" switch:

	emailrelay --as-proxy smtp.gmail.com:587 --client-tls --client-auth /etc/emailrelay.auth ...




Copyright (C) 2001-2008 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved.