Installing and configuring vpopmail

Vpopmail provides an easy way to manage virtual email domains and non /etc/passwd email accounts on your mail servers.

The purpose of this note is to show how to use Mysql as the authentication system. Having a users database also offers the advantage of communicating with the database via PHP, and creating web-based user interfaces to manage accounts.


Create vpopmail user and group:

groupadd -g 89 vchkpw
useradd -g vchkpw -u 89 -d /home/vpopmail vpopmail

Download the source from here: and configure. I tested the following with vpopmail-5.4.30 - 32 - 33

cd /usr/local/src
tar xzf vpopmail-5.4.33.tar.gz
cd vpopmail-5.4.33
chown -R root.root .
./configure \
        --enable-qmaildir=/var/qmail/ \
        --enable-qmail-newu=/var/qmail/bin/qmail-newu \
        --enable-qmail-inject=/var/qmail/bin/qmail-inject \
        --enable-qmail-newmrh=/var/qmail/bin/qmail-newmrh \
        --disable-roaming-users \
        --enable-auth-module=mysql \
        --enable-incdir=/usr/include/mysql \
        --enable-libdir=/usr/lib64 \
        --enable-logging=p \
        --disable-clear-passwd \
        --enable-auth-logging \
        --enable-sql-logging \
        --disable-valias \
        --disable-mysql-limits \
        --disable-passwd \
        --enable-qmail-ext \

--disable-roaming-users roaming users will be disabled, since we don't want to use POP before SMTP authorization. We will patch qmail with smtp-auth instead.

--enable-auth-module=mysql builds mysql support and  stores virtual users accounts into a mysql database.

--enable-incdir=/usr/include/mysql Your MySQL include dir (use just in case you installed mysql from binaries or source in a non standard location. Mount mysql dir somewhere if it is installed in a different machine).

--enable-libdir=/usr/lib64 Your MySQL lib dir. Obviously it might be /usr/lib on 32b systems

--disable-valias Do not store aliases in MySQL, but as dot-qmail files.
Note: it appears that dovecot-lda continues to look for .qmail-alias files also when you enable this. So this option is useless if you deliver via dovecot-lda

--disable-passwd Don't include /etc/passwd support. I don't want to manage real users, this is just a web server.

--disable-clear-passwd Clear password will be not be saved on DB. If you don't want to have problems when users forget their passwords and you want to recover them quickly switch this to --enable-clear-passwd. I also noticed that using the --disable-clear-passwd flag the change password mechanism is broken at least on version 5.4.33 (comments are welcome)

--enable-sql-logging Maintain the vlog table in MySQL (shows failed authentication requests).

--enable-auth-logging Maintain a lastauth table in MySQL (shows when / how a user last accessed their email)

--disable-mysql-limits MySQL doesn't store limits instead of .qmailadmin-limits files.

--enable-qmail-ext Enable qmail email address extension support (emails containing dots).

Compile and install:

make install-strip


vusaged looks up every vpopmail user and tracks how much storage space they’re using. It requires libev.

Installing libev

cd /usr/local/src
tar xzvf libev-4.22.tar.gz
cd libev-4.22
chown -R root.root .
make install

Installing and configuring vusaged

cd /usr/local/src/vpopmail-5.4.33/vusaged
cp -f vusaged /home/vpopmail/bin
cp -f etc/vusaged.conf /home/vpopmail/etc

Now copy the startup script ro /etc/rc.d (Slackware) or init.d and run it. This is a Slackware example:

cp contrib/rc.vusaged /etc/rc.d/
/etc/rc.d/rc.vusaged start


Check your ~vpopmail/etc/tcp.smtp file This file should list all the static IPs of your machines that you want to allow to relay out to the internet. For example: to allow relaying for localhost and the localnet 10.0.0.x edit your ~vpopmail/etc/tcp.smtp as follows:


add any other IP later, whenever you want. To give a client relay access, add an entry to ~vpopmail/etc/tcp.smtp like:

IP address of client:allow,RELAYCLIENT=""

Now build the tcp.smtp.db. This command must be run every time you modify tcp.smtp

cd ~vpopmail/etc
tcprules tcp.smtp.cdb tcp.smtp.tmp < tcp.smtp

Now setup a quota warning that will be delivered to users when they are at 90% quota

# nano ~vpopmail/domains/quotawarn.msg

From: SomeCompany Postmaster <>
To: SomeCompany User:;
Subject: Mail quota warning
Mime-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: 7bit

Your mailbox on the server is now more than 90% full.

So that you can continue to receive mail,
you need to remove some messages from your mailbox.

If you require assistance with this,
please contact our support department :

  email :
  Tel   : xx xxxx xx
chmod 600 ~vpopmail/domains/quotawarn.msg
chown vpopmail.vchkpw ~vpopmail/domains/quotawarn.msg

Now adjust ~vpopmail/etc/vlimits.default. I use to limit the default user quota to 100MB (in bytes):

