<!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>