diff -r 30113bfbe723 -r b3afb9f1e801 doc/HOWTO.info --- /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 +. + +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 + 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. + +