Guide updated on 29th of February 2016

Enabling web tools

In the two previous section, we 've installed 2 useful web tools (vqadmin and qmailadmin). We'll now enabling it ...

You first need to create appropriate name record in your DNS system (CNAME or A record). I advice you to create the alias mailadmin.yourdomain.tld pointing to your server IP. Whatever is your choice, this name should NOT BE THE SAME as your server hostname.

Then, create a virtual host corresponding to this new name record. Create the file /etc/apache2/sites-available/mailadmin.yourdomain.tld.conf as following :

<VirtualHost *:80>
        ServerAdmin your_email_adress
        DocumentRoot /var/www/mail
        ServerName mailadmin.yourdomain.tld
        ErrorLog /var/log/apache2/mailadmin.yourdomain.tld-error.log
        CustomLog /var/log/apache2/mailadmin.yourdomain.tld-access.log common
        <Directory /var/www/mail>
                AllowOverride All
                Options -Indexes
                Require all granted
        <Directory /var/www/mail/cgi-bin/>
                Options +ExecCGI +FollowSymLinks
                ForceType cgi-script
                Require all granted
        <Directory /var/www/mail/cgi-bin/vqadmin>
                AddHandler cgi-script .cgi
                ForceType Off
                AllowOverride None
                AuthType basic
                AuthName "private"
                AuthUserFile /var/www/mail/cgi-bin/vqadmin/.htpasswd
                Require valid-user
        <Directory /var/www/mail/images/qmailadmin/>
                ForceType Off
                Require all granted

You can create this virtualhost file like this :

cp /downloads/scripts/mailadmin.yourdomain.tld /etc/apache2/sites-available/mailadmin.yourdomain.tld.conf
cd /etc/apache2/sites-available/
sed -i 's/mailadmin.yourdomain.tld/mailadmin.yourdomain.tld/' mailadmin.yourdomain.tld.conf
sed -i 's/your_email_adress/' mailadmin.yourdomain.tld.conf

a2ensite mailadmin.yourdomain.tld
sed -e '/ScriptAlias/ s/^#*/#/' -i /etc/apache2/conf-available/serve-cgi-bin.conf
a2enmod cgi
systemctl restart apache2

We finally can test our web interfaces ...

Point your browser on http://mailadmin.yourdomain.tld/cgi-bin/vqadmin/vqadmin.cgi to test vqadmin (login: admin and the password you had chosen in step 7)

Point your browser on http://mailadmin.yourdomain.tld/cgi-bin/qmailadmin to test qmailadmin

Remove installed MTA

Users comments
Thibs - 05/08/2016 12:10

@Lorry :

If you are still using wheezy, try to add -wheezy on each page

For exemple the oldest version of this current page is

Lorry - 27/06/2016 11:58

There is another solution for wheezy  debian v 7.11, for Enabling web tools?

Lorry - 27/06/2016 11:48

 /etc/apache2/conf-available/serve-cgi-bin.conf not available in wheezy debian ????

Thibs - 28/09/2015 09:24


Do you have an error message in the logs ? The CGI files are dowloaded instead of executed ?

Best Regards



Bob d - 27/09/2015 20:40

I am having a bit of an issue getting the vqadmin and qmailadmin not firing when called upon. Debian 8.2 64bit. I have followed the steps, typing very carefully twice and copy and pasted the commands once with the same result. All of the cgi paths in the config files etc. are correct. Any suggestions?


Thibs - 27/05/2015 01:08


You can indeed have 2 different names (the server name and a CNAME)

Ajay - 16/05/2015 17:18


Thanks for the wheezy post. One small question. Can I use hostname.orginialdomainname.tld on this apache host configuration. Later you have configure host.original domain.tld for SMTP configuration. If I give different name, then I have to create two alias on my cpanel. Please suggest whether I should put the same name for both apache site and during SMTP configuration.

Eric - 01/03/2015 05:40

Okay, false alarm.

Turns out I have a coworker who thought it would be funny to setup a redirect and remove it every time I logged in.


So, everything works great.   Thanks

Thibs - 28/02/2015 12:52

Hello, Do you confirm you have the same as this :

root@YOURSERVER:~# ls -lah /var/www/mail/cgi-bin/vqadmin/
total 172K
drwxr-xr-x 3 vpopmail vchkpw   4.0K Feb 16 16:45 .
drwxr-xr-x 3 root     root     4.0K Feb 16 16:48 ..
-rw-r--r-- 1 www-data www-data  116 Feb 16 16:44 .htaccess
drwxr-xr-x 2 vpopmail vchkpw   4.0K Feb 16 16:43 html
-rw-r--r-- 1 root     root       44 Feb 16 16:45 .htpasswd
-rw-r--r-- 1 vpopmail vchkpw    864 Feb 16 16:43 vqadmin.acl
-rwsr-sr-x 1 root     root     145K Feb 16 16:43 vqadmin.cgi
Eric - 26/02/2015 15:56

First, I've installed Qmailrocks on a number of servers and it works fine.  This time has been different.

Okay, I've installed Qmailrocks on two different servers and twice on the same server with the same results when I am at this point to test the web tools.

On the first day, everything works fine.  I can get to vqadmin.cgi and qmailadmin and I can add domains and accounts with no issues.

On the second day, I can't access these two pages again!  Nothing was changed by me at all, all the files are still where they were.  DNS is still the same. And even using the IP addres instead of the domain name, gets me an error.

Not Found

The requested URL /cgi-bin/vqadmin/vqadmin.cgi was not found on this server.

Allen - 22/12/2014 21:46

