This is FAQ.info, produced by makeinfo version 4.7 from FAQ.texi.

     Copyright (C) 1998 Bruce Guenter

     VMailMgr Frequently Asked Questions.

1 Building and Installing
*************************

1.1 What compiler and libraries do I need to build vmailmgr?
============================================================

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.

1.2 Does vmailmgr work with shadow passwords?
=============================================

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.

1.3 Does vmailmgr support IMAP?
===============================

Yes, vmailmgr supports Courier-IMAP.  Some minor steps are needed to
make them work, the steps are in the next section of this file.

2 Setup and Configuration
*************************

2.1 What other software is needed to run vmailmgr?
==================================================

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
`http://untroubled.org/supervise-scripts/') and daemontools 0.60 (or
later, available at `http://untroubled.org/rpms/daemontools/') packages
are required.  If you need to use the `vmailmgrd' daemon, you will also
need the `unixserver' program, from the ucspi-unix package, available at
`http://untroubled.org/ucspi-unix/'.

     If you want to use the autoresponse feature, I recommend the use of
my own autoresponder program, `qmail-autoresponder' available at
`http://untroubled.org/qmail-autoresponder/'.

2.2 How do I record the output of vmailmgrd with syslog?
========================================================

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 command
`logger -t vmailmgrd -p mail.notice'.  See the respective man pages of
these two programs for more information.

     Note: The use of `syslog' for logging messages is strongly
discouraged due to problems with inefficent and buggy implementation of
`syslog'.

2.3 How do I record the output of vmailmgrd with multilog?
==========================================================

Make a directory into which the output will go, for example
`/var/log/vmailmgrd'. Pipe the output of `vmailmgrd' into the command
`multilog t /var/log/vmailmgrd'. See the documentation for `multilog'
for more information on how to adjust its output.

2.4 How do I setup VMmailMgr IMAP support?
==========================================

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.

   * You must copy `/usr/local/bin/authvmailmgr' to
     `/usr/lib/courier-imap/libexec/authlib/authvmailmgr'.

   * Then modify the `AUTHMODULES' statement in
     `/usr/lib/courier-imap/etc/imapd.config' and add `authvmailmgr' as
     the first authentication module.


2.5 Upgrading from Previous Versions
====================================

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.

2.5.1 Upgrading from version 0.96.6 or earlier
----------------------------------------------

The `vmailmgrd' daemon needs to be run by unixserver, as opposed to
being a stand-alone program previously.

2.5.2 Upgrading from version 0.96.2 or earlier
----------------------------------------------

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.

2.5.3 Upgrading from version 0.94 or earlier, using the POP bulletin facility
-----------------------------------------------------------------------------

The POP bulletin facility has been moved into a stand-alone program
that needs to be executed through `checkvpw-postsetuid'.

2.5.4 Upgrading from version 0.93 or earlier
--------------------------------------------

If you do not use the CGIs, you no longer need to run the `vmailmgrd'
daemon.

2.5.5 Upgrading from version 0.92.2 or earlier
----------------------------------------------

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'.

2.5.6 Upgrading from version 0.90.2 or earlier
----------------------------------------------

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 `*'.

2.5.7 Upgrading from version 0.88 or earlier
--------------------------------------------

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.

2.6 How do I configure qmail+patches to use vmailmgr for POP?
=============================================================

Put the string `checkvpw' into the file
`/etc/qmail/control/checkpassword' and restart `qmail-pop3d' by typing
`/etc/rc.d/init.d/pop3d restart'.

2.7 How do I allow clients to relay SMTP through me?
====================================================

Download and install relay-ctrl from
`http://untroubled.org/relay-ctrl/'.  It works with vmailmgr, for both
POP3 and IMAP clients.

3 Usage
*******

3.1 I can only use one IP address. How do I log in as a virtual user?
=====================================================================

There are two ways to log in without using multiple IP addresses.

   * 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'.

   * 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, `/var/qmail/control/virtualdomains' contains
     `testdomain.org:testuser', user `testuser' exists, and has set up
     a virtual mailbox with the name `v'.  The SEPARATORS variable in
     `/etc/vmailmgr/' contains `@:'.  This virtual user could log in as
     `v@testdomain.org', `v:testdomain.org', or `testuser-v'.

3.2 How do I get all misdirected mail sent to me?
=================================================

