Installing and configuring vpopmail

May 17, 2017 Roberto Puzzanghera28 comments

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 (original files here:, but you can download my local copy) 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.27.tar.gz
cd libev-4.27
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.


vchkpw auth errors

May need to fix suid permissions for vpopmail's vchkpw after compiling to avoid auth errors.


chmod ug+s /home/vpopmail/bin/vchkpw

Reply | Permalink

vchkpw auth errors

It wouldn't be better to run qmail-smtpd as vpopmail:vchkpw instead of letting everyone (not only qmail-smtpd) execute vchkpw with the owner's priviledges?

Reply | Permalink

libev missing

Hello Roberto,

I think I've found a small error in your guide: the latest available libev version is 4.27 and not 4.22:

Ciao !

Reply | Permalink

valias doesn't work


For some reason, vpopmail valias (i.e., storing valiases inside the MySQL database) doesn't work with chkuser, even if we configure both to do so. With valiases stored inside the database, vchkuser will reject emails sent to aliases (no mailbox). At least with me, chkuser only recognized valiases using the dot-qmail format. So, make sure to compile vpopmail with --disable-valias and --enable-qmail-ext as instructed, and remember that you will need to configure dot-qmail files for your aliases in the /home/vpopmail/domain/DOMAINNAME directory.

Reply | Permalink

Vusage configure error

I get this message during the configure phase of vusage and can't progress from there:

configure: error: No vauth_getpw in libvpopmail

So I am proceeding without implementing vusage (I also don't really acare about user quotas) so I hioe this will still work

Reply | Permalink

Vusage configure error

Same here, OS: Ubuntu 18.04

Reply | Permalink

Vusage configure error

look here (first item on google!)

Anyway everything will work even without vusaged

Reply | Permalink

Vusage configure error

Which unfortunately doesn't provide a solution...

If anyone managed to workaround this issue plz share here

Reply | Permalink

Vusage configure error

Try this:

LIBS=`head -1 /home/vpopmail/etc/lib_deps` ./configure --with-vpopmail=/home/vpopmail

Reply | Permalink


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


Reply | Permalink

if the aliases are stored in

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

Reply | Permalink


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.


Reply | Permalink

I agree. I will clarify this

I agree. I will clarify this in the lines above

Reply | Permalink

libev Version changed

Hi Roberto!

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

Reply | Permalink

Permission issue on tcp.*

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!!

Reply | Permalink

Hi Wlad,

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..). 

Reply | Permalink

Ok... I feel stupid.

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

Reply | Permalink

ps -ef|grep qmail

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...

Reply | Permalink



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

Reply | Permalink

Hi, which tool are you using

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

Reply | Permalink

Solved :)It was

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...

Reply | Permalink

Vpopmail configure


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


Reply | Permalink

Hello Winnetou This

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

Reply | Permalink

Hello!I'm aware that


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 

Reply | Permalink

If I understand well,

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

Reply | Permalink

I am installing vpopmail and

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!!

Reply | Permalink

can you dostrace

can you do

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

and see what happens?

Reply | Permalink

it works now

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. :)

Reply | Permalink