[[ch-mailreference]]
== Email Configuration

This is a detailed break-down of all the configuration options and
files available when configuring how email is handled for a domain.
Throughout this chapter, the domain +my-brilliant-site.com+ is used as an
example.  Thus all the configuration for +my-brilliant-site.com+ will be inside
the [directory]'/srv/my-brilliant-site.com/' directory.

[[s-mail-port-configuration]]
=== Port Configuration
(((Email, port numbers)))

The mail servers have been set up with standard port assignments as
follows.  These are all the standard ports for the protocols.

[options="header"]
|==================================
| Service | Port      | Encryption
| POP3    | 110       | TLS (using STARTTLS)
| IMAP    | 143       | TLS (using STARTTLS)
| SMTP    | 25 or 587 | TLS (using STARTTLS)
| POP3    | 995       | TLS (on connect)
| IMAP    | 993       | TLS (on connect)
| SMTP    | 465       | TLS (on connect)
| Sieve   | 4190      | TLS (using STARTTLS)
|==================================

[[s-mail-accepting]]
=== Accepting email for a domain
(((Email, accepting)))

In order for a domain to be configured to accept email, one of two
things must be present.  Either the domain must have a
[directory]'mailboxes/' directory present, or one of the files
'config/default_forward' or 'config/aliases' must be present.

For example, if the domain *my-brilliant-site.com* would like to host
mail normally, i.e. one mailbox per user hosted on the same machine,
then the directory [directory]'/srv/my-brilliant-site.com/mailboxes/'
should be created.  Then in there, one directory per user should be
created.  If *bob@my-brilliant-site.com* would like to receive mail,
then [directory]'/srv/my-brilliant-site.com/mailboxes/bob/'  should be
created.

Assuming that this is the only directory inside
[directory]'/srv/my-brilliant-site.com/mailboxes/' then only mail
addressed to *bob@my-brilliant-site.com* will be accepted.  Any other
mail addressed to *my-brilliant-site.com* will be rejected.

(((Email, catching all)))
If you would like to accept all mail for *my-brilliant-site.com*,
regardless of who it is addressed to, then create the file
'/srv/my-brilliant-site.com/config/default_forward'.  The contents of
this file should be a single email address, or a comma-separated list
of email addresses.  For example, to forward all mail to
*bob@my-brilliant-site.com*, regardless of who it is addressed to,
then '/srv/my-brilliant-site.com/config/default_forward' should
contain +bob@my-brilliant-site.com+.
(((config/,default_forward)))

(((Email, not accepting any)))
If you would like the domain *nomail.my-brilliant-site.com* not to
receive any mail at all, then remove the directory
[directory]'/srv/nomail.my-brilliant-site.com/mailboxes/' and ensure
that the file
'/srv/nomail.my-brilliant-site.com/config/default_forward' does not
exist.

[[s-unix-mail-accepting]]
=== Email for Unix users.
(((Email, accepting, unix)))

[IMPORTANT]
.Before you start this section
======================================================
 1. Both a unix user and a 'normal' Symbiosis email user
 can be set up to receive email to the same address. The 'normal' user
 will always take precedence over the unix user and have their
 mail delivered to their inbox first, so take care  when using this feature!
======================================================

A new feature in this release is the ability to have unix users
with email accounts based in their home directories. These will receive emails
for the host name of the machine, which you can find out by running 'hostname'
on the command line. The result of this will display the domain in the
email address the system users will get, eg, the part after the @.
The other half will be dictated by their username, eg, "admin" or "my-user".

To start with, we create a @.password@ file in, eg, @/home/my-user/@.
Initially this can contain the password in plain text.

Once the password file is in place, the new user will be able to login
and collect email.  Logins over SMTP, IMAP, and POP3 will all work
identically to a normal email user, with the same ports and SSL/TLS
requirements.  The principal difference is the username is just their
bare username, without a domain.  E.g. for a user `clare`, her login
for SMTP/IMAP/POP3 etc, is just `clare`.

Unix users' @Maildir@ directories will reside in /home/my-user/Maildir by default.
This allows these users to use system mail readers such as @mutt@ in order to
read and send email, obviating the need to use IMAP and SMTP.

These users are also able to control the following files:

  * @.forward@ - to control forwarding of emails.
  * @.vacation@ - to set a vacation (holiday) message.
  * @.sieve@ - to set up Sieve filters.


