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.



<<whatisit.png>>



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".



<<serverclient.png>>



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:



<<forwardto.png>>



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:



<<mailserver.png>>



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.



<<popbyname.png>>



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.









_____________________________________

Copyright (C) 2001-2023 Graeme Walker