default_quota           104857600

Fixing vusaged bug (only vpopmail 5.4.30)

This bug appears to have been fixed in version 5.4.32. So skip this section if you’re installing 5.4.32.

Setting the default quota seems to cause this error when creating new domains:

client_connect: warning: config_begin failed
Segmentation fault

I saw the same error when creating new users via qmailadmin. This appears to be a bug in the 5.4.30 version: So, even if you're not using vusaged it'll be necessary  to configure vusaged.conf as by Matt Brookings suggests, in order to avoid this bug:

cat > ~vpopmail/etc/vusagec.conf << __EOF__
  Disable = True;

If you’re interested in reading more about this, see, where Matt says that vusaged isn’t needed (for quotas to work) in vpopmail version 5.4.30.

Configuring mysql back end

Create the vpopmail user and database. Grant all privileges to the vpopmail user. Then quit out of MySQL and save the authentication information for the vpopmail account into the vpopmail.mysql config file:

> /usr/local/mysql/bin/mysql [-h mysql-IP] -u root -p 

CREATE USER 'vpopmail'@'mailserver-IP' IDENTIFIED BY 'vpopmailpwd'; 

GRANT ALL PRIVILEGES ON `vpopmail` . * TO 'vpopmail'@'mailserver-IP';

> echo "mysql-IP|0|vpopmail|vpopmailpwd|vpopmail" > ~vpopmail/etc/vpopmail.mysql

where mysql-IP is the IP of the server which runs mysqld, and mailserver-IP is the IP address where qmail is running. Usually you can specify ‘localhost’ or for both.

Creating virtual domains and virtual users

cd ~vpopmail/bin/

To add/delete a virtual domain

./vadddomain [./vdeldomain]

To add/delete a virtual user

./vadduser [./vdeluser]

To view information about user email accounts:


name:   user
passwd: xxxxxxxxxxxx
clear passwd: xxxxxxxxx
comment/gecos: Name Surname
uid:    0
gid:    0
flags:  0
gecos: Name Surname
limits: No user limits set.
dir:       /home/vpopmail/domains/
quota:     104857600S

These commands can be useful. But it will be much easier to manage domains and accounts when we install the vqadmin and qmailadmin web interfaces later.

You may be interested to take a look to this page concerning vpopmail testing.


I am installing vpopmail and vusaged on CentOS release 6.4 (Final)

but i encountered the error on vusaged.

[root@Dev vusaged]# /etc/rc.d/rc.vusaged start
Starting vusaged: failed

What is the problem? I am googling bu i couldn't found the solution.

please help me!!

can you do

strace /etc/rc.d/rc.vusaged start

and see what happens?

It works now. I uninstalled the libev source then installed libev using yum rpmforge repository.

# make uninstall
# yum -y install libev libev-devel

Sorry for the late reply. I totally forgot about this. I gave up last time and set up qmailtoaster on Centos 6 which was successful.

Now, I am experimenting qmail again using this setup. :)


While running ./configure on Gentoo systems (probably on other systems also) you have to add following options:

--enable-incdir=/usr/include/mysql \

Vpopmail works also with MariaDB 5.5.37 

BTW THX for great tutorial ;)

Best Regards


Hello Winnetou

This is the default location for mysql and mariadb, and I suppose that normally you don't even need to add those options, as the library will be automatically found. I  just added them for those (like me) who compile from source or don't use the package provided by their own distro


I'm aware that those paths are default and ./configure should find them, but it didn't, that's why I decided to post a comment ;)

When I run ./configure without those 2 optins it failed. I was installing qmail and vpopmail on freshly installed Gentoo 

If I understand well, omitting those two options gets vpopmail not to find the libraries?

Anyway as soon as possible I will add a clarification on the purpose


Some clients change their passwords with non-ascii char like "ěščřžýáíé", but these characters are broken in MySQL as clear passwords. Any idea what charset set to Mysql db or how to set vpopmail to use UTF-8? Everythink else is in UTF...

Anyway if i do /home/vpopmail/bin/vuserinfo clear password is ok, but in MySQL

SELECT pw_clear_passwd FROM vpopmail WHERE  pw_name .... password is broken

Hi, which tool are you using to change the pwd? I can use UTF8 characters here when connecting via imap/roundcube pwd plugin, but if I try with qmailadmin I get an error...

PS: and I can retrieve the clear pwd with an SQL query

Solved :)

It was misconfigured MySQL. I have no idea what charset did connection use when it was not configured but when I set this to my.cnf it start working correctly




collation-server = utf8_unicode_ci
init-connect= 'SET NAMES utf8'



Other problem is password from outlook... But I think there is no solution for clients using non UTF8 charset...

First of all, Roberto - THANK YOU for taking the time to put this resource together! I've formerly used JMS' tutorials etc but that was years ago. Once qmail etc is set up and working, you almost never have to touch it again except for security updates or maintenance so it's easy to forget the inner workings!

