Installing Vpopmail

Updated 4/13/09: With the help of John Simpson, I have removed the skel patch from the instructions. The skel directory located at ~vpopmail/skel will be copied using the onchange mechanisim.

Updated 3/29/09: John Simpson has since removed support and has stopped updating the skel patch. He was saying that I am the only one using the skel patch since I was the only one bugging him about it. Anyways, I am trying to update the 5.4.26 patch to support 5.4.27 and after 2 days, I haven't had much luck. This document has been changed to install vpopmail 5.4.26 from source.

This documentation will attempt to take you through a step-by-step installation of John Simpson's
qmail-updater service with vpopmail. If you don't know what this service does please visit the qmail-updater site here.

The qmail-updater service is actually very easy to install. The instructions given by John Simpson on his site are very easy to follow. The problem is the services won't work once you have all the right pieces in place. For convenience, I have transposed John Simpson's documentation to this documentation with his permission and also a special thanks to Jason King for the modified documentation he wrote specifically for FreeBSD.

Let's get things started: 

One of the first things we need to do is extract the tarball which contains the vpopmail skel(eton) files. Why do we need this you say? In layman's terms, rather than having vpopmail make a basic Maildir with new, cur and tmp in it, we are going to replace that with a completely customized Maildir. The next few commands will extract the tarball, extract it in the correct place and then chown and chmod it.

# cd ~vpopmail
# tar zxvf /downloads/qmailrocks/skel.tgz
# chown -R vpopmail:vchkpw skel/
# chmod -R 700 skel/
# chmod 0600 skel/.qmail skel/mailfilter

We now need to change where vpopmail is located in FreeBSD. The location where ports will try to install it is /usr/local/vpopmail so we're going to delete that folder and symlink it to ~vpopmail: 

# cd /usr/local
# rm -dfr vpopmail
# ln -s ~vpopmail /usr/local/vpopmail

You will need to set the service up to run under daemontools. This process is very painless. Just copy
and paste commands into the command line and everything will be fine. (Steps copied from

# cd /var/qmail/supervise
# mkdir -m 1755 qmail-updater
# mkdir -m 755 qmail-updater/log
# cd qmail-updater/log
# cp /downloads/qmailrocks/service-any-log-run run
# chmod 755 run
# cd ..
# cp /downloads/qmailrocks/pipe-watcher .
# cp /downloads/qmailrocks/update-qmail .
# cp /downloads/qmailrocks/service-qmail-updater-run run
# chmod 755 pipe-watcher update-qmail run

The pipe-watcher script has some variables you can adjust for your own purposes. I found no reason to change anything on my installation so you can keep them the way they are if you wish.

The last step is to simply link the qmail-updater directory in the /service directory so daemontools can run it.

# ln -s /var/qmail/supervise/qmail-updater /service/

Wait a few seconds then run: 

# svstat /service/qmail-updater /service/qmail-updater/log

You should see output similar to the following:

/service/qmail-updater: up (pid 5087) 6 seconds
/service/qmail-updater/log: up (pid 5087) 6 seconds 

After you've finished linking the service into daemontools, you're done. The service is running and you are ready to test it.

The qmail-updater service works by watching a file for data, once the service sees data on that file, it runs a script which updates the validrcptto database. To test you will need to open two sessions into your server so you can watch a log file and perform an action on a file at the same time. On one session tail the qmail-updater log file with this command, you will only be watching this window for stuff to be written to the log:

# tail -f /service/qmail-updater/log/main/current | tai64nlocal

On the other session you will be writing data to the file that the qmail-updater service is watching. As soon as you write data to the file, the qmail-updater service will run the script it's suppose to run which updates the validrcptto database with new user data if there is any. So lets write some data to the file:

# echo testing > /tmp/update-qmail

If you were watching your first session as you hit enter on that last command, you should have seen several things scroll by in the log file. If this happens then you have successfully installed the qmail-updater service. w00t!

Next, We will now cd to the vpopmail port and then enable onchange and logging and then install vpopmail!

# cd /usr/ports/mail/vpopmail
# make CONFIGURE_ARGS="--enable-logging=p --enable-onchange-script"
# make install clean

If that runs without errors, vpopmail is configured and installed. At this point I would add a domain and make sure it adds it okay.

Your users will be very happy they will have the ability to turn on or off their spam protection, change their passwords and all kinda of other fun stuff. 

Now for the hard(er) part. Now that you have the qmail-updater service running, that means you should be able to add a user through qmailadmin or vQadmin or even the command line and the validrcptto database should updated automagically right? Nope, not yet. You don't have anyway of automatically writing data to that watched file yet. That is where the onchange script comes into play. Vpopmail is the program you use to add/del users and domains, but vpopmail doesn't have a hook in that qmail-updater service you just installed so adding a user doesn't write data to that watched file yet. Plus, if you don't have the version of vpopmail that knows to invoke the "onchange" script, it still will not work.

what you here is what we need to do to invoke the onchange script

# cd ~vpopmail/etc
# cp /downloads/qmailrocks/onchange-skel onchange

This is the script that vpopmail will execute when a user/domain has been added/deleted from the system. Once you have created this file set the permissions on it:

# chown vpopmail:vchkpw ~vpopmail/etc/onchange
# chmod 750 ~vpopmail/etc/onchange
# chmod +x ~vpopmail/etc/onchange

This last command gives execute permissions to everyone on the file because I've not found a way to get this to work through qmailadmin or vQadmin otherwise. 

Now that your onchange script is in place, go ahead and tail the qmail-updater log file again and open up another session to your server:

# tail -f /service/qmail-updater/log/main/current

Now try adding a user through the command line and watch your log file to see if stuff appears in it: 

# cd ~vpopmail/bin
# ./vadduser password

If the log file fills up with stuff after you add this fake user, congratulations, you are all done with the qmail-updater process. You may also keep the log session open and try to add a user with qmailadmin or vQadmin just to make sure, but it should work fine from there so long as the permission have been set.

If the log file doesn't move, that means your version of vpopmail does not have the onchange patch in it. Read more about the onchange patch at John Simpsons website at .  

We need to now make a slight modification to the vchkpw file to make SMTP with SSL work correctly:

# cd ~vpopmail/bin
# chmod 6711 vchkpw
# chown vpopmail:vchkpw vchkpw

Please note:

If you are using vpopmail and want messages addressed to a non-existent mailbox to not be accepted, you must use "bounce-no-mailbox" (or "Set catchall bounced", if you use qmailadmin) for the domain. If you use "Set catchall email deleted", messages for non-existent mailboxes will be accepted from the internet and then deleted without being delivered to any mailbox. 

Configuring validrcptto