For qmail-ldap dubug how-to, refer to errata page.

• Install daemontools which is a collection of tools used for managing Unix/Linux services.
• Install ucspi-tcp which includes tcpserver and tcpclient. These are command-line tools for building TCP client-server applications.
• Install djbdns which is a lightweight, small, secure, and powerful DNS server and cache toolkit.
• qmail-ldap which gives you basic things along with core functionality of qmail along with ldap support
• SMTP authentication ( smtp-auth ) before sending mails. This is for our roaming users.
• SMTP with ssl/tls support
• POP3 with ssl support
• Provision to debug the installation if something goes wrong

• Download latest daemontools package from http://cr.yp.to/daemontools/ and follow the installation steps.
• Download latest ucspi-tcp package from http://cr.yp.to/ucspi-tcp/ and follow the installation steps.
• Download latest djbdns package from http://cr.yp.to/djbdns/ and follow the installation steps.
• Download qmail package, patch it with qmail-ldap patch and follow the installation steps

Few things you should note about this installation is that this installation is a little different than other source installations in a sense that it creates links in /command to the targets in your source location where you compiled the package. For this reason it is necessory that you gunzip the package on a location where you do not usually delete anything manually. Remember do NOT delete the source in fact DO NOT DELETE ANY SOURCE CODE after you install any qmail related package. It is wise to have a backup copy on your local machine or may be a CD burnt with the source code.

This should be enough for this installation. Once installation is complete you should see two process started newly.

For more information you may want to take a look at the author's page here

In this installation first we are going to patch ucspi-tcp package for ssl/tls support and then follow the normal installation procedure. Download the ucspi-tcp package from the location mentioned above. Download the ucspi-tcp ssl/tls patch from www.nrg4u.com. Follow the instructions to install.

Note that make setup check is run as root. The ucspi-tcp is installed under /usr/local. All the tools are installed under /usr/local. You may take a close look at the documentation from author's web site here

The installation of djbdns package is pretty straight. <Finish it later: Followed steps as per djb's directions>

We will be installing qmail on /var directory. Before you start installing qmail-ldap make sure that you have /var mounted without nosuid permissions if it is a seperate partition. This entry can be removed from /etc/fstab and by restarting the system. The following output of mount command is perfectly acceptable.

Whereas following output of mount command is sure indicates that the installation is going to create problem.

Download a fresh qmail package from the author's site. Gunzip it and and untar it. Download the latest qmail-ldap patch and gunzip it. Once done this, change to qmail directory and patch the qmail with qmail-ldap patch.

Now that you have your qmail patched, you have an array of operations to execute. First we will modify the Makefile to include all the options that we want to have in our qmail-ldap installation.

The unedited Makefile looks like this..after you patched the qmail code with qmail-ldap. Below I have added two hashes extra to each comment to avoide confusion with root prompt.

This patch is necessory only if you are planning to return appropriate message for each e-mail simscan refuses to deliver. For more information on qmail-queue-custom-error.patch refer to simscan page. This patch requires to be patched on fresh qmail-1.03 source which in this case is not true. So you are sure going to to get a few rejects. Aparently you have to manually patch the code after you apply ldap patch. For more on manually patching sources, refer to manually patching source code page.

You can find this patch in ~/contrib directory in simscan sources.

Now we will create different users and groups that qmail needs. The group vmail will be used for writing the mails to disk.

Now its time to issue the command (as root) to install the qmail.

If above command executes without any errors, qmail-ldap is installed on your server in /var/qmail. All binaries are installed in /var/qmail/bin. Documentation is installed in /var/qmail/doc. Man pages are installed in /var/qmail/man. Startup scripts are located at /var/qmail/boot you might want to take a look at.

We will now configure the qmail-ldap. Most of the configuration involve creating some vital files in /var/qmail/control. These files deside how some of the features are going to be handled by qmail-ldap. This is the primary runtime environment that qmail-ldap requires. Each control file is used for specific configuration which can be changed by changing the value in that file. Some control files must contain some specified values whereas some can be set according to your configuration.

~control/me: This should be set to FQDN (Fully Qualified Domain Name) of your server. For example if domain name of your server is ironclad.mil then you will add-

