<!doctype linuxdoc system>

<!-- LinuxDoc file was created by hand by <Dan Kuykendall> Wed April 23 -->

<article>

<title>

  VMailMgr HOWTO

</title>

<author>

  Bruce Guenter <url url="mailto:bruceg@em.ca">,

  Dan Kuykendall <url url="mailto:dan@kuykendall.org">

</author>

<date>

  v1.w, 2000-09-15

</date>

<abstract>

  This document explains how to setup VMailMgr support pop3 virtual domain 

  services in conjunction with Qmail.

</abstract>

<toc>

<sect>Introduction

<p>

  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.

</p>

<sect1>What is VMailMgr and why should I use it?

<p>

  VMailMgr is:<p> 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:

<itemize>

  <item> IP-based virtual server access (invisible to the POP3 user)

  <item> username-based access (username-virtualuser)

  <item> hostname-based access (virtualuser@virtual.host or

  virtualuser:virtual.host)

</itemize>

  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

</p>

<sect1>New versions 

<p>

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

  <url url="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 <url

  url="http://www.linuxdoc.org/">.

</p>

<sect1>Comments 

<p>

  Comments on this HOWTO should be directed to the VMailMgr mailing

  list.  To subscribe, send an email to <url

  url="mailto:vmailmgr-subscribe@lists.em.ca"

  name="vmailmgr-subscribe@lists.em.ca">.

</p>

<sect1>History 

<p>

  This document was started by Bruce Guenter and reworked by Dan

  Kuykendall.

</p>

<sect1>Copyrights and Trademarks 

<p>

  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

</p>

<p>

  A copy of the license is available at <url

  url="http://www.gnu.org/copyleft/fdl.txt" name="GNU Free

  Documentation License">.

</p>

<sect1>Acknowledgements and Thanks 

<p>

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

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

</p>

<sect>Installation

<sect1>Get the files

<p>

  Visit the VMailMgr website <url url="http://www.vmailmgr.org/"> to

  get the package.

<p>

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

</p>

<sect1>Install with RPMS

<sect2>Compiling SRC.RPM's

<p>

  Simply compile the src.rpm file with the `<tt>rpm --rebuild</tt>` command.

  -Example-

<code>

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

</code>

<sect2>Installing RPM's

<p>

  After compiling the source rpms, the binaries will be located 

  in `<tt>/usr/src/redhat/RPMS/i386/</tt>` or something similar.

  Simply run the following command for each package

<verb>

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

</verb>

  -Example-

<code>

  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

</code>

<sect1>Install with source

<p>

  If you dont ue RPMS you can install from source.<p>

  Run the following command

<verb>

  (As non-root user)

  tar zxf <package.tar.gz>

  cd <newly created dir>

  ./configure

  make

  (As root)

  make install

</verb>

  -Example-

<code>

  (As non-root user)

  tar zxf vmailmgr-0.96.9.tar.gz

  cd vmailmgr-0.96.9

  ./configure

  make

  (As root)

  make install

</code>

  That should do it.

</p>

<sect>Setup

<p>

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

  are installed in `<tt>/usr/bin</tt>`, and configuration is in

  `<tt>/etc/vmailmgr</tt>`, as is the case if you installed from the

  RPMs.

  If you installed from source, configure puts the binaries into

  `<tt>/usr/local/bin</tt>` and the configuration into

  `<tt>/usr/local/etc/vmailmgr</tt>` by default.

</p>

<sect1>Setting Up a Virtual Domain

<p>

  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 `<tt>me@mydomain.org</tt>`,

  with aliases of `<tt>myself@mydomain.org</tt>` and

  `<tt>myname@mydomain.org</tt>`.

