Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc


Qmail Gentoo-Wiki How-To's

The Site:

Other Gentoo-wiki Qmail



This howto has recently been updated to use the following ebuilds


> sys-apps/ucspi-tcp-0.88-r10
> net-mail/dot-forward-0.71-r1
> net-mail/cmd5checkpw-0.22-r1
> sys-process/daemontools-0.76-r4
> net-mail/queue-fix-1.4-r2
> net-mail/checkpassword-0.90-r1
> mail-mta/qmail-1.03-r15
> net-mail/relay-ctrl-3.1.1-r2
> net-mail/vpopmail-5.4.6-r1
> net-libs/courier-authlib-0.54  
> net-mail/courier-imap-4.0.1-r1

QUICK NOTE : In order to use vpopmail or qmailadmin Apache must run as user vpopmail:vpopmail.

There are 2 Ways of doing this, setting the SUID bit on the files, or changing the apache user to be vpopmail. After you install vpopmail change into their directory(/var/www/localhost/cgi-bin/)

chown vpopmail.vpopmail vqadmin
chown vpopmail.vpopmail qmailadmin
chmod g+s,u+s vqadmin
chmod g+s,u+s qmailadmin

You will need to edit your /etc/apache2/conf/commonapache.conf file to read

> User vpopmail
> Group vpopmail

and then restart apache with the command /etc/init.d/apache2 restart. Now back to our regularly scheduled programming.

Note This is likely to remove other apache functionality which relies on apache:apache for user:group. You are warned!

Ensure Proper USE Flags Are Set

> nano -w /etc/make.conf
  add apache2, maildir, valias, vhosts, authdaemond and mysql as USE flags.

Install QMAIL

First of all, make sure that you unmerge the other mail handlers that may be installed, such as ssmtp, sendmail, or postfix:

> emerge -C ssmtp sendmail postfix exim
> emerge /usr/portage/mail-mta/qmail/qmail-1.03-r15.ebuild 
> ebuild /var/db/pkg/mail-mta/qmail-1.03-r15/qmail-1.03-r15.ebuild config 
> ln -s /var/qmail/supervise/qmail-send /service/qmail-send 
> ln -s /var/qmail/supervise/qmail-smtpd /service/qmail-smtpd 

> rc-update add svscan default 
> /etc/init.d/svscan start


Using relay-ctrl is a simple and straightforward way to allow us to send email with email clients from anywhere.

> emerge relay-ctrl
> cd /etc/tcprules.d/
> nano -w tcp.qmail-smtp

Make your tcp.qmail-smtp file look like this - you only need to change the very last line to the internal IP address of your server.

> # to update the database after changing this file, run:
> # tcprules /etc/tcprules.d/tcp.qmail-smtp.cdb /etc/tcprules.d/.tcp.qmail-smtp.tmp < /etc/tcprules.d/tcp.qmail-smtp
> #-----------------------------------------------------
> #-----------------------------------------------------
> #
> # These IPs are ones that we have setup so that they arent RBL checked.
> # We have done this because these particular servers are RBL listed,
> # and for whatever reason they can't/won't fix their open relay problem,
> # and we still want to be able to receive mail from them.
> #
> # reminder text goes here for this entry so we know the story...
> # reminder text goes here for this entry so we know the story...
> #-----------------------------------------------------------------
> #
>,RBLSMTPD="-Connections from this IP have been banned."
> # heaps of spam from replyto of * dec2001
> 64.228.127.:allow,RBLSMTPD="-Connections refused due to spam from"
> 154.20.94.:allow,RBLSMTPD="-Connections refused due to spam from"
> 209.151.132.:allow,RBLSMTPD="-Connections refused due to spam from"
> 216.18.85.:allow,RBLSMTPD="-Connections refused due to spam from"
> #-----------------------------------------------------------------
> #
> # Local class-c's from our LAN are allowed to relay,
> # and we wont bother doing any RBL checking.
> #123.123.123.:allow,RELAYCLIENT="",RBLSMTPD=""
> #123.111.111.:allow,RELAYCLIENT="",RBLSMTPD=""
> #
> # Connections from localhost are allowed to relay
> # (because the WebMail server runs on localhost),
> # and obviously there is no point trying to perform an RBL check.
> #-----------------------------------------------------------------
> #
> # Everyone else can make connections to our server,
> # but not allowed to relay
> # RBL lookups are performed
> :allow
> # If you are using qmail-scanner, this line here is the correct one to use
> # instead (comment out the above ':allow' line FIRST) and applies that script
> # to any mail coming in that is not from a host allowed to relay. You can
> # change the value of the variable to any other value you desire to use custom
> # scripts for example.
> #:allow,QMAILQUEUE="/var/qmail/bin/"