In the `vmailmgr/' configuration directory, there is an entry 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.3 How can I put system accounts in a virtual domain?
======================================================

System accounts are those listed in `/etc/password' (or
`/var/qmail/users/cdb').  The system accounts are accessable, either
though SMTP or POP3 or IMAP, as `name@DOMAIN', where DOMAIN is listed in
`/var/qmail/control/locals'.

     Virtual accounts exist only as an artifact of vmailmgr management.
They are accessable as `name@DOMAIN', where DOMAIN is listed in
`/var/qmail/control/virtualdomains'.

     You *cannot* mix accounts within a domain between system and
virtual domains.  If the domain is in `control/locals', all accounts
for that domain must be system accounts.  If it is in
`control/virtualdomains', all accounts for that domain must be virtual
accounts.  Also, `control/locals' overrides `control/virtualdomains':
if the domain is in `locals', `virtualdomains' is ignored.

     As an aside, if the domain is neither in `locals' nor in
`virtualdomains', qmail will reject incoming messages, and vmailmgr will
treat it as local.

4 Troubleshooting
*****************

4.1 Bind error message from `vmailmgrd'.
========================================

If `vmailmgrd' reports

     vmailmgrd: bind: no such file or directory
     when you start it up, it means that can't create its socket file.
By default, it will try to create the socket file `/tmp/.vmailmgrd'.
You must ensure that `/tmp/' is writable, or that the socket is created
in some other place by setting SOCKET-FILE in the configuration.

4.2 Error sending to an alias: `qmail-queue' exited with an error!
==================================================================

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 `ls -s /usr/sbin /var/qmail/bin', since they've installed
the qmail binaries into `/usr/sbin'.

4.3 Running `vmailmgrd' fails.
==============================

When run by itself, `vmailmgrd' will report

     Timed out waiting for remote
     `vmailmgrd' needs to be run from `unixserver', part of the
ucspi-unix package available at `http://untroubled.org/ucspi-unix/'.

4.4 POP3 or IMAP logins take 30 seconds or longer.
==================================================

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.

     If you are using `tcpserver' for the head end to `qmail-pop3d',
then you may want to add the following 2 switches to the command line:
`-R' and `-H'.  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.

5 Miscellaneous
***************

5.1 How do I get in contact with other users?
=============================================

There is a mailing list run by the author. To subscribe, send an e-mail
(content and subject line is ignored) to
<vmailmgr-subscribe@lists.untroubled.org>.

     Remember that if you have a problem that you want us to diagnose,
we need to know the following important details:
  1. The output of `qmail-showctl'

  2. The contents of the `vmailmgrd' log for the attempt you are trying
     to diagnose

  3. The contents of the qmail and smtpd logs for a failed delivery
     attempt

  4. The contents of the pop3d logs for a failed login attempt

  5. The complete command line with which `vmailmgrd' and `qmail-pop3d'
     was invoked

     Please do not contact the author directly with vmailmgr questions.

5.2 Are development version of vmailmgr available anywhere?
===========================================================

Yes, they are available through anonymous CVS.  To access the CVS
server, set your `CVSROOT' to
`:pserver:cvs@bruce-guenter.dyndns.org:/CVS', log in with an empty
password, and check out the `vmailmgr' module.

5.3 How does incoming email get handled?
========================================

Incoming email is first received by the qmail SMTP daemon and inserted
into the qmail queue. Then `qmail-send' 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
`/var/qmail/control/virtualdomains', 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 `/var/qmail/users/cdb' if it exists)
to find the base user name and home directory (which I will call
`$HOME'). It then looks for the file ``$HOME'/.qmail-VIRTUAL'. If that's
not found, it looks for the file ``$HOME'/.qmail-default', which will
contain an instruction to pipe the message to `vdeliver'.

     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 ``$HOME'/.vmailmgr' and then in
`/etc/vmailmgr') 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 `vdeliver-predeliver'
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 `vdeliver-postdeliver' script and
executes any that are found.

5.4 How does outgoing email get handled?
========================================

Outgoing email is not handled by vmailmgr. For details on outgoing
email handling, check the qmail documentation.

5.5 What about security of CGI and PHP functions?
=================================================

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.

     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 making the whole server break.

     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.

     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.

     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.

5.6 What are the differences between vmailmgr and vpopmail?
===========================================================

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.