1.1. Why write this document?

Our exploration into setting up this mail server started with a simple question from our friend JD. He wanted to know if it was possible to set up a mail server where <jd@domain1.example> and <jd@domain2.example> were separate users and separate from <jd@mailserver.example>.

Of course we knew it was possible, but we didn't know exactly how to go about it. We didn't know what technology we would use nor how it would work. This started us down the path to find this information.

In our investigations to find documentation, we found bits of information here and there, but not one document that described a setup like this. We're hoping to fill that void with this paper.

3.1. Software Selection

Choosing one piece of software over another can often become the place of holy wars on the scale of emacs vs. vi. One could write a paper debating the merits of each of the SMTP servers out there, for example. This section briefly describes our choices for an SMTP server, an IMAP server, an LDAP server, and webmail software.

3.2. The Big Picture

Figure 1 shows how Postfix, Courier, Procmail, OpenLDAP and Jamm interact with each other. Postfix accepts incoming mail from SMTP and delivers it to the maildir mailboxes on the file system. It needs to have a list of valid users so it can bounce email for unknown users. It also needs to know where each user's mailbox is located on the file system so it can properly deliver messages. Postfix delivers the mail itself for virtual users and uses procmail as the MDA for local users.

Courier provides remote access to the maildir mailboxes via the IMAP and POP protocols. It needs to have a list of valid users and some means to authenticate them so users can log into their account. It, too, needs to know where each users' mailbox is located on the file system so it can read their messages.

Local user information can be accessed from the standard account database. A list of valid users can be obtained from /etc/passwd. The users' home directory, which can also be obtained from /etc/passwd, provides the location of the mailbox. Authentication can be handled by standard Unix mechanisms, such as pluggable authentication modules (PAM).

Virtual user information is stored in an LDAP directory since LDAP provides a mechanism for searching for valid users, getting user information, and authenticating users. It is possible to avoid an LDAP directory, but it will be more difficult to administer the virtual user information. For example, Postfix and Courier both support virtual users without LDAP using configuration files, but they have different file formats. It is possible to write scripts to keep these two sets of configuration files in sync, but it can be a chore and is error prone. Also, these file formats are not standard and require custom code to access them. LDAP is a much cleaner solution since it provides a standard interface for accessing the directory and many languages provided LDAP APIs. Jamm speaks LDAP and can manipulate the mail alias and account information stored in LDAP.

3.3. Mailbox Location

Local users' mail is stored in their home directory at ${HOME}/Maildir/ in the maildir format. It is standard practice for maildir delivery to go into the users' home directory rather than /var/. Both Postfix and Courier work with this standard behavior out of the box.

Unlike local users, there is no standard location for virtual user's email. We chose to create a single Unix account, called vmail, that holds all the virtual mailboxes. [1] Postfix and Courier support looking up the directory and Unix account information out of LDAP. This document only describes how to setup this system with one user, though you are free to choose a different policy. Each virtual domain has a subdirectory within the ~vmail/domains/ directory. For example, if there is a user <john@example.com>, mail would be stored in ~vmail/domains/example.com/john/ in maildir format.

4.1. Prerequisites

Here is the list of software, with their version numbers, that we have tested this configuration with:

Software

• Red Hat Linux 6.2 or greater

• Postfix 2.0.14 or greater

• OpenLDAP 2.0.21 or greater

• Courier-IMAP 1.4.1 or greater

• Procmail v3.22

• Jamm v0.9.5

4.2. Preparing the Unix System

To prepare the Unix system there are a few tasks you'll need to accomplish: create the vmail user and decide where you're going to store the virtual users email.

Creating the vmail user is just like creating any other system account. You'll want to have a UID and a GID that is used alone for vmail. You may also want to set its home directory to the location you've selected for the storage area of the virtual users' email.

In our system we used vmail as the user and group name. We also decided to store our virtual users email in /home/vmail.

The following example would work on a RedHat Linux distribution and result in a vmail user being created and an empty mail storage directory being created.

% useradd -k -m -r -d /home/vmail vmail
% mkdir ~vmail/domains
% chown vmail.vmail ~vmail/domains

You will also need to create an account and two groups for postfix, but that is covered in Postfix's INSTALL documentation.

4.3. OpenLDAP

