Install and Configure a Courier MTA Mail Server on Debian

Introduction

This guide explains how to install and configure a Courier MTA mail server on Debian. It covers SMTP and IMAP services, virtual mail users, aliases, mail relaying, authentication and troubleshooting. We will also secure email communications using TLS encryption and SSL/TLS certificates.

Test Environment

This guide was originally tested with the following software versions:

• Operating system: Debian 7.8 “Wheezy”
• Courier MTA: 0.68
• Courier IMAP: 4.10

Install Courier MTA and IMAP

Install Courier MTA, the secure SMTP and IMAP services, and the Gamin file monitoring utility:

root@host:~# apt-get update
root@host:~# apt-get install gamin courier-mta courier-mta-ssl courier-imap courier-imap-ssl

If you plan to provide POP3 access, install the corresponding Courier packages:

root@host:~# apt-get update
root@host:~# apt-get install courier-pop courier-pop-ssl

Configure Courier Authentication

Configure Courier to use its UserDB authentication backend. Edit the /etc/courier/authdaemonrc file and set the following value:

authmodulelist="authuserdb"

Courier UserDB stores virtual user account information in a database based on the Berkeley DB format.

Create the Virtual Mail User

To avoid creating a separate system account for each mailbox, create a dedicated system user named vmail. This account will own the mail directories for all virtual users.

root@host:~# useradd --system --uid 7200 --home-dir /data/vmail \
  --create-home --shell /usr/sbin/nologin vmail

Create the directory that will contain the Courier UserDB source files, then restrict access to the root user:

root@host:~# mkdir -p /etc/courier/userdb
root@host:~# chmod 700 /etc/courier/userdb

Create a Virtual Mail User

Add the virtual mailbox user1@domain1 to the UserDB file for domain1. The uid and gid values must match the identifiers assigned to the vmail account:

root@host:~# userdb -f /etc/courier/userdb/domain1 \
  user1@domain1 set \
  home=/data/vmail/domain1/user1 \
  mail=/data/vmail/domain1/user1/Maildir \
  uid=7200 \
  gid=7200

Set the Virtual User Password

Generate and store the password hashes used to authenticate the virtual mailbox:

root@host:~# userdbpw -md5 | \
  userdb -f /etc/courier/userdb/domain1 \
  user1@domain1 set systempw

root@host:~# userdbpw -hmac-sha1 | \
  userdb -f /etc/courier/userdb/domain1 \
  user1@domain1 set hmac-sha1pw

Create the User Maildir

Create the directory structure that will store the virtual mailboxes. In this example, all mail data is stored under /data/vmail.

root@host:~# mkdir -p /data/vmail/domain1
root@host:~# chown -R vmail:vmail /data/vmail
root@host:~# chmod 750 /data/vmail
root@host:~# chmod 750 /data/vmail/domain1

The resulting directory permissions should be similar to the following:

• /data: owned by root:root, with permissions 755
• /data/vmail: owned by vmail:vmail, with permissions 750
• /data/vmail/domain1: owned by vmail:vmail, with permissions 750

Create the mailbox directory for user1@domain1 and initialize its Maildir structure as the vmail user:

root@host:~# install -d -o vmail -g vmail -m 750 /data/vmail/domain1/user1
root@host:~# runuser -u vmail -- maildirmake /data/vmail/domain1/user1/Maildir

The maildirmake command creates the standard cur, new and tmp subdirectories required by the Maildir format.

Build the User Database

Ensure that the Courier UserDB directory and its source files are accessible only to the root user:

root@host:~# chmod 700 /etc/courier/userdb
root@host:~# chmod 600 /etc/courier/userdb/*

Compile the UserDB source files into the database used by Courier:

root@host:~# makeuserdb

Restart the Courier authentication service to apply the changes:

root@host:~# /etc/init.d/courier-authdaemon restart

Test authentication for the virtual mailbox:

root@host:~# authtest user1@domain1

Configure Email Aliases

Courier aliases redirect one email address to another. Edit the alias file associated with the hosted domain, for example /etc/courier/aliases/domain1:

alias@domain1: user1@domain1

Check the alias configuration without rebuilding the database:

root@host:~# makealiases -chk

If no error is reported, compile the alias database:

root@host:~# makealiases

Display the aliases currently stored in the compiled database:

root@host:~# makealiases -dump

Configure Local and Hosted Domains

Define the hostnames that Courier must treat as local. The /etc/courier/locals file should contain the local hostnames of the mail server:

root@host:~# echo "localhost" > /etc/courier/locals
root@host:~# echo "mail.domain1" >> /etc/courier/locals

Next, configure the email domains hosted by the server. Create one file for each hosted domain in the /etc/courier/hosteddomains directory:

root@host:~# mkdir -p /etc/courier/hosteddomains
root@host:~# echo "domain1" > /etc/courier/hosteddomains/domain1
root@host:~# makehosteddomains

Configure Courier SMTP to accept incoming messages addressed to domain1:

root@host:~# mkdir -p /etc/courier/esmtpacceptmailfor.dir
root@host:~# echo "domain1" > /etc/courier/esmtpacceptmailfor.dir/domain1
root@host:~# makeacceptmailfor

Configure an Outgoing SMTP Relay

If the server cannot deliver messages directly to recipient mail servers, Courier can forward all outgoing email through an external SMTP relay, also known as a smarthost. This may be required by your internet service provider or hosting provider.

Edit the /etc/courier/esmtproutes file and define the relay server:

: smtp.domain1

