http:// / scripts / rules / install.shtml

Installing the qmail Rules Interface

This page documents how to install the qmail rules interface system on your own server.

The web service's CGI scripts and the email processing script are all written in Perl. I tried to make the code as clear as I could, and have included enough comments that anybody who is at least halfway familiar with Perl should be able to read and understand them. There is also one simple shell script, used for setting the permissions on the files.


There are a few things which will need to be done on the server ahead of time in order to set up this system.

Once you have verified these items, you should be ready to start installing the system.


There are two ways to download the system.

Whichever option you choose, there are two more things which need to be done before you can use the system:

The first thing is to copy the .htaccess.dist file to .htaccess. This is because certain things about the web site (i.e. how to reach the database, how to reach vpopmaild, and a few tweaks on the visual appearance of the site) are configured using SetEnv lines in the .htaccess file, and I don't want updates (whether via tarball or subversion) to overwrite your configuration.

The other thing is to run the script. As the name implies, this will set the permissions on the files so that Apache will be able to read them.

If you are using the subversion repo, any time you do an svn update command in the future, you should run the script again.

$ cd /www/ (the web site's DocumentRoot)
$ cp .htaccess.dist .htaccess
$ sh

At this point, we can start setting up the application itself.

The Database

The process of setting up the database will be different, depending on which database engine you're using. Rather than trying to cram it all into one page, I have written separate pages for each database engine on which I have tested the system.

It should be possible to make the system work with other database engines (i.e. Oracle, Sybase, etc.) however I have no way to write or test the code to make that happen. The system uses the Perl DBI interface to connect to whatever engine you're using, so in theory any of the database engines with a DBD module should be usable.

Once the database is set up, you should be able to configure and use the web interface to be used to start creating rules.

Database Description

I have also written a page which describes the database schema and the codes used within the database.

The Web Interface

Create the .htaccess file

The configuration of the web interface is mostly done by changing environment variables in the .htaccess file. This file is not directly included with the download, however there is a file called .htaccess.dist which you should copy to .htaccess, and then customize it for your needs.

I did this for two reasons:

# cd /www/ (your web site's DocumentRoot)
# cp .htaccess.dist .htaccess
# ./


Once you have created the .htaccess file itself, you will need to edit the file. The variables you can configure are:

Assuming everything goes well, you should now be able to log in through the web interface and start entering rules.

Logging into the web interface

Enter the site's URL in your browser. Assuming you created a directory called "/rules" on a web site called "", the URL will be "".

You will see a login screen, asking for a userid and password. You should be able to log in using the email address and password of any vpopmail mailbox on the system.

User access levels

The users' access levels are controlled by vpopmail. You can look at a user's access level using vpopmail's "vuserinfo" command:

# vuserinfo name: admin passwd: $1$xxxxxxxx$xxxxxxxxxxxxxxxxxxxxxx clear passwd: comment/gecos: admin uid: 1 gid: 69632 flags: 69632 gecos: admin limits: has qmailadmin administrator access has system administrator access dir: /home/vpopmail/domains/ quota: NOQUOTA usage: NOQUOTA last auth: Sat Jun 30 19:02:16 2012 last auth ip: imap

The "limits:" item shows the status of several vpopmail flags which can be attached to each account. Two of these flags are used by qmailadmin, a web interface which allows mailbox owners to configure some things about their own mailboxes (i.e. their "real name", password, forwarding, and vacation auto-response message) and domain owners to create and administer mailboxes within their domains. These flags control which users have access to higher-level administrative functions.

There are two flags which are used by the rules system. One is called "qmailadmin administrator", which means they are able to administer mailboxes within their own domain. The other is called "system administrator", which means they are able to administer mailboxes in any domain on the system.

By default, any account with the username postmaster will automatically have domain-owner access, regardless of whether the "qmailadmin administrator" flag is set or not. Even if the flag is not set, postmaster accounts always have domain-owner access, both in qmailadmin and in this system. This seems to be hard-coded into vpopmail - as a test I tried removing both flags from a postmaster account, and vpopmaild still told me that the account had the "qmailadmin administrator" permission.

The "vmoduser" command is used to set or clear these flags.

Note that if you change the access flags for a user who is currently logged into the system, they will need to log out and back into the system for the system to realize that a change has been made.

You will probably need at least one account with system administrator (i.e. machine owner) access. If the server isn't handling your own email, or if you don't want to use your own account for this (in order to limit the possible damage in case your own password is compromised) you may wish to add a dummy domain with a name like "" (i.e. a domain with a name which does not, and cannot, exist in the real internet), create a dummy mailbox like "admin" in that domain, give that account domain and system administrator access, and use that account to administer the system-wide rules.

# vadddomain
Please enter password for postmaster:
enter password again:
# vadduser
Please enter password for
enter password again:
# vmoduser -aS

Configure system-wide rules

At this point, the database and web interface should be working. You should use the web interface to create any rules you will want to enforce when the system goes live. Note that until you change qmail-smtpd to use the processing script (below), any changes you make will not have any effect on your incoming mail, so you may want to take this opportunity to get familiar with how to use the interface, using mailboxes at all three access levels - a normal user, a domain administrator, and a system administrator.

My suggestions are:

The Filtering Script:

Once you have the rules set up the way you want them, the last step is to add the filtering script to qmail-smtpd's SMTP processing. Again, this requires that you have patched qmail with Jay Soffian's RCPTCHECK patch, and that you are running qmail-smtpd from daemontools. The script also requires access to the database, but it does not need to access vpopmaild in order to work.

How the script works

When qmail-smtpd receives a RCPT command from a client, if the RCPTCHECK environment variable exists and is not empty, it will save some values into environment variables and then run the script. In addition, there are other environment variables which are set by other programs, or by the run script for your qmail-smtpd service.

The script configures itself, and reads the data it needs in order to do the filtering, using environment variables. Those variables are:

In addition, if you are using my combined patch, these variables will also be available:

After saving the environment variables, qmail-smtpd executes the program specified in the RCPTCHECK variable. You can set this value in the "run" script for your qmail-smtpd service, you can set it in a tcpserver access control file, or (if you're using my combined patch) you can conditionally set or unset the variable when a successful AUTH command is processed, by setting an AUTH_SET_RCPTCHECK or AUTH_UNSET_RCPTCHECK variable.

Copying the script into place

The processing script itself is "lib/" in the download. (The ".htaccess" file in the main directory prevents web browsers from being able to access the file.) You can install it by copying or moving the script into /var/qmail/bin if you like having all of your binaries together, or you can create a symlink from /var/qmail/bin/ to the script, or you can just point the RCPTCHECK variable directly to the script within the web document root... whatever you are comfortable with doing on your own server. (On my own servers, I created a symlink in /var/qmail/bin pointing to the script within the web site, since the directory on the web site is under subversion control and I found that I wasn't always remembering to copy the new script into place when I updated it.)

The important part is that the RCPTCHECK variable needs to contain the full pathname to the script.

Wherever you put it, you need to make sure that the userid as which qmail-smtpd runs (which is qmaild by default) has permissions to read and execute the script itself, and that it has at least "execute" permissions on every directory from the script back up to the root of the filesystem (i.e. "/var/qmail/bin", "/var/qmail", "/var", and "/".)

Configuring the script

Before you can run the script, you will need to configure it. This is done by arranging things so that qmail-smtpd runs with the following environment variables set to appropriate values (see the list above for descriptions of what the values should be.)

Before you activate the processing script, you may want to add a debugging rule to one of your system-wide phases. This will make it easier to see what's going on by watching the qmail-smtpd log file.

Some people like to set environment variables using the tcpserver access control file (i.e. the cdb file that tcpserver's "-x" option points to), by adding environment variables to the entries like this:


If your tcpserver access control file contains a lot of entries, having to add this list of variables to the end of several lines can get very tedious. Because of this, and because a lot of the things for which I used to use the tcpserver access control file can now be done by this system, I prefer to edit the qmail-smtpd service's "run" script to make changes like this, and only use the tcpserver access control file for things which can't be done here (such as setting things like GREETDELAY or SPFBEHAVIOR.)

For example, my /service/qmail-smtpd/run script contains the following lines:


Activating the script

If you edited the tcpserver access control file, rebuilding the cdb file will effectively "activate" the processing script. Any messages which arrive from an IP address matched by the line(s) you edited will be processed by the script.

If you changed the "run" script, restart the service.

# svc -t /service/qmail-smtpd

After restarting the service, watch the log file for log messages from the processing script. If you see any errors, be ready to un-set the RCPTCHECK variable (and restart the service, if necessary) to pull the script out of the processing stream while you debug the problem.

# tail -F /service/qmail-smtpd/log/main/current | tai64nlocal

At this point, the system should be running. If you run into any problems, please refer to the troubleshooting page.