You do not need to follow any special instructions for compiling and installing OpenLDAP, so please consult its documentation for full instructions. For a production environment, you should read up on how to run OpenLDAP as a non-root user, setup a chroot environment, and replication. This section describes how to configure slapd for a single server and how to create the base tree structure. Please consult Figure 2 as this is the LDAP tree we will aim to setup.

---

4.3.1. Configuring slapd

All slapd configuration is in slapd.conf.

---

4.3.1.1. Adding Schemas

You need to make Jamm's schema file available, so copy the jamm.schema file in the Jamm distribution to /usr/local/etc/openldap/schema/jamm.schema. jamm.schema depends on cosine.schema and nis.schema. Add these lines to slapd.conf:

include /usr/local/etc/openldap/schema/cosine.schema include /usr/local/etc/openldap/schema/nis.schema include /usr/local/etc/openldap/schema/jamm.schema

---

4.3.1.2. Adding a Database Definition

Next, you need to set up a database definition. You can do this with the following lines:

database ldbm directory /usr/local/var/openldap-ldbm suffix "dc=myhosting,dc=example"

The database directive specifies the back-end type to use. You should use LDBM as the back-end database. The directory directive specifies the path to the LDBM database. The suffix directive specifies the root suffix for this database.

---

4.3.1.3. Creating the root User

The next few lines set up the "super user" or "root" account:

rootdn "cn=Manager,dc=myhosting,dc=example" rootpw {SSHA}ra0sD47QP32ASAlaAhF8kgi+8Aflbgr7

The rootdn entry has complete access to the database, which is why the password is stored outside the actual database. The password in rootpw should always be stored in hashed format. Do not store the password in clear text. To convert the clear text password secret to a hashed format, use the slappasswd command:

% slappasswd New password: secret Re-enter new password: secret {SSHA}ra0sD47QP32ASAlaAhF8kgi+8Aflbgr7

Take the output from slappasswd, and copy that into slapd.conf, as we did above.

---

4.3.1.4. Defining Indexes

To speed up searches, you should create indexes for commonly searched attributes. In OpenLDAP, you can not only choose which attributes to index, but you can choose which types of searches to index on. For example, if you index the field mail, you have the option of creating indexes for presence, equality, approximate, and/or substring searches. We want to create the following index policy:

• Create presence and equality indexes on objectClass.

• Create equality and substring indexes on mail and cn.

To implement this policy, add these lines to slapd.conf:

index objectClass pres,eq index mail,cn eq,sub

---

4.3.1.5. Setting up Access Control

The last part in slapd.conf is the access control. You can define your own policy, be here's the one we've adopted and Jamm follows:

• The user can change any of their own attributes.

• Anyone in the postmaster group of the domain may change any user's attributes in their domain, including the password. This allows the postmaster to reset a users password if they forget it.

• Anonymous (non-authenticated) users may read all information, except the password attribute.

Access control statements are evaluated in order, so they should be defined from most specific to most general. Access to the password attribute, userPassword, is the most specific in our case, and hence it's specified first:

access to dn=".*,jvd=([^,]+),o=hosting,dc=myhosting,dc=example" attr=userPassword by self write by group/jammPostmaster/roleOccupant=\ "cn=postmaster,jvd=$1,o=hosting,dc=myhosting,dc=example" write by anonymous auth by * none

Please note that the backslash in the above lines means that the line with the backslash and the following line are actually one. The lines are broken up here due to space concerns.

The access to line specifies what entries and attributes to which the following rules apply. The dn regular expression matches any entry in a domain of our hosting tree, and attr limits these rules to the userPassword attribute. Write access is granted to the user itself and anyone in the postmaster group. Anonymous users may only access this field when trying to authenticate. For all other cases, access is denied.

Next, all other attributes to entries in a domain's tree are specified:

access to dn=".*jvd=([^,]+),o=hosting,dc=myhosting,dc=example" by self write by group/jammPostmaster/roleOccupant=\ "cn=postmaster,jvd=$1,o=hosting,dc=myhosting,dc=example" write by * read

Please note that the backslash in the above lines means that the line with the backslash and the following line are actually one. The lines are broken up here due to space concerns.

This access to line is very similar the previous one, except that there is no attr specification. Hence, this matches all other attributes other than userPassword. Again, write access is granted to the user and anyone in the postmaster group. Everyone is granted read access.

Finally, we provide read access to all other elements in the database:

access to * by * read

---

4.3.1.5.1. Changes for OpenLDAP 2.2

