Support for DomainKeys in qmail has existed for a while thanks to a patch by Russel Nelson. Kyle Wheeler created a set of wrapper scripts that can be used to provide support for DKIM and DomainKeys. Mihai Secasiu has some wrapper scripts similar to Kyle’s that provide support for DKIM via the libdkim library instead of Perl’s Mail::DKIM module.

The current methods take different approaches to implement DKIM and DomainKeys. The DomainKeys patch creates a single program, qmail-dk that is called before qmail-queue. This program signs or verifies all incoming messages (that may later become outbound) based on the existence of the DKSIGN and DKVERIFY variables. The DKIM wrapper scripts wrap qmail-remote to sign messages and wrap qmail-queue (or qmail-dk) to verify incoming messages. This can be easier understood by looking at the qmail big picture.

I tend to agree with separate programs for signing outbound messages and verifying inbound messages as this allows signing all outbound messages, even those (such as NDRs) that never pass through qmail-queue. I also prefer patching qmail as it tends to be a little easier and requires less configuration after qmail is installed.

In this post I will show you how to patch qmail to support DKIM as well as DomainKeys. My qmail DKIM/DomainKeys patch uses neither Russel Nelson’s DomainKeys patch nor Kyle Wheeler’s DKIM/DomainKey wrappers, but borrows ideas from both. My patch uses the libdomainkeys and libdkim libraries to do the actual signing and verifying. Rather than creating two new programs, I patch qmail-smtpd (for verifying) and qmail-remote (for signing) directly.

I’ll do my best to provide step by step instructions for patching and installing for you non-Gentoo users, but in my next post I’ll share my ebuild which does it all for you.

1. Install libdomainkeys

The libdomainkeys library is used to sign and verify DomainKeys signatures.

2. Install libdkim

The libdkim library is used to sign and verify DKIM signatures. You’ll need g++ to compile this on your system. The library claims to be portable, but I needed to patch it to get it to compile on my Gentoo box. I’ve also included a (slightly modified) patch from Mihai Secasiu that makes working with libdkimtest much easier.

3. Patch and install qmail

I’m currently using John Simpson’s qmail Combined Patch Set for my qmail installation. The instructions below highlight how to apply my DKIM/DomainKeys patch on top of John’s combined patch. I’d highly recommend checking out John’s combined patch as it is about as close as you can get to an actively maintained qmail.

I’m not attempting to describe or document John’s patch in anyway in this post, as John runs an excellent site about qmail (qmail.jms1.net) that contains far more information than is contained here. Do not attempt to proceed without reading through John’s documentation as well as the rest of this post.

4. Configure DKIM/DomainKeys signing

Signing is done by qmail-remote and is controlled by the dksign control file. Signatures are created using a private key on your system, and verified by a public key stored in the DNS for the email domain.

Generate keys

Before you can sign an email, you must create at least one public/private key pair. You should create key pairs for every domain you wish to sign. To create keys for example.com:

It is very important that the default file be readable only by root and the group which qmailr (the qmail-remote user) belongs to. This is the private key used for signing messages and, if compromised, would allow others to sign messages as your domain.

Now add a TXT entry to the DNS for default._domainkey.example.com containing the quoted part in the /etc/domainkeys/example.com/default.pub. NOTE: You normally want to include the quotes!

Configure control files

Create a file /var/qmail/control/dksign containing one line:

The % will be replaced with the domain name in the From: header (or the Sender: header if it exists). If no file exists for the given domain, parent domains will be tried. For example if the message is from foo@bar.example.com, /etc/domainkeys/bar.example.com/default will be tested first. If the file does not exist, /etc/domainkeys/example.com/default will be tested. If no key can be found, the message will not be signed. If a key exists, but cannot be read or contains invalid data, the message will not be sent and will remain in the queue until the problem is fixed.

If you do not create the /var/qmail/control/dksign file, no messages will be signed.

Test outbound signing