[[s-email-passwords]]
=== Password files
(((Email, encrypting passwords)))

The password for a mailbox should be set by the contents of a file
named 'password' inside a user's mailbox directory.  The contents of
this file may be in plain text, or encrypted. If plain text is used,
the system will automatically encrypt the password.

To encrypt all email passwords on the system, you can run

    symbiosis-email-encrypt-passwords --verbose

The `--verbose` flag is there to provide more output.

=== Allowing users to change their own password

New in Symbiosis Jessie is the ability for users to change their own
passwords. This is done through the webmail system, which by default
is Squirrelmail, but the functionality is available in Roundcube also.

To change a password in Squirrelmail, log in and select Options. This
will being up the Options page :

screenshot::figures/SM-options.png

From there, select Change Password, where you must enter your current
password, and enter a new one. Passwords which are ether too weak or too
short will be rejected by the system.

screenshot::figures/SM_changepass.png

=== Suffixes
(((Email, using suffixes)))

All email addresses can be used with a suffix.  This allows people to
filter their email by the To: address.  The separator between the
local part and suffix is the +++ sign.

// have to use a passthrough here otherwise asciidoc gets confused on
// the plus sign.
For example, Bob signs up to a shopping site at http://example.com.
He might use pass:[<ulink url="mailto:bob+example@my-brilliant-site.com">bob+example@my-brilliant-site.com</ulink>] his email
address when signing up, such that he can filter all email from that
shop.

[[s-email-quotas]]
=== Enforcing mailbox size with quotas
(((Email, quotas)))
(((Quotas, email)))

Symbiosis can enforce users' mailbox size with quotas.  This will prevent mail
from being delivered to a user if their mailbox grows too large.
// *** TODO: not currently true.
// The user will receive a warning when they have filled up their mailbox to 75% of its size.

A default quota for each individual mailboxes in a domain can be specified in
'config/mailbox-quota'.  A per-mailbox quota can be defined in a file
named 'quota' which resides in a user's mailbox directory.
(((config/,mailbox-quota)))

These files both have the same format, which is just a number of bytes over
which mail should not be delivered.  This number can have a suffix of +k+, +M+,
or, +G+ which represent kilobytes, megabytes, and gigabytes, or +ki+, +Mi+, or
+Gi+ to represent kibibytes, mebibytes, and gibibytes, respectively.

For example, to limit the size of each mailbox for the domain
*my-brilliant-site.com* to 200MB, i.e. 200,000,000 bytes, put +200M+
in '/srv/my-brilliant-site.com/config/mailbox-quota'.

To grant *bob@my-brilliant-site.com* a 1GiB quota, i.e. 1,073,741,824 bytes,
put +1Gi+ in '/srv/my-brilliant-site.com/mailboxes/bob/quota'.
(((mailboxes/,user/,quota)))

Quotas in a user's mailbox directory take precedence over the default quota.

[[s-email-sieve]]
=== Server-side filtering using Sieve

@Sieve@ is a http://sieve.info[standard language] that users can employ to
filter their email on the server.  Additionally using any one of a number of
http://sieve.info/clients[clients], users can edit their filtering rules
without needing shell access to the server.

Each user can create a number of scripts in a directory called
[directory]'sieve.d/', with the current script being kept in a file called
'sieve'.
(((mailboxes/,user/,sieve.d)))
(((mailboxes/,user/,sieve)))

Only one of these scripts can be active at a given time for each user; add to
an existing file rather than creating a new one if you require extra filters.

[[s-email-forward-files]]
=== Forward files
(((Email, forwarding)))

There are two methods of forwarding email.  The first is a per-mailbox
forwarding service, and the second is a per-domain service.  For the
per-user service, a file named 'forward' should
be put in a user's mailbox directory.  The per-domain service uses the
same file format as the per-user service, but the file should be
uploaded to 'config/default_forward' instead.
(((config/,default_forward)))
(((mailboxes/,user/,forward)))

For example, *bob@my-brilliant-site.com* would set up a file called
'/srv/my-brilliant-site.com/mailboxes/bob/forward'.

If all the mail for *my-brilliant-site.com* needed to be forwarded
elsewhere, then the file would be called
'/srv/my-brilliant-site.com/config/default_forward'.
(((Email, forwarding, a whole domain)))

