diff -r 30113bfbe723 -r b3afb9f1e801 doc/HOWTO.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/HOWTO.texi Sun Jan 20 00:22:09 2008 +0100 @@ -0,0 +1,393 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename HOWTO.info +@settitle VMailMgr HOWTO +@setchapternewpage off +@paragraphindent 5 +@footnotestyle end +@c %**end of header + +@ifinfo +Copyright @copyright{} 1998 Bruce Guenter +@end ifinfo + +@titlepage +@title Vmailmgr HOWTO +@author Bruce Guenter +@author Dan Kuykendall +@subtitle @today{} +@end titlepage + +@ifinfo +This document explains how to setup VMailMgr support pop3 virtual domain +services in conjunction with Qmail. +@end ifinfo + +@c **************************************************************************** +@chapter 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. + +@section What is VMailMgr and why should I use it? + +VMailMgr is a series of utilities for managing virtual domains, including: +@itemize +@item +a password checking interface for qmail, which replaces the usual +checkpassword, and +@item +an authentication module for Courier IMAP +@end itemize + +These utilities 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 (virtual user logs in as @samp{username-virtualuser}) +@item +hostname-based access (virtual user logs in as @samp{virtualuser@@virtual.host} +or @samp{virtualuser:virtual.host}) +@end itemize + +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. + +@section New versions + +The newest version of this document can be found on the VMailMgr homepage +@uref{http://www.vmailmgr.org/} in various formats, including the +texinfo source and HTML and plaintext versions. + +@section Comments + +Comments on this HOWTO should be directed to the VMailMgr mailing +list. To subscribe, send a blank email to +@email{vmailmgr-subscribe@@lists.untroubled.org}. + +@section History + +This document was started by Bruce Guenter and reworked by Dan +Kuykendall, then by Charles Cazabon. + +@section Copyrights and Trademarks + +Copyright @copyright{} 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 +@uref{http://www.gnu.org/copyleft/fdl.txt,GNU Free Documentation License}. + +@section 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 +@email{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. + +@c **************************************************************************** +@chapter Installation + +@section Get the files + +Visit the VMailMgr website @uref{http://www.vmailmgr.org/} or one of its +mirror sites to download the package. There are two primary methods of +installing: + +@itemize +@item +from source + +@item +from a binary package -- specifically, an @code{RPM} binary package + +@end itemize + +If you get the binary RPMS you will need at least the vmailmgr package. + +@section Install with RPMS + +To install from binary @code{RPM} packages, you can download the binaries, +or build them from the source RPM package. + +@subsection Compiling the Source RPM (SRPM) Package + +If you download the binary packages directly, skip to the next step. + +Download the source rpm package (@samp{vmailmgr-@var{VERSION}.src.rpm}), +and then use the @code{rpm} tool to build the binary RPM package from it +with the @samp{rpm --rebuild} command as follows: + +@example +rpm --rebuild vmailmgr-1.0.0-1.src.rpm +@end example + +@subsection Installing the Binary RPM packages + +After compiling the source RPM, the binary RPM packages will be located +in the appropriate output directory (typically +@file{/usr/src/redhat/RPMS/i386/}). + +Install each package using the @samp{-i} option of @code{rpm} (i.e. +@samp{rpm -ivh @var{PACKAGE}.i386.rpm}) as follows: + +@example +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 +@end example + +@section 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: + +@example +tar xzf @file{vmailmgr-@var{VERSION}.tar.gz} +cd @file{vmailmgr-@var{VERSION}} +./configure +make +@end example + +Then, as user @samp{root}: + +@example +make install +@end example + +@c **************************************************************************** +@chapter Setup + +In the following setup examples, it is assumed that your binaries are installed +in the @file{/usr/bin]} directory, and configuration files are located in the +@file{/etc/vmailmgr/} directory, as is the case if you installed from the RPMs. + +If you installed from source, configure instead puts the binaries into +@file{/usr/local/bin/} and the configuration into +@file{/usr/local/etc/vmailmgr/} by default. + +@section 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 @samp{me@@mydomain.org}, +with aliases of @samp{myself@@mydomain.org} and +@samp{myname@@mydomain.org}. + +@enumerate +@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 @samp{PTR} record which matches an +entry in virtualdomains is nessesary, for example, if nslookup +10.56.33.122 returns @samp{mail.mydomain.com}, +@file{control/virtualdomains} needs an entry like +@samp{mail.mydomain.com:myuser}. + +For the example, we'll assume that the mail exchanger for +@samp{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 @samp{myuser}. + +@item +Configure qmail to recognize the domain. To do this, you need to +modify two of qmail's configuration files in +@file{/var/qmail/control}: @file{rcpthosts} and @file{virtualdomains}. +@itemize +@item +To @file{rcpthosts}, add the line @samp{mydomain.org}. +@item +To @file{virtualdomains}, add the line @samp{mydomain.org:myuser}. +@end itemize + +If you wish to have mail to @samp{anything.mydomain.org} +be delivered in the same way: +@itemize +@item +To @file{rcpthosts}, add the line @samp{.mydomain.org}. +@item +To @file{virtualdomains}, add the line @samp{.mydomain.org:myuser}. +@end itemize + +@item +Configure @code{qmail-popup}/@code{qmail-pop3d} to use @code{checkvpw} as the +password checker. This step is dependant on how you have installed qmail. +@itemize +@item +Replace @code{checkpassword} in the command you use to +invoke @code{qmail-popup}/@code{qmail-pop3d} (either in +@file{/etc/inet.conf} or in a @code{tcpserver} +command) with @code{checkvpw}. +@item +And/Or at the prompt type @samp{echo checkvpw > @file{/var/qmail/control/checkpassword}}. +@end itemize + +@item +Set up the vmailmgr files: +@itemize +@item +Either change user to the user you just created (for example, +type @samp{su - myuser}) or log in (with either telnet or +at the console) as the new user. +@item +Set up the base vmailmgr files by running @code{vsetup}. +@item +Use the included programs to add users and aliases. +For our example, we would type the following commands: + +@example +vadduser me +vaddalias myself me +vaddalias myname me +@end example + +@end itemize + +@end enumerate + +After you have completed all these steps, you will need to kill and +restart @code{qmail-send} to make it read the new +@file{virtualdomains} control file. + +If you are using @code{inetd} to launch @code{qmail-popup}, +@samp{kill -HUP} the @code{inetd} process as well. + +@section Using one IP address for mutiple domains + +There are two ways to log in without using multiple IP addresses. + +@enumerate +@item +The first way is to log in as +@samp{user@var{SEP}virtual.domain.org}, where @samp{user} is the +mailbox name of the virtual user, @var{SEP} is one of @samp{@@} or +@samp{:} (by default; this is configurable in the +@file{/etc/vmailmgr/} directory), and +@samp{virtual.domain.org} is the virtual domain's name, as +listed in @file{/var/qmail/control/virtualdomains}. + +@item +The second way is to use the internal form of the mailbox name -- +that is, @samp{baseuser-user}, where @samp{user} is the +same as above, and @samp{baseuser} is the username of the +managing user. + +@end enumerate + +For example, if @file{/var/qmail/control/virtualdomains} contains +@samp{mydomain.com:myuser} and user @samp{myuser} exists and has +set up a virtual mailbox with the name @samp{me}, and the +@file{separators} configuration file @file{/etc/vmailmgr/} contains @samp{@@}, +this virtual user could log in as @samp{me@@mydomain.com}, +@samp{me:mydomain.com}, or @samp{myuser-me}. + +@section Catching all misdirected mail in a virtual domain + +In the @code{vmailmgr} configuration directory, there is a +file called @file{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 @samp{+}). To make this deliver to you, +simply type @samp{vaddalias + me}. + +@section 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: + +@itemize +@item +Copy @file{/usr/bin/authvmailmgr} to +@file{/usr/lib/courier-imap/libexec/authlib/authvmailmgr}. + +@item +Modify the @code{AUTHMODULES} statement in +@file{/usr/lib/courier-imap/etc/imapd.config} and add +@samp{authvmailmgr} as the first authentication module. +@end itemize + +@section 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 +@file{/etc/vmailmgr/vdeliver-predeliver}, containing +the following: + +@example +#!/bin/sh +/usr/bin/vcheckquota +@end example + +This is executed as a shell script, so you will need to make it +executable by running the command @samp{chmod +x /etc/vmailmgr/vdeliver-predeliver}. + +@section Enabling processing of autoresponses + +Download and install the qmail-autoresponder package, found at +@uref{http://untroubled.org/qmail-autoresponder/}. + +As with the above section, create a shell script +@file{/etc/vmailmgr/vdeliver-postdeliver}, containing the following: + +@example +#!/bin/sh +if test -s $MAILDIR/autoresponse/message.txt ; then + qmail-autoresponder $MAILDIR/autoresponse/message.txt $MAILDIR/autoresponse +fi +@end example + +@section 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. + +@itemize +@item +For Python fans, there is vpyadmin by Bruce Guenter. The files can +be downloaded at @uref{http://untroubled.org/vpyadmin/}, and +the development code is online at +@uref{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: +@uref{http://omail.omnis.ch}. Online demo: +@uref{http://admin.omnis.ch/omail/} (test.com / test). + +@item +And there are also C-based CGI scripts in the @file{cgi} +subdirectory of the vmailmgr distribution. + +@end itemize + +@contents + +@bye +