Now that DKIM/DomainKeys signing is configured, you can test it by sending an email to sa-test (at) sendmail dot net. This reflector will reply (within seconds) to the envelope sender with a status of the DomainKeys and DKIM signatures.

If you experience problems, consult the qmail-remote man page or post a comment below and I’ll try to help.

5. Configure DKIM/DomainKeys verification

Verification is performed by qmail-smtpd and is controlled by the DKVERIFY environment variable. Messages are only verified if DKVERIFY is set and RELAYCLIENT is not set. You may control which IP addresses are verified using the tcpserver access file (sometimes stored in /etc/tcprules.d/tcp.qmail-smtp).

When verifying a message, the contents of DKVERIFY are checked against the status of the DomainKeys and DKIM results. Each test result is represented by a letter. DKVERIFY should contain a series of letters for DomainKeys results, a comma, and then a series of letters for the DKIM results. If the letter is uppercase, the message will be rejected (hard error). If the letter is lowercase, the message will be deferred (soft error). The DKVERIFY variable can be set but empty, in which case messages will be verified and an Authentication-Results: header will be added but all messages will be accepted regardless of status.

The letters for DomainKeys results are:

The letters for the DKIM results are:

I recommend a DKVERIFY value of DEGIJKfh,CGHIJMQRkl. This will only reject improperly formatted messages. Messages that don’t verify will still be allowed. I would advise against rejecting messages that don’t verify as there are still some problems with DomainKeys and DKIM (such as mailing lists). Rather than rejecting bad signatures, incorporate the Authentication-Results header into your broader spam prevention strategy.

The Authentication-Results header

All messages received by qmail-smtpd when DKVERIFY is set will add an Authentication-Results header to the incoming message. This header conforms to the IETF internet draft. Here’s an example from one of my emails:

Authentication-Results: bltweb.net; domainkeys=pass (ok); dkim=pass (ok)

6. Examples

Here are some examples to help you configure your box. Anything that normally should be private is made up.

Keys

For my bltweb.net domain name, here’s what my keys look like (these are not the actual keys installed on my system, those are private):

Signing Configuration

To sign emails for all domains for which I have a key in /etc/domainkeys, I set the control/dksign configuration file:

Verify Configuration

Here’s an example of my /etc/tcprules.d/tcp.qmail-smtp file. Make sure you regenerate the cdb file after editing your tcp.qmail-smtp file!

7. Finished

That’s it. You should now have a qmail installation capable of signing and verifying messages. More information is contained in the qmail-smtpd and qmail-remote man pages.

If you have any comments or find any bugs, please feel free to post a comment below.

One advantage that Host Virtual provided was a more recent Gentoo image.  Linode only offers a Gentoo 2007.0 install, which it doesn’t even list as a current distribution.  No worries, in this post I describe the steps I took to install a fresh Gentoo 2008.0 amd64 image on my new Linode!

Before we get started, some of the things I wanted on my system:

• x86_64 kernel running natively compiled 64-bit applications
• ReiserFS filesystem instead of ext3
• Basic LAMP server and no more

1. Create recovery configuration profile

1. From the Linode Manager Dashboard, click Deploy a Linux Distribution
2. Select an Unbuntu 8.10 64-bit (or similar 64-bit OS) with a 300MB disk drive. If you want swap space, you should configure that here.
3. Click Create Profile
4. Change the name of the profile to “Recovery Ubuntu 64bit”

2. Create the Gentoo disk image

1. From the Linode Manager Dashboard, click Create a new Disk Image
2. Give your disk a label (you can change this later) and size (most likely all the remaining disk space on your Linode)
3. Pick Unformatted / raw for the filesystem, we’ll format using ReiserFS later
4. Click Create Disk
5. Edit your Recovery Unbuntu 64bit profile: set /dev/xvdc to the disk image you just created.
6. Click Save Profile

3. Boot the recovery profile