Both of these files can be interpreted in two ways.  Firstly they can
be a comma separated list of email addresses.  For example, if Bob
wanted to forward his email onto Charlie and Dave, his forward file
might read

----------------
charlie@example.com, dave@example.com
-----------------

The second way these files are interpreted is as an @Exim@ filter file.
The full specification is documented at
http://www.exim.org/exim-html-4.72/doc/html/filter.html#CHAPeximfilter[the
@Exim@ project site].

Here are some examples of what is possible.

To forward mail on, but keep a copy
-------------------------------------------
# Exim filter
unseen deliver charlie@example.org
unseen deliver dave@example.com
-------------------------------------------
(((Email, forwarding, keeping a copy)))

To rewrite all mail for a domain to *example.com*. This is probably
best used in 'config/default_forward'.
-------------------------------------------
# Exim filter
deliver $local_part@example.com
-------------------------------------------

The
http://www.exim.org/exim-html-4.72/doc/html/filter.html#SECTex[Exim
documentation] has further examples of what is possible.

[[s-email-vacation-messages]]
=== Vacation messages
(((Email, vacation messages)))

It is possible to set a vacation message for a user by putting a
message in file called 'vacation' in the user's mailbox directory.
(((mailboxes/,user/,vacation)))

For example, for *bob@my-brilliant-site.com*, the message would go in
'/srv/my-brilliant-site.com/mailboxes/bob/vacation'.  On Bob's return,
the people who received vacation messages are logged to
'/srv/my-brilliant-site.com/mailboxes/bob/vacation.log'.  Once he's
read it, that file, along with
'/srv/my-brilliant-site.com/mailboxes/bob/vacation' and
'/srv/my-brilliant-site.com/mailboxes/bob/vacation.db' should *all* be
removed.
(((mailboxes/,user/,vacation.log)))
(((mailboxes/,user/,vacation.db)))

IMPORTANT: Vacation messages can irritate other email users by
replying to mailing lists, email bounces, and so on.  Every effort is
made to stop this from happening, but it is by no means fool-proof.


[[s-email-aliases]]
=== Email alias lists
(((Email, aliases)))

Each domain can have a list of aliases.  This is just a file that
contains a list of local parts, and a list of places they should be
sent on to.  This file should be in the [directory]'config/' directory
and is named 'aliases'.
(((config/,aliases)))

For example, *my-brilliant-site.com* has a list of dummy addresses
that should be sent on to Bob.  So the aliases file would be kept at
'/srv/my-brilliant-site.com/config/aliases' and contains the
following.

---------------------------------------
webmaster   bob@my-brilliant-site.com
chairman    charlie@example.com
staff       bob@my-brilliant-site.com, charlie@example.com, dave@example.com
---------------------------------------

This ensures that webmaster@my-brilliant-site.com is sent to
bob@my-brilliant-site.com; chairman@my-brilliant-site.com is sent to
charlie@example.com; staff@my-brilliant-site.com is sent to
bob@my-brilliant-site.com, charlie@example.com, and dave@example.com.

[[s-email-spam-and-virus]]
=== Spam and virus scanning

Symbiosis comes with
http://wiki.apache.org/spamassassin/[@SpamAssassin@] and 
http://www.clamav.net/[@ClamAV@] installed to protect your email users
against spam and virus in their inbox.  To enable these features,
simply create the files 'config/antispam' or 'config/antivirus' as
appropriate.  This will configure that domain to reject email if it is
considered to be spam, or if it contains a virus.

If you'd rather accept all email and simply tag it as spam, put the
word *tag* in 'config/antispam'.  This will also cause the email to be
delivered into the 'Spam/' folder for that user.


[[s-email-spamassassin-customisation]]
=== Customising @SpamAssassin@
(((SpamAssassin)))


The configuration for @SpamAssassin@ for the *admin* user is kept in
'/srv/.spamassassin/user_prefs'.  Here you can adjust what score is needed to
reject spam, and which tests are used during scanning.  This file will only
appear after a mail has been received with spam detection turned on, but
one can be created and configured before this occurs.

The file contains comments and instructions, and further tips can be
found on the
http://wiki.apache.org/spamassassin/UsingSpamAssassin[@SpamAssassin@
wiki].