This last line here is te one you need to change to your servers internal IP address. Once this file has been edited, then type this and hit enter...

> tcprules /etc/tcprules.d/tcp.qmail-smtp.cdb /etc/tcprules.d/.tcp.qmail-smtp.tmp < /etc/tcprules.d/tcp.qmail-smtp

and to finish up...

> /etc/init.d/svscan restart


> emerge /usr/portage/net-mail/vpopmail/vpopmail-5.4.6-r1.ebuild

First log into mysql as your mysql root user and pass. Then:

> create database vpopmail;
> use vpopmail;
> grant SELECT, INSERT, UPDATE, DELETE, CREATE, DROP on vpopmail.* to vpopmail@localhost identified by 'your password';
> flush privileges;
> quit

Do not replace the phrase 'your password' with your actual password in this instance.

Configure vpopmail's mysql user password

> nano /etc/vpopmail.conf 
 (Change the password from 'secret' to your database password defined earlier, and change the user to user vpopmail)

If you have problems with vpopmail not accepting mail properly, please ensure that /etc/vpopmail.conf is chmod 640 and owned by root:vpopmail

> chown root:vpopmail /etc/vpopmail.conf
> chmod 640 /etc/vpopmail.conf
> chown root:vpopmail /var/vpopmail/bin/vchkpw
> chmod 4711 /var/vpopmail/bin/vchkpw

Now you can add a domain with the command

> vadddomain

You can add a user at the commandline with the command

> vadduser

or delete a user

> vdeluser
 (You only have to do this if the vadddomain step below results in "command not found")
> env-update && source /etc/profile

Install Courier-IMAP as IMAP & POP3 Server

> emerge net-mail/courier-imap-4.0.1-r1

This should emerge courier-authlib and courier-IMAP. We'll configure courier-authlib first.

Note: Make sure it actually does emerge courier-authlib, if not, do emerge courier-authlib Note: AMD64 Users: courier-imap-4.0.1, the currently available "stable" version on amd64, will not work with the LOGINRUN configuration variable provided below. If you are on amd64, place the following in /etc/portage/package.keywords before building: >net-mail/courier-imap ~amd64

> nano -w /etc/courier/authlib/authdaemonrc

Ensure these headings look exactly like this in the authdaemonrc file

> authmodulelist="authvchkpw"
> authmodulelistorig="authvchkpw"

Do not have/leave/put extras in there. Now onto configuring courier-imap.

> nano -w /etc/courier-imap/imapd
> MAILDIR=.maildir
> MAILDIRPATH=.maildir
> PRERUN="envdir /etc/relay-ctrl relay-ctrl-chdir"
> LOGINRUN="relay-ctrl-allow"

Repeat process for imapd-ssl, pop3d, pop3d-ssl files as well, except instead of IMAPDSTART you'll want to look for POP3DSTART or whatevers appropriate depending on the file. Now lets add courier to our bootup scripts so it launches when we fire up Gentoo.

Note: If you are attempting to use relay-ctrl with courier-imap but without vpopmail you will need to edit /usr/lib/courier-imap/gentoo-*.rc and add $LOGINRUN before ${exec_prefix}/sbin/imaplogin

> rc-update add courier-authlib default
> rc-update add courier-imapd default
> rc-update add courier-pop3d default
> /etc/init.d/courier-imapd start
> /etc/init.d/courier-pop3d start

Update the SMTPD Config to Allow SMTP-AUTH Using VPOPMAIL

I've tried alot of iterations on this but the easiest and most straight forward way is to completely delete the contents of your /var/qmail/control/conf-smtpd file and just replace it with this. You need not replace or tweak this file at all after putting this in.

