--- a/doc/HOWTO.sgml Sun Jan 20 00:12:17 2008 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,372 +0,0 @@
-<!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>