In brief, to cause *more mail* to be rejected, you need to reduce the
threshold score.  Therefore change the line reading +# required_score
5+ should be changed to +required_score 4+.  Notice that the +#+ has
been removed at the start of the line to un-comment it.

Similarly if mail is being rejected, you can increase the score.

Further instructions can be found on the
http://wiki.apache.org/spamassassin/UsingSpamAssassin[@SpamAssassin@
wiki].

There is no facility to train the SpamAssassin Bayesian learner yet.

[[s-email-spam-virus-headers]]
=== Filtering mail using headers
(((Email, spam headers)))

Headers are added to messages when spam or virus scanning is enabled.  These
can be used by email clients to filter email, for example in to spam or
quarantine folders.

With spam scanning enabled, any email that *is* accepted has the following
headers added

 * +X-Spam-Score+
 * +X-Spam-Bar+
 * +X-Spam-Status+

The score is determined by @SpamAssassin@, and is the basis for
acceptance or rejection.  The higher the score, the more certain
@SpamAssassin@ is that the message is unwanted.  The default threshold
for rejection is 5.

The bar is a length of pluses or minuses that provide an easy-to-parse
representation of the score.  A positive score is given pluses, a
negative score minuses.  For example a score of 5.6 would be
represented as pass:[<literal>++++++</literal>]; a score of -2.2 would be represented as +--+.

The status is always either +innocent+ or +spam+, depending on the
score.

When virus scanning is enabled,  the header +X-Anti-Virus+ is added to messages
that have been scanned.  This is set to either +infected+ or +clean+.

The content of an email can be changed if it's marked as spam by @SpamAssassin@.
For example, you may wish to prepend an email's subject with `SPAM` to highlight
it in your inbox. To do this, append the following code block to the end of the
`/etc/exim4/system_filter` file:

--------------------------------------------------
if $h_X-Spam-Status: contains "spam"
then
    headers add "Old-Subject: $h_subject"
    headers remove "Subject"
    headers add "Subject: *** SPAM *** $h_old-subject"
    headers remove "Old-Subject"
endif
--------------------------------------------------

=== Using real-time blacklists from Spamhaus
(((Email, Spamhaus blocklists)))
(((Spamhaus)))

There are three lists from Spamhaus that can be used to reject email
based on the sender's IP address, namely

http://www.spamhaus.org/sbl[The Spamhaus Block List (SBL)]::  a list of addresses from which Spamhaus does not recommend receiving email.
http://www.spamhaus.org/xbl[The Exploits Block List (XBL)]:: a list of hijacked computers infected by third party exploits and viruses.
http://www.spamhaus.org/pbl[The Policy Block Lust (PBL)]:: a list of addresses that should not be sending unauthenticated email at all.

These lists are combined to form the Zen list.

The following instructions will enable use of these lists on our example domain
*my-brilliant-site.com*.

[procedure]
 - Connect to your machine using @FileZilla@
 - On the remote directory tree, navigate to
   [directory]'/srv/my-brilliant-site.com/config/'.
 - In this directory, create another directory called
   [directory]'blacklists/'.  This is done by clicking the right mouse
   button on the [directory]'config/' directory, and selecting |Create
   directory| from the menu that pops up.
 - On your local machine create a file called 'zen.spamhaus.org'.
   This is just an empty file.
 - Once this is done, navigate to the 'blacklists' directory on the
   remote file system, and select
   'zen.spamhaus.org' from the local file system, and upload it.  Make
   sure that the remote file has the correct name, i.e. no extra
   +.txt+ extension.

That is all that is needed to start using the Spamhaus Zen blacklist.
If you'd rather use a combination of lists create one or more of the
following files:

  * 'sbl.spamhaus.org' to enable the SBL list
  * 'xbl.spamhaus.org' to enable the XBL list
  * 'pbl.spamhaus.org' to enable the PBL list
  * 'sbl-xbl.spamhaus.org' to enable the combined SBL and XBL list
  * 'zen.spamhaus.org' to enable the combined SBL, XBL, and PBL list

=== Manually blocking incoming mail from specific sources
(((Email, Manually defined blocklists)))

