After following this article you will have a complete email solution for your (ve) Server using the following open-source technologies:

Postfix -- the MTA (Mail Transfer Agent) 
Courier -- the IMAP/POP3 service 
MySQL -- the database that will house your users and domains

NOTE: All of the steps below will use example.com for the domain. Please change where appropriate.

Installing needed packages

• Ensure that you have the universe repositories @ /etc/apt/pres.list enabled. They are enabled by default:

admin@wiki:~# cat /etc/apt/pres.list
deb http://archive.ubuntu.com/ubuntu karmic main restricted universe
deb http://archive.ubuntu.com/ubuntu karmic-updates main restricted universe
deb http://archive.ubuntu.com/ubuntu karmic-security main restricted universe
admin@wiki:~#

If you had to make any changes to your repository make sure to run the following commands to update your packages:

sudo apt-get update
sudo apt-get upgrade

• Now it's time to actually install all the packages we need using the apt-get command:

sudo apt-get install courier-authdaemon courier-authlib-mysql courier-pop courier-pop-ssl courier-imap courier-imap-ssl postfix postfix-mysql postfix-doc mysql-client mysql-server postfix-tls libsasl2-2 libsasl2-modules libsasl2-modules-sql sasl2-bin libpam-mysql openssl

• There will be several interactive prompts that will require your attention:

File:Postfix ubuntu 1.png 
As in all cases make sure you choose a strong password. 

File:Postfix ubuntu 2.png 
Choose "Internet Site" 

File:Postfix ubuntu 3.png 
This should be the FQDN (fully qualified domain name) you intend to use. Please make sure your DNS is configured for this domain. See Configuring DNS for your (ve) Server. 

File:Postfix ubuntu 4.png 
Select "No" here. 

Configuring MySQL

Now that we have all our software packages installed it's time to create our database and populate it:

• Create a database named email using your MySQL password

sudo mysqladmin -u root -p create email

• Log in to MySQL

mysql -u root -p

• We will now create an admin user named "email_admin" that will give Postfix/Courier complete access to the "email" database. Once again choose a strong password!

GRANT SELECT, INSERT, UPDATE, DELETE ON email.* TO 'email_admin'@'localhost' IDENTIFIED BY '<--strong_password-->';
GRANT SELECT, INSERT, UPDATE, DELETE ON email.* TO 'email_admin'@'localhost.localdomain' IDENTIFIED BY '<--strong_password-->';
FLUSH PRIVILEGES;

• Now that we have our database and user we need to create some tables on the "email" database:

USE email;

• The "domains" table will store each virtual domain that Postfix should receive emails for (e.g. example.com).

CREATE TABLE domains (domain varchar(50) NOT NULL, PRIMARY KEY (domain) );

• The "forwardings" table is for aliasing one email address to another.

CREATE TABLE forwardings (source varchar(80) NOT NULL, destination TEXT NOT NULL, PRIMARY KEY (source) );

• The "users" table stores all email addresses and encrypted passwords

CREATE TABLE users (email varchar(80) NOT NULL, password varchar(20) NOT NULL, PRIMARY KEY (email) );

• The transport table allows you to forward mails for individual users or whole domains to another server.

CREATE TABLE transport (domain varchar(128) NOT NULL default '', transport varchar(128) NOT NULL default '', UNIQUE KEY domain (domain));

• You can do a quick check to see your tables before exiting MySQL:

mysql>show tables;
+-----------------+
| Tables_in_email |
+-----------------+
| domains         |
| forwardings     |
| transport       |
| users           |
+-----------------+
4 rows in set (0.00 sec)

mysql> quit;

Configuring Postfix

Postfix relies on a bunch of configuration files that we will need to create:

• Create the file mysql-virtual_domains.cf

sudo nano /etc/postfix/mysql-virtual_domains.cf

with the following content:

user = email_admin
password = <--strong_password-->
dbname = email
query = SELECT domain AS virtual FROM domains WHERE domain='%s'
hosts = 127.0.0.1

• Create the file mysql-virtual_forwardings.cf

sudo nano /etc/postfix/mysql-virtual_forwardings.cf

with the following content:

user = email_admin
password = <--strong_password-->
dbname = email
query = SELECT destination FROM forwardings WHERE source='%s'
hosts = 127.0.0.1

• Create the file mysql-virtual_mailboxes.cf

sudo nano /etc/postfix/mysql-virtual_mailboxes.cf

with the following content:

user = email_admin
password = <--strong_password-->
dbname = email
query = SELECT CONCAT(SUBSTRING_INDEX(email,'@',-1),'/',SUBSTRING_INDEX(email,'@',1),'/') FROM users WHERE email='%s'
hosts = 127.0.0.1

• Create the file mysql-virtual_email2email.cf

sudo nano /etc/postfix/mysql-virtual_email2email.cf

with the following content:

user = email_admin
password = <--strong_password-->
dbname = email
query = SELECT email FROM users WHERE email='%s'
hosts = 127.0.0.1

• Create the file mysql-virtual_transports.cf

sudo nano /etc/postfix/mysql-virtual_transports.cf

with the following content:

user = email_admin
password = <--strong_password-->
dbname = email
query = SELECT transport FROM transport WHERE domain='%s'
hosts = 127.0.0.1

• Create the file mysql-virtual_mailbox_limit_maps.cf

sudo nano /etc/postfix/mysql-virtual_mailbox_limit_maps.cf

with the following content:

user = email_admin
password = <--strong_password-->
dbname = email
query = SELECT transport FROM transport WHERE domain='%s'
hosts = 127.0.0.1

• Now that we have all our files created we need to modify their ownership and permissions:

sudo chmod o= /etc/postfix/mysql-virtual_*.cf
sudo chgrp postfix /etc/postfix/mysql-virtual_*.cf

• Create the "vmail" user and group with the home directory /home/vmail. All of your mailboxes will live here:

groupadd -g 5000 vmail
useradd -g vmail -u 5000 vmail -d /home/vmail -m

• Now we will have to enter a lot of postconf commands. NOTE: Each of these is a separate command (lots of cut and paste but remember to replace with your own domain name when required)!

postconf -e 'myhostname = example.com'
postconf -e 'mydestination = '
postconf -e 'mynetworks = 127.0.0.0/8'
postconf -e 'message_size_limit = 30720000'
postconf -e 'virtual_alias_domains ='
postconf -e 'virtual_alias_maps = proxy:mysql:/etc/postfix/mysql-virtual_forwardings.cf, mysql:/etc/postfix/mysql-virtual_email2email.cf'
postconf -e 'virtual_mailbox_domains = proxy:mysql:/etc/postfix/mysql-virtual_domains.cf'
postconf -e 'virtual_mailbox_maps = proxy:mysql:/etc/postfix/mysql-virtual_mailboxes.cf'
postconf -e 'virtual_mailbox_base = /home/vmail'
postconf -e 'virtual_uid_maps = static:5000'
postconf -e 'virtual_gid_maps = static:5000'
postconf -e 'smtpd_sasl_auth_enable = yes'
postconf -e 'broken_sasl_auth_clients = yes'
postconf -e 'smtpd_sasl_authenticated_header = yes'
postconf -e 'smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination'
postconf -e 'smtpd_use_tls = yes'
postconf -e 'smtpd_tls_cert_file = /etc/postfix/smtpd.cert'
postconf -e 'smtpd_tls_key_file = /etc/postfix/smtpd.key'
postconf -e 'virtual_create_maildirsize = yes'
postconf -e 'virtual_maildir_extended = yes'
postconf -e 'proxy_read_maps = $local_recipient_maps $mydestination $virtual_alias_maps $virtual_alias_domains $virtual_mailbox_maps $virtual_mailbox_domains $relay_recipient_maps $relay_domains $canonical_maps $sender_canonical_maps $recipient_canonical_maps $relocated_maps $transport_maps $mynetworks $virtual_mailbox_limit_maps'

Configuring TLS and SASL authentication

In order to use [TLS] you will have to create a self-signed SSL certificate for your server.

• Change to the postfix directory and create the cert:

cd /etc/postfix
sudo openssl req -new -outform PEM -out smtpd.cert -newkey rsa:2048 -nodes -keyout smtpd.key -keyform PEM -days 365 -x509

You should see output similar to the following. Replace with your own values:

Generating a 2048 bit RSA private key
......................................................+++
.......+++
writing new private key to 'smtpd.key'

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.

Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:Los Angeles
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MT Example, Inc.
Organizational Unit Name (eg, section) []:Knowledge Center
Common Name (eg, YOUR name) []:wiki.example.com
Email Address []:helpdesk@wiki.example.com

• Now modify the permissions for the "smtpd.key" file:

sudo chmod o= /etc/postfix/smtpd.key

• Next we need to configure SASL authentication. Create the following directory and modify the "saslauthd" file to point to it:

sudo mkdir -p /var/spool/postfix/var/run/saslauthd
sudo nano /etc/default/saslauthd

We will need to modify two lines: Change the "START" value to "yes" and add the last line with the necessary option to point to your newly created directory:

#
# Settings for saslauthd daemon
# Please read /usr/share/doc/sasl2-bin/README.Debian for details.
#

# Should saslauthd run automatically on startup? (default: no)
START=yes

# Description of this saslauthd instance. Recommended.
# (suggestion: SASL Authentication Daemon)
DESC="SASL Authentication Daemon"

# Short name of this saslauthd instance. Strongly recommended.
# (suggestion: saslauthd)
NAME="saslauthd"

# Which authentication mechanisms should saslauthd use? (default: pam)
#
# Available options in this Debian package:
# getpwent -- use the getpwent() library function
# kerberos5 -- use Kerberos 5
# pam -- use PAM
# rimap -- use a remote IMAP server
# shadow -- use the local shadow password file
# sasldb -- use the local sasldb database file
# ldap -- use LDAP (configuration is in /etc/saslauthd.conf)
#
# Only one option may be used at a time. See the saslauthd man page
# for more information.
#
# Example: MECHANISMS="pam"
MECHANISMS="pam"

# Additional options for this mechanism. (default: none)
# See the saslauthd man page for information about mech-specific options.
MECH_OPTIONS=""

# How many saslauthd processes should we run? (default: 5)
# A value of 0 will fork a new process for each connection.
THREADS=5

# Other options (default: -c -m /var/run/saslauthd)
# Note: You MUST specify the -m option or saslauthd won't run!
#
# WARNING: DO NOT SPECIFY THE -d OPTION.
# The -d option will cause saslauthd to run in the foreground instead of as
# a daemon. This will PREVENT YOUR SYSTEM FROM BOOTING PROPERLY. If you wish
# to run saslauthd in debug mode, please run it by hand to be safe.
#
# See /usr/share/doc/sasl2-bin/README.Debian for Debian-specific information.
# See the saslauthd man page and the output of 'saslauthd -h' for general
# information about these options.
#
# Example for postfix users: "-c -m /var/spool/postfix/var/run/saslauthd"
#OPTIONS="-c -m /var/run/saslauthd"
OPTIONS="-c -m /var/spool/postfix/var/run/saslauthd -r"

• Create the file /etc/pam.d/smtp with the following content:

sudo nano /etc/pam.d/smtp

with the following content:

auth    required   pam_mysql.so user=email_admin passwd=<--strong_password--> host=127.0.0.1 db=email table=users usercolumn=email passwdcolumn=password crypt=1
account sufficient pam_mysql.so user=email_admin passwd=<--strong_password--> host=127.0.0.1 db=email table=users usercolumn=email passwdcolumn=password crypt=1

• Now create the file /etc/postfix/sasl/smtpd.conf:

sudo nano /etc/postfix/sasl/smtpd.conf

with the following content:

pwcheck_method: saslauthd
mech_list: plain login
allow_plaintext: true
auxprop_plugin: mysql
sql_hostnames: 127.0.0.1
sql_user: email_admin
sql_passwd: <--strong_password-->
sql_database: email
sql_select: select password from users where email = '%u'

• Once again we need to adjust the permissions of these files, in addition to adding the "postfix" user to the "sasl" group. We will also need to restart these two services so our new configurations to take effect:

sudo chmod o= /etc/pam.d/smtp
sudo chmod o= /etc/postfix/sasl/smtpd.conf
sudo adduser postfix sasl
sudo /etc/init.d/postfix restart
sudo /etc/init.d/saslauthd restart

Configuring Courier

At this point Courier does not know that we want to use MySQL for authentication. Let's change that.

• Edit /etc/courier/authdaemonrc and change the "authmodule" line:

sudo nano /etc/courier/authdaemonrc

...
authmodulelist="authmysql"
...

• Make a backup of /etc/courier/authmysqlrc and delete the contents of the existing file:

sudo cp /etc/courier/authmysqlrc /etc/courier/authmysqlrc_bak;sudo cat /dev/null > /etc/courier/authmysqlrc

• Now edit /etc/courier/authmysqlrc and add the following lines:

sudo nano /etc/courier/authmysqlrc

MYSQL_SERVER localhost
MYSQL_USERNAME email_admin
MYSQL_PASSWORD <--strong_password-->
MYSQL_PORT 0
MYSQL_DATABASE email
MYSQL_USER_TABLE users
MYSQL_CRYPT_PWFIELD password
#MYSQL_CLEAR_PWFIELD password
MYSQL_UID_FIELD 5000
MYSQL_GID_FIELD 5000
MYSQL_LOGIN_FIELD email
MYSQL_HOME_FIELD "/home/vmail"
MYSQL_MAILDIR_FIELD CONCAT(SUBSTRING_INDEX(email,'@',-1),'/',SUBSTRING_INDEX(email,'@',1),'/')

• We need to remove the default certificates that were created when we installed courier:

sudo rm -f /etc/courier/imapd.pem
sudo rm -f /etc/courier/pop3d.pem

• Now modify the following two files and change the CN (common name) for both to match your server name:

sudo nano /etc/courier/imapd.cnf
sudo nano /etc/courier/pop3d.cnf

...
CN=kb.example.com
...

• Next we will need to regenerate the certificates we just deleted to use our new info. We also will need to restart all associated services:

sudo mkimapdcert
sudo mkpop3dcert
sudo /etc/init.d/courier-authdaemon restart
sudo /etc/init.d/courier-imap restart
sudo /etc/init.d/courier-imap-ssl restart
sudo /etc/init.d/courier-pop restart
sudo /etc/init.d/courier-pop-ssl restart

• You can run a quick telnet test to see that the service is running correctly. Simply type "quit" to return to the shell:

admin@wiki:~# telnet localhost pop3
Trying 127.0.0.1...
Connected to localhost.localdomain.
Escape character is '^]'.
+OK Hello there.
quit
+OK Better luck next time.
Connection closed by foreign host.

• Let's now configure our aliases file for the root and postmaster users. Something like the following is fine assuming you have a user named admin:

nano /etc/aliases

postmaster:    root
root:   admin@wiki.example.com

Please note that whenever you make changes to this file you will have to run the "newaliases" command plus restart the postfix service:

sudo newaliases
sudo /etc/init.d/postfix restart

• Let's do a quick test using the "telnet" command again. We want to make sure that TLS and SMTP-AUTH are running:

telnet localhost 25

While in the session type

ehlo localhost

You should see the following output. Once again type "quit" to exit:

ehlo localhost
250-wiki.example.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-STARTTLS
250-AUTH PLAIN LOGIN
250-AUTH=PLAIN LOGIN
250-ENHANCEDSTATUSCODES
250-8BITMIME
250 DSN
quit
221 2.0.0 Bye
Connection closed by foreign host.

Adding Domain and Users to MySQL

Wow. We finally can add your domain and email users to MySQL. Please note that mail will only work for your domain if your zone file is properly configured with MX entries. If you have added a zone file for your domain in the AccountCenter you are all set to go.

• Log back into MySQL

mysql -u root -p

• Enter the following two lines at the mysql prompt. The first line adds the domain. The second line adds a user. In both lines make sure to replace with your own values.

USE email
INSERT INTO domains (domain) VALUES ('example.com');
INSERT INTO users (email, password) VALUES ('user@example.com', ENCRYPT('<--super_strong_password-->'));