<enum>

  <item>

    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 <tt>mail.mydomain.com</tt>,

    `<tt>virtualdomains</tt>` needs an entry like

    `<tt>mail.mydomain.com:myuser</tt>'

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

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

  <item>

    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 `<tt>myuser</tt>`.

  <item>

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

    modify two of qmail's configuration files in

    `<tt>/var/qmail/control</tt>` `<tt>rcpthosts</tt>` and

    `<tt>virtualdomains</tt>`.

    <itemize>

      <item>To `<tt>rcpthosts</tt>` :

        add the line `<tt>mydomain.org</tt>`. 

      <item>To `<tt>virtualdomains</tt>` :

        add the line `<tt>mydomain.org:myuser</tt>`.

    </itemize>

        If you wish to have mail to `<tt>anything.mydomain.org</tt>`

        be delivered in the same way, add the following

    <itemize>

      <item>To `<tt>rcpthosts</tt>` :

        add the line `<tt>.mydomain.org</tt>`. 

      <item>To `<tt>virtualdomains</tt>` :

        add the line `<tt>.mydomain.org:myuser</tt>`.

    </itemize>

  <item>

    Configure qmail-popup/qmail-pop3d to use `<tt>checkvpw</tt>` as

    the password checker. This step is dependant on how you have

    installed qmail.

    <itemize>

      <item>

        Replace `<tt>checkpassword</tt>` in the command you use to

        invoke qmail-popup/qmail-pop3d (either in

        `<tt>/etc/inet.conf</tt>` or in a `<tt>tcpserver</tt>`

        command) with `<tt>checkvpw</tt>`.

      <item>

        And/Or at the prompt type: `<tt>echo checkvpw >

        /var/qmail/control/checkpassword</tt>`

    </itemize>

  <item>

    Set up the vmailmgr files:

    <itemize>

      <item>

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

        type `<tt>su - myuser</tt>`) or log in (with either telnet or

        at the console) as the new user.

      <item>

        Set up the base vmailmgr files by running `<tt>vsetup</tt>`.

      <item>

        Use the included programs to add users and aliases.

        For our example, we would type the following commands:

<verb>

  vadduser me

  vaddalias myself me

  vaddalias myname me

</verb>

     </itemize>

</enum>

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

  restart `<tt>qmail-send</tt>` to make it read the new

  `<tt>virtualdomains</tt>` table.

<p>

  If you are using `<tt>inetd</tt>` to launch `<tt>qmail-popup</tt>`,

  `<tt>kill -HUP</tt>` the `<tt>inetd</tt>` process as well.

</p>

<sect1>Using one IP address for mutiple domains

<p>

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

<p>

<enum>

  <item>

    The first way is to log in as

    `<tt>userSEPvirtual.domain.org</tt>`, where `<tt>user</tt>` is the

    mailbox name of the virtual user, SEP is one of `<tt>@</tt>` or

    `<tt>:</tt>` (by default, this is configurable in the

    `<tt>/etc/vmailmgr/</tt>' directory), and

    `<tt>virtual.domain.org</tt>' is the virtual domain's name, as

    listed in `<tt>/var/qmail/control/virtualdomains</tt>'.

  <item>

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

    that is, `<tt>baseuser-user</tt>', where `<tt>user</tt>' is the

    same as above, and `<tt>baseuser</tt>' is the username of the

    managing user.

</enum>

  Example: `<tt>/var/qmail/control/virtualdomains</tt>' contains 

<verb>

  testdomain.org:testuser

</verb>

  User `<tt>myuser</tt>' exists, and has set up a virtual mailbox with

  the name `<tt>me</tt>'. The `<tt>separators</tt>' variable in

  `<tt>/etc/vmailmgr/</tt>' contains `<tt>@:</tt>'. This virtual user

  could log in as `<tt>me@mydomain.com</tt>',

  `<tt>me:mydomain.cm</tt>', or `<tt>myuser-me</tt>'.

<p>

<sect1>Catching all misdirected mail in a virtual domain

<p>

  In the `<tt>vmailmgr/</tt>' configuration directory, there is an

  entry called `<tt>default-username</tt>'. 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 `<tt>+</tt>'). To make this deliver to you,

  simply type:

<verb>

  vaddalias + me

</verb>

</p>

<sect1>VMailMgr IMAP support

<p>

  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.

<itemize>

  <item>

    You must copy `<tt>/usr/bin/authvmailmgr</tt>` to

    `<tt>/usr/lib/courier-imap/libexec/authlib/authvmailmgr</tt>`.

  <item>

    Then modify the `<tt>AUTHMODULES</tt>` statement in

    `<tt>/usr/lib/courier-imap/etc/imapd.config</tt>` and add

    `<tt>authvmailmgr</tt>` as the first authentication module.

</itemize>

</p>

<sect1>Enabling enforcement of virtual user quotas

<p>

  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

  `<tt>/etc/vmailmgr/vdeliver-predeliver</tt>`, containing

  the following:

<verb>

  #!/bin/sh

  /usr/bin/vcheckquota

</verb>

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

  executable by running the following command:

<verb>

  chmod +x /etc/vmailmgr/vdeliver-predeliver

</verb>

</p>

<sect1>Enabling processing of autoresponses

<p>

  Download and install the qmail-autoresponder package, found at

  <url url="http://em.ca/~bruceg/qmail-autoresponder/">.

  As with the above section, create a shell script

  `<tt>/etc/vmailmgr/vdeliver-postdeliver</tt>`, containing the

  following:

<verb>

  #!/bin/sh

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

  then

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

  fi

</verb>

</p>

<sect1>Web-based interfaces for vmailmgr

<p>

  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.

<enum>

  <item>

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

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

    the development code is online at <url

    url="http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/">

    (sample.org / samplevm).

  <item>

    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:

    <url url="http://omail.omnis.ch">. Online demo:

    <url url="http://admin.omnis.ch/omail/"> (test.com / test).

  <item>

    And there are also C-based CGI scripts in the <tt>cgi</tt>

    directory of the vmailmgr distribution.

</enum>

</p>

</article>