Chapter 16. Email Configuration

Table of Contents

16.1. Port Configuration
16.2. Accepting email for a domain
16.3. Email for Unix users.
16.4. Password files
16.5. Suffixes
16.6. Enforcing mailbox size with quotas
16.7. Server-side filtering using Sieve
16.8. Forward files
16.9. Vacation messages
16.10. Email alias lists
16.11. Customising SpamAssassin
16.12. Filtering mail using headers
16.13. Using real-time blacklists from Spamhaus
16.14. Manually blocking incoming mail from specific sources
16.15. Installing Roundcube webmail
16.16. Configuration layout

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 /srv/my-brilliant-site.com/ directory.

16.1. Port Configuration

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

Service Port Encryption

POP3

110

TLS

IMAP

143

TLS

SMTP

25 or 587

TLS

POP3

995

SSL

IMAP

993

SSL

SMTP

465

SSL

Sieve

4190

TLS

16.2. Accepting email for a domain

In order for a domain to be configured to accept email, one of two things must be present. Either the domain must have a 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 /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 /srv/my-brilliant-site.com/mailboxes/bob/ should be created.

Assuming that this is the only directory inside /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.

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.

If you would like the domain nomail.my-brilliant-site.com not to receive any mail at all, then remove the 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.

16.3. Email for Unix users.

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 latter half of 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/. This can contain either a plaintext password (not recommended) or a password encrypted with the symbiosis-encrypt-password utility.

Once the password file is in place, the new user will start to be able to start receiving email. Logins over SMTP, IMAP, and POP3 will all work identically to a normal email user, with the same ports and SSL/TLS requirements.

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.

16.4. Password files

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.

To encrypt a password on the command line, you can run the following command, substituting "my password" for your password. This encrypts the password using the SHA-512 algorithm.

echo "my password" | symbiosis-encrypt-password  > password

This just uses the standard crypt function available under most Linux platforms, as well as perl and PHP.

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

For example, Bob signs up to a shopping site at http://example.com. He might use bob+example@my-brilliant-site.com his email address when signing up, such that he can filter all email from that shop.

16.6. Enforcing mailbox size with quotas

Symbiosis can enforce users' mailbox size with quotas. This will prevent mail from being delivered to a user if their mailbox grows too large.

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.

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.

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

16.7. Server-side filtering using Sieve

Sieve is a standard language that users can employ to filter their email on the server. Additionally using any one of a number of 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 sieve.d/, with the current script being kept in a file called 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.

16.8. Forward files

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.

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.

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

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 Exim documentation has further examples of what is possible.

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

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.

Important

Vacation messages can cause 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.

16.10. Email alias lists

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 config/ directory and is named 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.

16.11. Customising 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 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 SpamAssassin wiki.

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

16.12. Filtering mail using 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 ++++++; 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.

16.13. Using real-time blacklists from Spamhaus

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

The Spamhaus Block List (SBL)
a list of addresses from which Spamhaus does not recommend receiving email.
The Exploits Block List (XBL)
a list of hijacked computers infected by third party exploits and viruses.
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.

  1. Connect to your machine using FileZilla

  2. On the remote directory tree, navigate to /srv/my-brilliant-site.com/config/.

  3. In this directory, create another directory called blacklists/. This is done by clicking the right mouse button on the config/ directory, and selecting Create directory from the menu that pops up.

  4. On your local machine create a file called zen.spamhaus.org. This is just an empty file.

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

16.14. Manually blocking incoming mail from specific sources

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.

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

16.16. Configuration layout

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

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/bob/
Mail will be accepted for the email address bob@my-brilliant-site.com.
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/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 Section 16.4, “Password files” for more information.
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 Section 16.6, “Enforcing mailbox size with quotas” for more information.
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 Section 16.8, “Forward files” for more information.
mailboxes/bob/vacation
File containing a vacation message for Bob. See Section 16.9, “Vacation messages” for more information.
mailboxes/bob/sieve
File containing a Sieve filter. This can be edited by the user without shell access to the server. See Section 16.7, “Server-side filtering using Sieve” for more information.
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 Section 16.10, “Email alias lists” for more information.
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 Section 16.8, “Forward files” for more information.
config/bytemark-antispam
This file indicates use of Bytemark’s wholesale anti-spam service, which is no longer provided.
config/antispam
If this file is present, then all email for the domain my-brilliant-site.com will be scanned by 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. See the section called “Scanning email to prevent spam and viruses” more information.
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 Section 16.6, “Enforcing mailbox size with quotas” for more information.
config/antivirus
If this file is present, then all email for the domain my-brilliant-site.com will be scanned for viruses by 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. See the section called “Scanning email to prevent spam and viruses” for more information.
config/blacklists/sbl.spamhaus.org
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Block List.
config/blacklists/xbl.spamhaus.org
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Exploits Block List.
config/blacklists/pbl.spamhaus.org
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Policy Block List.
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/zen.spamhaus.org
Reject mail for this domain if the sending machine’s IP is listed in the Spamhaus Zen Block List, which is a combination of the Spamhaus, Exploits, and Policy block lists.