--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/HOWTO.html Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,334 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE> VMailMgr HOWTO</TITLE>
+
+
+</HEAD>
+<BODY>
+<H1> VMailMgr HOWTO</H1>
+
+<H2>Bruce Guenter
+<A HREF="mailto:bruceg@em.ca">mailto:bruceg@em.ca</A>,
+ Dan Kuykendall
+<A HREF="mailto:dan@kuykendall.org">mailto:dan@kuykendall.org</A></H2> v1.w, 2000-09-15
+<P><HR>
+<EM> This document explains how to setup VMailMgr support pop3 virtual domain services in conjunction with Qmail.</EM>
+<HR>
+<H2><A NAME="s1">1. Introduction</A></H2>
+
+<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.
+<H2>1.1 What is VMailMgr and why should I use it?</H2>
+
+<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:
+<UL>
+<LI> IP-based virtual server access (invisible to the POP3 user)</LI>
+<LI> username-based access (username-virtualuser)</LI>
+<LI> hostname-based access (virtualuser@virtual.host or
+virtualuser:virtual.host)</LI>
+</UL>
+<P>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
+<H2>1.2 New versions </H2>
+
+<P>The newest version of this can be found on the VMailMgr homepage
+<A HREF="http://www.vmailmgr.org/">http://www.vmailmgr.org/</A> 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
+<A HREF="http://www.linuxdoc.org/">http://www.linuxdoc.org/</A>.
+<H2>1.3 Comments </H2>
+
+<P>Comments on this HOWTO should be directed to the VMailMgr mailing
+list. To subscribe, send an email to
+<A HREF="mailto:vmailmgr-subscribe@lists.em.ca">vmailmgr-subscribe@lists.em.ca</A>.
+<H2>1.4 History </H2>
+
+<P>This document was started by Bruce Guenter and reworked by Dan
+Kuykendall.
+<H2>1.5 Copyrights and Trademarks </H2>
+
+<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>A copy of the license is available at
+<A HREF="http://www.gnu.org/copyleft/fdl.txt">GNU Free Documentation License</A>.
+<H2>1.6 Acknowledgements and Thanks </H2>
+
+<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
+<A HREF="mailto:vmailmgr@lists.em.ca">vmailmgr@lists.em.ca</A>
+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.
+<H2><A NAME="s2">2. Installation</A></H2>
+
+<H2>2.1 Get the files</H2>
+
+<P>Visit the VMailMgr website
+<A HREF="http://www.vmailmgr.org/">http://www.vmailmgr.org/</A> to
+get the package.
+<P>If you get the binary RPMS you will need at least the vmailmgr package.
+<H2>2.2 Install with RPMS</H2>
+
+<H3>Compiling SRC.RPM's</H3>
+
+<P>Simply compile the src.rpm file with the `<CODE>rpm --rebuild</CODE>` command.
+-Example-
+<HR>
+<PRE>
+ rpm -ivh vmailmgr-0.96.9-1.src.rpm
+</PRE>
+<HR>
+<H3>Installing RPM's</H3>
+
+<P>After compiling the source rpms, the binaries will be located
+in `<CODE>/usr/src/redhat/RPMS/i386/</CODE>` or something similar.
+<P>Simply run the following command for each package
+<PRE>
+ rpm -ivh <location>/<package.i386.rpm>
+</PRE>
+
+-Example-
+<HR>
+<PRE>
+ 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
+</PRE>
+<HR>
+<P>
+<P>
+<H2>2.3 Install with source</H2>
+
+<P>If you dont ue RPMS you can install from source.
+<P>Run the following command
+<PRE>
+ (As non-root user)
+ tar zxf <package.tar.gz>
+ cd <newly created dir>
+ ./configure
+ make
+ (As root)
+ make install
+</PRE>
+
+-Example-
+<HR>
+<PRE>
+ (As non-root user)
+ tar zxf vmailmgr-0.96.9.tar.gz
+ cd vmailmgr-0.96.9
+ ./configure
+ make
+ (As root)
+ make install
+</PRE>
+<HR>
+
+That should do it.
+<H2><A NAME="s3">3. Setup</A></H2>
+
+<P>In the following setup examples, it is assumed that your binaries
+are installed in `<CODE>/usr/bin</CODE>`, and configuration is in
+`<CODE>/etc/vmailmgr</CODE>`, as is the case if you installed from the
+RPMs.
+If you installed from source, configure puts the binaries into
+`<CODE>/usr/local/bin</CODE>` and the configuration into
+`<CODE>/usr/local/etc/vmailmgr</CODE>` by default.
+<H2>3.1 Setting Up a Virtual Domain</H2>
+
+<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 `<CODE>me@mydomain.org</CODE>`,
+with aliases of `<CODE>myself@mydomain.org</CODE>` and
+`<CODE>myname@mydomain.org</CODE>`.
+<OL>
+<LI>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 <CODE>mail.mydomain.com</CODE>,
+`<CODE>virtualdomains</CODE>` needs an entry like
+`<CODE>mail.mydomain.com:myuser</CODE>'
+For the example, we'll assume that the mail exchanger for
+mydomain.org is already set up to point to your computer.</LI>
+<LI>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 `<CODE>myuser</CODE>`.</LI>
+<LI>Configure qmail to recognize the domain. To do this, you need to
+modify two of qmail's configuration files in
+`<CODE>/var/qmail/control</CODE>` `<CODE>rcpthosts</CODE>` and
+`<CODE>virtualdomains</CODE>`.
+<UL>
+<LI>To `<CODE>rcpthosts</CODE>` :
+add the line `<CODE>mydomain.org</CODE>`. </LI>
+<LI>To `<CODE>virtualdomains</CODE>` :
+add the line `<CODE>mydomain.org:myuser</CODE>`.</LI>
+</UL>
+
+If you wish to have mail to `<CODE>anything.mydomain.org</CODE>`
+be delivered in the same way, add the following
+<UL>
+<LI>To `<CODE>rcpthosts</CODE>` :
+add the line `<CODE>.mydomain.org</CODE>`. </LI>
+<LI>To `<CODE>virtualdomains</CODE>` :
+add the line `<CODE>.mydomain.org:myuser</CODE>`.</LI>
+</UL>
+</LI>
+<LI>Configure qmail-popup/qmail-pop3d to use `<CODE>checkvpw</CODE>` as
+the password checker. This step is dependant on how you have
+installed qmail.
+<UL>
+<LI>Replace `<CODE>checkpassword</CODE>` in the command you use to
+invoke qmail-popup/qmail-pop3d (either in
+`<CODE>/etc/inet.conf</CODE>` or in a `<CODE>tcpserver</CODE>`
+command) with `<CODE>checkvpw</CODE>`.</LI>
+<LI>And/Or at the prompt type: `<CODE>echo checkvpw >
+/var/qmail/control/checkpassword</CODE>`</LI>
+</UL>
+</LI>
+<LI>Set up the vmailmgr files:
+<UL>
+<LI>Either change user to the user you just created (for example,
+type `<CODE>su - myuser</CODE>`) or log in (with either telnet or
+at the console) as the new user.</LI>
+<LI>Set up the base vmailmgr files by running `<CODE>vsetup</CODE>`.</LI>
+<LI>Use the included programs to add users and aliases.
+For our example, we would type the following commands:
+<PRE>
+ vadduser me
+ vaddalias myself me
+ vaddalias myname me
+</PRE>
+</LI>
+</UL>
+</LI>
+</OL>
+
+After you have completed all these steps, you will need to kill and
+restart `<CODE>qmail-send</CODE>` to make it read the new
+`<CODE>virtualdomains</CODE>` table.
+<P>If you are using `<CODE>inetd</CODE>` to launch `<CODE>qmail-popup</CODE>`,
+`<CODE>kill -HUP</CODE>` the `<CODE>inetd</CODE>` process as well.
+<H2>3.2 Using one IP address for mutiple domains</H2>
+
+<P>There are two ways to log in without using multiple IP addresses.
+<P>
+<OL>
+<LI>The first way is to log in as
+`<CODE>userSEPvirtual.domain.org</CODE>`, where `<CODE>user</CODE>` is the
+mailbox name of the virtual user, SEP is one of `<CODE>@</CODE>` or
+`<CODE>:</CODE>` (by default, this is configurable in the
+`<CODE>/etc/vmailmgr/</CODE>' directory), and
+`<CODE>virtual.domain.org</CODE>' is the virtual domain's name, as
+listed in `<CODE>/var/qmail/control/virtualdomains</CODE>'.</LI>
+<LI>The second way is to use the internal form of the mailbox name --
+that is, `<CODE>baseuser-user</CODE>', where `<CODE>user</CODE>' is the
+same as above, and `<CODE>baseuser</CODE>' is the username of the
+managing user.</LI>
+</OL>
+
+Example: `<CODE>/var/qmail/control/virtualdomains</CODE>' contains
+<PRE>
+ testdomain.org:testuser
+</PRE>
+
+User `<CODE>myuser</CODE>' exists, and has set up a virtual mailbox with
+the name `<CODE>me</CODE>'. The `<CODE>separators</CODE>' variable in
+`<CODE>/etc/vmailmgr/</CODE>' contains `<CODE>@:</CODE>'. This virtual user
+could log in as `<CODE>me@mydomain.com</CODE>',
+`<CODE>me:mydomain.cm</CODE>', or `<CODE>myuser-me</CODE>'.
+<P>
+<P>
+<H2>3.3 Catching all misdirected mail in a virtual domain</H2>
+
+<P>In the `<CODE>vmailmgr/</CODE>' configuration directory, there is an
+entry called `<CODE>default-username</CODE>'. 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 `<CODE>+</CODE>'). To make this deliver to you,
+simply type:
+<PRE>
+ vaddalias + me
+</PRE>
+<H2>3.4 VMailMgr IMAP support</H2>
+
+<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.
+<UL>
+<LI>You must copy `<CODE>/usr/bin/authvmailmgr</CODE>` to
+`<CODE>/usr/lib/courier-imap/libexec/authlib/authvmailmgr</CODE>`.</LI>
+<LI>Then modify the `<CODE>AUTHMODULES</CODE>` statement in
+`<CODE>/usr/lib/courier-imap/etc/imapd.config</CODE>` and add
+`<CODE>authvmailmgr</CODE>` as the first authentication module.</LI>
+</UL>
+<H2>3.5 Enabling enforcement of virtual user quotas</H2>
+
+<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
+`<CODE>/etc/vmailmgr/vdeliver-predeliver</CODE>`, containing
+the following:
+<PRE>
+ #!/bin/sh
+ /usr/bin/vcheckquota
+</PRE>
+
+This is executed as a shell script, so you will need to make it
+executable by running the following command:
+<PRE>
+ chmod +x /etc/vmailmgr/vdeliver-predeliver
+</PRE>
+<H2>3.6 Enabling processing of autoresponses</H2>
+
+<P>Download and install the qmail-autoresponder package, found at
+<A HREF="http://em.ca/~bruceg/qmail-autoresponder/">http://em.ca/~bruceg/qmail-autoresponder/</A>.
+As with the above section, create a shell script
+`<CODE>/etc/vmailmgr/vdeliver-postdeliver</CODE>`, containing the
+following:
+<PRE>
+ #!/bin/sh
+ if test -s $MAILDIR/autoresponse/message.txt
+ then
+ qmail-autoresponder $MAILDIR/autoresponse/message.txt $MAILDIR/autoresponse
+ fi
+</PRE>
+<H2>3.7 Web-based interfaces for vmailmgr</H2>
+
+<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.
+<OL>
+<LI>For Python fans, there is vpyadmin by Bruce Guenter. The files can
+be downloaded at
+<A HREF="http://em.ca/~bruceg/vpyadmin/">http://em.ca/~bruceg/vpyadmin/</A>, and
+the development code is online at
+<A HREF="http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/">http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/</A>
+(sample.org / samplevm).</LI>
+<LI>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:
+<A HREF="http://omail.omnis.ch">http://omail.omnis.ch</A>. Online demo:
+<A HREF="http://admin.omnis.ch/omail/">http://admin.omnis.ch/omail/</A> (test.com / test).</LI>
+<LI>And there are also C-based CGI scripts in the <CODE>cgi</CODE>
+directory of the vmailmgr distribution.</LI>
+</OL>
+</BODY>
+</HTML>