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