1   VMailMgr FAQ

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

     3   <mailto:dan@kuykendall.org>

     4   v1.0, 23 April 2000

     5 

     6   VMailMgr Frequently Asked Questions.

     7   ______________________________________________________________________

     8 

     9   Table of Contents

    10 

    11 

    12   1. Building and Installing

    13 

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

    15      1.2 Does vmailmgr work with shadow passwords?

    16      1.3 Does vmailmgr support IMAP?

    17 

    18   2. Setup and Configuration

    19 

    20      2.1 What other software is needed to run vmailmgr?

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

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

    23      2.4 How do I setup VMmailMgr IMAP support?

    24      2.5 Upgrading from Previous Versions

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

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

    27 

    28   3. Usage

    29 

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

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

    32 

    33   4. Troubleshooting

    34 

    35      4.1 Bind error message from vmailmgrd.

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

    37      4.3 Running vmailmgrd fails.

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

    39 

    40   5. Miscellaneous

    41 

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

    43      5.2 Are development version of vmailmgr available anywhere?

    44      5.3 How does incoming email get handled?

    45      5.4 How does outgoing email get handled?

    46      5.5 What about security of CGI and PHP functions?

    47      5.6 What are the differences between vmailmgr and vpopmail?

    48 

    49 

    50   ______________________________________________________________________

    51 

    52   11..  BBuuiillddiinngg aanndd IInnssttaalllliinngg

    53 

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

    55 

    56   You will need a working C and C++ compiler and linker. You will not

    57   need any C++ libraries.  The package is being developed under Linux

    58   using egcs and glibc version 2, and may rely on some gcc/g++

    59   extensions.

    60 

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

    62 

    63   This package should work without changes both with and without shadow

    64   passwords as long as the shadow password libraries are present when

    65   this package is built. The `configure' script will detect what method

    66   of shadow passwords are being used and the programs will be built

    67   accordingly.

    68 

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

    70 

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

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

    73 

    74   22..  SSeettuupp aanndd CCoonnffiigguurraattiioonn

    75 

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

    77 

    78   VMailMgr is based around qmail's handling of virtual users, and as

    79   such requires qmail for its operation. If you wish to use the `init'

    80   file to start/stop vmailmgrd or are installing the RPM package,

    81   supervise-scripts version 2.2 (or later, available at

    82   <http://em.ca/~bruceg/supervise-scripts/>) and daemontools 0.60 (or

    83   later, available at  <http://em.ca/~bruceg/rpms/daemontools/>)

    84   packages are required.  If you need to use the vmailmgrd daemon, you

    85   will also need the unixserver program, from the ucspi-unix package,

    86   available at  <http://em.ca/~bruceg/ucspi-unix/>.

    87 

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

    89   own autoresponder program, qmail-autoresponder available at

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

    91 

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

    93 

    94   Output from vmailmgrd can be recorded by either splogger (part of

    95   qmail) or with the logger that comes with several flavours of UNIX. To

    96   use splogger, pipe the output of vmailmgrd into the command `splogger

    97   vmailmgrd'. This will timestamp each entry and tag them with the word

    98   `vmailmgrd'. By default, splogger logs to facility 2 (mail). To use

    99   logger, pipe the output of vmailmgrd into the comamand `logger -t

   100   vmailmgrd -p mail.notice'. See the respective man pages of these two

   101   programs for more information.

   102 

   103   Note: The use of syslog for logging messages is strongly discouraged

   104   due to problems with inefficent and buggy implementation of syslog.

   105 

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

   107 

   108   Make a directory into which the output will go, for example

   109   `/var/log/vmailmgrd'. Pipe the output of vmailmgrd into the command

   110   `multilog t /var/log/vmailmgrd'. See the documentation for multilog

   111   for more information on how to adjust its output.

   112 

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

   114 

   115   VMailMgr supports Courier-IMAP, but Courier-IMAP does not auto detect

   116   VMailMgr.  This means that some minor work is required for making the

   117   two work together.

   118 

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

   120      imap/libexec/authlib/authvmailmgr`.

   121 

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

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

   124      authentication module.

   125 

   126   22..55..  UUppggrraaddiinngg ffrroomm PPrreevviioouuss VVeerrssiioonnss

   127 

   128   If you are upgrading from an older version, you may need to make some

   129   changes to your system before or after doing the upgrade. The

   130   following table outlines the necessary changes. Note that you need to

   131   follow the instructions for all later versions of the software.

   132 

   133   If you are upgrading from version:

   134 

   135      00..9966..66 oorr eeaarrlliieerr

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

   137         to being a stand-alone program previously.

   138 

   139      00..9966..22 oorr eeaarrlliieerr

   140         Make sure the `vmailmgrd' daemon and vmailmgr CGIs are disabled

   141         before upgrading, and upgrade them along with the main package.

   142         Changes were made to the daemon interface that will cause adding

   143         users and aliases to flake out. As well, the listdomain

   144         interface was completely redone.

   145 

   146 

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

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

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

   150 

   151 

   152      00..9933 oorr eeaarrlliieerr

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

   154         `vmailmgrd' daemon.

   155 

   156 

   157      00..9922..22 oorr eeaarrlliieerr

   158         The configuration changed from reading a single file to reading

   159         a set of files in a directory. Read the configuration

   160         documentation and run the program `vconf2dir'.

   161 

   162 

   163      00..9900..22 oorr eeaarrlliieerr

   164         The name of the user to which mail to an unknown user is

   165         delivered changed from `*' to `+'. If you were using this

   166         feature, either change all your domains to accomodate this

   167         change, or set the `default-username' config file to contain

   168         `*'.

   169 

   170 

   171      00..8888 oorr eeaarrlliieerr

   172         The file format of the virtual password tables has changed from

   173         plain text files to CDB tables. You will need to suspend local

   174         deliveries before upgrading, and run the program `vpasswd2cdb'

   175         as each base user after upgrading, before re-enabling local

   176         deliveries.

   177 

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

   179 

   180   Put the string `checkvpw' into the file

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

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

   183 

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

   185 

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

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

   188 

   189   33..  UUssaaggee

   190 

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

   192   uusseerr??

   193 

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

   195 

   196   The first way is to log in as `userSEPvirtual.domain.org', where

   197   `user' is the mailbox name of the virtual user, SEP is one of `@' or

   198   `:' (by default, this is configurable in the `/etc/vmailmgr/'

   199   directory), and `virtual.domain.org' is the virtual domain's name, as

   200   listed in `/var/qmail/control/virtualdomains'.

   201 

   202   The second way is to use the internal form of the mailbox name -- that

   203   is, `baseuser-user', where `user' is the same as above, and `baseuser'

   204   is the username of the managing user.

   205 

   206   Example: `/var/qmail/control/virtualdomains' contains

   207 

   208     testdomain.org:testuser

   209 

   210 

   211   User `testuser' exists, and has set up a virtual mailbox with the name

   212   `v'. The `separators' variable in `/etc/vmailmgr/' contains `@:'. This

   213   virtual user could log in as `v@testdomain.org', `v:testdomain.org',

   214   or `testuser-v'.

   215 

   216 

   217 

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

   219 

   220   In the `vmailmgr/' configuration directory, there is an entry called

   221   `default-username'. If mail to a virtual domain does not match any

   222   users or aliases in that domain, it is delivered to the name listed in

   223   this configuration item if it exists (which defaults to `+'). To make

   224   this deliver to you, simply type:

   225 

   226     vaddalias + me

   227 

   228 

   229 

   230   44..  TTrroouubblleesshhoooottiinngg

   231 

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

   233 

   234   If vmailmgrd reports `vmailmgrd: bind: no such file or directory' when

   235   you start it up, it means that can't create its socket file.  By

   236   default, it will try to create the socket file `/tmp/.vmailmgrd'. You

   237   must ensure that `/tmp' is writable, or that the socket is created in

   238   some other place by setting `socket-file' in the configuration.

   239 

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

   241 

   242   If qmail reports "deferral: vdeliver: qmail-queue exited with an

   243   error!", check where your qmail is installed.  On Debian systems, you

   244   will need to type "ls -s /usr/sbin /var/qmail/bin", since they've

   245   installed the qmail binaries into /usr/sbin.

   246 

   247   44..33..  RRuunnnniinngg vvmmaaiillmmggrrdd ffaaiillss..

   248 

   249   When run by itself, vmailmgrd will report "Timed out waiting for

   250   remote".  vmailmgrd needs to be run from unixserver, part of the

   251   ucspi-unix package available at  <http://em.ca/~bruceg/ucspi-unix/>.

   252 

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

   254 

   255   This is almost certainly a DNS lookup problem.  Make sure that DNS

   256   lookups aren't timing out, that lookups on all your IP addresses

   257   aren't failing, and that you can lookup remote addresses as well.

   258 

   259   If you are using 'tcpserver' for the head end to qmail-pop3d, then you

   260   may want to the following 2 switches to the command line: -R and -H.

   261   The former prevents tcpserver from attempting to obtain TCPREMOTEINFO

   262   from the remote host.  This eliminates an "ident" lookup that may be

   263   being blocked or silently dropped by a firewall.  The latter prevents

   264   tcpserver from doing a DNS lookup on the remote IP.

   265   55..  MMiisscceellllaanneeoouuss

   266 

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

   268 

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

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

   271   subscribe@lists.em.ca>.

   272 

   273   Remember that if you have a problem that you want us to diagnose, we

   274   need to know the following important details:

   275 

   276   1. The output of `qmail-showctl`

   277 

   278   2. The contents of the vmailmgrd log for the attempt you are trying to

   279      diagnose

   280 

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

   282      attempt

   283 

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

   285 

   286   5. The complete command line with which vmailmgrd and qmail-pop3d was

   287      invoked

   288 

   289      Please do not contact the author directly with vmailmgr questions.

   290 

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

   292 

   293   Yes, they are available through anonymous CVS.  To access the CVS

   294   server, set your CVSROOT to :pserver:cvs@bruce-

   295   guenter.dyndns.org:/CVS, log in with an empty password, and check out

   296   the vmailmgr module.

   297 

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

   299 

   300   Incoming email is first received by the qmail SMTP daemon and inserted

   301   into the qmail queue. Then `qmail-send' examines the email envelope

   302   (which details the recipient address or addresses) to determine how to

   303   dispatch the message. It looks up the domain name of each recipient in

   304   `/var/qmail/control/virtualdomains', and prefixes the user name with

   305   the string that it finds. It then looks up the resulting user name in

   306   the system password table (or in `/var/qmail/users/cdb' if it exists)

   307   to find the base user name and home directory (which I will call

   308   `$HOME'). It then looks for the file `$HOME/.qmail-VIRTUAL'. If that's

   309   not found, it looks for the file `$HOME/.qmail-default', which will

   310   contain an instruction to pipe the message to `vdeliver'.

   311 

   312   This is where vmailmgr first enters the picture. The virtual user name

   313   is sent to `vdeliver' through environment variables. It looks in the

   314   configuration files (in `$HOME/.vmailmgr' and then in `/etc/vmailmgr')

   315   to determine the location of the password table, and looks up the

   316   virtual user name in the table to determine delivery instructions. If

   317   the name is not found, the message is bounced and delivery ends.

   318   Otherwise, it then looks for the `vdeliver-predeliver' script in the

   319   configuration directories (in reverse order) and executes any that are

   320   found. It then delivers the message to all the listed destinations --

   321   an optional mailbox directory and zero or more forwarding addresses.

   322   Finally, it looks for the `vdeliver-postdeliver' script and executes

   323   any that are found.

   324 

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

   326 

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

   328   email handling, check the qmail documentation.

   329 

   330 

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

   332 

   333   The socket used by the daemon is a UNIX-domain socket (as opposed to

   334   Internet-domain), meaning you need local access on the computer to

   335   open up a connection.  The path for this socket is run-time

   336   configurable.

   337 

   338   The daemon forks a new connection for each connection, up to a

   339   configurable maximum (at which point it stops listening, IIRC, I

   340   should verify this).  The idea of threading has been completely

   341   discarded to avoid a bug in a command creeping in and makeing the

   342   whole server break.

   343 

   344   The protocol spoken over the socket is explicitly bounded to at most

   345   64kB of data, and all data is prefixed by a size.  Static-sized

   346   buffers are only used with static-sized reads, and therefore can't be

   347   overflowed with stack-smashing tricks.

   348 

   349   The daemon commands setuid to the appropriate user as soon as the base

   350   user has been verified, to avoid doing any more than necessary as

   351   root, as well as to avoid the possibility of tricking the daemon into

   352   reading a file another user wouldn't normally have access to.

   353 

   354   To help avoid DoS on the local computer, a 1-second alarm is set as

   355   soon as the connection is received, and is only cleared once all the

   356   data has been read.  If it takes longer than 1 second to read the data

   357   from the socket, the server process exits.

   358 

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

   360 

   361   The primary difference between vmailmgr and vpopmail is the use of

   362   base users.  With vmailmgr there is one base user for each virtual

   363   domain.  With vpopmail, there is one base user for the entire virtual

   364   domain system.

   365 

   366 

   367 

   368 

   369 

   370 

   371 

   372 

   373 

   374 

   375 

   376 

   377 

   378 

   379 

   380 

   381 

   382 

   383 

   384 

   385 

   386 

   387 

   388 

   389 

   390 

   391 

   392 

   393 

   394 

   395 

   396