218 lines
8.7 KiB
Plaintext
218 lines
8.7 KiB
Plaintext
E-MailRelay User Guide
|
|
======================
|
|
|
|
What is it?
|
|
-----------
|
|
E-MailRelay is a simple store-and-forward e-mail transfer agent. It's a program
|
|
which runs in the background and accepts e-mail from front-ends (KMail, Outlook,
|
|
Netscape etc.), stores the messages on the hard disk, and when next connected
|
|
to the Internet forwards them to a downstream SMTP server for onward delivery.
|
|
|
|
The E-MailRelay program ("emailrelay") can run in two main modes: a storage
|
|
daemon, or a forwarding agent. As a storage daemon it waits for connections
|
|
from your e-mail front-end and stores the mail which it receives in a spool
|
|
directory. As a forwarding agent it pulls messages out of the spool directory
|
|
and passes them on to a remote server -- typically an ISP mail server.
|
|
|
|
E-MailRelay uses the Simple Message Transfer Protocol (SMTP). When running as a
|
|
storage daemon it acts as an SMTP server, and when running as a forwarding
|
|
agent it acts as an SMTP client.
|
|
|
|
The program can also run as a proxy server. In this mode e-mails submitted at
|
|
the server interface are passed on to the dowstream server immediately, without
|
|
spooling. This can be useful when combined with mail pre-processing to do things
|
|
like encryption, message archiving, addition of digital signatures, etc.
|
|
|
|
E-MailRelay runs on GNU/Linux, FreeBSD, Solaris and Windows.
|
|
|
|
What it's not
|
|
-------------
|
|
E-MailRelay does not get involved in processing incoming e-mail messages; it
|
|
only operates on outgoing messages. Incoming e-mail messages will probably be
|
|
retrieved from your ISP by your e-mail front-end program, using the POP3 or
|
|
IMAP protocols.
|
|
|
|
E-MailRelay is not a routing MTA. It is designed to be used in situations where
|
|
all outgoing e-mail message go out to the Internet, so it is not an appropriate
|
|
choice if you send e-mail to other people who use the same machine or to people
|
|
who are on the same local area network.
|
|
|
|
Why use it?
|
|
-----------
|
|
The motivation for developing E-MailRelay is that e-mail store-and-forward
|
|
using SMTP is conceptually a very simple thing, but most popular MTAs are
|
|
complex. E-MailRelay just stores messages and then forwards them on to your
|
|
ISP, whereas a fully-featured MTA does clever things with address re-writing,
|
|
message routing, local delivery, loop detection, fancy DNS lookups etc.
|
|
|
|
In particular the configuration of some popular MTAs is notoriously complex
|
|
and arcane, whereas the only thing the E-MailRelay system needs is the name of
|
|
your ISP's mail server.
|
|
|
|
Even with the move away from dial-up Internet connections a simple
|
|
store-and-forward MTA like E-MailRelay may still be useful for mobile computers
|
|
and PDAs which need to store mail while away from the network.
|
|
|
|
E-MailRelay can also pre-process the e-mail messages which pass through it. This
|
|
could be used to compensate for features, such as encryption, which are not
|
|
available in your e-mail client program, or it could be used to enforce
|
|
formatting or legal requirements for all outgoing mail.
|
|
|
|
Running E-MailRelay
|
|
-------------------
|
|
To run E-MailRelay as a storage daemon use the command:
|
|
|
|
emailrelay --as-server
|
|
|
|
To run E-MailRelay as a forwarding agent (once connected to the Internet), use
|
|
a command like this:
|
|
|
|
emailrelay --as-client mail.myisp.net:smtp
|
|
|
|
where "mail.myisp.net" is replaced with the name of your ISP's SMTP server.
|
|
|
|
To run E-MailRelay as a personal proxy server (on port 10025) to the system's
|
|
default MTA use a command something like this:
|
|
|
|
emailrelay --as-proxy localhost:smtp --no-syslog --port 10025 --filter ${HOME}/.emailrelay/mailfilter --spool-dir ${HOME}/.emailrelay/spool
|
|
|
|
where "mailfilter" is a program which you have written to do the appropriate
|
|
mail processing.
|
|
|
|
For more information on the command-line options refer to the reference guide
|
|
or run:
|
|
|
|
emailrelay --help
|
|
|
|
Starting the daemon at boot-time
|
|
--------------------------------
|
|
The standard installation of E-MailRelay (using "make install") puts most of
|
|
the files into the right places, but it does not set things up so that the
|
|
daemon starts at boot time, or that e-mail gets forwarded automatically when
|
|
you connect to the Internet. You have to do those bits yourself because of the
|
|
differences between the various GNU/Linux distributions.
|
|
|
|
Many systems, including the most popular GNU/Linux distributions, use the
|
|
System-V mechanism for starting daemons at boot time. The directory
|
|
"/etc/init.d" (or "/sbin/init.d") contains a start/stop script for each daemon
|
|
process, and then symbolic links in the "rc<N>.d" subdirectories control which
|
|
scripts are run when entering or leaving a particular run-level (<N>). The
|
|
links point back into the start/stop script in the parent directory, using a
|
|
"S" prefix for the starting link, and a "K" prefix for the stopping link. The
|
|
numeric part of the link name determines the order in which the links are
|
|
called.
|
|
|
|
Before you start you will need to know where your "init.d" directory can be
|
|
found and what your default run level is:
|
|
|
|
$ ls -d /*/init.d
|
|
$ runlevel | awk '{print $2}'
|
|
|
|
Assuming these are "/etc/init.d" and "5" you should (as root) copy the
|
|
E-MailRelay start/stop script into "/etc/init.d":
|
|
|
|
$ cp /usr/local/libexec/emailrelay.sh /etc/init.d
|
|
|
|
Then determine an appropriate numeric value for the link names by looking at
|
|
the "sendmail" links:
|
|
|
|
$ cd /etc/init.d/rc5.d
|
|
$ ls *sendmail*
|
|
|
|
Assuming sendmail links are "S10sendmail" and "K10sendmail", create
|
|
the "emailrelay" links in the same format:
|
|
|
|
$ cd /etc/init.d/rc5.d
|
|
$ ln -s ../emailrelay.sh S10emailrelay
|
|
$ ln -s ../emailrelay.sh K10emailrelay
|
|
|
|
And finally remove sendmail from the run-level (otherwise both
|
|
daemons compete for the standard SMTP listening port):
|
|
|
|
$ cd /etc/init.d/rc5.d
|
|
$ rm *sendmail
|
|
|
|
(There are also KDE and GNOME GUIs which you can use to do the latter steps.)
|
|
|
|
Triggering onward delivery
|
|
--------------------------
|
|
This section assumes that you are using "pppd" to establish your dial-up
|
|
Internet connection. (Note that KDE's "kppp" and Red Hat's "rp3" are graphical
|
|
front-ends to the underlying "pppd" daemon.)
|
|
|
|
The 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 grub around
|
|
inside "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
|
|
"ip-up.local" script:
|
|
|
|
$ cd /etc/ppp
|
|
$ cat << EOF > ip-up.local
|
|
#!/bin/sh
|
|
exec /usr/local/sbin/emailrelay --as-client <myisp>:smtp
|
|
EOF
|
|
$ chmod +x ip-up.local
|
|
|
|
Notification of failed e-mails
|
|
------------------------------
|
|
If e-mail messages become corrupted or inaccessible within the spool directory
|
|
then they will get failed within the E-MailRelay system. In order to get failed
|
|
e-mails to 'bounce' back into your in-tray you will need to run the
|
|
"emailrelay-notify.sh" script periodically. Note that this script requires
|
|
that you have "procmail" installed on your system to act as a "delivery agent".
|
|
|
|
There are not many ways in which an e-mail can fail within the E-MailRelay
|
|
system. If everything is set up correctly then perhaps the most likely case is
|
|
that you have run out of disk space. If you are not too worried about getting
|
|
failed mail to bounce, or if you do not have a suitable delivery agent, then
|
|
a simple check in your ".profile" script for "*.bad" files in the spool
|
|
directory may be sufficient:
|
|
|
|
$ cat <<EOF >> ~/.profile
|
|
if test -f /usr/local/var/spool/emailrelay/*.envelope.bad ; then echo Failed mail >&2 ; fi
|
|
EOF
|
|
|
|
|
|
Glossary
|
|
--------
|
|
|
|
# ISP
|
|
Internet Service Provider.
|
|
|
|
# MTA
|
|
Message Transfer Agent. Something which accepts incoming e-mail messages
|
|
and passes them on either to a local user, or to another MTA. A sophisticated
|
|
MTA program, which is widely used on the Internet, is "sendmail".
|
|
|
|
# SMTP
|
|
Simple Message Transfer Protocol. A set of rules which dictate how
|
|
e-mail messages are passed from one part of the e-mail system to the next.
|
|
The protocol rules are set out in the document "RFC2821".
|
|
|
|
# POP3
|
|
Post Office Protocol 3. A protocol for fetching incoming e-mail messages.
|
|
Many e-mail front-ends will fetch messages directly from an ISP using the POP
|
|
protocol, or a program like "fetchmail" may do it on their behalf.
|
|
|
|
# IMAP
|
|
Internet Message Access Protocol. A newer alternative to POP3.
|
|
|
|
# PPP
|
|
Point to Point Protocol. A low-level protocol used in dial-up connections
|
|
to an ISP. Usually implemented by the "pppd" program on GNU/Linux.
|
|
|
|
|
|
|
|
Copyright (C) 2001 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved.
|