VMailMgr HOWTO

  Bruce Guenter  <mailto:bruceg@em.ca>, Dan Kuykendall

  <mailto:dan@kuykendall.org>

  v1.w, 2000-09-15

  This document explains how to setup VMailMgr support pop3 virtual

  domain   services in conjunction with Qmail.

  ______________________________________________________________________

  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 SRC.RPM's

        2.2.2 Installing RPM's

     2.3 Install with 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

  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  VMailMgr (short 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.

  11..11..  WWhhaatt iiss VVMMaaiillMMggrr aanndd wwhhyy sshhoouulldd II uussee iitt??

  VMailMgr is:

  A series of utilities for managing virtual domains which include a

  password checking interface for qmail which replaces the usual

  checkpassword, and an authentication module for Courier IMAP, that

  provide access to the virtual mailboxes by one of three methods:

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

  +o  username-based access (username-virtualuser)

  +o  hostname-based access (virtualuser@virtual.host or

     virtualuser:virtual.host)

  You should use it if you prefer to have each domain controlled by a

  seperate username, allowing the use of system quotas and better

  security

  11..22..  NNeeww vveerrssiioonnss

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

  <http://www.vmailmgr.org/> in its HTML version as well as in the

  source package SGML source, HTML, and text.  Other versions may be

  found in different formats at the LDP homepage

  <http://www.linuxdoc.org/>.

  11..33..  CCoommmmeennttss

  Comments on this HOWTO should be directed to the VMailMgr mailing

  list.  To subscribe, send an email to vmailmgr-subscribe@lists.em.ca

  <mailto:vmailmgr-subscribe@lists.em.ca>.

  11..44..  HHiissttoorryy

  This document was started by Bruce Guenter and reworked by Dan

  Kuykendall.

  11..55..  CCooppyyrriigghhttss aanndd TTrraaddeemmaarrkkss

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

  11..66..  AAcckknnoowwlleeddggeemmeennttss aanndd TThhaannkkss

  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.em.ca

  <mailto:vmailmgr@lists.em.ca> 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.

  22..  IInnssttaallllaattiioonn

  22..11..  GGeett tthhee ffiilleess

  Visit the VMailMgr website  <http://www.vmailmgr.org/> to get the

  package.

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

  package.

  22..22..  IInnssttaallll wwiitthh RRPPMMSS

  22..22..11..  CCoommppiilliinngg SSRRCC..RRPPMM''ss

  Simply compile the src.rpm file with the `rpm --rebuild` command.

  -Example-

  ______________________________________________________________________

    rpm -ivh vmailmgr-0.96.9-1.src.rpm

  ______________________________________________________________________

  22..22..22..  IInnssttaalllliinngg RRPPMM''ss

  After compiling the source rpms, the binaries will be located in

  `/usr/src/redhat/RPMS/i386/` or something similar.

  Simply run the following command for each package

    rpm -ivh <location>/<package.i386.rpm>

  -Example-

  ______________________________________________________________________

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

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

  ______________________________________________________________________

  22..33..  IInnssttaallll wwiitthh ssoouurrccee

  If you dont ue RPMS you can install from source.

  Run the following command

    (As non-root user)

    tar zxf <package.tar.gz>

    cd <newly created dir>

    ./configure

    make

    (As root)

    make install

  -Example-

  ______________________________________________________________________

    (As non-root user)

    tar zxf vmailmgr-0.96.9.tar.gz

    cd vmailmgr-0.96.9

    ./configure

    make

    (As root)

    make install

  ______________________________________________________________________

  That should do it.

  33..  SSeettuupp

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

  installed in `/usr/bin`, and configuration is in `/etc/vmailmgr`, as

  is the case if you installed from the RPMs.  If you installed from

  source, configure puts the binaries into `/usr/local/bin` and the

  configuration into `/usr/local/etc/vmailmgr` by default.

  33..11..  SSeettttiinngg UUpp aa VViirrttuuaall DDoommaaiinn

  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, `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`.

  +o  To `rcpthosts` : add the line `mydomain.org`.

  +o  To `virtualdomains` : add the line `mydomain.org:myuser`.

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

     the same way, add the following

  +o  To `rcpthosts` : add the line `.mydomain.org`.

  +o  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.

  +o  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`.

  +o  And/Or at the prompt type: `echo checkvpw >

     /var/qmail/control/checkpassword`

  5. Set up the vmailmgr files:

  +o  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.

  +o  Set up the base vmailmgr files by running `vsetup`.

  +o  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` table.

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

  `inetd` process as well.

  33..22..  UUssiinngg oonnee IIPP aaddddrreessss ffoorr mmuuttiippllee ddoommaaiinnss

  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.

     Example: `/var/qmail/control/virtualdomains' contains

       testdomain.org:testuser

  User `myuser' exists, and has set up a virtual mailbox with the name

  `me'. The `separators' variable in `/etc/vmailmgr/' contains `@:'.

  This virtual user could log in as `me@mydomain.com', `me:mydomain.cm',

  or `myuser-me'.

  33..33..  CCaattcchhiinngg aallll mmiissddiirreecctteedd mmaaiill iinn aa vviirrttuuaall ddoommaaiinn

  In the `vmailmgr/' configuration directory, there is an entry 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

  33..44..  VVMMaaiillMMggrr IIMMAAPP ssuuppppoorrtt

  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.

  +o  You must copy `/usr/bin/authvmailmgr` to `/usr/lib/courier-

     imap/libexec/authlib/authvmailmgr`.

  +o  Then modify the `AUTHMODULES` statement in `/usr/lib/courier-

     imap/etc/imapd.config` and add `authvmailmgr` as the first

     authentication module.

  33..55..  EEnnaabblliinngg eennffoorrcceemmeenntt ooff vviirrttuuaall uusseerr qquuoottaass

  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 exe-

  cutable by running the following command:

    chmod +x /etc/vmailmgr/vdeliver-predeliver

  33..66..  EEnnaabblliinngg pprroocceessssiinngg ooff aauuttoorreessppoonnsseess

  Download and install the qmail-autoresponder package, found at

  <http://em.ca/~bruceg/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

  33..77..  WWeebb--bbaasseedd iinntteerrffaacceess ffoorr vvmmaaiillmmggrr

  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.

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

     be downloaded at  <http://em.ca/~bruceg/vpyadmin/>, and the

     development code is online at  <http://bruce-

     guenter.dyndns.org/cgi-bin/vpyadmin/> (sample.org / samplevm).

  2. And if you like PHP, you can use oMail-admin by Olivier Mller: 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).

  3. And there are also C-based CGI scripts in the cgi directory of the

     vmailmgr distribution.