MailChannels: Setup Qmail – Help Center

Overview

This guide provides instructions on how to configure the qmail Mail Transfer Agent (MTA) to relay outbound email through the MailChannels Outbound Filtering service. This involves setting up SMTP authentication, ensuring the correct headers are added for sender identification, and routing mail to MailChannels.

Important: Configuring qmail to use MailChannels Outbound Filtering can be a complex process due to qmail's modular structure. Please proceed with caution and ensure you understand the changes you are making to your qmail configuration. These instructions aim to be comprehensive but may not cover every specific qmail setup.

Audience: Server administrators managing qmail servers. Familiarity with qmail configuration, control files, and patching processes is essential.

Prerequisites:

Root access to your qmail server.
Your MailChannels SMTP username and password.
qmail patched to enable SMTP authentication (AUTH SMTP). If you have not already done this, you will need to consult relevant qmail documentation or guides to apply the necessary patches (e.g., SMTPAUTH for qmail).
qmail patched with the qmailqueue patch (e.g., Bruce Guenter's patch) or a similar mechanism to modify messages or headers before they are queued.

Configuration Steps

The process involves ensuring your qmail installation can authenticate with MailChannels and add a vital X-AuthUser header, then configuring it to use MailChannels as a smarthost.

1. Configure the X-AuthUser Header

This header is crucial for MailChannels to identify the responsible user or script in your system if problematic email is sent. The following steps outline one common method using Bruce Guenter's qmailqueue patch and qmail-qfilter.

Install a qmail filter program like qmail-qfilter: Apply Bruce Guenter's qmail-qfilter, If not already applied. Download the patch (commonly found by searching for "qmailqueue-patch") and apply it to your qmail source.
Recompile qmail after applying the patch.
Modify your qmail-smtpd run script:
- Locate your qmail-smtpd run script (e.g., /service/qmail-smtpd/run or /var/qmail/supervise/qmail-smtpd/run).
- Add or modify the QMAILQUEUE environment variable definition to point to your filter script. This line should be placed before the exec qmail-smtpd line:
```
export QMAILQUEUE="/var/qmail/bin/qmail-authuser-filter.sh"
```

Create the qmail-authuser-filter.sh script:

- Create the file /var/qmail/bin/qmail-authuser-filter.sh.
- Make it executable:
```
chmod +x /var/qmail/bin/qmail-authuser-filter.sh
```
- Ensure it's owned by the user that qmail-smtpd runs as if necessary, though often it's executed before qmail-smtpd drops privileges.
- Add the following content:
```
#!/bin/sh
# This script passes the email through qmail-qfilter with our perl script.
exec /usr/local/bin/qmail-qfilter /var/qmail/bin/qmail-authuser-header.pl
```
  Note: Adjust the path to qmail-qfilter if it's installed elsewhere.

Create the qmail-authuser-header.pl Perl script:

Create the file /var/qmail/bin/qmail-authuser-header.pl.
Make it executable: chmod +x /var/qmail/bin/qmail-authuser-header.pl.

Add the following content:

#!/usr/bin/perl
# This script adds the X-AuthUser header using the TCPREMOTEINFO environment variable.
# TCPREMOTEINFO should be set by tcpserver to the authenticated user.

my $auth_user = $ENV{'TCPREMOTEINFO'};

if ($auth_user) {
    print "X-AuthUser: $auth_user\n";
} else {
    # Fallback if TCPREMOTEINFO is not set, though it should be for authenticated senders.
    # Consider logging this or using a default/unknown value if appropriate for your setup.
    # For MailChannels, an identifiable user is preferred.
    my $fallback_user = $ENV{'SMTPREMOTEIP'} || "unknown_sender";
    print "X-AuthUser: $fallback_user\n";
}

# Print the rest of the email
while(<STDIN>) {
    print;
}
exit 0; # Exit 0 to ensure qmail-qfilter passes the message on.

Note: For this script to effectively capture the authenticated user, your tcpserver setup for qmail-smtpd (often in the run script) must correctly set TCPREMOTEINFO upon successful SMTP authentication. This usually involves tcpserver options that enable user identification after AUTH.
Warning: Modifying qmail configuration files, applying patches, and creating scripts incorrectly can disrupt email services. Proceed with extreme caution. Always back up your configuration files and qmail source before making changes. Test thoroughly in a non-production environment if possible.

2. Set up MailChannels Outbound Filtering as a Smart Host

This step configures qmail to route all outgoing mail (except for explicitly local domains) to the MailChannels SMTP servers using the credentials you've been provided.

Edit or create the smtproutes file:
- Locate or create your smtproutes file. This is typically /var/qmail/control/smtproutes.

- To route all external email through MailChannels, add the following line:
  :smtp.mailchannels.net:25 YourMailChannelsUsername YourMailChannelsPassword
- Replace YourMailChannelsUsername and YourMailChannelsPassword with the actual SMTP credentials provided by MailChannels.
- If outbound TCP port 25 is blocked in your network, you can use alternative ports 587 or 2525. For example:
  :smtp.mailchannels.net:587 YourMailChannelsUsername YourMailChannelsPassword
- Important: The leading colon : means this rule applies to all domains not matched by more specific entries in smtproutes and not listed in /var/qmail/control/locals.

3. Restart qmail Services

After making all the configuration changes, you must restart the relevant qmail services for the new settings to take effect. The command to restart qmail can vary depending on how it was installed and is managed on your system (e.g., using qmailctl, svc, or specific init scripts).

A common command is:

qmailctl restart

Or, if managing services individually (e.g., with daemontools):

svc -t /service/qmail-smtpd
svc -t /service/qmail-send

Consult your qmail installation documentation for the precise commands.

Optional qmail Configurations (Advanced)

These settings can help you manage the qmail queue, control how qmail identifies itself, and adjust resource usage. These are configured by creating or editing files in the /var/qmail/control/ directory. Remember to restart qmail (specifically qmail-send for most of these, or a full qmailctl restart) after making changes.

Queue Lifetime (queuelifetime):
- Function: Defines the total time (in seconds) a message can remain in the queue before qmail stops trying to deliver it and sends a bounce.
- Default: 604,800 seconds (7 days).
- Configuration: To change this, create or edit /var/qmail/control/queuelifetime and place a number representing the desired seconds. For example, for 2 days (172,800 seconds):
```
echo "172800" > /var/qmail/control/queuelifetime
```
  Shorter lifetimes mean users are notified of permanent failures sooner, but might give up on transient issues too quickly. Longer lifetimes allow more retry attempts for hosts that are temporarily down.

Server Identity (me and helohost):
- me File:
  - Function: This critical file defines the Fully Qualified Domain Name (FQDN) of your mail server. It's used as the default for many qmail operations, including the HELO name if helohost isn't set.
  - Configuration: Ensure /var/qmail/control/me contains the primary FQDN of your mail server (e.g., mail.yourdomain.com).
```
echo "mail.yourserver.example.com" > /var/qmail/control/me
```
    This FQDN should have a valid A record in DNS, and ideally, a matching rDNS (PTR) record for your server's sending IP.

helohost File (Optional):
- Function: Specifies the hostname qmail-remote uses in the SMTP HELO/EHLO command. If this file doesn't exist, the value from me is used.
- Configuration: If you need a specific HELO name different from me (though usually they should align), create /var/qmail/control/helohost:
```
echo "smtp-out.yourserver.example.com" > /var/qmail/control/helohost
```
  Ensure this is also a valid, resolvable FQDN.

Delivery Concurrency:
- Remote Delivery Concurrency (concurrencyremote):
  - Function: Controls the maximum number of simultaneous remote SMTP delivery processes qmail-send will start.
  - Default: Usually 20 (compile-time limit often 120).
  - Configuration: Adjust based on your server's resources and network capacity. For a busier server, you might increase it:
```
echo "50" > /var/qmail/control/concurrencyremote
```

Local Delivery Concurrency (concurrencylocal):
- Function: Controls the maximum number of simultaneous local delivery processes.
- Default: Usually 10.
- Configuration:
```
echo "20" > /var/qmail/control/concurrencylocal
```

Connection Timeouts (for qmail-remote):
- timeoutconnect:
  - Function: Number of seconds qmail-remote will wait for the remote SMTP server to accept a connection.
  - Default: 60 seconds.
  - Configuration: /var/qmail/control/timeoutconnect
```
echo "30" > /var/qmail/control/timeoutconnect
```

timeoutremote:
- Function: Number of seconds qmail-remote will wait for each response from the remote SMTP server after the initial connection.
- Default: 1200 seconds (20 minutes).
- Configuration: /var/qmail/control/timeoutremote
```
echo "600" > /var/qmail/control/timeoutremote
```

Verify Configuration and Monitor

After configuring qmail and restarting the services:

Send Test Emails: Send emails from an account on your server to various external email addresses (e.g., Gmail, Outlook.com).
Check Mail Logs:

Examine your qmail logs (locations vary, often under /var/log/qmail/ or managed by multilog to directories like /var/log/qmail/qmail-send/current and /var/log/qmail/qmail-smtpd/current).
Look for lines indicating successful delivery via smtp.mailchannels.net.
Check for any error messages related to authentication or relaying.

Review MailChannels Host Console:

Log in to your MailChannels Host Console.
- Check the "Log Search" and "Activity" sections to see if your test messages are being processed.
- Verify that the X-AuthUser header is present and correctly identifies the sender as you expect. The senderID value's third field will contain the value Qmail insert into the X-AuthUser header.
Test Bounces (Optional but Recommended):
- Send an email to a deliberately non-existent address at a remote domain to see if bounces are processed correctly and returned via MailChannels.

Consistent monitoring of your mail logs and the MailChannels console is crucial, especially after making configuration changes, to ensure smooth operation and to quickly identify any issues with sender authentication or mail flow.