The colon at the beginning of the line applies the route to all destination domains. To use a specific TCP port, append it to the relay hostname:

: smtp.domain1,587

If the SMTP relay requires authentication, add the corresponding credentials to /etc/courier/esmtpauthclient:

smtp.domain1,587 username password

Restrict access to the authentication file because it contains the relay password in plain text:

root@host:~# chown root:root /etc/courier/esmtpauthclient
root@host:~# chmod 600 /etc/courier/esmtpauthclient

Enable SMTP TLS and Authentication

Edit /etc/courier/esmtpd to configure the SMTP service, enable STARTTLS and define the supported authentication mechanisms.

Check or update the following parameters:

COURIERTLS=/usr/bin/couriertls
TLS_CERTFILE=/etc/courier/esmtpd.pem
TLS_TRUSTCERTS=/etc/ssl/certs
TLS_VERIFYPEER=NONE

ESMTPAUTH="PLAIN LOGIN"
ESMTPAUTH_TLS="PLAIN LOGIN"

ESMTPDSTART=YES

The TLS_CERTFILE file must contain the SMTP server certificate and its unencrypted private key. It must not be readable by unprivileged users.

root@host:~# chown root:root /etc/courier/esmtpd.pem
root@host:~# chmod 600 /etc/courier/esmtpd.pem

Require TLS 1.2 or Later

Configure Courier to accept only TLS 1.2 or later. Edit /etc/courier/esmtpd and set:

TLS_PROTOCOL="TLSv1.2+"

Enable IMAP IDLE

The IMAP IDLE extension allows compatible email clients to receive mailbox updates without repeatedly polling the server. For example, clients can be notified when a message is added, removed or marked as read.

Edit /etc/courier/imapd and check that the following parameters are enabled:

IMAP_CAPABILITY="IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE"
IMAP_USELOCKS=1
IMAP_ENHANCEDIDLE=1

Restart the Courier IMAP service to apply the changes:

root@host:~# /etc/init.d/courier-imap restart

See the Courier IMAP documentation for more information.

Set the Maximum Email Size

Courier reads the maximum accepted message size, expressed in bytes, from /etc/courier/sizelimit. The following example sets a limit of 50 MiB:

root@host:~# echo "52428800" > /etc/courier/sizelimit

Configure a Catch-All Address

A catch-all address receives messages sent to addresses that do not otherwise exist in a hosted domain. In this example, all unmatched messages for domain1 are delivered to the mailbox associated with the virtual user alias@domain1.

Ensure that the catch-all mailbox exists, then create its default Courier delivery instruction:

root@host:~# install -d -o vmail -g vmail -m 750 /data/vmail/domain1/alias
root@host:~# runuser -u vmail -- maildirmake /data/vmail/domain1/alias/Maildir
root@host:~# printf '%s\n' "./Maildir" > /data/vmail/domain1/alias/.courier-default
root@host:~# chown vmail:vmail /data/vmail/domain1/alias/.courier-default
root@host:~# chmod 600 /data/vmail/domain1/alias/.courier-default

Authorize SMTP Relay for Trusted Clients

By default, Courier should only accept messages addressed to domains hosted by the server. To allow a trusted device or application to relay messages to external domains without SMTP authentication, add its IP address to the Courier SMTP access rules.

Create or edit a file in /etc/courier/smtpaccess, for example /etc/courier/smtpaccess/trusted-clients:

root@host:~# nano /etc/courier/smtpaccess/trusted-clients

Add the trusted client IP address followed by a tab character and the allow,RELAYCLIENT rule:

192.168.1.50<TAB>allow,RELAYCLIENT

Rebuild the Courier SMTP access database:

root@host:~# makesmtpaccess

Restart the Courier SMTP services to apply the new rule:

root@host:~# /etc/init.d/courier-mta restart
root@host:~# /etc/init.d/courier-mta-ssl restart

Archive Maildir Messages by Date

The following example moves messages whose Date header contains the year 2012 to the .Sent.2012 Maildir folder.

First, create the destination Maildir folder if it does not already exist:

root@host:~# runuser -u vmail -- maildirmake /data/vmail/domain1/user1/Maildir/.Sent.2012

Move to the cur directory containing the messages to archive:

root@host:~# cd /data/vmail/domain1/user1/Maildir/.Sent/cur

Before moving any messages, display the files whose Date header contains 2012:

root@host:~# find . -maxdepth 1 -type f -print0 | \
  while IFS= read -r -d '' message; do
    if grep -qm1 '^Date:.*2012' "$message"; then
      printf '%s\n' "$message"
    fi
  done

After checking the results, move the matching messages to the destination folder:

root@host:~# find . -maxdepth 1 -type f -print0 | \
  while IFS= read -r -d '' message; do
    if grep -qm1 '^Date:.*2012' "$message"; then
      mv -- "$message" ../../.Sent.2012/cur/
      printf 'Moved: %s\n' "$message"
    fi
  done

Useful Courier MTA Commands

• Display the current mail queue:

root@host:~# mailq

• Display the files stored in the Courier mail spool:

root@host:~# ls -Rhl /var/lib/courier/msgs/

• Remove a specific message from the queue:

root@host:~# cancelmsg message-id

• Remove all messages from the queue:

root@host:~# mailq | awk '/^[[:space:]]*[0-9A-F]+\./ { print $2 }' | \
  while IFS= read -r message_id; do
    cancelmsg "$message_id"
  done

References

• Official Courier Mail Server documentation
• Courier mail queue and delivery documentation
• Courier IMAP documentation
• ArchWiki: Courier MTA