diff -r 000000000000 -r 6f7a81934006 doc/HOWTO.txt --- /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 , Dan Kuykendall + + 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 + 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 + . + + 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 + . + + 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 + . + + 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 + 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 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 / + + + -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 + cd + ./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 + . 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 , and the + development code is online at (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: + . Online demo: + (test.com / test). + + 3. And there are also C-based CGI scripts in the cgi directory of the + vmailmgr distribution. + + + + + + + + + + + + + + + + + + + + + + + + + + +