This is HOWTO.info, produced by makeinfo version 4.7 from HOWTO.texi.

     Copyright (C) 1998 Bruce Guenter

     This document explains how to setup VMailMgr support pop3 virtual

domain services in conjunction with Qmail.

1 Introduction

**************

VMailMgr (an abbreviation for Virtual Mail Manager) is a package of

programs designed to manage multiple domains of mail addresses and

mailboxes on a single host.  It co-operates with qmail for mail

delivery and program control.

1.1 What is VMailMgr and why should I use it?

=============================================

VMailMgr is a series of utilities for managing virtual domains,

including:

   * a password checking interface for qmail, which replaces the usual

     checkpassword, and

   * an authentication module for Courier IMAP

     These utilities provide access to the virtual mailboxes by one of

three methods:

   * IP-based virtual server access (invisible to the POP3 user)

   * username-based access (virtual user logs in as

     `username-virtualuser')

   * hostname-based access (virtual user logs in as

     `virtualuser@virtual.host' or `virtualuser:virtual.host')

     You should use VMailMgr if you prefer to have each domain

controlled by a seperate username, allowing the use of system quotas

and better security.

1.2 New versions

================

The newest version of this document can be found on the VMailMgr

homepage `http://www.vmailmgr.org/' in various formats, including the

texinfo source and HTML and plaintext versions.

1.3 Comments

============

Comments on this HOWTO should be directed to the VMailMgr mailing list.

To subscribe, send a blank email to

<vmailmgr-subscribe@lists.untroubled.org>.

1.4 History

===========

This document was started by Bruce Guenter and reworked by Dan

Kuykendall, then by Charles Cazabon.

1.5 Copyrights and Trademarks

=============================

Copyright (C) Dan Kuykendall.

     Permission is granted to copy, distribute and/or modify this

document under the terms of the GNU Free Documentation License, Version

1.1 or any later version published by the Free Software Foundation

     A copy of the license is available at GNU Free Documentation

License (http://www.gnu.org/copyleft/fdl.txt).

1.6 Acknowledgements and Thanks

===============================

Thanks to Bruce Guenter for VMailMgr and the core of this HOWTO.

Thanks to Mike Bell, who always seems to have the answers to my

questions. Finally, thanks to all those on the

<vmailmgr@lists.untroubled.org> mailing list who have helped me, or

asked the same stuff so many times that I had to write this to stop the

repeat questions.

2 Installation

**************

2.1 Get the files

=================

Visit the VMailMgr website `http://www.vmailmgr.org/' or one of its

mirror sites to download the package.  There are two primary methods of

installing:

   * from source

   * from a binary package - specifically, an `RPM' binary package

     If you get the binary RPMS you will need at least the vmailmgr

package.

2.2 Install with RPMS

=====================

To install from binary `RPM' packages, you can download the binaries,

or build them from the source RPM package.

2.2.1 Compiling the Source RPM (SRPM) Package

---------------------------------------------

If you download the binary packages directly, skip to the next step.

     Download the source rpm package (`vmailmgr-VERSION.src.rpm'), and

then use the `rpm' tool to build the binary RPM package from it with

the `rpm --rebuild' command as follows:

     rpm --rebuild vmailmgr-1.0.0-1.src.rpm

2.2.2 Installing the Binary RPM packages

----------------------------------------

After compiling the source RPM, the binary RPM packages will be located

in the appropriate output directory (typically

`/usr/src/redhat/RPMS/i386/').

     Install each package using the `-i' option of `rpm' (i.e.  `rpm

-ivh PACKAGE.i386.rpm') as follows:

     rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-1.0.0-1.i386.rpm

     rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-daemon-1.0.0-1.i386.rpm

2.3 Install from source

=======================

If you dont use RPM packages, you can install from source with the

following commands. First, as a regular, non-root user:

     tar xzf `vmailmgr-VERSION.tar.gz'

     cd `vmailmgr-VERSION'

     ./configure

     make

     Then, as user `root':

     make install

3 Setup

*******

In the following setup examples, it is assumed that your binaries are

installed in the `/usr/bin]' directory, and configuration files are

located in the `/etc/vmailmgr/' directory, as is the case if you

installed from the RPMs.

     If you installed from source, configure instead puts the binaries

into `/usr/local/bin/' and the configuration into

`/usr/local/etc/vmailmgr/' by default.

3.1 Setting Up a Virtual Domain

===============================

The following steps are necessary to set up a virtual domain with

vmailmgr (assuming vmailmgr has been compiled and installed). As an

example, we'll set up a virtual user `me@mydomain.org', with aliases of

