336 lines
15 KiB
Plaintext
336 lines
15 KiB
Plaintext
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 Mac OS X),
|
|
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 (Thunderbird,
|
|
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 does not do routing of individual messages; it is not a routing MTA.
|
|
It forwards all e-mail messages 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.
|
|
|
|
The code has few dependencies on third-party libraries or run-time environments
|
|
so it is easy to build and install especially when targeting embedded systems.
|
|
|
|
The single-threaded, event-driven design with non-blocking i/o may provide
|
|
better performance and resource usage than some of the alternatives.
|
|
|
|
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.
|
|
|
|
Typical applications of E-MailRelay include:
|
|
* spam filtering and virus checking incoming mail
|
|
* adding digital signatures or legal disclaimers to outgoing mail
|
|
* store-and-forward for outgoing mail across an intermittent Internet connection
|
|
* adding authentication and encryption where the existing infrastructure does not support it
|
|
* taking messages in with SMTP and serving them to local POP clients
|
|
* giving multiple POP clients independent copies of incoming e-mail
|
|
* SMTP proxying by running the proxy server on the firewall host
|
|
|
|
Running E-MailRelay
|
|
-------------------
|
|
To use E-MailRelay in store-and-forward mode use the "--as-server" option to
|
|
start the storage daemon in the background, and then trigger delivery of spooled
|
|
messages by running with the "--as-client" option 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:25 --spool-dir /tmp
|
|
|
|
To get behaviour more like a proxy you can add the "--poll" option 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:25
|
|
|
|
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:25
|
|
|
|
If you want to edit or filter e-mail as it passes through the proxy then specify
|
|
your pre-processor program with the "--filter" option, something like this:
|
|
|
|
emailrelay --as-proxy smarthost:25 --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.
|
|
|
|
By default E-MailRelay will always reject connections from remote machines. To
|
|
allow connections from anywhere use the "--remote-clients" option, but please
|
|
check your firewall settings to make sure this cannot be exploited by spammers.
|
|
|
|
On Windows add "--hidden" to suppress message boxes and also add "--no-daemon"
|
|
if running as a service.
|
|
|
|
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
|
|
options (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 option, so you can edit this file to add and
|
|
remove server options. Refer to the reference guide for a complete list of
|
|
configuration options.
|
|
|
|
On Windows the installation program creates a startup batch file called
|
|
"emailrelay-start.bat" that contains all the server command-line options 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
|
|
options using the shortcut properties tab.
|
|
|
|
If you are using authentication then you will have to create the text files
|
|
containing your authentication secrets (account names, passwords and password
|
|
hashes). The "--server-auth", "--client-auth" and "--pop-auth" command-line
|
|
options 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. It takes you through a sequence of configuration
|
|
pages and then on the last page creates or updates the configuration files, ie.
|
|
the authentication secrets file and the configuration file "emailrelay.conf"
|
|
or "emailrelay-start.bat".
|
|
|
|
Logging
|
|
-------
|
|
If the "--log" option is used then E-MailRelay program issues warnings and error
|
|
messages to the "syslog" system on Unix or to the Event Viewer's Application log
|
|
on Windows.
|
|
|
|
On Unix systems you can also redirect the standard error stream to a file,
|
|
although you should note that the "--as-server" and "--as-proxy" options
|
|
implicitly close the standard error stream soon after startup, so you should
|
|
replace them with their equivalent options without the "--close-stderr" part.
|
|
|
|
On Windows you can log to a file by adding the "--log-file" option to the
|
|
command-line in the startup batch file. The installation process creates a
|
|
second startup batch file that contains this option, so check for that first.
|
|
|
|
For more verbose logging add the "--verbose" option to the command-line.
|
|
|
|
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 and get you into trouble with your ISP. 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" option 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 just set up your firewall to block incoming
|
|
connections on ports 25 (SMTP) and 110 (POP) and also use the "--interface"
|
|
option on the E-MailRelay command-line so that it only listens for incoming
|
|
connections on the local network.
|
|
|
|
If you do need to accept connections from the Internet then you should require
|
|
all clients to authenticate themselves by using the "--server-auth" option on
|
|
the E-MailRelay command-line. If you also want local clients running on your
|
|
internal network to be able to bypass this authentication then you can put those
|
|
trusted IP addresses in the E-MailRelay secrets file with an authentication
|
|
mechanism of "NONE". Refer to the reference guide for more information.
|
|
|
|
Running as a POP server
|
|
-----------------------
|
|
E-MailRelay can run as a POP server so that e-mail client programs can retrieve
|
|
messages from the E-MailRelay spool directory directly.
|
|
|
|
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 ("emailrelay.auth" in
|
|
this example) containing usernames and passwords. A simple example would look
|
|
like this:
|
|
|
|
server APOP user1 password1
|
|
server APOP user2 password2
|
|
|
|
It can sometimes be useful to serve up the same e-mail messages to multiple POP
|
|
clients. For example, you might use several e-mail clients on your local network
|
|
and you would like to see your mail on all of them equally. The "--pop-by-name"
|
|
option is intended to be used in this scenario; each e-mail client sees its own
|
|
copy of the e-mail messages, stored in its own sub-directory of the main spool
|
|
directory. The name of the sub-directory is simply the name that the client uses
|
|
to authenticate with the E-MailRelay server. You just need to create the
|
|
sub-directory for each client and then specify "emailrelay-filter-copy"
|
|
as the "--filter" program.
|
|
|
|
Refer to the reference guide for more information.
|
|
|
|
Triggering delivery over dial-up
|
|
--------------------------------
|
|
If you are using E-MailRelay on Unix to store and forward e-mail over an
|
|
intermittent link to Internet such as dial-up or wireless networking, then you
|
|
might need to set things up so that the network tells E-MailRelay when to start
|
|
forwarding e-mail.
|
|
|
|
On Linux systems you should find that there are special directories where you
|
|
can install your own hook scripts that are called whenever a dial-up or wireless
|
|
network connection is established. For dial-up this might be "/etc/ppp/ip-up.d",
|
|
and for wireless "/etc/network/if-up.d".
|
|
|
|
Just create a two-line script like this in the relevant directory:
|
|
|
|
#!/bin/sh
|
|
exec /usr/local/sbin/emailrelay --as-client=myisp.net:smtp
|
|
|
|
and make it executable using "chmod +x".
|
|
|
|
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" script periodically. 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.
|
|
|
|
Usage patterns
|
|
--------------
|
|
The simplest ways of using E-MailRelay for SMTP are as a proxy or for
|
|
store-and-forward, 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" options, 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.
|
|
|
|
On Unix your "--filter" shell script could look something like this:
|
|
|
|
#!/bin/sh
|
|
spamassassin "$1" > "$1.tmp"
|
|
mv "$1.tmp" "$1"
|
|
exit 0
|
|
|
|
On Windows an equivalent batch script would be:
|
|
|
|
c:\Program Files\perl\site\bin\spamassassin.bat %1 > %1.tmp
|
|
ren %1.tmp %1
|
|
exit 0
|
|
|
|
Or you could adapt the "emailrelay-runperl.js" example script.
|
|
|
|
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 also enable TLS/SSL support in
|
|
E-MailRelay by using the "--client-tls" option.
|
|
|
|
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" option:
|
|
|
|
emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=/etc/emailrelay.auth ...
|
|
|
|
Connection tunnelling
|
|
---------------------
|
|
E-MailRelay can send mail out via a SOCKS v4 proxy, which makes it easy to route
|
|
your mail through an encrypted tunnel using "ssh -N -D" or via the Tor
|
|
anonymising network.
|
|
|
|
For example, this will run an E-MailRelay proxy on port 1025 that routes via a
|
|
local tor server on port 9050 to the mail server at example.com:
|
|
|
|
emailrelay --port 1025 --as-proxy=example.com:25@localhost:9050 --domain=anonymous.org --connection-timeout=300
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2001-2013 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved.
|