VMailMgr FAQ

  Bruce Guenter  <mailto:bruceg@em.ca>, Dan Kuykendall

  <mailto:dan@kuykendall.org>

  v1.0, 23 April 2000

  VMailMgr Frequently Asked Questions.

  ______________________________________________________________________

  Table of Contents

  1. Building and Installing

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

     1.2 Does vmailmgr work with shadow passwords?

     1.3 Does vmailmgr support IMAP?

  2. Setup and Configuration

     2.1 What other software is needed to run vmailmgr?

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

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

     2.4 How do I setup VMmailMgr IMAP support?

     2.5 Upgrading from Previous Versions

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

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

  3. Usage

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

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

  4. Troubleshooting

     4.1 Bind error message from vmailmgrd.

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

     4.3 Running vmailmgrd fails.

     4.4 POP3 or IMAP logins take 30 seconds or longer.

  5. Miscellaneous

     5.1 How do I get in contact with other users?

     5.2 Are development version of vmailmgr available anywhere?

     5.3 How does incoming email get handled?

     5.4 How does outgoing email get handled?

     5.5 What about security of CGI and PHP functions?

     5.6 What are the differences between vmailmgr and vpopmail?

  ______________________________________________________________________

  11..  BBuuiillddiinngg aanndd IInnssttaalllliinngg

  11..11..  WWhhaatt ccoommppiilleerr aanndd lliibbrraarriieess ddoo II nneeeedd ttoo bbuuiilldd vvmmaaiillmmggrr??

  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.

  11..22..  DDooeess vvmmaaiillmmggrr wwoorrkk wwiitthh sshhaaddooww ppaasssswwoorrddss??

  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.

  11..33..  DDooeess vvmmaaiillmmggrr ssuuppppoorrtt IIMMAAPP??

  Yes, vmailmgr supports Courier-IMAP.  Some minor steps are needed to

  make them work, the steps are in the next section of this file.

  22..  SSeettuupp aanndd CCoonnffiigguurraattiioonn

  22..11..  WWhhaatt ootthheerr ssooffttwwaarree iiss nneeeeddeedd ttoo rruunn vvmmaaiillmmggrr??

  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://em.ca/~bruceg/supervise-scripts/>) and daemontools 0.60 (or

  later, available at  <http://em.ca/~bruceg/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://em.ca/~bruceg/ucspi-unix/>.

  If you want to use the autoresponse feature, I recommend the use of my

  own autoresponder program, qmail-autoresponder available at

  <http://em.ca/~bruceg/qmail-autoresponder/>.

  22..22..  HHooww ddoo II rreeccoorrdd tthhee oouuttppuutt ooff vvmmaaiillmmggrrdd wwiitthh ssyysslloogg??

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

  22..33..  HHooww ddoo II rreeccoorrdd tthhee oouuttppuutt ooff vvmmaaiillmmggrrdd wwiitthh mmuullttiilloogg??

  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.

  22..44..  HHooww ddoo II sseettuupp VVMMmmaaiillMMggrr IIMMAAPP ssuuppppoorrtt??

  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.

  +o  You must copy `/usr/local/bin/authvmailmgr` to `/usr/lib/courier-

     imap/libexec/authlib/authvmailmgr`.

  +o  Then modify the `AUTHMODULES` statement in `/usr/lib/courier-

     imap/etc/imapd.config` and add `authvmailmgr` as the first

     authentication module.

  22..55..  UUppggrraaddiinngg ffrroomm PPrreevviioouuss VVeerrssiioonnss

  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.

  If you are upgrading from version:

     00..9966..66 oorr eeaarrlliieerr

        The `vmailmgrd' daemon needs to be run by unixserver, as opposed

        to being a stand-alone program previously.

     00..9966..22 oorr eeaarrlliieerr

        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.

     00..9944 oorr eeaarrlliieerr,, uussiinngg tthhee PPOOPP bbuulllleettiinn ffaacciilliittyy

        The POP bulletin facility has been moved into a stand-alone

        program that needs to be executed through `checkvpw-postsetuid'.

     00..9933 oorr eeaarrlliieerr

        If you do not use the CGIs, you no longer need to run the

        `vmailmgrd' daemon.

     00..9922..22 oorr eeaarrlliieerr

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

     00..9900..22 oorr eeaarrlliieerr

        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

        `*'.

     00..8888 oorr eeaarrlliieerr

        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.

  22..66..  HHooww ddoo II ccoonnffiigguurree qqmmaaiill++ppaattcchheess ttoo uussee vvmmaaiillmmggrr ffoorr PPOOPP??

  Put the string `checkvpw' into the file

  `/etc/qmail/control/checkpassword' and restart pop3d by typing

  `/etc/rc.d/init.d/pop3d restart'.

  22..77..  HHooww ddoo II aallllooww cclliieennttss ttoo rreellaayy SSMMTTPP tthhrroouugghh mmee??

  Download and install relay-ctrl from  <http://em.ca/~bruceg/relay-

  ctrl/>.  It works with vmailmgr, for both POP3 and IMAP clients.

  33..  UUssaaggee

  33..11..  II ccaann oonnllyy uussee oonnee IIPP aaddddrreessss.. HHooww ddoo II lloogg iinn aass aa vviirrttuuaall

  uusseerr??

  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.

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

  33..22..  HHooww ddoo II ggeett aallll mmiissddiirreecctteedd mmaaiill sseenntt ttoo mmee??

  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

  44..  TTrroouubblleesshhoooottiinngg

  44..11..  BBiinndd eerrrroorr mmeessssaaggee ffrroomm vvmmaaiillmmggrrdd..

  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.

  44..22..  EErrrroorr sseennddiinngg ttoo aann aalliiaass:: qqmmaaiill--qquueeuuee eexxiitteedd wwiitthh aann eerrrroorr!!

  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.

  44..33..  RRuunnnniinngg vvmmaaiillmmggrrdd ffaaiillss..

  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://em.ca/~bruceg/ucspi-unix/>.

  44..44..  PPOOPP33 oorr IIMMAAPP llooggiinnss ttaakkee 3300 sseeccoonnddss oorr lloonnggeerr..

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

  55..  MMiisscceellllaanneeoouuss

  55..11..  HHooww ddoo II ggeett iinn ccoonnttaacctt wwiitthh ootthheerr uusseerrss??

  There is a mailing list run by the author. To subscribe, send an e-

  mail (content and subject line is ignored) to  <mailto:vmailmgr-

  subscribe@lists.em.ca>.

  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.

  55..22..  AArree ddeevveellooppmmeenntt vveerrssiioonn ooff vvmmaaiillmmggrr aavvaaiillaabbllee aannyywwhheerree??

  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.

  55..33..  HHooww ddooeess iinnccoommiinngg eemmaaiill ggeett hhaannddlleedd??

  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.

  55..44..  HHooww ddooeess oouuttggooiinngg eemmaaiill ggeett hhaannddlleedd??

  Outgoing email is not handled by vmailmgr. For details on outgoing

  email handling, check the qmail documentation.

  55..55..  WWhhaatt aabboouutt sseeccuurriittyy ooff CCGGII aanndd PPHHPP ffuunnccttiioonnss??

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

  55..66..  WWhhaatt aarree tthhee ddiiffffeerreenncceess bbeettwweeeenn vvmmaaiillmmggrr aanndd vvppooppmmaaiill??

  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.