For those of you who don't have access to your companies (or your own) DNS system, you can add the IP address of your Qmail server to your client workstations "hosts" file.


For example I'm setting up a Debian test machine in VMware and don't have access to my companies DNS server.  For this portion of the guide I set the FQDN as "mailadmin.acme.lan" with the ip address of my VM server) in my hosts file.

On Windows you can find this in your %SystemRoot%\Windows\System32\drivers\etc folder.  On Linux systems /etc/hosts is where you'll find it.

Obiously this will only work for those in a testing environment, you'll eventually want to set it up proper.

Hope that helps!


Sirnene - 31/08/2014 11:42

On ubuntu server need use

a2enmod cgi
a2enmod perl

delete .htaccess and on virtual conf add

AuthType Basic
AuthUserFile /var/www/mail/cgi-bin/vqadmin/.htpasswd
AuthName vQadmin
require valid-user
Options +ExecCGI -Indexes
order deny,allow
Stenhh - 30/03/2013 09:48


I have been running a mail server based upon this tutorial for several years without any problems. Thanks for the effort.

However, when trying to implement a secure webserver I encounter problems. My I kindly request that the tutorial reflects also this important part. I would appreciate that the tutorial also cover this issue in the same excellent way that the rest of subjects.

Thanks in advance


Thibs - 28/03/2013 22:46

@Jurgen Your advice is good ...  In my case I've made a certificate especially for that (

Jurgen - 26/03/2013 22:07

a feature for those who are interested, I added the following to the above vhost configuration to add SSL to everything using the mailadmin sub domain:

#a2enmod ssl

now edit the site vhost file:

<VirtualHost *:443>


+        SSLEngine On

+        SSLCertificateFile      /var/qmail/control/clientcert.pem

+        SSLCertificateKeyFile   /var/qmail/control/clientcert.pem


and thats it, everything is now enrypted using the certificatse created earlier in the howto.
Tomaszg - 22/02/2013 12:48

One year later..

Deploying next server.

Forgot about:

a2enmod ssl

Enabling module ssl.

Tomaszg - 28/03/2012 14:53

Forgot about enabling SSL module:

a2enmod ssl

Thibs - 08/03/2012 17:10

Good suggestion !

BTW, It's possible to have FREE official certificates through

Tomaszg - 07/03/2012 17:03

Ok, now all is working  fine.

I recommend use HTTPS instead of HTTP since there are clear passwords.

To enable HTTPS in Apache:

Generate certs:
openssl genrsa -out /etc/apache2/ssl/apache.key 1024
openssl req -new -x509 -days 365 -key /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt

and check it:
openssl x509 -in /etc/apache2/ssl/apache.crt -noout -subject

Modify Apache website:

<VirtualHost *:443>
SSLEngine On
SSLCertificateFile /etc/apache2/ssl/apache.crt
SSLCertificateKeyFile /etc/apache2/ssl/apache.key
<Directory /var/www/someweb/>
AllowOverride All
Order Deny,Allow
Allow from all

And it will work. I've disabled Qmail over 80, so only 443 is enabled.

Tomaszg - 07/03/2012 15:09

It worked like a charm.

However, now I'm trying to add HTTPS support to every admin panel in Qmail.

There is /etc/apache2/sites-available/default-ssl file but seems it doesn't work (going to https://server_ip shows no page available, site is enabled anyway). No clear error in /var/log/apache2/error.log.. port is opened.. hmm still investigating issue

Richard mastny - 03/02/2012 03:55

Invalid language file

cd /var/www/mail/cgi-bin/vqadmin/html

e.g.: cp de de-de

but be aware!

some browsers have set e.g. "de-DE" (the second "DE" is UPPERcase!)

so you have to cp de de-DE

Abdullah aykir - 11/11/2011 16:48

You may get

Invalid language file

error if your browser uses a default language encoding other than the ones that are supported by vqadmin. The quick solution is to copy one of the language files with a new name.


assume your vqadmin is installed in /var/www/mail/cgi-bin/vqadmin/

than you can do

cd /var/www/mail/cgi-bin/vqadmin/html

cp en tr

that solved my problem with Turkish encoding.


Thanks for the greate site.

Greg - 29/10/2011 07:42

What is the default User Account , Domain Name and Password for qmailadmin ?? After this process ??

Thibs - 20/12/2010 12:36

>In your instruction what FQDN do you use to access the webmail interface?  mailadmin.yourdomain.tld/webmail

Refer to for the webmail part

>Why do you suggest the hostname be different from the mailadmin.yourdomain.tld?

It's to avoid changing the default apache configuration. I just make the changes into a virtual host

Rdun - 15/12/2010 03:48


 In your instruction what FQDN do you use to access the webmail interface?  mailadmin.yourdomain.tld/webmail

Why do you suggest the hostname be different from the mailadmin.yourdomain.tld?

Ivo - 27/09/2010 18:50

If you are not able to add a new domain in vqadmin , try tail -n 20 /var/log/apache2/mailadmin.yourdomain.tld-error.log

If you see something like "Warning: Failed to delete dir_control for yourdomain.tld" then check your mysql connection settings in /home/vpopmail/etc/vpopmail.mysql

Color Coded Qmail Installation Key
  Regular Black Text     Qmail installation notes and summaries by the author.
  Bold Black Text     Commands to be run by you, the installer.
  Bold/Regular Red Text    Vital and/or critical information.
  Regular Blue text     Denotes helpful tips and hints or hyperlinks.
  Regular Orange Text     Command line output.
  Bold/Regular green text     Denotes the contents of a file or script.