1   VMailMgr HOWTO

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

     3   <mailto:dan@kuykendall.org>

     4   v1.w, 2000-09-15

     5 

     6   This document explains how to setup VMailMgr support pop3 virtual

     7   domain   services in conjunction with Qmail.

     8   ______________________________________________________________________

     9 

    10   Table of Contents

    11 

    12 

    13   1. Introduction

    14 

    15      1.1 What is VMailMgr and why should I use it?

    16      1.2 New versions

    17      1.3 Comments

    18      1.4 History

    19      1.5 Copyrights and Trademarks

    20      1.6 Acknowledgements and Thanks

    21 

    22   2. Installation

    23 

    24      2.1 Get the files

    25      2.2 Install with RPMS

    26         2.2.1 Compiling SRC.RPM's

    27         2.2.2 Installing RPM's

    28      2.3 Install with source

    29 

    30   3. Setup

    31 

    32      3.1 Setting Up a Virtual Domain

    33      3.2 Using one IP address for mutiple domains

    34      3.3 Catching all misdirected mail in a virtual domain

    35      3.4 VMailMgr IMAP support

    36      3.5 Enabling enforcement of virtual user quotas

    37      3.6 Enabling processing of autoresponses

    38      3.7 Web-based interfaces for vmailmgr

    39 

    40 

    41   ______________________________________________________________________

    42 

    43   11..  IInnttrroodduuccttiioonn

    44 

    45   VMailMgr (short for Virtual MAIL ManaGeR) is a package of programs

    46   designed to manage multiple domains of mail addresses and mailboxes on

    47   a single host. It co-operates with qmail for mail delivery and program

    48   control.

    49 

    50   11..11..  WWhhaatt iiss VVMMaaiillMMggrr aanndd wwhhyy sshhoouulldd II uussee iitt??

    51 

    52   VMailMgr is:

    53 

    54   A series of utilities for managing virtual domains which include a

    55   password checking interface for qmail which replaces the usual

    56   checkpassword, and an authentication module for Courier IMAP, that

    57   provide access to the virtual mailboxes by one of three methods:

    58 

    59   +o  IP-based virtual server access (invisible to the POP3 user)

    60 

    61   +o  username-based access (username-virtualuser)

    62 

    63   +o  hostname-based access (virtualuser@virtual.host or

    64      virtualuser:virtual.host)

    65 

    66 

    67   You should use it if you prefer to have each domain controlled by a

    68   seperate username, allowing the use of system quotas and better

    69   security

    70 

    71   11..22..  NNeeww vveerrssiioonnss

    72 

    73   The newest version of this can be found on the VMailMgr homepage

    74   <http://www.vmailmgr.org/> in its HTML version as well as in the

    75   source package SGML source, HTML, and text.  Other versions may be

    76   found in different formats at the LDP homepage

    77   <http://www.linuxdoc.org/>.

    78 

    79   11..33..  CCoommmmeennttss

    80 

    81   Comments on this HOWTO should be directed to the VMailMgr mailing

    82   list.  To subscribe, send an email to vmailmgr-subscribe@lists.em.ca

    83   <mailto:vmailmgr-subscribe@lists.em.ca>.

    84 

    85   11..44..  HHiissttoorryy

    86 

    87   This document was started by Bruce Guenter and reworked by Dan

    88   Kuykendall.

    89 

    90   11..55..  CCooppyyrriigghhttss aanndd TTrraaddeemmaarrkkss

    91 

    92   Copyright (c)  Dan Kuykendall.  Permission is granted to copy,

    93   distribute and/or modify this document under the terms of the GNU Free

    94   Documentation License, Version 1.1 or any later version published by

    95   the Free Software Foundation

    96 

    97   A copy of the license is available at GNU Free   Documentation License

    98   <http://www.gnu.org/copyleft/fdl.txt>.

    99 

   100   11..66..  AAcckknnoowwlleeddggeemmeennttss aanndd TThhaannkkss

   101 

   102   Thanks to Bruce Guenter for VMailMgr and the core of this HOWTO.

   103   Thanks to Mike Bell, who always seems to have the answers to my

   104   questions. Finally, thanks to all those on the vmailmgr@lists.em.ca

   105   <mailto:vmailmgr@lists.em.ca> mailing list who have helped me, or

   106   asked the same stuff so many times that I had to write this to stop

   107   the repeat questions.

   108 

   109   22..  IInnssttaallllaattiioonn

   110 

   111   22..11..  GGeett tthhee ffiilleess

   112 

   113   Visit the VMailMgr website  <http://www.vmailmgr.org/> to get the

   114   package.

   115 

   116   If you get the binary RPMS you will need at least the vmailmgr

   117   package.

   118 

   119   22..22..  IInnssttaallll wwiitthh RRPPMMSS

   120 

   121   22..22..11..  CCoommppiilliinngg SSRRCC..RRPPMM''ss

   122 

   123   Simply compile the src.rpm file with the `rpm --rebuild` command.

   124   -Example-

   125 

   126   ______________________________________________________________________

   127     rpm -ivh vmailmgr-0.96.9-1.src.rpm

   128   ______________________________________________________________________

   129 

   130 

   131 

   132 

   133   22..22..22..  IInnssttaalllliinngg RRPPMM''ss

   134 

   135   After compiling the source rpms, the binaries will be located in

   136   `/usr/src/redhat/RPMS/i386/` or something similar.

   137 

   138   Simply run the following command for each package

   139 

   140     rpm -ivh <location>/<package.i386.rpm>

   141 

   142 

   143   -Example-

   144 

   145   ______________________________________________________________________

   146     rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-0.96.9-1.i386.rpm

   147     rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-daemon-0.96.9-1.i386.rpm

   148   ______________________________________________________________________

   149 

   150 

   151 

   152 

   153 

   154   22..33..  IInnssttaallll wwiitthh ssoouurrccee

   155 

   156   If you dont ue RPMS you can install from source.

   157 

   158   Run the following command

   159 

   160     (As non-root user)

   161     tar zxf <package.tar.gz>

   162     cd <newly created dir>

   163     ./configure

   164     make

   165     (As root)

   166     make install

   167 

   168 

   169   -Example-

   170 

   171   ______________________________________________________________________

   172     (As non-root user)

   173     tar zxf vmailmgr-0.96.9.tar.gz

   174     cd vmailmgr-0.96.9

   175     ./configure

   176     make

   177     (As root)

   178     make install

   179   ______________________________________________________________________

   180 

   181 

   182   That should do it.

   183 

   184   33..  SSeettuupp

   185 

   186   In the following setup examples, it is assumed that your binaries are

   187   installed in `/usr/bin`, and configuration is in `/etc/vmailmgr`, as

   188   is the case if you installed from the RPMs.  If you installed from

   189   source, configure puts the binaries into `/usr/local/bin` and the

   190   configuration into `/usr/local/etc/vmailmgr` by default.

   191 

   192   33..11..  SSeettttiinngg UUpp aa VViirrttuuaall DDoommaaiinn

   193 

   194   The following steps are necessary to set up a virtual domain with

   195   vmailmgr (assuming vmailmgr has been compiled and installed). As an

   196   example, we'll set up a virtual user `me@mydomain.org`, with aliases

   197   of `myself@mydomain.org` and `myname@mydomain.org`.

   198 

   199   1. Set up a DNS entry for the domain. This is not covered here, as it

   200      is dependant on far too many other things.  I will mention that to

   201      make IP based virtual domains work a PTR record which matches an

   202      entry in virtualdomains is nessesary, for example, if nslookup

   203      10.56.33.122 returns mail.mydomain.com, `virtualdomains` needs an

   204      entry like `mail.mydomain.com:myuser' For the example, we'll assume

   205      that the mail exchanger for mydomain.org is already set up to point

   206      to your computer.

   207 

   208   2. Set up a base user for the domain. Create a user, with a name of

   209      your choosing.  Since the maildirs for all the users in the virtual

   210      domain will be stored under this user's home directory, make sure

   211      you set the user up in a partition or disk that is appropriate for

   212      such storage. The tools that you should use to accomplish this step

   213      vary greatly between different systems. For our example, I'll add a

   214      user `myuser`.

   215 

   216   3. Configure qmail to recognize the domain. To do this, you need to

   217      modify two of qmail's configuration files in `/var/qmail/control`

   218      `rcpthosts` and `virtualdomains`.

   219 

   220   +o  To `rcpthosts` : add the line `mydomain.org`.

   221 

   222   +o  To `virtualdomains` : add the line `mydomain.org:myuser`.

   223 

   224      If you wish to have mail to `anything.mydomain.org` be delivered in

   225      the same way, add the following

   226 

   227   +o  To `rcpthosts` : add the line `.mydomain.org`.

   228 

   229   +o  To `virtualdomains` : add the line `.mydomain.org:myuser`.

   230 

   231   4. Configure qmail-popup/qmail-pop3d to use `checkvpw` as the password

   232      checker. This step is dependant on how you have installed qmail.

   233 

   234   +o  Replace `checkpassword` in the command you use to invoke qmail-

   235      popup/qmail-pop3d (either in `/etc/inet.conf` or in a `tcpserver`

   236      command) with `checkvpw`.

   237 

   238   +o  And/Or at the prompt type: `echo checkvpw >

   239      /var/qmail/control/checkpassword`

   240 

   241   5. Set up the vmailmgr files:

   242 

   243   +o  Either change user to the user you just created (for example, type

   244      `su - myuser`) or log in (with either telnet or at the console) as

   245      the new user.

   246 

   247   +o  Set up the base vmailmgr files by running `vsetup`.

   248 

   249   +o  Use the included programs to add users and aliases.  For our

   250      example, we would type the following commands:

   251 

   252        vadduser me

   253        vaddalias myself me

   254        vaddalias myname me

   255 

   256 

   257 

   258   After you have completed all these steps, you will need to kill and

   259   restart `qmail-send` to make it read the new `virtualdomains` table.

   260 

   261   If you are using `inetd` to launch `qmail-popup`, `kill -HUP` the

   262   `inetd` process as well.

   263 

   264 

   265   33..22..  UUssiinngg oonnee IIPP aaddddrreessss ffoorr mmuuttiippllee ddoommaaiinnss

   266 

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

   268 

   269 

   270   1. The first way is to log in as `userSEPvirtual.domain.org`, where

   271      `user` is the mailbox name of the virtual user, SEP is one of `@`

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

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

   274      as listed in `/var/qmail/control/virtualdomains'.

   275 

   276   2. The second way is to use the internal form of the mailbox name --

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

   278      `baseuser' is the username of the managing user.

   279 

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

   281 

   282        testdomain.org:testuser

   283 

   284 

   285   User `myuser' exists, and has set up a virtual mailbox with the name

   286   `me'. The `separators' variable in `/etc/vmailmgr/' contains `@:'.

   287   This virtual user could log in as `me@mydomain.com', `me:mydomain.cm',

   288   or `myuser-me'.

   289 

   290 

   291 

   292   33..33..  CCaattcchhiinngg aallll mmiissddiirreecctteedd mmaaiill iinn aa vviirrttuuaall ddoommaaiinn

   293 

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

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

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

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

   298   this deliver to you, simply type:

   299 

   300     vaddalias + me

   301 

   302 

   303 

   304   33..44..  VVMMaaiillMMggrr IIMMAAPP ssuuppppoorrtt

   305 

   306   VMailMgr supports Courier-IMAP, but Courier-IMAP does not come with an

   307   authentication module for VMailMgr.  This means that some minor work

   308   is required for making the two work together.

   309 

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

   311      imap/libexec/authlib/authvmailmgr`.

   312 

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

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

   315      authentication module.

   316 

   317   33..55..  EEnnaabblliinngg eennffoorrcceemmeenntt ooff vviirrttuuaall uusseerr qquuoottaass

   318 

   319   VMailMgr supports per-virtual-user quotas, but not out of the box, as

   320   it is not needed by the majority of users, and requires an extra

   321   program to be run on each delivery.  To configure quota support,

   322   create the file `/etc/vmailmgr/vdeliver-predeliver`, containing the

   323   following:

   324 

   325     #!/bin/sh

   326     /usr/bin/vcheckquota

   327 

   328 

   329   This is executed as a shell script, so you will need to make it exe-

   330   cutable by running the following command:

   331     chmod +x /etc/vmailmgr/vdeliver-predeliver

   332 

   333 

   334 

   335   33..66..  EEnnaabblliinngg pprroocceessssiinngg ooff aauuttoorreessppoonnsseess

   336 

   337   Download and install the qmail-autoresponder package, found at

   338   <http://em.ca/~bruceg/qmail-autoresponder/>.  As with the above

   339   section, create a shell script `/etc/vmailmgr/vdeliver-postdeliver`,

   340   containing the following:

   341 

   342     #!/bin/sh

   343     if test -s $MAILDIR/autoresponse/message.txt

   344     then

   345       qmail-autoresponder $MAILDIR/autoresponse/message.txt $MAILDIR/autoresponse

   346     fi

   347 

   348 

   349 

   350   33..77..  WWeebb--bbaasseedd iinntteerrffaacceess ffoorr vvmmaaiillmmggrr

   351 

   352   There are currently a few working solutions to administrate your

   353   vmailmgr system via a web interface. Only requirement is that the

   354   vmailmgrd daemon is running, and that you have a webserver on your

   355   system.

   356 

   357   1. For Python fans, there is vpyadmin by Bruce Guenter. The files can

   358      be downloaded at  <http://em.ca/~bruceg/vpyadmin/>, and the

   359      development code is online at  <http://bruce-

   360      guenter.dyndns.org/cgi-bin/vpyadmin/> (sample.org / samplevm).

   361 

   362   2. And if you like PHP, you can use oMail-admin by Olivier Mller: it

   363      fully supports all vmailmgr functions, and speaks englich, french,

   364      italian, spanish, german and russian. Project homepage:

   365      <http://omail.omnis.ch>. Online demo:

   366      <http://admin.omnis.ch/omail/> (test.com / test).

   367 

   368   3. And there are also C-based CGI scripts in the cgi directory of the

   369      vmailmgr distribution.

   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