--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/HOWTO.sgml Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,372 @@
+<!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>