email howto qmail freebsd

I have been self-hosting my emails for various domains for over 15 years now. I use qmail-ldap and it’s been a very reliable, trusty pal. I had to move my mail server from a FreeBSD 5 system to an Ubuntu box back in 2008 and now that I’m moving it again, I decided to document the steps. My mail system is coming home to FreeBSD so please expect some things to be specific to that operating system.

There will be two parts to it: I will setup a fresh qmail-ldap installation on the new machine in the first part. It will be configured as a secondary MX, meaning it will already accept email for its domains. The second part will cover the migration of the user maildirs and make the secondary MX the new primary one.


Install qmail-ldap using the ports system:

cd /usr/ports/qmail-ldap; make install clean

Create a self-signed SSL-certicate to enable TLS. Creating a signing request and buying a “verified” cert is a waste of money for an SMTP service. Don’t do it. Run make certificate while still in your port’s dir and supply OpenSSL with the information it requests.

The post-install message tells us to add QMAIL_SLAVEPORT=ldap to /etc/make.conf. Also, you can make qmail-ldap your system’s default mailer by running /var/qmail/scripts/enable-qmail



The install script wasn’t able to determine my host’s FQDN. Give qmail a hint as shown below (replace with your real hostname). And while we’re at it: In order to receive email directed to your host (mainly for bounces going to postmaster@), you should add your FQDN to your locals file, too:

echo > /var/qmail/control/me
echo > /var/qmail/control/locals

Mail domain routing

Next we configure the list of domains for which our new mail server should receive email. This new mail server won’t deliver email to mailboxes just yet, so we also need to add the primary mail servers for these domains. Replace with your email domain and with the the IPv4 address of the primary (ie. current) mail server.

echo > /var/qmail/control/rcpthosts
echo > /var/qmail/control/smtproutes

#  Plus other mail domains you want to add

Ldap information

qmail-ldap doesn’t need a running LDAP service as long as we don’t do local delivery. However, it requires some files to exist, so we just fill them with placeholder values:

echo ou=qmail,o=YourOrg > /var/qmail/control/ldapbasedn
echo cn=admin,o=YourOrg > /var/qmail/control/ldaplogin
echo > /var/qmail/control/ldapserver
echo supersecret > /var/qmail/control/ldappassword

chown qmaild /var/qmail/control/ldappassword
chmod o= /var/qmail/control/ldappassword


There is a default /var/qmail/control/qmail-smtpd.rules which should work alright for a secondary MX. If not, I changed mine to look like this:


Starting the service

When all files are in place, chdir to /var/qmail/control and run make.

My installation got path info in all /var/qmail/log/*/run files wrong. We only need to fix two of them now:

--- /var/qmail/log/qmail/run.orig  2016-05-09 00:27:47.746747325 +0200
+++ /var/qmail/log/qmail/run 2016-05-09 00:27:53.325749795 +0200
@@ -1,4 +1,4 @@

-exec setuidgid qmaill multilog t /var/qmail/var/qmail/log/qmail
+exec setuidgid qmaill multilog t /var/qmail/log/qmail
--- /var/qmail/log/qmail-smtp/run.orig  2016-05-09 00:17:45.995784308 +0200
+++ /var/qmail/log/qmail-smtp/run 2016-05-09 00:17:50.931780269 +0200
@@ -1,4 +1,4 @@

- exec setuidgid qmaill multilog t /var/qmail/var/qmail/log/qmail-smtpd
+ exec setuidgid qmaill multilog t /var/qmail/log/qmail-smtpd

qmail-ldap uses DJB’s daemontools and it should be installed as a port dependency. To activate it:

# Start using daemontools
echo 'svsan_enable="YES"' >> /etc/rc.conf
/usr/local/etc/rc.d/svscan start

To start and monitor qmail using daemontools, run these commands:

cd /var/service
ln -s /var/qmail/boot/qmail
ln -s /var/qmail/boot/qmail-smtp

Your mail service should be running now. Test it with telnet 25.

DNS records

You may start updating your DNS records for your domain. Add your new server as a mail exchange (MX) with a priority of 20 (or higher). Once your changes have propagated through the internet (it may take a while depending on your TTL settings) you will start seeing mails pouring in. They should be redirected to your primary mail host transparently.

comments powered by Disqus