> QMAIL_TCPSERVER_PRE="${QMAIL_TCPSERVER_PRE} envdir /etc/relay-ctrl relay-ctrl-chdir"
> QMAIL_SMTP_PRE="${QMAIL_SMTP_PRE} relay-ctrl-check"
> [ -z "${QMAIL_SMTP_POST}" ] && QMAIL_SMTP_POST=/bin/true
> QMAIL_SMTP_CHECKPASSWORD="/var/vpopmail/bin/vchkpw"

Note for qmail-1.03-r16 (and later?): If you're using qmail-1.03-r16 you will most likely have to change the last line above to QMAIL_SMTP_POST="${QMAIL_SMTP_CHECKPASSWORD} ${QMAIL_SMTP_POST}" for your server to accept SMTP connections.

Final touches to bring this together

> svc -t /var/qmail/supervise/qmail-smtpd
> chmod u+s /var/vpopmail/bin/vchkpw

The following step makes sending mail a lot faster under some circumstances, and I highly recommend that you do the following if you notice delays of 30 to 45 seconds sending mail:

> nano -w /var/qmail/control/conf-common
TCPSERVER_OPTS="-H -R -l 0" (that's lower-case L followed by zero)

Install Spam Database Clients

- snip - 

I have mercilessly edited the following spam/virus scanning instructions out as its now so out-of-date to just be misleading. I am personally going to workshop this in the next 30 days (today is March 12th) and will update this howto to reflect these new versions. Heck you couldn't even get ebuilds for the versions this was previously written for. That being said, if you get everything going this far and want to get on this before I do, please feel free. Functionality we're trying to reestablish from the original version of this how to includes

Qmail Scanner F-prot ClamAV SpamAssassin Pyzor Razor DCC

Install Squirrel Mail

> emerge squirrelmail
> cd /var/www/localhost/htdocs
> mv squirrelmail mail
> cd mail
> ./configure

Go forth and setup squirrelmail. Make sure the mail/data and mail/plugins directories are owned by vpopmail:vpopmail

Theres are some great plugins for squirrelmail including one for qmailadmin and another for virtual hosting. I encourage you to take a look and shop around a bit at for more details.

Install QMAIL Admin

> emerge /usr/portage/net-mail/ezmlm-idx-mysql/ezmlm-idx-mysql-0.40-r2.ebuild
> emerge /usr/portage/net-mail/autorespond/autorespond-2.0.4.ebuild
> emerge /usr/portage/net-mail/qmailadmin/qmailadmin-1.2.1.ebuild

You can access qmailadmin from here. If the image files are not showing, you'll have to copy the qmailadmin images to wherever apache is trying to access them from. You can find out where by checking your /var/log/apache2/error_log. Note that this version still does not use valias to maintain forward/alias info, and you'll need to install 1.2.1 from source for that to work.


I plan on adding troubleshooting that I've had to do in order to get qmail+vpopmail to work. I personally spent roughly 16 hours beating my head into the wall to get all this working to my smiling pleasure. Because information is so lacking, I thought I'd stick it here.

Remember, whenever changing the configuration for qmail, you need to run either of the two commands to have qmail use them:

svc -t /service/qmail-send
/etc/init.d/svscan restart

The Qmail Usenet Group has a fair amount of input on specific problems that happen with Qmail, and a few with Vpopmail working with Qmail.

Default Email Account: Let's say you want to have all email sent to a virtual domain dump to the mailbox "". To do this, create a .qmail-default file in that virtual domain's root directory (/var/vpopmail/domains/ Chmod to 644 just to be sure qmail can read it. In that file, add the following line:

| /var/vpopmail/bin/vdelivermail

In this case, I changed the me file (and the locals file) to be '' This way the system did not try to deliver mail to local users (see below), and would not also try to deliver mail meant for local users to be routed to the virtual domain.

No mailbox: This occurs when the system is trying to route a remote email to a local user, and said local

Additional Information

More in-depth information about the qmail MTA is available:

Retrieved from ""

Last modified: Sun, 08 Jun 2008 13:14:00 +0000 Hits: 44,193