--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FAQ.sgml Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,373 @@
+<!doctype linuxdoc system>
+
+<!-- LinuxDoc file was created by hand by <Dan Kuykendall> Wed April 23 -->
+<article>
+<title>
+ VMailMgr FAQ
+</title>
+<author>
+ Bruce Guenter <url url="mailto:bruceg@em.ca">,
+ Dan Kuykendall <url url="mailto:dan@kuykendall.org">
+</author>
+<date>
+ v1.0, 23 April 2000
+</date>
+<abstract>
+ VMailMgr Frequently Asked Questions.
+</abstract>
+
+<toc>
+
+<sect>Building and Installing
+
+<sect1>What compiler and libraries do I need to build vmailmgr?
+<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.
+</p>
+
+<sect1>Does vmailmgr work with shadow passwords?
+<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.
+</p>
+
+<sect1>Does vmailmgr support IMAP?
+<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.
+</p>
+
+<sect>Setup and Configuration
+
+<sect1>What other software is needed to run vmailmgr?
+<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 <url
+ url="http://em.ca/~bruceg/supervise-scripts/">) and daemontools 0.60
+ (or later, available at <url
+ url="http://em.ca/~bruceg/rpms/daemontools/">) packages are
+ required. If you need to use the <tt>vmailmgrd</tt> daemon, you
+ will also need the <tt>unixserver</tt> program, from the ucspi-unix
+ package, available at <url url="http://em.ca/~bruceg/ucspi-unix/">.
+</p>
+
+<p>
+ If you want to use the autoresponse feature, I recommend the use of
+ my own autoresponder program, <tt>qmail-autoresponder</tt> available
+ at <url url="http://em.ca/~bruceg/qmail-autoresponder/">.
+</p>
+
+<sect1>How do I record the output of vmailmgrd with syslog?
+<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 `<tt>logger -t vmailmgrd -p mail.notice</tt>'. See the
+ respective man pages of these two programs for more information.
+</p>
+<p>
+ Note: The use of syslog for logging messages is strongly discouraged
+ due to problems with inefficent and buggy implementation of syslog.
+</p>
+
+<sect1>How do I record the output of vmailmgrd with multilog?
+<p>
+ Make a directory into which the output will go, for example
+ `<tt>/var/log/vmailmgrd</tt>'. Pipe the output of vmailmgrd into the
+ command `<tt>multilog t /var/log/vmailmgrd</tt>'. See the
+ documentation for multilog for more information on how to adjust its
+ output.
+</p>
+
+<sect1>How do I setup VMmailMgr IMAP support?
+<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.
+<itemize>
+ <item>You must copy `<tt>/usr/local/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>Upgrading from Previous Versions
+<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:
+<descrip>
+<tag>0.96.6 or earlier</tag>
+<p>
+ The `vmailmgrd' daemon needs to be run by unixserver, as opposed
+ to being a stand-alone program previously.
+</p>
+<tag>0.96.2 or earlier</tag>
+<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>
+<tag>0.94 or earlier, using the POP bulletin facility</tag>
+<p>
+ The POP bulletin facility has been moved into a stand-alone
+ program that needs to be executed through `checkvpw-postsetuid'.
+<p>
+<tag>0.93 or earlier</tag>
+<p>
+ If you do not use the CGIs, you no longer need to run the
+ `vmailmgrd' daemon.
+<p>
+<tag>0.92.2 or earlier</tag>
+<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>
+<tag>0.90.2 or earlier</tag>
+<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>
+<tag>0.88 or earlier</tag>
+<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.
+</descrip>
+</p>
+
+<sect1>How do I configure qmail+patches to use vmailmgr for POP?
+<p>
+Put the string `<tt>checkvpw</tt>' into the file
+`<tt>/etc/qmail/control/checkpassword</tt>' and restart pop3d by
+typing `<tt>/etc/rc.d/init.d/pop3d restart</tt>'.
+</p>
+
+<sect1>How do I allow clients to relay SMTP through me?
+<p>
+ Download and install relay-ctrl from <url
+ url="http://em.ca/~bruceg/relay-ctrl/">.
+ It works with vmailmgr, for both POP3 and IMAP clients.
+</p>
+
+<sect>Usage
+
+<sect1>I can only use one IP address. How do I log in as a virtual user?
+<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
+ `<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>'.
+<p>
+ 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.
+
+ Example: `<tt>/var/qmail/control/virtualdomains</tt>' contains
+<verb>
+ testdomain.org:testuser
+</verb>
+ User `<tt>testuser</tt>' exists, and has set up a virtual mailbox
+ with the name `<tt>v</tt>'. The `<tt>separators</tt>' variable in
+ `<tt>/etc/vmailmgr/</tt>' contains `<tt>@:</tt>'. This virtual user
+ could log in as `<tt>v@testdomain.org</tt>',
+ `<tt>v:testdomain.org</tt>', or `<tt>testuser-v</tt>'.
+<p>
+
+<sect1>How do I get all misdirected mail sent to me?
+<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>
+
+<sect>Troubleshooting
+
+<sect1>Bind error message from vmailmgrd.
+<p>
+ If vmailmgrd reports `<tt>vmailmgrd: bind: no such file or
+ directory</tt>' when you start it up, it means that can't create its
+ socket file. By default, it will try to create the socket file
+ `<tt>/tmp/.vmailmgrd</tt>'. You must ensure that `<tt>/tmp</tt>' is
+ writable, or that the socket is created in some other place by
+ setting `<tt>socket-file</tt>' in the configuration.
+</p>
+
+<sect1>Error sending to an alias: qmail-queue exited with an error!
+<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 "<tt>ls -s /usr/sbin /var/qmail/bin</tt>",
+ since they've installed the qmail binaries into /usr/sbin.
+</p>
+
+<sect1>Running vmailmgrd fails.
+<p>
+ When run by itself, vmailmgrd will report "<tt>Timed out waiting for
+ remote</tt>". vmailmgrd needs to be run from unixserver, part of
+ the ucspi-unix package available at <url
+ url="http://em.ca/~bruceg/ucspi-unix/">.
+</p>
+
+<sect1>POP3 or IMAP logins take 30 seconds or longer.
+<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>
+
+<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: <tt>-R</tt>
+ and <tt>-H</tt>. 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.
+</p>
+
+<sect>Miscellaneous
+
+<sect1>How do I get in contact with other users?
+<p>
+ There is a mailing list run by the author. To subscribe, send an
+ e-mail (content and subject line is ignored) to <url
+ url="mailto:vmailmgr-subscribe@lists.em.ca">.
+<p>
+ Remember that if you have a problem that you want us to diagnose, we
+ need to know the following important details:
+<enum>
+ <item>The output of `<tt>qmail-showctl</tt>`
+ <item>The contents of the vmailmgrd log for the attempt you are
+ trying to diagnose
+ <item>The contents of the qmail and smtpd logs for a failed delivery
+ attempt
+ <item>The contents of the pop3d logs for a failed login attempt
+ <item>The complete command line with which vmailmgrd and qmail-pop3d
+ was invoked
+</enum>
+ Please do not contact the author directly with vmailmgr questions.
+</p>
+
+<sect1>Are development version of vmailmgr available anywhere?
+<p>
+ Yes, they are available through anonymous CVS.
+ To access the CVS server, set your <tt>CVSROOT</tt> to
+ <tt>:pserver:cvs@bruce-guenter.dyndns.org:/CVS</tt>, log in with an
+ empty password, and check out the <tt>vmailmgr</tt> module.
+</p>
+
+<sect1>How does incoming email get handled?
+<p>
+ Incoming email is first received by the qmail SMTP daemon and
+ inserted into the qmail queue. Then `<tt>qmail-send</tt>' 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
+ `<tt>/var/qmail/control/virtualdomains</tt>', 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
+ `<tt>/var/qmail/users/cdb</tt>' if it exists) to find the base user
+ name and home directory (which I will call `<tt>$HOME</tt>'). It
+ then looks for the file `<tt>$HOME/.qmail-VIRTUAL</tt>'. If that's
+ not found, it looks for the file `<tt>$HOME/.qmail-default</tt>',
+ which will contain an instruction to pipe the message to
+ `<tt>vdeliver</tt>'.
+<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 `<tt>$HOME/.vmailmgr</tt>' and then
+ in `<tt>/etc/vmailmgr</tt>') 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 `<tt>vdeliver-predeliver</tt>' 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 `<tt>vdeliver-postdeliver</tt>'
+ script and executes any that are found.
+</p>
+
+<sect1>How does outgoing email get handled?
+<p>
+ Outgoing email is not handled by vmailmgr. For details on outgoing
+ email handling, check the qmail documentation.
+</p>
+
+<sect1>What about security of CGI and PHP functions?
+<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>
+<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>
+<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>
+<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>
+<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.
+</p>
+
+<sect1>What are the differences between vmailmgr and vpopmail?
+<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.
+</p>
+
+</article>