Courier vMail HowTo

1. Set use flags

courier supports the following use flags:
postgres ldap mysql pam nls ipv6 spell fax crypt

Suggested flags for this howto are:
mysql ipv6 spell crypt

2. Install courier

$ emerge courier

3. Setup courier

a. Edit SSL cert config files

edit the following files in /etc/courier
esmtpd.cnf
imapd.cnf
pop3d.cnf

Replace the default values with values matching your site, this will be used in generating SSL certs
for the different services.

b. Run config script (create SSL certs)

$ ebuild /var/db/pkg/net-mail/courier-${PV}/courier-${PV}.ebuild config

c. Enable various services

edit the following files in /etc/courier
imapd
imapd-ssl
pop3d
pop3d-ssl
esmtpd
esmtpd-msa
esmtpd-ssl
there is a line near the end usually that says $serviceSTART=NO
where $service is usually the capitalized name of the file you are editing, you need to change that line to YES

N. Setup webadmin/webmail

$ echo \"Include /etc/courier/apache-sqwebmail.inc\" >> /etc/apache*/conf/apache.conf
$ chmod a+rx /usr/lib/courier/courier/webmail
$ echo "some_password" > /etc/courier/webadmin/password
where "some_password" is the password you want to use for the
There should be one word in this file. The webadmin password
$ chown mail:mail password
$ chmod 400 password

if you aren't going to be using https to connect to the admin interface,
you'll have to do:
$ touch /etc/courier/webadmin/unsecureok
but make sure you only connect from secured hosts over a secure network

4. Configure MySQL

you need to setup the mysql user db, and then run the following commands to setup the table.

connect to mysql as root (or somebody that has permissions to add users and databases), and run the following commands:

mysql> CREATE DATABASE courier;
mysql> use courier;
mysql> CREATE TABLE passwd (
       id                    char(128) DEFAULT '' NOT NULL,
       crypt                 char(128) DEFAULT '' NOT NULL,
       clear                 char(128) DEFAULT '' NOT NULL,
       name                  char(128) DEFAULT '' NOT NULL,
       uid                   int(10) unsigned DEFAULT '8' NOT NULL,
       gid                   int(10) unsigned DEFAULT '12' NOT NULL,
       home                  char(255) DEFAULT '' NOT NULL,
       maildir               char(255) DEFAULT '' NOT NULL,
       defaultdelivery       char(255) DEFAULT '' NOT NULL,
       quota                 char(255) DEFAULT '' NOT NULL,
       options               char(255) DEFAULT '' NOT NULL,
       KEY id (id(128))
);
mysql> grant select on courier.passwd to courier@localhost identified by "$insert_password";

You can change the above settings, just make sure you set the correct settings in the mysql section of the web setup or the authmysqlrc config file.

5. Configuring courier

edit /etc/courier/authmysqlrc
make sure the following are set appropriately:
MYSQL_SERVER
MYSQL_USERNAME
MYSQL_PASSWORD
MYSQL_SOCKET
MYSQL_DATABASE
MYSQL_CLEAR_PWFIELD
MYSQL_UID_FIELD
MYSQL_GID_FIELD
MYSQL_MAILDIR_FIELD
MYSQL_DEFAULTDELIVERY(optional)
MYSQL_QUOTA_FIELD(optional)

specifically, MYSQL_SOCKET will have to be changed

edit /etc/courier/authdaemonrc
find the line that says authmodulelist, and make it like the following
"authmodulelist=authmysql"
same for the version line
"version=authdaemond.mysql"

edit /etc/courier/aliases/system
edit the line with postmaster on it
"postmaster: you@yourdomain.com"

edit /etc/courier/hosteddomains
this file should have a list of all domains in it (one per line)

edit /etc/courier/smtpaccess/default
the settings should pretty self explanatory, you just need to enable access from any ip addresses/subnets that apply to you
As an alternative to smtpaccess, you can setup smtpauth, then anybody can connect from anywhere in the world as long as they auth first

5. Setup maildir's

for every user's directory you need to change to the directory and run:
$ maildirmake .maildir
$ you need to set ownership to the uid and gid of the courier user (normally "mail")

6. Setup users

Add users to the database using your mysql client of choice (phpmyadmin is a good one).
table of fields to fill in:

field	description	example
id	email address	userfoo@foo.com
crypt	crypt'ed password for the user	I've never used this, so I can't give an example
clear	cleartext password for the user	mysecret
name	user's real name	Bob Foo
uid	uid for mail user	8
gid	gid for mail user	12
home	path to users homedir	/home/mail/userfoo
maildir	path to the users maildir	/home/mail/userfoo/.maildir
defaultdelivery	if you need to override the systems DEFAULT_DELIVERY	./.maildir
quota
options	comma separated var=value pairs	disableimap=1,disablepop3=1,disablewebmail=1

FAQ:
Q: OMGUFB, I can't login.
A: first, check the MYSQL_SOCKET setting in /etc/courier/authmysqlrc
second, enable mysql logging, and see if courier is connecting to the database

Q: what's esmtpd-msa?
A: msa stands for Message Submission Agent, it's supposedly the new way for MUAs to submit messages to be sent by the MTA. I don't currently know of any MUAs that support this. See the rfc (cache) for more info


currently a lot of different block lists are being picked off one by one, so I
suggest bypassing the block list checks, and stick with the content scanning via spamassassin


TODO:
walk through setting up spamassassin
urge them to use phpmyadmin, or something similar