454 lines
18 KiB
Markdown
454 lines
18 KiB
Markdown
E-MailRelay User Guide
|
|
======================
|
|
|
|
What is it?
|
|
-----------
|
|
E-MailRelay is a lightweight [SMTP][] store-and-forward mail server with [POP][] access
|
|
to spooled messages. It can be used as a personal internet mail server with
|
|
SpamAssassin spam filtering and [DNSBL][] connection blocking. Forwarding can be
|
|
to a fixed smarthost or using DNS MX routing. External scripts can be used for
|
|
address validation and e-mail message processing.
|
|
|
|
|
|
|
|
E-MailRelay runs as a single process using the same non-blocking i/o model as
|
|
Squid and nginx giving excellent scalability and resource usage.
|
|
|
|
The code has few dependencies on third-party libraries or run-time environments
|
|
so it is easy to build and install.
|
|
|
|
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.
|
|
|
|
Basic operation
|
|
---------------
|
|
E-MailRelay can be run straight from the command-line, and on Windows you can
|
|
run `emailrelay.exe` or `emailrelay-textmode.exe` from the zip file without
|
|
going through the installation process.
|
|
|
|
To use E-MailRelay in store-and-forward mode use the `--as-server` option to
|
|
start the storage daemon in the background, and then do delivery of spooled
|
|
messages by running with `--as-client`.
|
|
|
|
|
|
|
|
For example, to start a storage daemon in the background listening on port 10025
|
|
use a command like this:
|
|
|
|
emailrelay --as-server --port 10025 --spool-dir /tmp
|
|
|
|
On Windows use `c:/temp` for testing, rather than `/tmp`.
|
|
|
|
Or to run it in the foreground:
|
|
|
|
emailrelay --log --no-daemon --port 10025 --spool-dir /tmp
|
|
|
|
And then to forward the spooled mail to `smtp.example.com` run something
|
|
like this:
|
|
|
|
emailrelay --as-client smtp.example.com:25 --spool-dir /tmp
|
|
|
|
To forward continuously you can add the `--poll` and `--forward-to` options to
|
|
the server command-line:
|
|
|
|
|
|
|
|
For example, this starts a server that also forwards spooled-up e-mail every
|
|
minute:
|
|
|
|
emailrelay --as-server --poll 60 --forward-to smtp.example.com:25
|
|
|
|
Or for a server that forwards each message as soon as it has been received, you
|
|
can use `--forward-on-disconnect`:
|
|
|
|
emailrelay --as-server --forward-on-disconnect --forward-to smtp.example.com:25
|
|
|
|
To edit or filter e-mail as it passes through the server specify your filter
|
|
program with the `--filter` option, something like this:
|
|
|
|
emailrelay --as-server --filter /tmp/set-from.js
|
|
|
|
Look for example filter scripts in the `examples` directory.
|
|
|
|
E-MailRelay can also be used as a personal internet mail server:
|
|
|
|
|
|
|
|
Use `--remote-clients` (`-r`) to allow connections from outside the local
|
|
network, define your domain name with `--domain` and use an address verifier as
|
|
a first line of defense against spammers:
|
|
|
|
emailrelay --as-server -v -r --domain=example.com --address-verifier=account:
|
|
|
|
Then enable POP access to the incoming e-mails with `--pop`, `--pop-port` and
|
|
`--pop-auth`:
|
|
|
|
emailrelay ... --pop --pop-port 10110 --pop-auth /etc/emailrelay.auth
|
|
|
|
Set up the POP account with a user-id and password in the `--pop-auth` secrets
|
|
file. The secrets file should contain a single line of text like this:
|
|
|
|
server plain <userid> <password>
|
|
|
|
For more information on the command-line options refer to the reference guide
|
|
or run:
|
|
|
|
emailrelay --help --verbose
|
|
|
|
Configuration
|
|
-------------
|
|
After a full installation the E-MailRelay server will normally be started up
|
|
automatically when the machine boots up.
|
|
|
|
On Unix-like systems the server will read its configuration settings from a file
|
|
`/etc/emailrelay.conf`.
|
|
|
|
On Windows E-MailRelay typically runs as a Windows Service and it reads its
|
|
configuration from the startup batch file `emailrelay-start.bat`.
|
|
|
|
You can change the E-MailRelay server configuration by editing the configuration
|
|
file or startup batch file directly and then restarting the server. Or you can
|
|
use the E-MailRelay configuration GUI if it is available.
|
|
|
|
In many cases E-MailRelay will need to be configured with user-ids and
|
|
passwords. For example, if e-mail is being forwarded to a `smarthost` for onward
|
|
routing then you will need to supply the user-id and password for your account
|
|
on the smarthost. These details must be entered into a `secrets` file and then
|
|
one of `--server-auth`, `--client-auth` or `--pop-auth` must be used to point to
|
|
the file.
|
|
|
|
The E-MailRelay reference document describes the format of the secrets file.
|
|
|
|
Logging
|
|
-------
|
|
E-MailRelay is normally installed so that it logs its activity to a log file,
|
|
but it can also send logging information to `syslog` on Unix systems or the to
|
|
the Event Viewer on Windows.
|
|
|
|
Logging is configured with options like `--log`, `--log-file`, `--as-server` and
|
|
`--syslog`, so check these in the configuration file or startup batch file.
|
|
|
|
For more verbose logging add the `--verbose` option. This is a good idea when
|
|
setting up or trouble-shooting your E-MailRelay configuration.
|
|
|
|
Failures and retries
|
|
--------------------
|
|
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 messages to be retried then just remove
|
|
the `.bad` filename suffix. On Unix-like systems you can do this automatically
|
|
with a cron job that runs the `emailrelay-resubmit.sh` script occasionally.
|
|
|
|
Once a failed message has been renamed it will be forwarded along with all the
|
|
others. It is a good idea to use regular polling (eg. `--poll=60`) to make sure
|
|
that this happens in a timely manner.
|
|
|
|
Open mail servers
|
|
-----------------
|
|
If you are running E-MailRelay as an internet mail server then you need to be
|
|
careful about abuse by spammers and bot-nets. You will also need to be sure that
|
|
incoming e-mail messages are never automatically routed back out to the internet
|
|
because that will definitely attract abuse.
|
|
|
|
By default an E-MailRelay server will only accept connections from local network
|
|
addresses, so for an internet mail server you will need to add the
|
|
`--remote-clients` option. When you add `--remote-clients` you should be
|
|
sure that you have a firewall that blocks connections to any other ports that
|
|
E-MailRelay might have open, or use the `--interface` option to limit their
|
|
scope.
|
|
|
|
A good first step in limiting abuse is to use an address verifier that checks
|
|
that e-mails are correctly addressed to you. You can use the built-in address
|
|
verifier called `account:` to do this or you can write your own verifier script.
|
|
|
|
emailrelay --as-server --remote-clients --address-verifier=account: --domain=mydomain.com
|
|
|
|
Refer to the `Address verifiers` section in the E-MailRelay reference document
|
|
for more details.
|
|
|
|
If you want to run an internet mail server that is not open to everyone then you
|
|
can require that remote users authenticate themselves. Do this with a secrets
|
|
file containing a user-id and password for every remote user, something like
|
|
this:
|
|
|
|
server plain user1 password1
|
|
server plain user2 password2
|
|
|
|
And then use `--server-auth` to point to the file:
|
|
|
|
emailrelay --as-server --remote-clients --server-auth=/etc/emailrelay.auth
|
|
|
|
Refer to the `Authentication` section in the E-MailRelay reference document for
|
|
more details.
|
|
|
|
Running as a POP server
|
|
-----------------------
|
|
E-MailRelay can run as a POP server so that an e-mail client program can
|
|
retrieve messages from the E-MailRelay spool directory.
|
|
|
|
To allow POP access use the `--pop` and `--pop-auth` command-line options,
|
|
something like this:
|
|
|
|
emailrelay --as-server --pop --pop-auth=/etc/pop.auth
|
|
|
|
You will need to create the POP authentication secrets file containing usernames
|
|
and passwords, as above.
|
|
|
|
If you use more than one e-mail client program then you will probably want to
|
|
make independent copies of your e-mails for each. Use a `--filter` program to
|
|
copy the e-mail files into multiple sub-directories of the main spool directory
|
|
and then use `--pop-by-name` so that each e-mail client accesses its own
|
|
sub-directory according to which account name it used when authenticating.
|
|
|
|
The filter can be an external program or the built-in `copy:` filter:
|
|
|
|
emailrelay --as-server --filter=copy:pop --pop --pop-by-name --pop-auth=/etc/pop.auth
|
|
|
|
Add the account for each e-mail client in the POP authentication secrets file
|
|
and manually create the corresponding sub-directory.
|
|
|
|
The `--pop-by-name` option is also useful when e-mail messages are being
|
|
copied into individual mailboxes by the `deliver:` filter. In this case each
|
|
sub-directory is a mailbox containing only those e-mails that are addressed to
|
|
the mailbox owner.
|
|
|
|
|
|
|
|
Refer to the `Delivery` section in the E-MailRelay reference document for more
|
|
information.
|
|
|
|
If you are using POP to view a spool directory that is also being used for
|
|
e-mail forwarding then you must use `--pop-no-delete`.
|
|
|
|
IMAP
|
|
----
|
|
E-MailRelay does not support the [IMAP][] protocol directly but a simple filter
|
|
script can be used to move e-mails into a [maildir][] directory and an IMAP server
|
|
such as [dovecot][] can be used to serve them from there.
|
|
|
|
It is normally sufficient for a filter script to just move the E-MailRelay
|
|
content file straight into the mailbox `cur` directory, delete the corresponding
|
|
envelope file and then exit with an exit code of 100.
|
|
|
|
The built-in `deliver:` filter will automatically do this if it sees that the
|
|
target sub-directory of the spool directory is actually a `maildir` mailbox.
|
|
|
|
Triggering delivery
|
|
-------------------
|
|
If you are using E-MailRelay on a Linux/Unix system to store and forward e-mail
|
|
over an intermittent link to the internet such as dial-up or wireless
|
|
networking, then you might need to arrange for E-MailRelay to be notified when
|
|
it can start forwarding e-mail.
|
|
|
|
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=smtp.example.com:smtp
|
|
|
|
and make it executable using `chmod +x`.
|
|
|
|
You can also trigger forwarding from the E-MailRelay server via the `--admin`
|
|
interface.
|
|
|
|
Rate limiting
|
|
-------------
|
|
If you need to slow the rate at which e-mails are forwarded you can use a
|
|
`--client-filter` program to introduce a delay. On Windows this JavaScript
|
|
filter program would give you a delay of a minute:
|
|
|
|
WScript.Sleep( 60000 ) ;
|
|
WScript.Quit( 0 ) ;
|
|
|
|
However, this can cause timeouts at the server, so a better approach is to use
|
|
`--client-filter exit:102` so that only one e-mail message is forwarded on each
|
|
polling cycle, and then use `--poll 60` to limit it to one e-mail per minute.
|
|
|
|
SpamAssassin
|
|
------------
|
|
The E-MailRelay server can use [SpamAssassin](http://spamassassin.apache.org)
|
|
to mark or reject potential spam.
|
|
|
|
It's easiest to run SpamAssassin's `spamd` program in the background and let
|
|
E-MailRelay send incoming messages to it over the local network.
|
|
|
|
The built-in `spam-edit:` filter is used to pass e-mail messages to spamd:
|
|
|
|
emailrelay --as-server --filter=spam-edit:127.0.0.1:783
|
|
|
|
If SpamAssassin detects a message is spam it will edit it into a spam report
|
|
with the original e-mail moved into an attachment.
|
|
|
|
Alternatively use the `spam:` filter if spam e-mails should be rejected
|
|
outright:
|
|
|
|
emailrelay --as-server --filter=spam:127.0.0.1:783
|
|
|
|
Google mail
|
|
-----------
|
|
To send mail via Google mail's SMTP gateway you will need to obtain a new
|
|
`application password` from Google: log in to your Google account and look for
|
|
the account's security settings and then `app passwords`. Create the password
|
|
for E-MailRelay selecting an application type `other`.
|
|
|
|
Then create a client secrets file for E-MailRelay containing your account name
|
|
and the new application password. You may already have this file on Windows as
|
|
`C:\ProgramData\E-MailRelay\emailrelay.auth`.
|
|
|
|
You should edit the secrets file to contain one `client` line, something like
|
|
this:
|
|
|
|
client plain myname@gmail.com myapppassword
|
|
|
|
Then change the E-MailRelay startup batch file or configuration file to refer
|
|
to your secrets file by using the `--client-auth` option.
|
|
|
|
Also set the `--as-proxy` or `--forward-to` option to `smtp.gmail.com:587` and
|
|
add `--client-tls` to enable [TLS][] encryption.
|
|
|
|
On Windows the E-MailRelay startup batch file should contain something like this:
|
|
|
|
emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ...
|
|
|
|
Or an equivalent configuration file like this:
|
|
|
|
forward-to smtp.gmail.com:587
|
|
client-tls
|
|
client-auth C:/ProgramData/E-MailRelay/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 created by `ssh -N -D` or via the Tor
|
|
anonymising network.
|
|
|
|
For example, this will run an E-MailRelay proxy on port 587 that routes via a
|
|
local Tor server on port 9050 to the mail server at smtp.example.com:
|
|
|
|
emailrelay --port 587 --as-proxy=smtp.example.com:25@localhost:9050 --domain=anon.net --anonymous --connection-timeout=300
|
|
|
|
Blocklists and dynamic firewalls
|
|
--------------------------------
|
|
E-MailRelay can consult with remote DNSBL blocklist servers in order to block
|
|
incoming connections from known spammers. For example:
|
|
|
|
emailrelay -r --dnsbl=zen.spamhaus.org,bl.mailspike.net ...
|
|
|
|
Refer to the documentation of the `--dnsbl` option for more details.
|
|
|
|
It is also possible to integrate E-MailRelay with intrusion detection systems
|
|
such as `fail2ban` that monitor log files and dynamically modify your iptables
|
|
firewall. Use E-MailRelay's `--log-address` command-line option so that the
|
|
spammers' IP addresses are logged and made visible to `fail2ban`.
|
|
|
|
Bcc handling
|
|
------------
|
|
E-MailRelay transfers e-mail messages without changing their content in any way,
|
|
other than by adding a `Received` header. In particular, if a message contains a
|
|
`Bcc:` header when it is submitted to the E-MailRelay server it will have the
|
|
same `Bcc:` header when forwarded.
|
|
|
|
It is normally the responsibility of the program that submits an e-mail message
|
|
to submit it separately for each `Bcc` recipient, removing the `Bcc:` header
|
|
from the message content or changing it to contain only the 'current' recipient.
|
|
If this is not done, perhaps through misconfiguration of the e-mail user agent
|
|
program, then `Bcc` recipients may be visible to the `To` and `Cc` message
|
|
recipients.
|
|
|
|
An E-MailRelay `--filter` script can be used to reject messages with incorrect
|
|
`Bcc:` headers, and an example script is included.
|
|
|
|
Advanced set-up
|
|
---------------
|
|
As an example of an advanced E-MailRelay setup consider the following
|
|
command-line, split onto multiple lines for readability:
|
|
|
|
emailrelay
|
|
--log --verbose --log-time --log-network
|
|
--close-stderr --syslog
|
|
--pid-file @app/emailrelay.pid
|
|
--user root
|
|
|
|
--in-spool-dir @app/in
|
|
--in-port 25
|
|
--in-domain example.com
|
|
--in-address-verifier account:
|
|
--in-dnsbl 1.1.1.1:53,500,1,dnsbl.example.com
|
|
--in-filter spam-edit:127.0.0.1:783
|
|
--in-filter deliver:
|
|
--in-server-smtp-config +chunking,+smtputf8
|
|
--in-size 100000000
|
|
--in-pop
|
|
--in-pop-port 110
|
|
--in-pop-auth pam:
|
|
--in-pop-by-name
|
|
|
|
--out-spool-dir @app/out
|
|
--out-port 587
|
|
--out-forward-on-disconnect
|
|
--out-forward-to-some
|
|
--out-poll 60
|
|
--out-address-verifier account:check
|
|
--out-delivery-dir @app/in
|
|
--out-filter deliver:
|
|
--out-filter split:
|
|
--out-client-filter mx:
|
|
--out-forward-to 127.0.0.1:588
|
|
--out-domain example.com
|
|
|
|
--other-spool-dir @app/other
|
|
--other-port 588
|
|
--other-interface 127.0.0.1
|
|
--other-client-tls
|
|
--other-client-auth plain:YWxpY2VAZ21haWwuY29t:UGFzc3cwcmQ
|
|
--other-forward-to smtp.gmail.com:587
|
|
--other-poll 3600
|
|
|
|
This is a three-in-one configuration so there are effectively three E-MailRelay
|
|
servers running in one process, named `in`, `out` and `other`.
|
|
|
|
The `in` server is an internet-facing e-mail server with delivery to individual
|
|
mailboxes that can be accessed via POP. The `account:` verifier checks the
|
|
addressees in the incoming e-mails against the list of accounts on the local
|
|
machine and against the given domain name; the IP address of the network
|
|
connection is checked against a DNSBL database; SpamAssassin is used to
|
|
identify spam; and Linux [PAM][] is used for POP authentication.
|
|
|
|
The `out` server is a routing [MTA][] that sends outgoing e-mail messages directly
|
|
to destination servers. The filter makes copies so that eash e-mail message goes
|
|
to just one domain. The client filter uses DNS MX queries against the local
|
|
system's default name servers to do the routing. If any e-mail messages are
|
|
addressed to local users they are short-circuited and delivered directly to
|
|
their `in` mailboxes.
|
|
|
|
The `other` server does store-and-forward to a gmail smarthost and acts as the
|
|
default destination for the `out` server. In this example the gmail password is
|
|
given directly on the command-line but it is normally more secure to use a
|
|
separate secrets file.
|
|
|
|
|
|
|
|
|
|
|
|
[DNSBL]: https://en.wikipedia.org/wiki/DNSBL
|
|
[IMAP]: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol
|
|
[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
|
|
[PAM]: https://en.wikipedia.org/wiki/Linux_PAM
|
|
[POP]: https://en.wikipedia.org/wiki/Post_Office_Protocol
|
|
[SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
|
|
[SOCKS]: https://en.wikipedia.org/wiki/SOCKS
|
|
[TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security
|
|
[dovecot]: https://www.dovecot.org
|
|
[maildir]: https://en.wikipedia.org/wiki/Maildir
|
|
|
|
_____________________________________
|
|
Copyright (C) 2001-2023 Graeme Walker
|