--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/HOWTO.info Sun Jan 20 00:22:09 2008 +0100
@@ -0,0 +1,331 @@
+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.
+
+