`myself@mydomain.org' and `myname@mydomain.org'.

  1. Set up a DNS entry for the domain. This is not covered here, as it

     is dependant on far too many other things.  I will mention that to

     make IP based virtual domains work a `PTR' record which matches an

     entry in virtualdomains is nessesary, for example, if nslookup

     10.56.33.122 returns `mail.mydomain.com', `control/virtualdomains'

     needs an entry like `mail.mydomain.com:myuser'.

     For the example, we'll assume that the mail exchanger for

     `mydomain.org' is already set up to point to your computer.

  2. Set up a base user for the domain.  Create a user, with a name of

     your choosing.  Since the maildirs for all the users in the

     virtual domain will be stored under this user's home directory,

     make sure you set the user up in a partition or disk that is

     appropriate for such storage. The tools that you should use to

     accomplish this step vary greatly between different systems. For

     our example, I'll add a user `myuser'.

  3. Configure qmail to recognize the domain. To do this, you need to

     modify two of qmail's configuration files in `/var/qmail/control':

     `rcpthosts' and `virtualdomains'.

        * To `rcpthosts', add the line `mydomain.org'.

        * To `virtualdomains', add the line `mydomain.org:myuser'.

     If you wish to have mail to `anything.mydomain.org' be delivered

     in the same way:

        * To `rcpthosts', add the line `.mydomain.org'.

        * To `virtualdomains', add the line `.mydomain.org:myuser'.

  4. Configure `qmail-popup'/`qmail-pop3d' to use `checkvpw' as the

     password checker.  This step is dependant on how you have

     installed qmail.

        * Replace `checkpassword' in the command you use to invoke

          `qmail-popup'/`qmail-pop3d' (either in `/etc/inet.conf' or in

          a `tcpserver' command) with `checkvpw'.

        * And/Or at the prompt type `echo checkvpw >

          `/var/qmail/control/checkpassword''.

  5. Set up the vmailmgr files:

        * Either change user to the user you just created (for example,

          type `su - myuser') or log in (with either telnet or at the

          console) as the new user.

        * Set up the base vmailmgr files by running `vsetup'.

        * Use the included programs to add users and aliases.  For our

          example, we would type the following commands:

               vadduser me

               vaddalias myself me

               vaddalias myname me

     After you have completed all these steps, you will need to kill and

restart `qmail-send' to make it read the new `virtualdomains' control

file.

     If you are using `inetd' to launch `qmail-popup', `kill -HUP' the

`inetd' process as well.

3.2 Using one IP address for mutiple domains

============================================

There are two ways to log in without using multiple IP addresses.

  1. The first way is to log in as `userSEPvirtual.domain.org', where

     `user' is the mailbox name of the virtual user, SEP is one of `@'

     or `:' (by default; this is configurable in the `/etc/vmailmgr/'

     directory), and `virtual.domain.org' is the virtual domain's name,

     as listed in `/var/qmail/control/virtualdomains'.

  2. The second way is to use the internal form of the mailbox name -

     that is, `baseuser-user', where `user' is the same as above, and

     `baseuser' is the username of the managing user.

     For example, if `/var/qmail/control/virtualdomains' contains

`mydomain.com:myuser' and user `myuser' exists and has set up a virtual

mailbox with the name `me', and the `separators' configuration file

`/etc/vmailmgr/' contains `@', this virtual user could log in as

`me@mydomain.com', `me:mydomain.com', or `myuser-me'.

3.3 Catching all misdirected mail in a virtual domain

=====================================================

In the `vmailmgr' configuration directory, there is a file called

`default-username'. If mail to a virtual domain does not match any

users or aliases in that domain, it is delivered to the name listed in

this configuration item if it exists (which defaults to `+'). To make

this deliver to you, simply type `vaddalias + me'.

3.4 VMailMgr IMAP support

=========================

VMailMgr supports Courier-IMAP, but Courier-IMAP does not come with an

authentication module for VMailMgr.  This means that some minor work is

required for making the two work together.

     The steps are:

   * Copy `/usr/bin/authvmailmgr' to

     `/usr/lib/courier-imap/libexec/authlib/authvmailmgr'.

   * Modify the `AUTHMODULES' statement in

     `/usr/lib/courier-imap/etc/imapd.config' and add `authvmailmgr' as

     the first authentication module.

3.5 Enabling enforcement of virtual user quotas

===============================================

VMailMgr supports per-virtual-user quotas, but not out of the box, as

it is not needed by the majority of users, and requires an extra

program to be run on each delivery.

     To configure quota support, create the file

`/etc/vmailmgr/vdeliver-predeliver', containing the following:

     #!/bin/sh

     /usr/bin/vcheckquota

     This is executed as a shell script, so you will need to make it

executable by running the command `chmod +x

/etc/vmailmgr/vdeliver-predeliver'.

3.6 Enabling processing of autoresponses

========================================

Download and install the qmail-autoresponder package, found at

`http://untroubled.org/qmail-autoresponder/'.

     As with the above section, create a shell script

`/etc/vmailmgr/vdeliver-postdeliver', containing the following:

     #!/bin/sh

     if test -s $MAILDIR/autoresponse/message.txt ; then

       qmail-autoresponder $MAILDIR/autoresponse/message.txt $MAILDIR/autoresponse

     fi

3.7 Web-based interfaces for vmailmgr

=====================================

There are currently a few working solutions to administrate your

vmailmgr system via a web interface. Only requirement is that the

vmailmgrd daemon is running, and that you have a webserver on your

system.

   * For Python fans, there is vpyadmin by Bruce Guenter. The files can

     be downloaded at `http://untroubled.org/vpyadmin/', and the

     development code is online at

     `http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/' (sample.org /

     samplevm).

   * And if you like PHP, you can use oMail-admin by Olivier Müller: it

     fully supports all vmailmgr functions, and speaks englich, french,

     italian, spanish, german and russian. Project homepage:

     `http://omail.omnis.ch'. Online demo:

     `http://admin.omnis.ch/omail/' (test.com / test).

   * And there are also C-based CGI scripts in the `cgi' subdirectory

     of the vmailmgr distribution.