burble.dn42/emailrelay
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emailrelay/doc/userguide.html
Graeme Walker 2a4d620121 v2.5
2023-08-10 12:00:00 +00:00

647 lines
24 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<title>E-MailRelay User Guide</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<link rel="stylesheet" href="emailrelay.css" type="text/css">
</head>
<body>
<!-- index:0::::E-MailRelay User Guide -->
<div class="div-main">
<h1><a class="a-header" name="H_1">E-MailRelay User Guide</a></h1> <!-- index:1:H:E-MailRelay User Guide -->
<h2><a class="a-header" name="SH_1_1">What is it?</a></h2> <!-- index:2:SH:1:1:What is it? -->
<p>
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.
</p>
<img src="whatisit.png" alt="image">
<p>
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.
</p>
<p>
The code has few dependencies on third-party libraries or run-time environments
so it is easy to build and install.
</p>
<p>
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.
</p>
<h2><a class="a-header" name="SH_1_2">Basic operation</a></h2> <!-- index:2:SH:1:2:Basic operation -->
<p>
E-MailRelay can be run straight from the command-line, and on Windows you can
run <em>emailrelay.exe</em> or <em>emailrelay-textmode.exe</em> from the zip file without
going through the installation process.
</p>
<p>
To use E-MailRelay in store-and-forward mode use the <em>--as-server</em> option to
start the storage daemon in the background, and then do delivery of spooled
messages by running with <em>--as-client</em>.
</p>
<img src="serverclient.png" alt="image">
<p>
For example, to start a storage daemon in the background listening on port 10025
use a command like this:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --port 10025 --spool-dir /tmp
</pre>
</div><!-- div-pre -->
<p>
On Windows use <em>c:/temp</em> for testing, rather than <em>/tmp</em>.
</p>
<p>
Or to run it in the foreground:
</p>
<div class="div-pre">
<pre>emailrelay --log --no-daemon --port 10025 --spool-dir /tmp
</pre>
</div><!-- div-pre -->
<p>
And then to forward the spooled mail to <em>smtp.example.com</em> run something
like this:
</p>
<div class="div-pre">
<pre>emailrelay --as-client smtp.example.com:25 --spool-dir /tmp
</pre>
</div><!-- div-pre -->
<p>
To forward continuously you can add the <em>--poll</em> and <em>--forward-to</em> options to
the server command-line:
</p>
<img src="forwardto.png" alt="image">
<p>
For example, this starts a server that also forwards spooled-up e-mail every
minute:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --poll 60 --forward-to smtp.example.com:25
</pre>
</div><!-- div-pre -->
<p>
Or for a server that forwards each message as soon as it has been received, you
can use <em>--forward-on-disconnect</em>:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --forward-on-disconnect --forward-to smtp.example.com:25
</pre>
</div><!-- div-pre -->
<p>
To edit or filter e-mail as it passes through the server specify your filter
program with the <em>--filter</em> option, something like this:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --filter /tmp/set-from.js
</pre>
</div><!-- div-pre -->
<p>
Look for example filter scripts in the <em>examples</em> directory.
</p>
<p>
E-MailRelay can also be used as a personal internet mail server:
</p>
<img src="mailserver.png" alt="image">
<p>
Use <em>--remote-clients</em> (<em>-r</em>) to allow connections from outside the local
network, define your domain name with <em>--domain</em> and use an address verifier as
a first line of defense against spammers:
</p>
<div class="div-pre">
<pre>emailrelay --as-server -v -r --domain=example.com --address-verifier=account:
</pre>
</div><!-- div-pre -->
<p>
Then enable POP access to the incoming e-mails with <em>--pop</em>, <em>--pop-port</em> and
<em>--pop-auth</em>:
</p>
<div class="div-pre">
<pre>emailrelay ... --pop --pop-port 10110 --pop-auth /etc/emailrelay.auth
</pre>
</div><!-- div-pre -->
<p>
Set up the POP account with a user-id and password in the <em>--pop-auth</em> secrets
file. The secrets file should contain a single line of text like this:
</p>
<div class="div-pre">
<pre>server plain &lt;userid&gt; &lt;password&gt;
</pre>
</div><!-- div-pre -->
<p>
For more information on the command-line options refer to the reference guide
or run:
</p>
<div class="div-pre">
<pre>emailrelay --help --verbose</pre>
</div><!-- div-pre -->
<h2><a class="a-header" name="SH_1_3">Configuration</a></h2> <!-- index:2:SH:1:3:Configuration -->
<p>
After a full installation the E-MailRelay server will normally be started up
automatically when the machine boots up.
</p>
<p>
On Unix-like systems the server will read its configuration settings from a file
<em>/etc/emailrelay.conf</em>.
</p>
<p>
On Windows E-MailRelay typically runs as a Windows Service and it reads its
configuration from the startup batch file <em>emailrelay-start.bat</em>.
</p>
<p>
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.
</p>
<p>
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 <em>smarthost</em> 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 <em>secrets</em> file and then
one of <em>--server-auth</em>, <em>--client-auth</em> or <em>--pop-auth</em> must be used to point to
the file.
</p>
<p>
The E-MailRelay reference document describes the format of the secrets file.
</p>
<h2><a class="a-header" name="SH_1_4">Logging</a></h2> <!-- index:2:SH:1:4:Logging -->
<p>
E-MailRelay is normally installed so that it logs its activity to a log file,
but it can also send logging information to <em>syslog</em> on Unix systems or the to
the Event Viewer on Windows.
</p>
<p>
Logging is configured with options like <em>--log</em>, <em>--log-file</em>, <em>--as-server</em> and
<em>--syslog</em>, so check these in the configuration file or startup batch file.
</p>
<p>
For more verbose logging add the <em>--verbose</em> option. This is a good idea when
setting up or trouble-shooting your E-MailRelay configuration.
</p>
<h2><a class="a-header" name="SH_1_5">Failures and retries</a></h2> <!-- index:2:SH:1:5:Failures and retries -->
<p>
If e-mail messages cannot be forwarded by the E-MailRelay system then the
envelope files in the spool directory are given a <em>.bad</em> suffix. The reason for
the failure will be recorded in the envelope file itself.
</p>
<p>
You should check for <em>.bad</em> envelope files in the E-MailRelay spool directory
from time to time. If you want failed messages to be retried then just remove
the <em>.bad</em> filename suffix. On Unix-like systems you can do this automatically
with a cron job that runs the <em>emailrelay-resubmit.sh</em> script occasionally.
</p>
<p>
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. <em>--poll=60</em>) to make sure
that this happens in a timely manner.
</p>
<h2><a class="a-header" name="SH_1_6">Open mail servers</a></h2> <!-- index:2:SH:1:6:Open mail servers -->
<p>
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.
</p>
<p>
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
<em>--remote-clients</em> option. When you add <em>--remote-clients</em> 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 <em>--interface</em> option to limit their
scope.
</p>
<p>
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 <em>account:</em> to do this or you can write your own verifier script.
</p>
<div class="div-pre">
<pre>emailrelay --as-server --remote-clients --address-verifier=account: --domain=mydomain.com
</pre>
</div><!-- div-pre -->
<p>
Refer to the <em>Address verifiers</em> section in the E-MailRelay reference document
for more details.
</p>
<p>
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:
</p>
<div class="div-pre">
<pre>server plain user1 password1
server plain user2 password2
</pre>
</div><!-- div-pre -->
<p>
And then use <em>--server-auth</em> to point to the file:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --remote-clients --server-auth=/etc/emailrelay.auth
</pre>
</div><!-- div-pre -->
<p>
Refer to the <em>Authentication</em> section in the E-MailRelay reference document for
more details.
</p>
<h2><a class="a-header" name="SH_1_7">Running as a POP server</a></h2> <!-- index:2:SH:1:7:Running as a POP server -->
<p>
E-MailRelay can run as a POP server so that an e-mail client program can
retrieve messages from the E-MailRelay spool directory.
</p>
<p>
To allow POP access use the <em>--pop</em> and <em>--pop-auth</em> command-line options,
something like this:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --pop --pop-auth=/etc/pop.auth
</pre>
</div><!-- div-pre -->
<p>
You will need to create the POP authentication secrets file containing usernames
and passwords, as above.
</p>
<p>
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 <em>--filter</em> program to
copy the e-mail files into multiple sub-directories of the main spool directory
and then use <em>--pop-by-name</em> so that each e-mail client accesses its own
sub-directory according to which account name it used when authenticating.
</p>
<p>
The filter can be an external program or the built-in <em>copy:</em> filter:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --filter=copy:pop --pop --pop-by-name --pop-auth=/etc/pop.auth
</pre>
</div><!-- div-pre -->
<p>
Add the account for each e-mail client in the POP authentication secrets file
and manually create the corresponding sub-directory.
</p>
<p>
The <em>--pop-by-name</em> option is also useful when e-mail messages are being
copied into individual mailboxes by the <em>deliver:</em> filter. In this case each
sub-directory is a mailbox containing only those e-mails that are addressed to
the mailbox owner.
</p>
<img src="popbyname.png" alt="image">
<p>
Refer to the <em>Delivery</em> section in the E-MailRelay reference document for more
information.
</p>
<p>
If you are using POP to view a spool directory that is also being used for
e-mail forwarding then you must use <em>--pop-no-delete</em>.
</p>
<h2><a class="a-header" name="SH_1_8">IMAP</a></h2> <!-- index:2:SH:1:8:IMAP -->
<p>
E-MailRelay does not support the IMAP protocol directly but a simple filter
script can be used to move e-mails into a <em>maildir</em> directory and an IMAP server
such as <em>dovecot</em> can be used to serve them from there.
</p>
<p>
It is normally sufficient for a filter script to just move the E-MailRelay
content file straight into the mailbox <em>cur</em> directory, delete the corresponding
envelope file and then exit with an exit code of 100.
</p>
<p>
The built-in <em>deliver:</em> filter will automatically do this if it sees that the
target sub-directory of the spool directory is actually a <em>maildir</em> mailbox.
</p>
<h2><a class="a-header" name="SH_1_9">Triggering delivery</a></h2> <!-- index:2:SH:1:9:Triggering delivery -->
<p>
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.
</p>
<p>
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 <em>/etc/ppp/ip-up.d</em>, and for
wireless <em>/etc/network/if-up.d</em>.
</p>
<p>
Just create a two-line script like this in the relevant directory:
</p>
<div class="div-pre">
<pre>#!/bin/sh
exec /usr/local/sbin/emailrelay --as-client=smtp.example.com:smtp
</pre>
</div><!-- div-pre -->
<p>
and make it executable using <em>chmod +x</em>.
</p>
<p>
You can also trigger forwarding from the E-MailRelay server via the <em>--admin</em>
interface.
</p>
<h2><a class="a-header" name="SH_1_10">Rate limiting</a></h2> <!-- index:2:SH:1:10:Rate limiting -->
<p>
If you need to slow the rate at which e-mails are forwarded you can use a
<em>--client-filter</em> program to introduce a delay. On Windows this JavaScript
filter program would give you a delay of a minute:
</p>
<div class="div-pre">
<pre>WScript.Sleep( 60000 ) ;
WScript.Quit( 0 ) ;
</pre>
</div><!-- div-pre -->
<p>
However, this can cause timeouts at the server, so a better approach is to use
<em>--client-filter exit:102</em> so that only one e-mail message is forwarded on each
polling cycle, and then use <em>--poll 60</em> to limit it to one e-mail per minute.
</p>
<h2><a class="a-header" name="SH_1_11">SpamAssassin</a></h2> <!-- index:2:SH:1:11:SpamAssassin -->
<p>
The E-MailRelay server can use <a href="http://spamassassin.apache.org">SpamAssassin</a>
to mark or reject potential spam.
</p>
<p>
It's easiest to run SpamAssassin's <em>spamd</em> program in the background and let
E-MailRelay send incoming messages to it over the local network.
</p>
<p>
The built-in <em>spam-edit:</em> filter is used to pass e-mail messages to spamd:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --filter=spam-edit:127.0.0.1:783
</pre>
</div><!-- div-pre -->
<p>
If SpamAssassin detects a message is spam it will edit it into a spam report
with the original e-mail moved into an attachment.
</p>
<p>
Alternatively use the <em>spam:</em> filter if spam e-mails should be rejected
outright:
</p>
<div class="div-pre">
<pre>emailrelay --as-server --filter=spam:127.0.0.1:783</pre>
</div><!-- div-pre -->
<h2><a class="a-header" name="SH_1_12">Google mail</a></h2> <!-- index:2:SH:1:12:Google mail -->
<p>
To send mail via Google mail's SMTP gateway you will need to obtain a new
<em>application password</em> from Google: log in to your Google account and look for
the account's security settings and then <em>app passwords</em>. Create the password
for E-MailRelay selecting an application type <em>other</em>.
</p>
<p>
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
<em>C:\ProgramData\E-MailRelay\emailrelay.auth</em>.
</p>
<p>
You should edit the secrets file to contain one <em>client</em> line, something like
this:
</p>
<div class="div-pre">
<pre>client plain myname@gmail.com myapppassword
</pre>
</div><!-- div-pre -->
<p>
Then change the E-MailRelay startup batch file or configuration file to refer
to your secrets file by using the <em>--client-auth</em> option.
</p>
<p>
Also set the <em>--as-proxy</em> or <em>--forward-to</em> option to <em>smtp.gmail.com:587</em> and
add <em>--client-tls</em> to enable TLS encryption.
</p>
<p>
On Windows the E-MailRelay startup batch file should contain something like this:
</p>
<div class="div-pre">
<pre>emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ...
</pre>
</div><!-- div-pre -->
<p>
Or an equivalent configuration file like this:
</p>
<div class="div-pre">
<pre>forward-to smtp.gmail.com:587
client-tls
client-auth C:/ProgramData/E-MailRelay/emailrelay.auth</pre>
</div><!-- div-pre -->
<h2><a class="a-header" name="SH_1_13">Connection tunnelling</a></h2> <!-- index:2:SH:1:13:Connection tunnelling -->
<p>
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 <em>ssh -N -D</em> or via the Tor
anonymising network.
</p>
<p>
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:
</p>
<div class="div-pre">
<pre>emailrelay --port 587 --as-proxy=smtp.example.com:25@localhost:9050 --domain=anon.net --anonymous --connection-timeout=300</pre>
</div><!-- div-pre -->
<h2><a class="a-header" name="SH_1_14">Blocklists and dynamic firewalls</a></h2> <!-- index:2:SH:1:14:Blocklists and dynamic firewalls -->
<p>
E-MailRelay can consult with remote DNSBL blocklist servers in order to block
incoming connections from known spammers. For example:
</p>
<div class="div-pre">
<pre>emailrelay -r --dnsbl=zen.spamhaus.org,bl.mailspike.net ...
</pre>
</div><!-- div-pre -->
<p>
Refer to the documentation of the <em>--dnsbl</em> option for more details.
</p>
<p>
It is also possible to integrate E-MailRelay with intrusion detection systems
such as <em>fail2ban</em> that monitor log files and dynamically modify your iptables
firewall. Use E-MailRelay's <em>--log-address</em> command-line option so that the
spammers' IP addresses are logged and made visible to <em>fail2ban</em>.
</p>
<h2><a class="a-header" name="SH_1_15">Bcc handling</a></h2> <!-- index:2:SH:1:15:Bcc handling -->
<p>
E-MailRelay transfers e-mail messages without changing their content in any way,
other than by adding a <em>Received</em> header. In particular, if a message contains a
<em>Bcc:</em> header when it is submitted to the E-MailRelay server it will have the
same <em>Bcc:</em> header when forwarded.
</p>
<p>
It is normally the responsibility of the program that submits an e-mail message
to submit it separately for each <em>Bcc</em> recipient, removing the <em>Bcc:</em> 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 <em>Bcc</em> recipients may be visible to the <em>To</em> and <em>Cc</em> message
recipients.
</p>
<p>
An E-MailRelay <em>--filter</em> script can be used to reject messages with incorrect
<em>Bcc:</em> headers, and an example script is included.
</p>
<h2><a class="a-header" name="SH_1_16">Advanced set-up</a></h2> <!-- index:2:SH:1:16:Advanced set-up -->
<p>
As an example of an advanced E-MailRelay setup consider the following
command-line, split onto multiple lines for readability:
</p>
<div class="div-pre">
<pre>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
</pre>
</div><!-- div-pre -->
<p>
This is a three-in-one configuration so there are effectively three E-MailRelay
servers running in one process, named <em>in</em>, <em>out</em> and <em>other</em>.
</p>
<p>
The <em>in</em> server is an internet-facing e-mail server with delivery to individual
mailboxes that can be accessed via POP. The <em>account:</em> 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.
</p>
<p>
The <em>out</em> 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 <em>in</em> mailboxes.
</p>
<p>
The <em>other</em> server does store-and-forward to a gmail smarthost and acts as the
default destination for the <em>out</em> 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.
</p>
<div class="div-footer">
<p>
Copyright (C) 2001-2023 Graeme Walker
</p>
</div><!-- div-footer -->
</div> <!-- div-main -->
</body>
</html>
<!-- Copyright (C) 2001-2023 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
Reference in New Issue View Git Blame Copy Permalink