OpenLDAP's ACL directives changed slightly in version 2.2. The above reasoning still applies. The changes are minor but important: dn has been changed to dn.regex and we've added a .expand modifier to group/jammPostmaster/roleOccupant.

access to dn.regex=".*,jvd=([^,]+),o=hosting,dc=myhosting,dc=example" attr=userPassword by self write by group/jammPostmaster/roleOccupant.expand=\ "cn=postmaster,jvd=$1,o=hosting,dc=myhosting,dc=example" write by anonymous auth by * none access to dn.regex=".*jvd=([^,]+),o=hosting,dc=myhosting,dc=example" by self write by group/jammPostmaster/roleOccupant.expand=\ "cn=postmaster,jvd=$1,o=hosting,dc=myhosting,dc=example" write by * read access to * by * read

dn: dc=myhosting, dc=example
objectClass: top
objectClass: domain
domainComponent: myhosting

dn: cn=Manager, dc=myhosting, dc=example
objectClass: top
objectClass: organizationalRole
cn: Manager

dn: o=hosting, dc=myhosting, dc=example
objectClass: top
objectClass: organization
o: hosting

$ ldapadd -x -D "cn=Manager,dc=myhosting,dc=example" -w secret -f base.ldif
adding new entry "dc=myhosting, dc=example"
adding new entry "cn=Manager, dc=myhosting, dc=example"
adding new entry "o=hosting, dc=myhosting, dc=example"

4.4. Postfix

We'll only cover the sections of Postfix that pertain to the mail hosting. To deal with other parts of Postfix setup, please visit the Postfix web page[14]. However, we do recommend that you set up as much of Postfix as you can to run in a chroot environment. In our experience, this means all of the Postfix daemons except pipe, local, and virtual.

% make makefiles CCARGS="-I/usr/local/include -DHAS_LDAP" \
AUXLIBS="-L/usr/local/lib -lldap -L/usr/local/lib -llber"

mailbox_command = /usr/bin/procmail

domains_server_host = localhost
domains_search_base = o=hosting,dc=myhosting,dc=example
domains_query_filter = (&(objectClass=JammVirtualDomain)(jvd=%s)(accountActive=TRUE)(delete=FALSE))
domains_result_attribute = jvd
domains_bind = no
domains_scope = one

aliases_server_host = localhost
aliases_search_base = o=hosting,dc=myhosting,dc=example
aliases_query_filter = (&(objectClass=JammMailAlias)(mail=%s)(accountActive=TRUE))
aliases_result_attribute = maildrop
aliases_bind = no

accounts_server_host = localhost
accounts_search_base = o=hosting,dc=myhosting,dc=example
accounts_query_filter = (&(objectClass=JammMailAccount)(mail=%s)(accountActive=TRUE)(delete=FALSE))
accounts_result_attribute = mailbox
accounts_bind = no

accountsmap_server_host = localhost
accountsmap_search_base = o=hosting,dc=myhosting,dc=example
accountsmap_query_filter = (&(objectClass=JammMailAccount)(mail=%s)(accountActive=TRUE)(delete=FALSE))
accountsmap_result_attribute = mail
accountsmap_bind = no

virtual_alias_maps = ldap:accountsmap, ldap:aliases

virtual_transport = virtual
virtual_mailbox_base = /home/vmail/domains
virtual_mailbox_maps = ldap:accounts
virtual_mailbox_domains = ldap:domains
virtual_minimum_uid = 101
virtual_uid_maps = static:101
virtual_gid_maps = static:101

4.5. Courier

You do not need to follow any special instructions for installing Courier, so please see its documentation for full instructions. It should auto-detect LDAP and build it in. You should seriously consider passing the --enable-workarounds-for-imap-client-bugs option to ./configure, otherwise Netscape mail users may have trouble interacting with your server. Yeah, this bends the IMAP protocol a little bit, but it's better to have happy users than a perfect protocol with unhappy users.

authmodulelist="authldap authpam"

LDAP_GLOB_UID           vmail
LDAP_GLOB_GID           vmail
LDAP_HOMEDIR            homeDirectory
LDAP_MAILDIR            mailbox
LDAP_CRYPTPW            userPassword
LDAP_FILTER             (objectClass=JammMailAccount)(accountActive=TRUE)(delete=FALSE)

IMAPDSSLSTART=YES
IMAPDSTARTTLS=NO
TLS_CERTFILE=/usr/local/share/imapd.pem

4.6. Jamm