~control/locals: Include entries to all the domains for which you will accept mails from remote hosts. This also tells qmail-ldap to locally deliver the mails for domains having entry in this file. For now we will have just one entry in this file as shown below

~control/recpthosts: Include entries of all the domains for which you will accept mails from remote hosts. Recipients domains listed in ~control/rcpthosts are allowed to relay messages without further checks. Here also we will have just one entry in this file as shown below

~control/ldapserver: This file should contain the IP of FQDN of the LDAP server that will contain qmail user accounts. In my case it is going to be secure.ironclad.mil. If you are running ldap server (slapd) without any parameters to it on the same server then you will have to add IP 127.0.0.1

~control/ldaplogin: This file contains the username for the LDAP server connection. It is same as one you have defined in your slapd.conf. In my case it is Manager. Consult your slapd.conf file for precise info.

~control/ldappassword: This file contains password for the LDAP server connection. It is same as one you specified in slapd.conf in hash format. Note that the password in this file is clear text. This file should be owned by root and mode should be (600) i.e. read and write (rw-------) access to root only. If you are using auth-smtp or rcpt-verify then permissions must be adjusted accordingly so that qmail-smtpd user has read access to the file. In our case qmaild is the qmail-smtpd user

~control/ldapbasedn: File should contain the base DN under which qmail-ldap users will exist. In our case we have an OU called qmail_users under dc=ironclad,dc=mil which is the root node in our tree. So I would do it like..

~control/ldapobjectclass: This file contains the objectClass against which all searches in LDAP tree will be limited. The default objectClass is qmailUser to we will add it to this file.

~control/ldapdefaultdelivery: This file contains a boolean value which indicates whether to look in /etc/passwd file (system accounts) if a user is not found in LDAP. We want our setup to use LDAP only and all our mail users will be virtual users so we will set it up to 0.

~control/ldapmessagestore: This should be set to the location where you want to store all mail message on your server. We will store the mail messages for all the users in /var/vmail

~control/ldapuid: This should contain the uid of vmail user that we have created in the previous section. If you don't know where to find it you can find it using following command

~control/ldapgid: This should contain the gid of vmail that we have created in the previous section. We have found it in code segment above

~control/defaultdelivery: For our purpose we are going to use Maildirs for storing emails. This we tell qmail by specifying in this file. Note below, the trailing / (slash) of Maildir is necessory.

By default Debian ships with exim as the system MTA. To make sure that it does not interfere with our new qmail-ldap installation in any way, we will simply shut it down. If you don't do it, be sure to face some nasty errors. Alternately you may like to remove it from rc.conf file. If you decide to remove it from rc*.conf files so that it won't start automatically when you reboot the machine, you need to do a few things. To remove it from rc?.d directory you have to first determine which runlevel you are currently running in. You can verify this by looking at your /etc/inittab file. To verify your current runlevel, search /etc/inittab file for an entry looking like this:id:2:initdefault:. Here id:2:initdefault: the number after id: denotes your current runlevel which is 2 here.

For every runlevel Linux has a different directory in /etc directory, named as /etc/rc0.d, /etc/rc1.d and so on. Usually /etc/init.d contain files which are actual startup scripts for the programs. These files are targets for symlinks in /etc/rc*.d directories. So for runlevel 2 we will look at /etc/rc2.d directory

On issueing command file, I get following info

To disable exim you have to move the file from directory for this runlevel. The file can be found in /etc/rc2.d/. In this directory you need to find the script/symlink to the file exim*. For me the startup file in runlevel for exim is /etc/rc2.d/S20exim4. This file is a symlink to /etc/init.d/exim4. Removing this link will prohibit exim initializing on reboot in runlevel 2 (in this case). Remember other runlevels can still start exim. Alternately you can remove the script /etc/init.d/exim4 itself. But that will leave the links to this file from all rc*.d directories broken which certainly isn't desirable. Or you will have to remove the links as well, from all the /etc/rc?.d directories So better approach is to remove the link from /etc/rc2.d.

To stop exim you can kill the process (which is crude way to stop exim) like this.

Its time to create a dirmaker script. In the section Editing Makefile we enabled two options called MDIRMAKE=-DAUTOMAILDIRMAKE and HDIRMAKE=-DAUTOHOMEDIRMAKE This script will be used by qmail-ldap for creating mail directories (Maildir). Place the following script as /var/qmail/bin/dirmaker. The dirmake script for our installation will be:

Make this script executable.

Tell qmail to use this script for creating new directories by specifying it in /var/qmail/control/dirmaker. If qmail-ldap finds this file with the appropriate path to the script in /var/qmail/control/dirmaker it turns the DAUTOHOMEDIRMAKE patch on. Note that the file should contain absolute path. If the mail user entry exists in LDAP but the home directory and/or Maildir for the user does not exist, this script will create necessory directories.

~control/dirmaker: This is the file which tells qmail-ldap to enable creation of automatic directory structures and the script to use to create these directories.

Now its time to test the configuration we have been doing so far. To test this installation first we will create a symlink to /var/qmail/boot/qmail directory in /service directory. This will start the qmail in few seconds. This is done by daemontools. Then verify that the service is up.

Also you can determine the processes by issueing command. (Edited output)

svscanboot
\_ svscan
|   \_ supervise
|   |   \_ dnscache
|   \_ supervise
|   |   \_ multilog
|   \_ supervise
|   |   \_ qmail-send
|   |       \_ qmail-lspawn
|   |       \_ qmail-rspawn
|   |       \_ qmail-clean
|   |       \_ qmail-todo
|   |       \_ qmail-clean
|   \_ supervise
|       \_ multilog
\_ readproctitle

If your outputs agree with the above outputs, and everything looks good, try injecting a mail to some user already in LDAP but not having any directories present. After injecting email to the user check the logs.

The log output (in red color) above indicate that the things are working ok.

The qmail-smtpd we are starting is plain vanilla version of smtpd. The run script can be found at location /var/qmail/boot/qmail-smtpd/run. This run script was installed at the time of qmail-installation. Before starting qmail-smtpd we need to define rules for smtpd in /var/qmail/control/qmail-smtpd.rules. After defining rules we will create a cdb file from this database. The next step would be to create a link in /service targeting to the smtpd run script.

An unedited qmail-smtpd run script is shown below.

The /var/qmail/control/qmail-smtpd.rules file after defining the desired rules.

Now we need to create cdb file from this /var/qmail/control/qmail-smtpd.rules file. To do this change directory to /var/qmail/control and then run following command:

The line in /var/qmail/boot/qmail-smtpd/run script that tells to refer to cdb file is tcpserver -v -URl $ME -x$QMAIL/control/qmail-smtpd.cdb \. If the script won't find qmail-smtpd.cdb file in place, you simply won't be able to make connection to the SMTP port as qmail-smtpd/run will not find the said cdb file. You may refer to my mail relaying document for more details.

After everything is in place, we will create the link to /var/qmail/boot/qmail-smtpd/run in /service directory. svc will then start the service within few seconds.

You can check if the smtpd service is up or not by issuing command

If you get output something like this, you are up with SMTP. Now you can try sending some mail to your server from some other email address not on your server. If mail got through, thats the confirmation of SMTP service running at your server.

SMTP AUTH is particulary useful when you have roaming users as well as users with dynamic IP assigned by their ISPs. These users can now use your SMTP server to relay their mails even if their IP or network is not listed in your allowed list of networks/IPs in qmail-smtpd.cdb file. Authenticated SMTP will allow such users to enter their credentials which are verified against their account entry in qmail-ldap and upon successful authentication they will be granted access to relay mails using your server regardless of their current IP or network. Read more about relaying in my mail relaying document.

In order to qmail-smtpd support this functionality you have to edit current /var/qmail/boot/qmail-smtpd/run script to invoke auth-smtp program installed with qmail-ldap in your installation. Open this file in your favorite editor and look for the following lines towards end of file.

Add command $QMAIL/bin/auth_smtp /usr/bin/true to the last line, so now the last line in your run script become..

Now add these variables to your qmail-smtpd.rules file

So now your qmail-smtpd.rules file will look as shown below

Now you have to rebuild the cdb file from qmail-smtpd.rules file. For this you have to issue following command as root. The variable SMTPAUTH tells qmail-smtpd that authorization is required before relaying mail from your server. Next variable NOPBS tells smtpd not to use PBS (POP Before SMTP). You do not need this since you are using SMTP AUTH. This may be required when you are using clustered servers but not now.