While publicly maintained blacklists like spamhaus are much easier to rely on
and lower maintenance, at some point you might find occasion to block specific
email senders. Symbiosis allows blocking based on these criteria:

  * Hostname of sender, which is matched against the reverse DNS of the sender's IP. Example entry: '*.bad-domain.com'
  * IP of sender, which can be a single IP or a range specified in CIDR notation (be wary of blocking too much if you use this option). Example entry: '192.168.0.1'
  * Address of sender. This option may specify wildcard records, eg "*@example.com" will catch all emails from that domain. Please note this works on the "envelope from" rather than the "from" address. Example entry: 'bad_sender@example.com'.

To block with one of these criteria, you can use:

  * '/etc/exim4/blacklist/by_hostname' for eg '.bad-domain.com'
  * '/etc/exim4/blacklist/by_ip' for '192.168.0.1'
  * '/etc/exim4/blacklist/by_sender' for 'bad_sender@example.com'

Each entry to these files should be on a new line.

It is also possible to explicitly allow email from senders that would
otherwise be blacklisted by adding entries in similarly named files
under '/etc/exim4/whitelist'.

[[s-mail-rate-limiting]]
=== Rate limiting outbound email

Symbiois can now easily be configured to limit the number of outbound emails, either per-user, or per-domain.
You might want to rate limit to prevent anyone taking advantage of your server, maybe using it
to send out SPAM. The limit can be configured on a per-user basis with the following file :

'/srv/domain.com/mailboxes/bob/ratelimit'

and on a per-domain basis with the following file :

'/srv/domain.com/config/mailbox-ratelimit'

In both cases, the contents of the file should be a number, which represents the allowed limit per day.
If the file is left blank, the default of 100 is applied. Senders who breach this limit will
be sent an error email to explain why their message has not been sent, and discarded.

[[s-email-outbound-ip]]
=== Setting an outbound IP for all email from a domain

If the domain has a 'config/ip' file in place then the IP in that file
will be used for outgoing email.  This can be useful if your machine
has a number of IP addresses and you're suffering from deliverability
issues.
((config/,ip))

[[s-mail-configuration-roundcube]]
=== Installing Roundcube webmail

Roundcube is another webmail client which can be used with Symbiosis. To install
it, simply run:

  * @sudo apt-get install symbiosis-webmail-roundcube@

This will install the roundcube packages and set them up. MySQL credentials will
be required to complete the installation, and you should provide these to dpkg
when prompted.

After the install has completed, Roundcube will be the default webmail client,
accessible at @my-brilliant-site.com/webmail@ and all other domains hosted on the machine.

[[s-mail-configuraion-blocking]]
=== Blocking email

Symbiosis allows you to blacklist email senders by:

* email address (specific and wildcarded)
* by IP (specific and a range)
* by hostname (also specific or wildcarded).

Execute the following actions as `root` user rather than `admin`.

To block a specific email address, simply add the address to the file
`/etc/exim4/blacklist/by_sender`.

The `by_sender` list accepts email addresses like
`malefactor@example.com` or wildcarded ones like `*@example.com` to
block a whole domain. Note that this blacklist is matched against the
_Envelope Sender_ address, rather than the _From_ address.

To block by IP, add the IP address to `/etc/exim4/blacklist/by_ip`

The `by_ip` list accepts IP addresses like `192.168.66.6` or ranges like
`10.66.6.0/24`. This is used to blacklist by the IP address of the
connecting machine.

Finally the `by_hostname` list accepts hostnames like `bad.example.com`,
or wildcarded like `*.example.com`. This is used to blacklist against
the reverse DNS of the IP of the host connecting.

[[s-mail-configuration-layout]]
=== Configuration layout
(((Email, configuration layout)))

Here is an example configuration layout for the domain
'my-brilliant-site.com'.  All the following files are kept in
[directory]'/srv/my-brilliant-site.com/'.

[directory]'mailboxes/':: This is where
individual mailboxes are defined.  If this directory does not exist,
then mail will not be accepted for 'my-brilliant-site.com', unless a
default forwarding address or filter has been set up.
(((mailboxes/)))

[directory]'mailboxes/bob/':: Mail will be
accepted for the email address bob@my-brilliant-site.com.
(((mailboxes/, user/)))

[directory]'mailboxes/bob/Maildir/':: This
is where the email for bob@my-brilliant-site.com will be delivered. It
will be *created automatically* upon receipt of the first message to
that address.
(((mailboxes/,user/,Maildir/)))