Installing and configuring a web servlet container like Tomcat or Resin is outside the scope of this document. However, once you have a working servlet container, installing and configuring Jamm is a snap.

Drop the jamm.war file into the webapp deployment directory. Make a directory named jamm, cd into that directory and then un(j|w)ar the file into the jamm directory. cd to the WEB-INF directory. Copy jamm.properties.dist to jamm.properties, and edit jamm.properties as apppropriate.

% mkdir jamm
% cd jamm
% jar -xf ../jamm-0.9.1.war
% cd WEB-INF
% cp jamm.properties.dist jamm.properties

Now you need to edit jamm.properties as appropriate. To continue to follow our examples for dc=myhosting,dc=example, we've edited the following lines in jamm.properties.

jamm.ldap.search_base = o=hosting,dc=myhosting,dc=example
jamm.ldap.root_dn = cn=Manager,dc=myhosting,dc=example

None of the values in jamm.properties should have quotes around them. This will cause problems at run time as Jamm is not expecting them. This has bitten people in the past when they copied their rootdn from slapd.conf.

4.7. SquirrelMail

Since SquirrelMail works directly against IMAP it does exactly what we want it to out of the box. Consider it to be the same as any other IMAP client. There is nothing special about SquirrelMail's setup in this configuration, just follow its install documentation.

We recommend that you set up SquirrelMail on a webserver that is running SSL. This will allow you to make sure that passwords are not going across the network in the clear.

5.1. Site Admin

When a site admin logs in, they are presented with a list of domains. They can click on the domain to drill down to that domain admin page or manipulate the capabilities of the domain admin.

Can Edit Accounts controls the ability for a domain admin to add and remove virtual accounts. When this is switched off, the domain admin can still modify the attributes of existing accounts such as the password.

Appoint Postmasters controls the ability for a domain admin to grant the powers of domain admin to other accounts in the domain. With this turned off, only the site admin can give users domain admin access.

Domain Is Active turns on or off the "active" flag on the domain in ldap. If your mail server or imap server are configured to pay attention to this flag, one can turn on or off domains temporarily without removing them from ldap.

5.2. Domain Admin

When a domain admin logs in, they are presented with a list of accounts and aliases for their domain. They can click on a user to drill down to that user admin page, add or delete accounts or aliases, appoint other admins/postmasters, and activate and deactivate accounts. Some of this options may not be present depending on how the site admin has configured the domain's capabilities.

Delete Account does pretty much what it says it will.

Account Is Active actives or deactives an account without deleting it. Much like Domain Is Active, your mail server and imap servers must be configured to pay attention to this flag inside ldap.

Postmaster gives or removes the ability for that user to act as a domain admin.

5.3. User Admin

When a user logs in, they are presented with a user screen appropriate to whether they have an account or an alias. Currently, all that a user with an account can do is change their password. An alias user is a bit more intereting, they can edit their destination(s).

To add destinations to an alias, the user only needs to add them in the text area in either a comma seperated list or one per line. To delete destinations, just check the box next to the destination to be deleted.

5.4. Account creation notes

When you create an account or an alias inside the LDAP database it will instantly become active as far as the mail system is concerned. For virtual accounts, it should be noted that the Unix directory in ~vmail is not created at this time. However, we can work around this because Postfix's virtual delivery agent will create the necessary directories the first time it has to deliver mail. Due to this fact, we recommend sending a welcome e-mail as soon as you create the account.

5.5. Account deletion notes

When you delete an account or an alias in the LDAP database, it will instantly become inactive. For virtual accounts, it should be noted that the Unix file system isn't cleaned up, i.e. the data remains on disk until a sysadmin can remove it. This will allow you to keep the data from dead accounts around for a grace period in case the account was deleted in error. However, if another account is created with the same name with the same mail path, the data will be available to the new user. This could be considered a privacy violation for the previous user.

7.1. Dave Dribin

Dave has been using Unix since 1991 and Linux since 1993. He has been professionally developing software for or on Unix since 1995. He is currently an independent consultant specializing in custom software ranging from embedded systems in C and assembly language to enterprise systems in Java.

7.2. Keith Garner

Keith has been using Linux since January 1994. He originally installed it to learn Unix better and ended up becoming a believer and advocate of the Open Source movement. He is currently employed by the National Association of REALTORS as a Strategic Architect in the Center for REALTOR Technology. He lives in Bartlett, IL, with his wife, their cat, and 6 computers.