You have to restart the smtpd service for these changes to take effect. To do this issue following command as root.

To test this setup try sending mail from some other host using sender's address on mail envelop as your servers default domain. It should ask you for authentication. If this works, you are done with SMTP AUTH. Don't forget to verify the service is running using svstat command as follows before you test.

When you authenticate over internet, auth passwords are in clear text equivalent base64 encoding. So if someone can capture the packets using some packet capturing tool, your users are vulnerable to Identity theft. So a step beyond this authenticated SMTP relaying is the ability to negotiate a secure connection with your SMTP server for secure authentication and privacy of data transferred over the Internet. This will prevent password sniffing. qmail-ldap allows us to use and configure this ability in qmail-smtpd. Remember we have enabled a variable TLS=-DTLS_REMOTE -DTLS_SMTPD -DTLSDEBUG in Makefile before qmail installation. Refer to the Editing Makefile Section. This built the ability in our installation to configure SMTP with TLS option.

Before configuring this abilty you have to make sure you have created certificate by running make cert command in the patched source of qmail.

Read more on make cert.

It will prompt you to supply some vital information that will appear on your certificate. Remember, you need to provide the your server name as Common Name here. This will also change the permissions of the certificate file. Make sure permissions are as shown below:

~control/smtpcert: This is one this you have to perform before you restart qmail-smtpd. You have to define the path of cert.pem in this this file. It would be appropriate if you specify absolute path to this file as follows.

This certificate will be sent to your clients when they smtp using tls. One this has been done you have to restart smtpd as follows. In my experience smtp with tls WILL NOT work until you add path to cert.pem to ~control/smtpcert file.

Clients have to select appropriate options in their mail clients for using SSL or TLS with your SMTP server. Ascribe your clients to their email-client documentation if you/they are unsure about how to do it. When they try to send a message to SMTP server, their mail client will receive a certificate notice asking to proceed with encrypted SMTP. qmail-ldap can enforce client SMTP encryption as a mandatory feature by setting. This can be either specific clients or universally. For specific clients you can set this in /var/qmail/control/qmail-smtpd.rules or to set this feature globally you have to set the variable in /var/qmail/boot/qmail-smtpd/env which is same as /service/smtpd/env as it is nothing but symlink to the qmail-smtpd in /var/qmail/boot. You can enforce this globally as follows.

Else you can do this in qmail-smtpd.rules file by changing last line of /service/smtpd/run as follows.

Do not forget to create cdb file from qmail-smtpd.rules file. Restart the smtpd service as follows.

You will find the run script in /var/qmail/boot/qmail-pop3d. It was installed at the time of qmail-ldap installation. Before creating pop3 service in /service you need to edit the /var/qmail/control/qmail-pop3d.rules file to reflect changes as follows.

We do not want to use POP-Before-SMTP which we specified using veriable NOPBS. You do not have to edit /var/qmail/boot/qmail-pop3d/run script. You have to create cdb file from /var/qmail/control/qmail-pop3d.rules file. For this, change to the /var/qmail/control directory and execute tcprules command as follows.

Next you have to create a symlink to /var/qmail/boot/qmail-pop3d in /service directory as follows.

This should start the pop3d service in few seconds. You can verify this by issueing following command.

If your output is similar to the output shown above, your pop3d is running now. You can try configuring and receiving mails using your favorite mail-client.

qmail-ldap provides special run script for pop3 with ssl. You will find this script in /var/qmail/boot/qmail-pop3d-ssl. To make this script work for you you might have to change the exec statement toward the end of the qmail-pop3d-ssl/run script as shown below. To be specific check out second line in code below. It should be tcpserver -v -HRl $ME -x$QMAIL/control/qmail-pop3d.cdb \. This is because we are going to have similar rules for vanilla POP3 and POP3 with SSL. If you want to have seperate rules for some users, you have to specify different .rules file and create a cdb file from that, and then add path to that file in run script.

To tell svc to start service, you need to create a link to /var/qmail/boot/qmail-pop3d-ssl in /service. This will start the service in few second which you can later verify using svstat command.

If your output agrees with the output shown above you are up with POP3-SSL. You can set your mail-client to use POP3 with SSL and verify its working. In case of problem, check errata page.