--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FAQ.html Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,297 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE> VMailMgr FAQ</TITLE>
+
+
+</HEAD>
+<BODY>
+<H1> VMailMgr FAQ</H1>
+
+<H2>Bruce Guenter
+<A HREF="mailto:bruceg@em.ca">mailto:bruceg@em.ca</A>,
+ Dan Kuykendall
+<A HREF="mailto:dan@kuykendall.org">mailto:dan@kuykendall.org</A></H2> v1.0, 23 April 2000
+<P><HR>
+<EM> VMailMgr Frequently Asked Questions.</EM>
+<HR>
+<H2><A NAME="s1">1. Building and Installing</A></H2>
+
+<H2>1.1 What compiler and libraries do I need to build vmailmgr?</H2>
+
+<P>You will need a working C and C++ compiler and linker. You will not
+need any C++ libraries. The package is being developed under Linux
+using egcs and glibc version 2, and may rely on some gcc/g++
+extensions.
+<H2>1.2 Does vmailmgr work with shadow passwords?</H2>
+
+<P>This package should work without changes both with and without
+shadow passwords as long as the shadow password libraries are
+present when this package is built. The `configure' script will
+detect what method of shadow passwords are being used and the
+programs will be built accordingly.
+<H2>1.3 Does vmailmgr support IMAP?</H2>
+
+<P>Yes, vmailmgr supports Courier-IMAP. Some minor steps are needed to
+make them work, the steps are in the next section of this file.
+<H2><A NAME="s2">2. Setup and Configuration</A></H2>
+
+<H2>2.1 What other software is needed to run vmailmgr?</H2>
+
+<P>VMailMgr is based around qmail's handling of virtual users, and as
+such requires qmail for its operation. If you wish to use the `init'
+file to start/stop vmailmgrd or are installing the RPM package,
+supervise-scripts version 2.2 (or later, available at
+<A HREF="http://em.ca/~bruceg/supervise-scripts/">http://em.ca/~bruceg/supervise-scripts/</A>) and daemontools 0.60
+(or later, available at
+<A HREF="http://em.ca/~bruceg/rpms/daemontools/">http://em.ca/~bruceg/rpms/daemontools/</A>) packages are
+required. If you need to use the <CODE>vmailmgrd</CODE> daemon, you
+will also need the <CODE>unixserver</CODE> program, from the ucspi-unix
+package, available at
+<A HREF="http://em.ca/~bruceg/ucspi-unix/">http://em.ca/~bruceg/ucspi-unix/</A>.
+<P>If you want to use the autoresponse feature, I recommend the use of
+my own autoresponder program, <CODE>qmail-autoresponder</CODE> available
+at
+<A HREF="http://em.ca/~bruceg/qmail-autoresponder/">http://em.ca/~bruceg/qmail-autoresponder/</A>.
+<H2>2.2 How do I record the output of vmailmgrd with syslog?</H2>
+
+<P>Output from vmailmgrd can be recorded by either splogger (part of
+qmail) or with the logger that comes with several flavours of
+UNIX. To use splogger, pipe the output of vmailmgrd into the command
+`splogger vmailmgrd'. This will timestamp each entry and tag them
+with the word `vmailmgrd'. By default, splogger logs to facility 2
+(mail). To use logger, pipe the output of vmailmgrd into the
+comamand `<CODE>logger -t vmailmgrd -p mail.notice</CODE>'. See the
+respective man pages of these two programs for more information.
+<P>Note: The use of syslog for logging messages is strongly discouraged
+due to problems with inefficent and buggy implementation of syslog.
+<H2>2.3 How do I record the output of vmailmgrd with multilog?</H2>
+
+<P>Make a directory into which the output will go, for example
+`<CODE>/var/log/vmailmgrd</CODE>'. Pipe the output of vmailmgrd into the
+command `<CODE>multilog t /var/log/vmailmgrd</CODE>'. See the
+documentation for multilog for more information on how to adjust its
+output.
+<H2>2.4 How do I setup VMmailMgr IMAP support?</H2>
+
+<P>VMailMgr supports Courier-IMAP, but Courier-IMAP does not auto
+detect VMailMgr. This means that some minor work is required for
+making the two work together.
+<UL>
+<LI>You must copy `<CODE>/usr/local/bin/authvmailmgr</CODE>` to
+`<CODE>/usr/lib/courier-imap/libexec/authlib/authvmailmgr</CODE>`.</LI>
+<LI>Then modify the `<CODE>AUTHMODULES</CODE>` statement in
+`<CODE>/usr/lib/courier-imap/etc/imapd.config</CODE>` and add
+`<CODE>authvmailmgr</CODE>` as the first authentication module.</LI>
+</UL>
+<H2>2.5 Upgrading from Previous Versions</H2>
+
+<P>If you are upgrading from an older version, you may need to make
+some changes to your system before or after doing the upgrade. The
+following table outlines the necessary changes. Note that you need
+to follow the instructions for all later versions of the software.
+<P>If you are upgrading from version:
+<DL>
+<DT><B>0.96.6 or earlier</B><DD><P>The `vmailmgrd' daemon needs to be run by unixserver, as opposed
+to being a stand-alone program previously.
+<DT><B>0.96.2 or earlier</B><DD><P>Make sure the `vmailmgrd' daemon and vmailmgr CGIs are disabled
+before upgrading, and upgrade them along with the main
+package. Changes were made to the daemon interface that will
+cause adding users and aliases to flake out. As well, the
+listdomain interface was completely redone.
+<P>
+<DT><B>0.94 or earlier, using the POP bulletin facility</B><DD><P>The POP bulletin facility has been moved into a stand-alone
+program that needs to be executed through `checkvpw-postsetuid'.
+<P>
+<DT><B>0.93 or earlier</B><DD><P>If you do not use the CGIs, you no longer need to run the
+`vmailmgrd' daemon.
+<P>
+<DT><B>0.92.2 or earlier</B><DD><P>The configuration changed from reading a single file to reading a
+set of files in a directory. Read the configuration documentation
+and run the program `vconf2dir'.
+<P>
+<DT><B>0.90.2 or earlier</B><DD><P>The name of the user to which mail to an unknown user is
+delivered changed from `*' to `+'. If you were using this
+feature, either change all your domains to accomodate this
+change, or set the `default-username' config file to contain `*'.
+<P>
+<DT><B>0.88 or earlier</B><DD><P>The file format of the virtual password tables has changed from
+plain text files to CDB tables. You will need to suspend local
+deliveries before upgrading, and run the program `vpasswd2cdb' as
+each base user after upgrading, before re-enabling local
+deliveries.
+</DL>
+<H2>2.6 How do I configure qmail+patches to use vmailmgr for POP?</H2>
+
+<P>Put the string `<CODE>checkvpw</CODE>' into the file
+`<CODE>/etc/qmail/control/checkpassword</CODE>' and restart pop3d by
+typing `<CODE>/etc/rc.d/init.d/pop3d restart</CODE>'.
+<H2>2.7 How do I allow clients to relay SMTP through me?</H2>
+
+<P>Download and install relay-ctrl from
+<A HREF="http://em.ca/~bruceg/relay-ctrl/">http://em.ca/~bruceg/relay-ctrl/</A>.
+It works with vmailmgr, for both POP3 and IMAP clients.
+<H2><A NAME="s3">3. Usage</A></H2>
+
+<H2>3.1 I can only use one IP address. How do I log in as a virtual user?</H2>
+
+<P>There are two ways to log in without using multiple IP addresses.
+<P>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
+`<CODE>/etc/vmailmgr/</CODE>' directory), and
+`<CODE>virtual.domain.org</CODE>' is the virtual domain's name, as
+listed in `<CODE>/var/qmail/control/virtualdomains</CODE>'.
+<P>The second way is to use the internal form of the mailbox name --
+that is, `<CODE>baseuser-user</CODE>', where `<CODE>user</CODE>' is the same
+as above, and `<CODE>baseuser</CODE>' is the username of the managing
+user.
+<P>Example: `<CODE>/var/qmail/control/virtualdomains</CODE>' contains
+<PRE>
+ testdomain.org:testuser
+</PRE>
+
+User `<CODE>testuser</CODE>' exists, and has set up a virtual mailbox
+with the name `<CODE>v</CODE>'. The `<CODE>separators</CODE>' variable in
+`<CODE>/etc/vmailmgr/</CODE>' contains `<CODE>@:</CODE>'. This virtual user
+could log in as `<CODE>v@testdomain.org</CODE>',
+`<CODE>v:testdomain.org</CODE>', or `<CODE>testuser-v</CODE>'.
+<P>
+<P>
+<H2>3.2 How do I get all misdirected mail sent to me?</H2>
+
+<P>In the `<CODE>vmailmgr/</CODE>' configuration directory, there is an
+entry called `<CODE>default-username</CODE>'. 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 `<CODE>+</CODE>'). To make this deliver to you,
+simply type:
+<PRE>
+ vaddalias + me
+</PRE>
+<H2><A NAME="s4">4. Troubleshooting</A></H2>
+
+<H2>4.1 Bind error message from vmailmgrd.</H2>
+
+<P>If vmailmgrd reports `<CODE>vmailmgrd: bind: no such file or
+directory</CODE>' when you start it up, it means that can't create its
+socket file. By default, it will try to create the socket file
+`<CODE>/tmp/.vmailmgrd</CODE>'. You must ensure that `<CODE>/tmp</CODE>' is
+writable, or that the socket is created in some other place by
+setting `<CODE>socket-file</CODE>' in the configuration.
+<H2>4.2 Error sending to an alias: qmail-queue exited with an error!</H2>
+
+<P>If qmail reports "deferral: vdeliver: qmail-queue exited with an
+error!", check where your qmail is installed. On Debian systems,
+you will need to type "<CODE>ls -s /usr/sbin /var/qmail/bin</CODE>",
+since they've installed the qmail binaries into /usr/sbin.
+<H2>4.3 Running vmailmgrd fails.</H2>
+
+<P>When run by itself, vmailmgrd will report "<CODE>Timed out waiting for
+remote</CODE>". vmailmgrd needs to be run from unixserver, part of
+the ucspi-unix package available at
+<A HREF="http://em.ca/~bruceg/ucspi-unix/">http://em.ca/~bruceg/ucspi-unix/</A>.
+<H2>4.4 POP3 or IMAP logins take 30 seconds or longer.</H2>
+
+<P>This is almost certainly a DNS lookup problem. Make sure that DNS
+lookups aren't timing out, that lookups on all your IP addresses
+aren't failing, and that you can lookup remote addresses as well.
+<P>If you are using 'tcpserver' for the head end to qmail-pop3d, then you
+may want to the following 2 switches to the command line: <CODE>-R</CODE>
+and <CODE>-H</CODE>. The former prevents tcpserver from attempting to
+obtain TCPREMOTEINFO from the remote host. This eliminates an "ident"
+lookup that may be being blocked or silently dropped by a firewall.
+The latter prevents tcpserver from doing a DNS lookup on the remote
+IP.
+<H2><A NAME="s5">5. Miscellaneous</A></H2>
+
+<H2>5.1 How do I get in contact with other users?</H2>
+
+<P>There is a mailing list run by the author. To subscribe, send an
+e-mail (content and subject line is ignored) to
+<A HREF="mailto:vmailmgr-subscribe@lists.em.ca">mailto:vmailmgr-subscribe@lists.em.ca</A>.
+<P>Remember that if you have a problem that you want us to diagnose, we
+need to know the following important details:
+<OL>
+<LI>The output of `<CODE>qmail-showctl</CODE>` </LI>
+<LI>The contents of the vmailmgrd log for the attempt you are
+trying to diagnose</LI>
+<LI>The contents of the qmail and smtpd logs for a failed delivery
+attempt</LI>
+<LI>The contents of the pop3d logs for a failed login attempt</LI>
+<LI>The complete command line with which vmailmgrd and qmail-pop3d
+was invoked</LI>
+</OL>
+
+Please do not contact the author directly with vmailmgr questions.
+<H2>5.2 Are development version of vmailmgr available anywhere?</H2>
+
+<P>Yes, they are available through anonymous CVS.
+To access the CVS server, set your <CODE>CVSROOT</CODE> to
+<CODE>:pserver:cvs@bruce-guenter.dyndns.org:/CVS</CODE>, log in with an
+empty password, and check out the <CODE>vmailmgr</CODE> module.
+<H2>5.3 How does incoming email get handled?</H2>
+
+<P>Incoming email is first received by the qmail SMTP daemon and
+inserted into the qmail queue. Then `<CODE>qmail-send</CODE>' examines
+the email envelope (which details the recipient address or
+addresses) to determine how to dispatch the message. It looks up the
+domain name of each recipient in
+`<CODE>/var/qmail/control/virtualdomains</CODE>', and prefixes the user
+name with the string that it finds. It then looks up the resulting
+user name in the system password table (or in
+`<CODE>/var/qmail/users/cdb</CODE>' if it exists) to find the base user
+name and home directory (which I will call `<CODE>$HOME</CODE>'). It
+then looks for the file `<CODE>$HOME/.qmail-VIRTUAL</CODE>'. If that's
+not found, it looks for the file `<CODE>$HOME/.qmail-default</CODE>',
+which will contain an instruction to pipe the message to
+`<CODE>vdeliver</CODE>'.
+<P>This is where vmailmgr first enters the picture. The virtual user
+name is sent to `vdeliver' through environment variables. It looks
+in the configuration files (in `<CODE>$HOME/.vmailmgr</CODE>' and then
+in `<CODE>/etc/vmailmgr</CODE>') to determine the location of the
+password table, and looks up the virtual user name in the table to
+determine delivery instructions. If the name is not found, the
+message is bounced and delivery ends. Otherwise, it then looks for
+the `<CODE>vdeliver-predeliver</CODE>' script in the configuration
+directories (in reverse order) and executes any that are found. It
+then delivers the message to all the listed destinations -- an
+optional mailbox directory and zero or more forwarding
+addresses. Finally, it looks for the `<CODE>vdeliver-postdeliver</CODE>'
+script and executes any that are found.
+<H2>5.4 How does outgoing email get handled?</H2>
+
+<P>Outgoing email is not handled by vmailmgr. For details on outgoing
+email handling, check the qmail documentation.
+<H2>5.5 What about security of CGI and PHP functions?</H2>
+
+<P>The socket used by the daemon is a UNIX-domain socket (as opposed to
+Internet-domain), meaning you need local access on the computer to
+open up a connection. The path for this socket is run-time
+configurable.
+<P>The daemon forks a new connection for each connection, up to a
+configurable maximum (at which point it stops listening, IIRC, I
+should verify this). The idea of threading has been completely
+discarded to avoid a bug in a command creeping in and makeing the
+whole server break.
+<P>The protocol spoken over the socket is explicitly bounded to at most
+64kB of data, and all data is prefixed by a size. Static-sized
+buffers are only used with static-sized reads, and therefore can't be
+overflowed with stack-smashing tricks.
+<P>The daemon commands setuid to the appropriate user as soon as the base
+user has been verified, to avoid doing any more than necessary as
+root, as well as to avoid the possibility of tricking the daemon into
+reading a file another user wouldn't normally have access to.
+<P>To help avoid DoS on the local computer, a 1-second alarm is set as
+soon as the connection is received, and is only cleared once all the
+data has been read. If it takes longer than 1 second to read the data
+from the socket, the server process exits.
+<H2>5.6 What are the differences between vmailmgr and vpopmail?</H2>
+
+<P>The primary difference between vmailmgr and vpopmail is the use of
+base users. With vmailmgr there is one base user for each virtual
+domain. With vpopmail, there is one base user for the entire
+virtual domain system.
+</BODY>
+</HTML>