301 lines
13 KiB
Plaintext
301 lines
13 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
|
|
|
|
|
|
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 will
|
|
probably 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 substituing 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 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 front-end 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 log output and compare what you do interactively with what
|
|
the program does. Usually when running as a server E-MailRelay logging goes to
|
|
the "syslog" system, and when running as a client it goes to the standard error
|
|
stream ("stderr"). To get the server to log onto stderr, replace the
|
|
"--as-server" command-line switch with "--log --no-syslog". Refer to the
|
|
reference guide for more information.
|
|
|
|
On Windows things are a bit more difficult because there is no syslog equivalent
|
|
on Win9x, and the standard error stream often gets lost. Starting E-MailRelay
|
|
from cygwin/bash on Win98 keeps stderr open (albeit with dreadful performance),
|
|
whereas the standard command prompt does not. If necessary the environment
|
|
variable "GLOGOUTPUT_FILE" can be defined as the name of a log file.
|
|
|
|
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.
|