[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

   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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

1.4 History

   This document was started by Bruce Guenter and reworked by Dan

   Kuykendall, then by Charles Cazabon.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

                                2. Installation

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

2.2 Install with RPMS

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

   build them from the source RPM package.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

  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

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

  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

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

                                   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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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'.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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'.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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'.

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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

     _________________________________________________________________

   [ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [

   ? ]

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.

     _________________________________________________________________

   [Top] [Contents] [Index] [ ? ]

                               Table of Contents

   1. Introduction

   1.1 What is VMailMgr and why should I use it?

       1.2 New versions

       1.3 Comments

       1.4 History

       1.5 Copyrights and Trademarks

       1.6 Acknowledgements and Thanks

   2. Installation

   2.1 Get the files

       2.2 Install with RPMS

   2.2.1 Compiling the Source RPM (SRPM) Package

       2.2.2 Installing the Binary RPM packages

   2.3 Install from source

   3. Setup

   3.1 Setting Up a Virtual Domain

       3.2 Using one IP address for mutiple domains

       3.3 Catching all misdirected mail in a virtual domain

       3.4 VMailMgr IMAP support

       3.5 Enabling enforcement of virtual user quotas

       3.6 Enabling processing of autoresponses

       3.7 Web-based interfaces for vmailmgr

     _________________________________________________________________

   [Top] [Contents] [Index] [ ? ]

                            Short Table of Contents

     1. Introduction

     2. Installation

     3. Setup

     _________________________________________________________________

   [Top] [Contents] [Index] [ ? ]

                              About this document

   This document was generated by Bruce.Guenter.dyndns.org on December,

   29 2004 using texi2html

   The buttons in the navigation panels have the following meaning:

     Button      Name                    Go to                From 1.2.3 go to

     [ < ]       Back     previous section in reading order   1.2.2

     [ > ]      Forward   next section in reading order       1.2.4

     [ << ]    FastBack   previous or up-and-previous section 1.1

     [ Up ]       Up      up section                          1.2

     [ >> ]   FastForward next or up-and-next section         1.3

     [Top]        Top     cover (top) of document            

   [Contents]  Contents   table of contents                  

    [Index]      Index    concept index                      

     [ ? ]       About    this page                          

   where the Example assumes that the current position is at

   Subsubsection One-Two-Three of a document of the following structure:

     * 1. Section One

     * 1.1 Subsection One-One

     * ...

     1.2 Subsection One-Two

     * 1.2.1 Subsubsection One-Two-One

     * 1.2.2 Subsubsection One-Two-Two

     * 1.2.3 Subsubsection One-Two-Three     <== Current Position

     * 1.2.4 Subsubsection One-Two-Four

     1.3 Subsection One-Three

     * ...

     1.4 Subsection One-Four

     _________________________________________________________________

   This document was generated by Bruce.Guenter.dyndns.org on December,

   29 2004 using texi2html