Using VMailMgr

---

Bruce Guenter created VMailMgr. It includes a set of utilities for managing virtual domains with virtual users. The core utilities are:

• checkvpw, an authentication module for qmail-pop3d

• authvmailmgr, an authentication module for Courier-IMAP

• vdeliver, an MDA that delivers mail to mailboxes belonging to virtual users

• vsetup, a utility for setting up a new virtual domain

• vadduser, a utility for adding a new virtual user to a virtual domain

More information about VMailMgr is available on the Web (http://www.vmailmgr.org/).

Installing VMailMgr

qmail must be installed before VMailMgr can be set up:

1. Download the source tarball. At the time of this writing, version 0.96.9 is the current release. Use your favorite Web browser or the wget utility, if it's installed on your system:

    $ wget http://www.vmailmgr.org/current/vmailmgr-0.96.9.tar.gz —07:51:05— http://www.vmailmgr.org/current/vmailmgr-0.96.9.tar.gz            => `vmailmgr-0.96.9.tar.gz' Connecting to www.vmailmgr.org:80. . . connected! HTTP request sent, awaiting response. . . 200 OK Length: 362,379 [application/x-gzip]     0K ->.......... .......... .......... .......... .......... .......... [ 14%]    50K ->.......... .......... .......... .......... .......... .......... [ 28%]   100K ->.......... .......... .......... .......... .......... .......... [ 42%]   150K ->.......... .......... .......... .......... .......... .......... [ 56%]   200K ->.......... .......... .......... .......... .......... .......... [ 70%]   250K ->.......... .......... .......... .......... .......... .......... [ 84%]   300K ->.......... .......... .......... .......... .......... .......... [ 98%]   350K ->.......... .......... .......... .......... .......... .......... [100%] 07:53:02 (3.06 KB/s) - `vmailmgr-0.96.9.tar.gz' saved [362379/362379] $ 

2. Extract the source:

    $ zcat vmailmgr-0.96.9.tar.gz | tar xf - $ 

3. Configure the build:

    $ cd vmailmgr-0.96.9 $ ./configure creating cache ./config.cache checking for a BSD compatible install. . . /usr/bin/install -c checking whether build environment is sane. . . yes ...lots of output ending with something like: creating php/Makefile creating python/Makefile creating config.h $ 

4. Make the binaries:

    $ make make all-recursive make[1]: Entering directory `/usr/local/src/vmailmgr-0.96.9' Making all in python ...lots of output ending with something like: make[2]: Entering directory `/usr/local/src/vmailmgr-0.96.9' make[2]: Leaving directory `/usr/local/src/vmailmgr-0.96.9' make[1]: Leaving directory `/usr/local/src/vmailmgr-0.96.9' $ 

   Note 

   On some systems, make fails with errors about "strlen," "strcpy," or "_exit" being declared. If this happens, add these two lines: #include <string.h> and #include <stdlib.h> to the top of config.h and lib/mystring/append.cc, and re-run the make command.

5. Install the binaries:

    $ su root Password: rootpassword # make install Making install in python make[1]: Entering directory `/usr/local/src/vmailmgr-0.96.9/python' make[2]: Entering directory `/usr/local/src/vmailmgr-0.96.9/python' ...lots of output ending with something like: make[2]: Nothing to be done for `install-data-am'. make[2]: Leaving directory `/usr/local/src/vmailmgr-0.96.9' make[1]: Leaving directory `/usr/local/src/vmailmgr-0.96.9' # 

Configuring VMailMgr

VMailMgr is now installed. Now add a virtual domain; in this example you'll use virtual.example.com.

Note 

A Domain Name System (DNS) record—preferably a mail exchanger (MX) record—must be set up to direct mail for the virtual domain to the system hosting the virtual domain. The details are beyond the scope of this book and are highly dependent upon the DNS software in use.

1. Create a user account for the manager of the domain, if it doesn't already exist. All of the mailboxes for the domain will be stored under this user's home directory, so be sure it's large enough to accommodate the expected volume of mail. For this example, the manager will be josh:

    $ su root Password: rootpassword # useradd josh # 

2. Configure the domain as a qmail virtual domain. To do this, you need to modify two of qmail's configuration files in /var/qmail/control: rcpthosts and virtualdomains. To rcphosts, add this line:

    virtual.example.com 

To virtualdomains, add this line:

 virtual.example.com:josh 

3. Configure your qmail-pop3d service to use checkvpw as the checkpassword utility. For example, if your qmail-pop3d service is started in /service/qmail-pop3d/run, you would change the line from something like this:

    exec /usr/local/bin/softlimit -m 2000000 \     /usr/local/bin/tcpserver -v -R -H -l 0 -x /etc/tcp.pop3.cdb -c "$MAXPOP3D" \          0 110 /var/qmail/bin/qmail-popup FQDN /bin/checkpassword \          /var/qmail/bin/qmail-pop3d Maildir 2>&1 

to this:

 exec /usr/local/bin/softlimit -m 2000000 \     /usr/local/bin/tcpserver -v -R -H -l 0 -x /etc/tcp.pop3.cdb -c "$MAXPOP3D" \          0 110 /var/qmail/bin/qmail-popup FQDN /usr/local/bin/checkvpw\          /var/qmail/bin/qmail-pop3d Maildir 2>&1 

Restart the qmail-pop3d service to incorporate the change:

 # svc -t /service/qmail-pop3d # 

4. Configure the VMailMgr files for the domain:

    # su - josh $ /usr/local/bin/vsetup vsetup: created users directory. vsetup: wrote '.qmail-default' file. vsetup: added alias 'mailer-daemon' vsetup: added alias 'postmaster' vsetup: added alias 'root' $ 

5. Add a virtual user:

    $ /usr/local/bin/vadduser zack Enter the user's new password: somepassword Please type it again for verification: somepassword vadduser: user 'zack' successfully added $ 

6. Send qmail-send a HUP signal to cause it to reread virtualdomains. If you have installed the qmailctl script from Chapter 2, "Installing mail," you can do this:

    # qmailctl reload Sending HUP signal to qmail-send. # 

If your qmail is run by svscan/supervise from the /service directory, you can run svc to send the signal:

 # svc -h /service/qmail-send # 

Testing VMailMgr

Now that VMailMgr is installed and configured, you should test it to make sure it works and hasn't broken non-virtual users/domains:

1. Authenticate as a non-virtual user via the qmail-pop3d service:

    # telnet 0 110 Trying 0.0.0.0. . . Connected to 0. Escape character is '^]'. +OK < 18025.993992124@FQDN> user somerealuser +OK pass somepassword +OK quit +OK Connection closed by foreign host. # 

The +OK response to the pass command indicates successful authentication. If the response starts with -ERR, the authentication failed.

2. Authenticate as a virtual user via the qmail-pop3d service. Use the virtual user's e-mail address as the username and supply the password you set in step 5 of "Configuring VMailMgr":

    # telnet 0 110 Trying 0.0.0.0. . . Connected to 0. Escape character is '^]'. +OK < [e-mail]> user [e-mail] +OK pass somepassword +OK quit +OK Connection closed by foreign host. # 

If this test fails, double-check the username and password, step 3 of "Configuring VMailMgr," and all of the installation steps.

3. Test the virtual user with a Post Office Protocol (POP) 3 Mail User Agent (MUA).

Note 

Some MUAs truncate the username at the at-sign (@). As a workaround,VMailMgr also recognizes usernames as user:domain. For example: zack:virtual.example.com.

---