1. From the Linode Manager Dashboard, boot your recovery profile
2. Log in with your favorite ssh client: root@<linode vps IP> and the root password you set up in section 1
3. Install some tools required in later steps:
   root@li # apt-get update
   root@li # apt-get install reiserfsprogs wget

4. Set up Gentoo

This section roughly follows the Gentoo Quick Install Guide.

1. Create the ReiserFS filesystem:
   root@li # mkreiserfs /dev/xvdc
2. Mount the filesystem:
   root@li # mkdir -p /mnt/gentoo
   root@li # mount /dev/xvdc /mnt/gentoo
   root@li # cd /mnt/gentoo
3. Set up the stage:
   root@li # wget http://gentoo.osuosl.org/releases/amd64/2008.0/stages/stage3-amd64-2008.0.tar.bz2
   root@li # tar xjpf stage3*
   root@li # rm stage3*
4. Install latest portage snapshot:
   root@li # cd /mnt/gentoo/usr
   root@li # wget http://gentoo.osuosl.org/snapshots/portage-latest.tar.bz2
   root@li # tar xjf portage-lat*
   root@li # rm portage-lat*
5. Chroot into the new Gentoo environment:
   root@li # cd /
   root@li # mount -t proc proc /mnt/gentoo/proc
   root@li # mount -o bind /dev /mnt/gentoo/dev
   root@li # cp -L /etc/resolv.conf /mnt/gentoo/etc/
   root@li # chroot /mnt/gentoo /bin/bash
   li50-172 / # env-update && source /etc/profile
6. Set your timezone:
   li50-172 / # ls /usr/share/zoneinfo
   (Using US/Central as an example)
   li50-172 / # cp /usr/share/zoneinfo/US/Central /etc/localtime
   li50-172 / # nano -w /etc/conf.d/clock
   (Change value of TIMEZONE variable, e.g. TIMEZONE=”US/Central”)
   li50-172 / # date
   Mon Feb 9 14:41:50 CST 2009
7. Set host and domain name
   li50-172 / # cd /etc
   li50-172 etc # echo “127.0.0.1 mybox.at.myplace mybox localhost” > hosts
   li50-172 etc # sed -i -e ‘s/HOSTNAME.*/HOSTNAME=”mybox”/’ conf.d/hostname
   li50-172 etc # hostname mybox
   li50-172 etc # hostname -f
   mybox.at.myplace
8. Configure fstab mount points
   li50-172 etc # nano -w fstab

   Edit the fstab file similar to:

   /dev/xvda     /       reiserfs     noatime,notail  0 1
   /dev/xvdb     none    swap         sw              0 0
   

9. Edit /etc/inittab.
   To ensure the lish console works if you ever need it, edit the terminals section of /etc/inittab to look like:

   # TERMINALS
   c1:12345:respawn:/sbin/agetty 38400 hvc0 linux
   #c2:2345:respawn:/sbin/agetty 38400 tty2 linux
   #c3:2345:respawn:/sbin/agetty 38400 tty3 linux
   #c4:2345:respawn:/sbin/agetty 38400 tty4 linux
   #c5:2345:respawn:/sbin/agetty 38400 tty5 linux
   #c6:2345:respawn:/sbin/agetty 38400 tty6 linux
   

10. Configure networking and SSH:
    li50-172 etc # rc-update add net.eth0 default
    * net.eth0 added to runlevel default
    li50-172 etc # rc-update add sshd default
    * sshd added to runlevel default
    li50-172 etc # passwd
    New UNIX password: type_the_password
    Retype new UNIX password: type_the_password_again
    passwd: password updated successfully
11. Install system tools:
    li50-172 etc # emerge logrotate syslog-ng vixie-cron reiserfsprogs dhcpcd
    li50-172 etc # rc-update add syslog-ng default
    * syslog-ng added to runlevel default
    li50-172 etc # rc-update add vixie-cron default
    * vixie-cron added to runlevel default
12. Prepare to reboot:
    li50-172 etc # exit
    root@li # umount /mnt/gentoo/proc /mnt/gentoo/dev/ /mnt/gentoo
    root@li # exit

