Topaz email system user's Manual

Introduction

Most of the Unix traditions in mail are respected, and greatly extended. The main deviation is that by default mail comes to $HOME/Maildir/, and not to /var/mail/login.

You have an email address login@agate.conuropsis.org where login is your username on the machine. Please read that address sometimes, that is where our announces go. You are naturally free to redirect it to another address should you wish so. (Create a file .forward in your home with the address you wish to redirect to.)

You can also have any address login-FOO@agate.conuropsis.org you wish. See below.

You can also have a complete virtual mail domain for you, eventually shared with other user. Most advanced features (such as sender grey/blacklisting, anti-virus checks, etc) are only available on virtual domains. The conuropsis.org domain is such a virtual domain.

Agate uses the Exim4 mail system. .forward files thus support, in addition to the standard Unix contents of a list of email addresses, files and/or directories, a rather powerful filtering (programming) language. See /usr/share/doc/exim4/filter.txt.gz for the full documentation of it.

A .procmailrc will automatically get used. No need to futz with your .forward just for that. The same for maildrop.

You can test your changes without actually sending mail with the "/usr/sbin/exim4 -bt address_to_test@domain" command.

Alias-like files

All conuropsis-specific extensions are implemented, unless noted otherwise, by alias-like files. These are files whose syntax is similar to the classic /etc/aliases, that is lines of the form

lhs: rhs

where lhs is the key. For files that configure a domain, this is the localpart (left of the @) of the address. For files that configure one user's email (through delegation from a domain or for the agate.conuropsis.org domain), these are the extension part of the address, that is the part following the -, including the - itself. In that case, the extension part can naturally be empty.

The lhs can contain wildcards, or (perl-compatible syntax) regular expressions starting with ^. In exact terms, the lookup into these files are Exim nwildlsearch. See info --node='(exim4)Single-key lookup types' for the full possibilities.

Extension addresses

• an email address. Mail is then forwarded to this email. The domain agate.conuropsis.org is appended if no domain is given.
• A pipe construct.
• A filename, starting with "/". Mail gets delivered to that file, in UNIX mbox format, with "From "-line escaping.
• A directory name, starting with AND ending by "/". Mail gets delivered to that directory in Maildir format.
• an email local part (without @domain), with prepended "\". Mail is forwarded to local_part in the same domain.
• the string ":blackhole:", in which case mail to that address is thrown away.
• the string ":defer:" to queue the mail, but not do any delivery.
• the string ":fail:" to force delivery to fail. Any text following ":fail:" or ":defer:" is placed in the error text associated with the failure. You can also give an SMTP response code.
• the string ":unknown:" to force "lhs at example.tld" not to exist.
• and other things, too, read the exim documentation of you want: Sections 22.4 to 22.7.

Your own domain: basics

The configuration of a domain happens in PREFIX/srv/email/DOMAIN, where PREFIX is your home for domains assigned to one user and the group's home (/home/groups/GROUP) for domains shared by users. A specific localpart can be delegated to another user by listing that localpart in the delegations file. You must then install a symlink from that localpart to a directory in ~USER/srv/email/DOMAIN. Lookups in that directory are then done on the extension part only. (That is, the user that got a localpart delegated must match the empty lhs to use the address without any extension part). All features are delegated, including blacklists, greylists, virus scanning, ...

The aliases file decides what to do with email in that domain. lhs is the localpart being matched, rhs is a list of email addresses (agate.conuropsis.org added if no domain given), or the string ":relay:" to relay the mail to a lower MX (subject to a callout).

You can suspend delivery to the domain by creating a file named "lock" in the domain configuration directory. This ensures that no mail will bounce because of a syntax error / half-done changes to the aliases file while you are changing it. Don't forget to remove it after! It doesn't get obsoleted automatically, and after time-out time is reached, the emails queued will bounce.

Delegation

Extension addresses

Sender verification

By default, before accepting a mail, we (try to) check that the sender (envelope from) address does exist, as well as the postmaster address in the same domain. You can whitelist (exempt) addresses from this check in the file /etc/exim/virtual/domain.tld/sender_verify_whitelist. This file has the usual “aliases-file like” syntax. The rhs is supposed to contain an (eventually empty) address list. Exim address lists are documented in info '--node=(exim4)Address lists'.

You can also tweak the options of the check, e.g. disable callouts or postmaster callouts, in the /etc/exim/virtual/domain.tld/sender_verify_options file. A match in this file replaces the default options completely. Again, this file as the usual “aliases-file like” syntax.

Each user of a virtual mail domain can have a list of blocked senders. The file /etc/exim/virtual/domain.tld/sender_blacklist is an “alias-like” file where the lhs is the recipient, eventually wildcarded, and the rhs an address list to be blacklisted.

DNS Blacklisting

Each user of a virtual mail domain can use several realtime blockhole lists (rbl). See for example this article for a definition. The file /etc/exim/virtual/domain.tld/dns_blacklist_table is an “alias-file like” file where the lhs is the recipient, eventually wildcarded, and the rhs is a colon-separated list of rbl to use.

For example if you want user foo in your domain to use dnsbl sbl.spamhaus.org and dnsbl.njabl.org you would add a line:

foo:	sbl.spamhaus.org:dnsbl.njabl.org

DNS Greylisting (somewhat)

Each user of a virtual mail domain can use several realtime blockhole lists (rbl) whose address lists will be used to activate greylisting against a given sending host. See this description of greylisting. The file /etc/exim/virtual/domain.tld/dns_greylist_table is an “alias-file like” file where the lhs is the recipient, eventually wildcarded, and the rhs is a colon-seperated list of rbl to use.

For example if you want user foo in your domain to use dnsbl sbl.spamhaus.org and dnsbl.njabl.org you would add a line:

foo:	sbl.spamhaus.org:dnsbl.njabl.org

This means that when an host is trying to send an email to foo and the address of the sending host is listed in sbl.spamhaus.org or dnsbl.njabl.org, then this transaction will be greylisted (the first attempt will get a temporary reject, and if an attempt occurs within a timeframe of less than 2 days and more than 5 minutes, then further identical transactions within the following two months will be accepted without more delay). This feature was added to make a good use of rbl even if you don't trust them enough to block mail outright.

Mail scanning

Topaz has malware (virus, worms, etc) and MIME defect scanning possibilities for email. The idea of the latter is that these MIME defects may be a way to get past the malware scanner. They are not enabled by default. If you have a shell account, you can manage the settings yourself.

Matching messages can be either denied (topaz doesn't accept to take them at all) or just tagged (a header is added).

The configuration files use /etc/aliases syntax (see the previous section of this document), with wildcarding extensions.

• To deny malware-containing messages, put a rhs of ":deny:" in /etc/exim/virtual/domain.tld/malware.
• To tag malware-containing messages, put a rhs of ":tag:" in /etc/exim/virtual/domain.tld/malware. A header X-Topaz-Malware: Yes (name_of_detected_malware) will be added.
• To deny MIME-defective messages, put a rhs of ":yes:N" in /etc/exim/virtual/domain.tld/demime_deny, where N is a number between 0 and 3 (inclusive). Messages whose defect level is above N will be denied. You can also leave N out, a default value will then be used.
• To tag MIME-defective messages, put a rhs of ":yes:N" in /etc/exim/virtual/domain.tld/demime_tag, where N is a number between 0 and 3 (inclusive). Messages whose defect level is above N will be tagged. You can also leave N out, a default value will then be used. A header X-Topaz-MimeErrorLevel: error_level (description of error) will be added.

The defect level is the one given by the demime facility of Exim.