'mailboxes/bob/password':: File containing
the password for bob@my-brilliant-site.com allowing him to collect his
email over IMAP/POP3, and relay email using SMTP. His username is the
same as his email address.  See <<s-email-passwords>> for more
information.
(((mailboxes/,user/,password)))

'mailboxes/bob/quota':: File containing the quota for a user.  The quota
should a number of bytes.  This can be followed by one of +k+, +M+, or +G+ to
specify kibibytes, mebibytes, or gibibytes respectively.  For example +100M+
would be 100 mebibytes, or 104857600 bytes.  See <<s-email-quotas>> for more
information.
(((mailboxes/,user/,quota)))

'mailboxes/bob/forward':: File containing
either a comma-separated list of addresses, or an Exim filter. All
mail addressed to bob@my-brilliant-site.com will be forwarded to the
list of addresses, or processed by the filter. See <<s-email-forward-files>>
for more information.
(((mailboxes/,user/,forward)))

'mailboxes/bob/vacation':: File containing
a vacation message for Bob.  See <<s-email-vacation-messages>> for more
information.
(((mailboxes/,user/,vacation)))

'mailboxes/bob/sieve':: File containing a Sieve filter.  This can be edited by
the user without shell access to the server.  See <<s-email-sieve>> for more
information.
(((mailboxes/,user/,sieve)))

'config/aliases':: This file contains a
list of aliases for a domain.  The format is the local username
followed by one or more spaces, and then comma separated list of email
addresses which should receive the mail.  See <<s-email-aliases>> for
more information.
(((config/,aliases)))

'config/default_forward':: File containing either a comma-separated list of
addresses, or an Exim filter. All mail addressed to the domain
my-brilliant-site.com for local parts without directories under mailboxes will
be forwarded to this address or processed by this filter. See
<<s-email-forward-files>> for more information.
(((config/,default_forward)))

'config/antispam':: If this file is
present, then all email for the domain my-brilliant-site.com will be
scanned by http://spamassassin.apache.org[@SpamAssassin@] to determine whether it is spam. If it is
spam, it will be rejected. If that file begins with the word tag, mail
will never be rejected, just tagged as usual.
(((config/,antispam)))

'config/mailbox-quota':: If this file is present, then all mailboxes
for this domain will have their quota determined by this file.  The quota
should a number of bytes.  This can be followed by one of +k+, +M+, or +G+ to
specify kilobytes, megabytes, or gigabytes respectively.  For example +100M+
would be 100 megabytes, or 100,000,000 bytes.  See <<s-email-quotas>> for more
information.
(((config/,mailbox-quota)))

'config/antivirus':: If this file is
present, then all email for the domain my-brilliant-site.com will be
scanned for viruses by http://www.clamav.net[@ClamAV@]. If a message is determined to contain a
virus, it will be rejected. If that file begins with the word tag,
mail will never be rejected, just tagged.
(((config/,antivirus)))

'config/blacklists/sbl.spamhaus.org':: Reject mail for
this domain if the sending machine's IP is listed in the
http://www.spamhaus.org/sbl[Spamhaus Block List].
(((config/,blacklists/,sbl.spamhaus.org)))

'config/blacklists/xbl.spamhaus.org':: Reject mail for
this domain if the sending machine's IP is listed in the
http://www.spamhaus.org/xbl[Spamhaus Exploits Block List].
(((config/,blacklists/,xbl.spamhaus.org)))

'config/blacklists/pbl.spamhaus.org':: Reject mail for
this domain if the sending machine's IP is listed in the
http://www.spamhaus.org/pbl[Spamhaus Policy Block List].
(((config/,blacklists/,pbl.spamhaus.org)))

'config/blacklists/sbl-xbl.spamhaus.org':: Reject mail
for this domain if the sending machine's IP is listed in either the
Spamhaus or the Exploits block lists.
(((config/,blacklists/,sbl-xbl.spamhaus.org)))

'config/blacklists/zen.spamhaus.org':: Reject mail for
this domain if the sending machine's IP is listed in the
http://www.spamhaus.org/zen/[Spamhaus Zen Block List], which is a
combination of the Spamhaus, Exploits, and Policy block lists.
(((config/,blacklists/,zen.spamhaus.org)))