5. Set up Gentoo profile

1. From the Linode Manager, shutdown the recovery Linode.
2. Create a new profile by clicking Create a new Configuration Profile
3. Set the following options:
   • Label: Gentoo 2008.0 amd64
   • Kernel: a 64-bit kernel, e.g. 2.6.27.4-x86_64-linode3
   • Drive: /dev/xvda: The disk image you set up in section 2 (not the small Ubuntu recovery disk)
   • Drive: /dev/xvdb: Swap Image

6. Boot Gentoo and finish installation

1. From the Linode Manager, click the Boot button for your new Gentoo profile
2. Log in via ssh: root@<Linode VPS IP>
   (You may have to delete the old ssh key out of your known_hosts file on your local machine)
3. Add a non-root user, install sudo and disable root logins via SSH:
   mybox ~ # useradd -m -G wheel username
   mybox ~ # passwd username
   New UNIX password: type_the_password
   Retype new UNIX password: type_the_password_again
   passwd: password updated successfully
   mybox ~ # nano -w /etc/ssh/sshd_config
   (Add a line: PermitRootLogin: no)
   mybox ~ # emerge sudo
   mybox ~ # visudo
   (Uncomment the line: “%wheel ALL=(ALL) ALL“, around line 24)
   mybox ~ # /etc/init.d/sshd restart
4. Install a simple conservative firewall:
   mybox ~ # emerge iptables
   mybox ~ # iptables -A INPUT -p tcp -m tcp –dport 22 -j ACCEPT
   mybox ~ # iptables -A INPUT -p icmp -m icmp –icmp-type 8 -j ACCEPT
   mybox ~ # iptables -A INPUT -i lo -j ACCEPT
   mybox ~ # iptables -A INPUT -m state –state RELATED,ESTABLISHED -j ACCEPT
   mybox ~ # iptables -P FORWARD DROP
   mybox ~ # iptables -P INPUT DROP
   mybox ~ # /etc/init.d/iptables save
   mybox ~ # /etc/init.d/iptables start
   mybox ~ # rc-update add iptables default
   * iptables added to runlevel default
5. Select a Gentoo mirror and update make.conf:
   mybox ~ # emerge mirrorselect
   mybox ~ # mirrorselect -i -o >> /etc/make.conf
   mybox ~ # mirrorselect -i -r -o >> /etc/make.conf
   mybox ~ # nano -w /etc/make.conf

   Edit the file to include the parts in bold:

   # Typical Linode has 4 processors, make use of them when compiling
   MAKEOPTS="-j5"
   
   CHOST="x86_64-pc-linux-gnu"
   CFLAGS="-march=nocona -O2 -pipe"
   CXXFLAGS="${CFLAGS}"
   

   At this point you should also run emerge -vpe world and decide what USE variables you want to include in your make.conf file.

6. Define locales:
   mybox ~ # nano -w /etc/locale.gen
   (Uncomment the first two en_US lines)
   mybox ~ # locale-gen
7. Update portage and installed packages:
   mybox ~ # emerge portage
   mybox ~ # emerge -vpuD –newuse world
   mybox ~ # emerge -vUD –newuse world
   (Go grab some lunch, this is going to take a while.)
   mybox ~ # emerge –oneshot libtool
   mybox ~ # emerge gentoolkit
   mybox ~ # revdep-rebuild

7. Reboot and enjoy

At this point I like to reboot the server to ensure that everything comes back up the way I expect it. This isn’t necessary however.

After reboot my server was using just under a GB of data (990264 bytes) and about 60MB of RAM. The server is now ready to install apache, mysql, etc. I’ll be looking at optimizing my memory usage in a later post.

Note: If you found this helpful and are interesting in signing up for Linode, feel free to use my referral code below. I’m only putting this out there if you’d like to use it – you can easily sign up for a Linode VPS without it!
http://www.linode.com/?r=edff465df97bb1e29468836d3700c79a2d24a17e