Installing and configuring VPopMail

September 1, 2025 by Roberto Puzzanghera 192 comments

VPopMail version: 5.6.9
github: sagredo-dev/vpopmail
Download
Changelog
README.vdelivermail
Inter7's original page

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

Changelog

Sep 1, 2025 (v. 5.6.9)
- added -std=gnu17 to gain compatibility with gcc-15 (PR #6)
- pw_clear_passwd field enlarged to varchar(128) to create room for long passwords (tx Ricardo Brisighelli) c54688d
Mar 29, 2025 (v5.6.8)
defaultdelivery feature (--enable-defaultdelivery) changes (more info here, commit):
- vdelivermail is installed by default in .qmail-default of newly created domains with option 'delete' as in the previous version.
- if no user's valiases and no .qmail are found, then the message is sent to the control/defaultdelivery file, so that dovecot-lda (or whatelse) can execute the sieve rules and finally store the message into inbox.
- if vdelivermail is found in control/defaultdelivery, then it is ignored to avoid loops. The delivery is done by vdelivermail
- v. 5.6.8 is backward compatible. The users having .qmail from previous versions of the defauldelivery feature are not affected by this change.
Mar 23, 2025 (v. 5.6.7)
- bug fix in vpopmaild.c: Crypted[64] enlarged to Crypted[128] to make room for SHA-512 passwords. This restores the usability of the RoundCube's 'password' plugin (commit)
- fixed quota calculation in sql procedures for dovecot (tx Hakan Cakiroglu) (commit)
- minor changes to the usage function of vmakedotqmail.c (commit)
Feb 9, 2025 (v. 5.6.5)
- added pwd strength check also for vadduser.c
- removed -std=c99 -D_XOPEN_SOURCE=500 arguments from CFLAGS in configure.ac to make clang happy
- several changes to compile on FreeBSD clang v. 18.1.6
Dec 20, 2024 (v 5.6.4)
- Password strength enforcement (PR #5, grabbed from Matt Brookings' 5.5.0-dev version)
- Dropped min pwd length feature.
- vmysql.h: tables' layout changed in order to have VARCHAR instead of CHAR. Fields containing ip addresses enlarged to VARCHAR(39), to create room for ipv6. Unix timestamps definition changed from BIGINT(20) to INT(11). (commit 44bad58) Have a look to the upgrade notes below.
Oct 14, 2024 (v. 5.6.2)
- fixed a configure break where a trivial C test program exits on error with gcc-14.1 due to missing headers
- vusaged/domain.c: fixed -Wimplicit-function-declaration compilation warning
- vmysql.h: dropped the multicolumn PRIMARY KEY in valias table to allow multiple forwards for a given alias.
   In case one already has the valias table defined, this is the sql query for the upgrade:
   ALTER TABLE `vpopmail`.`valias` DROP PRIMARY KEY, ADD INDEX (`alias`, `domain`, `valias_type`) USING BTREE;
   ALTER TABLE `vpopmail`.`valias` ADD `id` INT NOT NULL AUTO_INCREMENT FIRST, ADD PRIMARY KEY (`id`);

Program changes made by me

The vpopmail-5.6.x code has been modified by several people, in particular by TLK games who started the project in 2022 adding all existing patches arouund the net, mine included. Unfortunately that project appears to be abandoned, so I decided to continue on my own fork.

I made latest vpopmail gcc and clang compliant and (among the other things) added the following features:

sql-aliasdomains, which makes vpopmail save the aliasdomains to MySQL. This makes the dovecot sql auth driver aware of the aliasdomains, provided that you modify the sql query as well (see the dovecot page for more info).
defaultdelivery feature: vdelivermail is installed by default in .qmail-default of newly created domains with option 'delete'. If no user's valiases and no .qmail are found, then the message is sent to the control/defaultdelivery file, so that dovecot-lda (or whatelse) can store the mail into inbox and execute the sieve rules. if vdelivermail is found in control/defaultdelivery, then it is ignored to avoid loops. The delivery remains in charge to .qmail-default, i.e. vdelivermail.
More info here, have also a look to the doc/README.defaultdelivery file.
dovecot-sql-procedures patch
If you want to use the dovecot's sql auth driver with one table for each domain (--disable-many-domains) you have to heavily customize your queries to the sql database. With this patch vpopmail installs the sql procedures and functions in the database when you create a new domain. The procedures can be called by dovecot to perform the auth.
The sql stuff supports aliasdomains and mysql limits and will be loaded from ~/vpopmail/etc/disable-many-domains_procedures.sql. You can customize the sql procedure editing this file.
You have to configure with --enable-mysql-bin=PATH as we have to install the procedures calling the mysql bin as a shell command (no way to load an sql query from a file in C language, comments welcome).
the MySQL database schema has been revised switching all char columns to varchar
s/qmail cdb patch This patch, which gets vpopmail to locate correctly the qmail assign.cdb for s/qmail users, it's not used anymore because it was replaced by a similar patch, where s/qmail users should compile vpopmail with --enable-qmail-cdb-name=assign.cdb
recipient check patch. It can be used with Erwin Hoffmann's s/qmail to accomplish the recipient check. Not important in my installation, look at doc/README.vrcptcheck for more info.
A fix to the following issues (patch by Ali Erturk TURKER):
- vdelivermail.c checks spamassassin permissions, instead of maildrop permissions.
- vopen_smtp_relay() return values corrected, so that open_smtp_relay() can detect and report database connection errors (vmysql.c, voracle.pc, vpgsql.c)
- vdel_limits() core-dumps if a database connection is not available beforehand. (vmysql.c, voracle.pc)

Upgrading to v. 5.6.x

When upgrading from version 5.4.33 to version 5.6.x, if you have the accounts on SQL, you should enlarge the vpopmail.pw_passwd column size, as the default password encryption is SHA512, which is longer than the old MD5; you can disable SHA512 pwd with --disable-sha512-passwords at configure time. The default dimension for the vpopmail.pw_passwd column is now 128.
Here is the SQL query to upgrade the vpopmail table:

ALTER TABLE `vpopmail` CHANGE `pw_passwd` `pw_passwd` VARCHAR(128) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL;

Upgrading from version 5.6.3 to 5.6.4

Several other non breaking changes have been made to the MySQL tables' layout. Here is how you can quickly alter the tables (inlcluded the change mentioned above):

/* vpopmail */
ALTER TABLE `vpopmail` CHANGE `pw_name` `pw_name` VARCHAR(64) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL; 
ALTER TABLE `vpopmail` CHANGE `pw_domain` `pw_domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL; 
ALTER TABLE `vpopmail` CHANGE `pw_passwd` `pw_passwd` VARCHAR(128) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL;
ALTER TABLE `vpopmail` CHANGE `pw_gecos` `pw_gecos` VARCHAR(64) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL;
ALTER TABLE `vpopmail` CHANGE `pw_dir` `pw_dir` VARCHAR(160) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL;
ALTER TABLE `vpopmail` CHANGE `pw_shell` `pw_shell` VARCHAR(20) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL; 

/* vlog */
ALTER TABLE `vlog` CHANGE `user` `user` VARCHAR(32) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL; 
ALTER TABLE `vlog` CHANGE `passwd` `passwd` VARCHAR(32) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL;
ALTER TABLE `vlog` CHANGE `domain` `domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL; 
ALTER TABLE `vlog` CHANGE `remoteip` `remoteip` VARCHAR(39) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL; 
ALTER TABLE `vlog` CHANGE `error` `error` TINYINT(1) NULL DEFAULT NULL;
ALTER TABLE `vlog` CHANGE `timestamp` `timestamp` INT NOT NULL DEFAULT '0'; 

/* lastauth */
ALTER TABLE `lastauth` CHANGE `user` `user` VARCHAR(32) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL; 
ALTER TABLE `lastauth` CHANGE `domain` `domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL; 
ALTER TABLE `lastauth` CHANGE `remote_ip` `remote_ip` VARCHAR(39) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;
ALTER TABLE `lastauth` CHANGE `timestamp` `timestamp` INT NOT NULL DEFAULT '0'; 

/* limits */
ALTER TABLE `limits` CHANGE `domain` `domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL; 

/* alias */
ALTER TABLE `valias` CHANGE `alias` `alias` VARCHAR(32) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;
ALTER TABLE `valias` CHANGE `domain` `domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;

/* dir_control */
ALTER TABLE `dir_control` CHANGE `domain` `domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;

/* aliasdomains */
ALTER TABLE `aliasdomains` CHANGE `alias` `alias` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;
ALTER TABLE `aliasdomains` CHANGE `domain` `domain` VARCHAR(96) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL;

Setup

Create the vpopmail user and group. Be aware that the home directory below is going to be the one where vpopmail will be installed, so you can change it if you want to have vpopmail elsewhere. You can also decide to assign different uid/gid to vpopmail, as qmail will be able to determine them dinamically.

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

In the following configure command you may have to replace --enable-incdir=/usr/include/mysql with --enable-incdir=/usr/include/mariadb or whatelse, depending on the location where your system installed the library and its headers.

VPOPMAIL_VERSION=5.6.9
wget https://github.com/sagredo-dev/vpopmail/archive/refs/tags/v${VPOPMAIL_VERSION}.tar.gz
tar xzf v${VPOPMAIL_VERSION}.tar.gz
cd vpopmail-${VPOPMAIL_VERSION}
chown -R root:root .

# freebsd users may have to issue an 'autoreconf -f -i' here
./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=e \
        --disable-clear-passwd \
        --enable-auth-logging \
        --enable-sql-logging \
        --disable-passwd \
        --enable-qmail-ext \
        --enable-learn-passwords \
        --enable-mysql-limits \
        --enable-valias \
        --enable-sql-aliasdomains \
        --enable-defaultdelivery

--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-authentication 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-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 not be saved to database for security reasons. 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.

--enable-logging=e Logs failed attempts on syslog (no failed passwords will be shown).

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

--enable-mysql-limits MySQL stores domain limits instead of .qmailadmin-limits files.

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

--enable-sql-aliasdomains (default) saves domain aliases to MySQL in order to validate the authentication for domain aliases when using the dovecot's sql driver, provided that you modify the password_query accordingly.

--enable-valias Store aliases in MySQL

--enable-defaultdelivery send the email to control/defaultdelivery after checking the user's virtual aliases and .qmail files respectively. control/defaultdelivery can run dovecot-lda to execute the sieve rules and finally store the message into inbox. More info here.

s/qmail users should add --enable-qmail-cdb-name=assign.cdb as the users/assign file is compiled as assign.cdb and not as cdb.

Compile and install:

make install-strip

`vusaged`

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

Installing `libev`

Official page

We need to install the header files in /usr/local/include/libev to avoid conflicts with the libevent library (they both have an event.h header file), which is probably already installed.

cd /usr/local/src
wget  http://dist.schmorp.de/libev/libev-4.33.tar.gz
tar xzvf libev-4.33.tar.gz
cd libev-4.33
chown -R root:root .
./configure --includedir=/usr/local/include/libev
make
make install
ldconfig

Installing and configuring `vusaged`

VPOPMAILDIR=/home/vpopmail
cd /usr/local/src/vpopmail-${VPOPMAIL_VERSION}/vusaged
LDFLAGS=-L/usr/local/lib CFLAGS=-I/usr/local/include/libev LIBS=`head -1 $VPOPMAILDIR/etc/lib_deps` \
./configure --with-vpopmail=$VPOPMAILDIR
make
cp -f vusaged ~vpopmail/bin
cp -f etc/vusaged.conf ~vpopmail/etc

Troubleshooting

If you get an error like this after the configure command

configure: error: No vauth_getpw in libvpopmail

try to rebuild the configure script in this way:

autoreconf -f -i

and then proceed to configure and compile. I patched the configure.ac to avoid the break. This is actually a work around. If you solve the library linking error let me know.

Take a look to the discussion in the comments, as Luca suggested a different solution, which didn't solve for me but that I'm suggesting above in this page.

Quota setup

You don't actually have to let vpopmail handle the quota warnings, as Dovecot can do it in a more efficient way. I'm leaving here this paragraph in case is still usefull to anyone.

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

# nano ~vpopmail/domains/.quotawarn.msg

From: SomeCompany Postmaster <postmaster@yourdomain.com>
Reply-To: postmaster@yourdomain.com
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 : support@yourdomain.com
  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 400MB (in bytes):

default_quota           419430400

Configuring `mysql` back end

Create the vpopmail user and database. Grant all privileges to the vpopmail user:

> mysql [-h mysql-IP] -u root -p 

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

GRANT USAGE ON * . * TO 'vpopmail'@'mailserver-IP' IDENTIFIED BY 'vpopmailpwd' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0 ;
CREATE DATABASE IF NOT EXISTS vpopmail;
GRANT ALL PRIVILEGES ON `vpopmail` . * TO 'vpopmail'@'mailserver-IP';

Then quit out of MySQL and save the authentication information for the vpopmail account into the vpopmail.mysql config file:

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

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 0.0.0.0 for both.

Creating virtual domains and virtual users

cd ~vpopmail/bin/

To add/delete a virtual domain

./vadddomain yourdomain.net [./vdeldomain yourdomain.net]

To add/delete a virtual user

./vadduser user@yourdomain.net [./vdeluser user@yourdomain.net]

To view information about user email accounts:

./vuserinfo user@yourdomain.net

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/yourdomain.net/user
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.

Domain aliases when using the `dovecot`'s sql auth driver

If you don't have domain aliases or this is a fresh installation you can skip this step.

If you already have domain aliases and want to switch to the dovecot's sql auth driver, don't forget to read carefully the page where the vpopmail/dovecot setup concerning domain aliases is explained, as you'll have to save your existing alias/domains pairs to MySQL.

In short, you can quickly save all your domain aliases to MySQL in this way

vsavealiasdomains -A

Type

vsavealiasdomains -h

for more options.

The database record will be saved by VPopMail for the new aliases that you will create from now on.

Password strength enforcement feature

Starting from version 5.6.4 we have a password strength enforcement feature, that I grabbed from the development version 5.5.0 that was never released. To find out how it works it is sufficient to read the documentation in the configuration file (do not rename it).

I think that this is a feature to be addressed to the end users or to the domain administrators, rather than to us server administrators. This is the reason why you may choose to disable it, leaving the default configuration as is. In fact, as you know, we already have cracklib securing the password strength on qmailadmin side. Or you can decide to enable this additional check if you want to secure the password change plugin shipped with the webmail (Roundcube has a password plugin).

qmail

Upgrading qmail

add a comment

Comments

VPOMAIL migration from version

Ricardo Buchalla Auada October 20, 2025 20:18 CET

Hi Roberto !

I opened this new thread, because the other one was solved. Thank you.

I have a platform that uses vpopmail 5.4.33 (the old stuff).

And I am migrating my whole system for an updated version.

I installed vpopmail 5.6.9 and it´s working fine, as per the other thread.

I pointed the new vpopmail to the old mysql database, that is running for the version 5.4.33, and tried to change the password of one of my accounts, for a testing matter.

What happens is that my old system does not undestand the codification and brings an auth error.

I haven´t yet adjusted the old mysql database for larger passwords, as explained in the page, because I´m affraid of "breaking" the old system that is a production one.

So, I wonder if:

1- the problem with the password for the new vpopmail not being compatible with the old system is just a matter of issuing the mysql commands for larger passwords, as you instructed in the page

2- if I do modify the old mysql with these commands, will it keep working normally for the old platform, or it might break.

I need the mysql database to be able to work for both platform, the old and the new one, because I cannot afford to reset all the passwords.

Thank you!

Best regards,

Ricardo Auada