I have everything going so far but haven't been able to get passed the testing stages; When I telnet to 587, the logs for qmail-submission gives me this:

warning: dropping connection, unable to read /home/vpopmail/etc/tcp.submission.cdb: access denied 

Can you please confirm what the perms are supposed to be? Right now they're owned by root at 644. Any pointers on this would be greatly appreciated!!

Hi Wlad,

yes the priviledges are correct. It's strange because every user should be able to read that file.. 

Anyway, who is the user who runs qmail-smtpd and qmail-submission? If you migrated from JMS configuration you may have to check/adjust the priviledges of the ~vpopmail/ dir.  In particular I suggest to check if the vpopmail:vchkpw userIDs are 89:89 (if I remember well JMS configuration uses non standard IDs for users..). 

ps -ef|grep qmail
root       606  1831  0 11:17 pts/0    00:00:00 grep --color=auto qmail
root      1865  1863  0 Jan08 pts/0    00:00:00 supervise qmail-smtpd
root      1871  1863  0 Jan08 pts/0    00:00:00 supervise qmail-send
root      1875  1863  0 Jan08 pts/0    00:00:00 supervise qmail-submission
qmaill    1877  1866  0 Jan08 pts/0    00:00:00 /usr/local/bin/multilog t s16000000 n200 /var/log/qmail/smtpd
qmaill    1879  1872  0 Jan08 pts/0    00:00:00 /usr/local/bin/multilog t s16000000 n200 /var/log/qmail/send
qmaill    1881  1874  0 Jan08 pts/0    00:00:00 /usr/local/bin/multilog t /var/log/qmail/vpopmaild
qmaill    1884  1876  0 Jan08 pts/0    00:00:00 /usr/local/bin/multilog t s16000000 n200 /var/log/qmail/submission
qmails   16495  1871  0 02:13 pts/0    00:00:00 qmail-send
vpopmail 16497  1865  0 02:13 pts/0    00:00:00 /usr/local/bin/tcpserver -v -H -R -l 0 -x /home/vpopmail/etc/tcp.smtp.cdb -c 20 -u 89 -g 89 0 25 /var/qmail/bi                                                                    n/qmail-smtpd
vpopmail 16499  1875  0 02:13 pts/0    00:00:00 /usr/local/bin/tcpserver -v -H -R -l 0 -x /home/vpopmail/etc/tcp.submission.cdb -c 20 -u 89 -g 89 0 587 /var/q                                                                    mail/bin/qmail-smtpd /home/vpopmail/bin/vchkpw /bin/true
root     16508 16495  0 02:13 pts/0    00:00:00 qmail-lspawn | /home/vpopmail/bin/vdelivermail '' bounce-no-mailbox
qmailr   16509 16495  0 02:13 pts/0    00:00:00 qmail-rspawn
qmailq   16510 16495  0 02:13 pts/0    00:00:00 qmail-clean
qmails   16511 16495  0 02:13 pts/0    00:00:00 qmail-todo
qmailq   16512 16495  0 02:13 pts/0    00:00:00 qmail-clean

Wow long/ugly past - but all ownerships seem fine from looking at this and I'm perplexed. As for JMS, that was years ago on a separate server. I founds this guide last night and like the fact that things can be updated with the most current - in regards to paches etc. Versions of other sources:

Vpopmail: 5.4.33,
libev: 4.22
netqmail: 1.06
libsrs2: 1.0.18
libdomainkeys: 0.69

And yes, id -g/-u vpopmail:vchkpw are both 89; I've turned every kind of permission based type of app off (apparmor for instance), every firewall etc etc with no change. I got no errors during compilation and did everything step by step and in order on this brand new server running ubuntu with multiple IPs. Speaking of IPs that was something I was going to ask about as well on how to specifically bind 587/25 to a specific IP but as long as MX records are set up properly there shouldn't be a need for that.

Roberto, sorry about the long post - just trying to figure this one out as everything seems to be running fine and like you said perms are right...

Ok... I feel stupid. ~vpopmail main dir was owned by root:root grrrr. Works now. ALL those dang hours - that happens when it's late, going on no sleep :) Again Roberto, thank you for this great guide! Lots of Coffee incoming to you haha

Hi Roberto!

The libev 4.11 not exits, this changed to 4.22, at link

Hi Roberto,

As far I know and dovecot-lda is concerned it is not the presence of the configuration flag --enable-valias that hinders dovecot LDA from delivering to aliases it is the absence of a .qmail-'alias' alias file


if the aliases are stored in the database, why the .qmail-alias is needed?

Hi Roberto,

I was only trying to point out that dovecot-lda is not affected by the --disable-valias/--enable-valias flags. On the other hand vdelivermail is affected and will use dot-qmail files in one case and the virtual alias database in the other case.
Dovecot-lda and --enable-valias can live quite happily together as long as you use dot-qmail files for you aliases.


I agree. I will clarify this in the lines above