2.7. Configuring Inbound Email

Incoming mail destined for RT is processed through RT's mailgate, conveniently called rt-mailgate. When it is invoked, this script parses the incoming message, and transfers it to your main RT server for processing. The mailgate does not have to run on the same machine as your main RT server, as long as it can communicate with it via http or https.

MTAs have the ability to pass mail destined for particular addresses to a program instead of to a mailbox, and RT utilizes this. Unfortunately, this feature is configured differently for different MTAs. Most of them support Sendmail's traditional aliases format, so that's the format we'll be using for the examples in the following sections. A notable exception is qmail, which will be covered separately.

2.7.1. Mailgate Options

Several different command line options are supported by rt-mailgate (as shown in Table 2-3).

Table 2-3. Mailgate options

Option	Meaning
action=comment|correspond	Select whether this email should be processed as a comment or correspondence.
queue=QUEUENAME	Select which queue to process the email into.
url=URL OF RT INSTANCE	The URL of your RT instance.
debug	Print debugging messages.
extension=queue|action|ticket	Select the Queue, Action, or Ticket to operate on based on the $EXTENSION environment variable. For systems like Sendmail and Postfix which support rt+extension@host notation.
timeout=SECONDS	How many seconds to give up after. Defaults to 180.

2.7.2. Using the mailgate with Sendmail or Postfix

Sendmail's /etc/aliases file uses a simple name: value format, with the address receiving the mail on the left of the colon and the address to which it expands on the right hand side. The expansion address can be one of a few different types, including a different email address, a filename, or a program. There can be several expansion addresses as well, separated by commas.^[*] You must run the newaliases command after editing /etc/aliases.

^[*] This is a very simple way to implement mailing lists.

To specify a program to run when mail comes to an address you can use this syntax:

  correspond: "|/opt/rt3/bin/rt-mailgate --queue General --action correspond --url http://rt.example.com/" 

This passes the message to the script /opt/rt3/bin/rt-mailgate, which is configured with the command line arguments following the script name.

Modern versions of Sendmail require all programs called from the /etc/aliases file to be symlinked into the /etc/smrsh/ directory. You will receive DSN: Service unavailable errors if you haven't done this. Use the following command:

     # ln -s /opt/rt3/bin/rt-mailgate  /etc/smrsh/ 

Postfix sometimes stores its aliases file at /etc/postfix/aliases. This file is in the same format as Sendmail's. After editing it you must run Postfix's newaliases script.

2.7.3. Using the mailgate with qmail

Unlike Sendmail and Postfix, qmail uses specially-named files in a user's home directory to determine the handler for a message. Since you have already created a user account for RT, you can set that user up to process all RT-related mail. When qmail's delivery agent tries to figure out what to do with an incoming message for a user, it first looks to see if there is an extension to the username. By default, this extension is separated from the username by a dash (-), so you could have [e-mail], where rt is the username and foo is the extension. If there is an extension, then qmail will look in the rt user's ~/.qmail-foo file for delivery instructions. Otherwise, it looks in the rt user's ~/.qmail file.

To set up mail delivery into RT, you can create a series of .qmail files, two for each queue (for responses and comments). For example, the General queue would be handled by these files:

     # cat ~rt/.qmail-general  |/opt/rt3/bin/rt-mailgate --queue General --action correspond --url http://rt.example.com/           # cat ~rt/.qmail-general-comment  |/opt/rt3/bin/rt-mailgate --queue General --action comment --url http://rt.example.com/ 

With these files in place, mail sent to [e-mail] will become correspondence in the General queue, and mail sent to [e-mail] will become comments in the General queue.

You also can create a catch-all .qmail-default file:

     # cat ~rt/.qmail-default  |/opt/rt3/bin/rt-mailgate --queue $DEFAULT --action correspond --url http://rt.example.com/ 

Anything sent to rt-queuename will be delivered as correspondence to the queuename queue.

Note the rt- at the beginning of each address; that is because the mail is actually being sent to the rt user and handled using qmail's convenient features. Setting up qmail so that these messages are handled globally, and not by a particular user, is a little different. Rather than a global /etc/aliases file, like the other MTAs use, qmail has a general alias user that handles all system-wide aliases. To make this user handle mail for RT, simply create the files ~alias/.qmail-general and ~alias/.qmail-general-comment with the same content as before. This allows the RT addresses to be [e-mail] and [e-mail]. Under RT2, the mail handling script had to be setgid to the rt group, so the user restriction was important, but under RT3, this is no longer the case.

2.7.4. Using the mailgate with procmail

You also can call the mailgate from procmail. This allows you to perform virus or spam filtering before mail gets to RT. This can be very important because RT addresses are often published in places where spam-crawlers can find them.

Here's an example procmail file that performs spam and virus filtering with SpamAssassin and ClamAV:

     CLAMSCAN=`/usr/bin/clamscan --mbox --disable-summary --stdout -`           :0 iD     * CLAMSCAN ?? FOUND     viruses           :0fw     | spamassassin           :0 H     * ^X-Spam-Status: Yes     spam           :0     * ^TO_rt-general@  | /opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/           :0     * ^TO_rt-general-comment@  | /opt/rt3/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/ 

This file will send all messages to [e-mail] to the general queue as correspondence, and all messages to [e-mail] to the general queue as a comment. With a little bit of procmail magic, you can do much more powerful filtering and mail direction, but that's beyond the scope of this book.

For more information on procmail, try The Procmail Companion (Addison Wesley), or visit http://procmail.org/ for more procmail resources.