/*
 * $Id: index.html,v 1.1 2004/12/18 13:06:35 nsfung Exp nsfung $
 * SM-MBDB-PGS, PostgreSQL enabled Sendmail MailboxDatabase
 */

Author
------
Author: Nelson Fung 

Purpose
-------
This patch containts modified Sendmail files.  It enables Sendmail
MailboxDatabase to talk with PostgreSQL.

Introduction
------------
There was a need to build something which allows mail delivery to
virtual and real users. 

   "Virtual" Users 
   ---------------
   These are users without /etc/passwd entries.  They are present in
   PostgreSQL (or your favourite RDBMS) tables only.  Moreover, mail
   spool for virtual users is located under one real uid and
   gid.(i.e. in /etc/passwd)

   "Real" Users
   ------------
   These are users with entries in /etc/passwd.

NOTE: Although the idea presented here should work with other RDBMS,
      since I chose to work with PostgreSQL, I'm referring to
      PostgreSQL in from here onwards when I say "database" etc.
      However, you can subsitute words like "PostgreSQL", "database",
      "db" etc, with the name of your favourite RDBMS.

The Scheme of Things
--------------------
Let's say we host mail for one virtual domain 'virtual.ltd' with a few
hundred users.  Mail bound for 'virtual.ltd' is delivered under this
directory:

   /home/virtmail/virtual.ltd

So, the mailbox 'user1@virtual.ltd' is found at:

   /home/virtmail/virtual.ltd/user1/inbox

For this exercise, we have created a 'real' user called 'virtmail' in
/etc/passwd.  

Mailboxes for real users on our box are located in their respective
home directories, e.g.:

   /home/user1/inbox

NOTE: "vpopmail"  already does
      something like this.  However, vpopmail works with qmail
       only.  I wanted something with Sendmail
      .  If you want something with qmail,
      please see the abovementioned "vpopmail."


Sendmail meets PostgreSQL (PG)
------------------------------
By default, Sendmail looks up users in /etc/passwd.  For mail delivery
to virtual users, Sendmail must be able to talk to PG and find virtual
users.

Sendmail has recently (since v8.12.x?) started to provide an API for
local mailbox delivery lookup via [MailboxDatabase] (sm_mbdb).  So, it
wasn't too difficult to get Sendmail to work with PostgreSQL.

It turned out that only this files needed changes:

   /sendmail-8.13.2/libsm/mbdb.c

The advantage of getting sm_mbdb to talk to PostgreSQL is that
Sendmail will be able to accept/reject mail for virtual users right
away, without having to 1) accept it  then 2) pipe it through to some
program and 3) leave it to the program to accept/reject it.

This is especially useful when there are multiple MX machines to
accept mail for virtual users.  Moreover, since mail.local(8) and
vacation(1) also use sm_mbdb, once this patch is implemented, a local
delivery agent (assuming your system can handle mail.local(8),) and
vacation(8) are ready for virtual users.

Contents
--------
This package containes the following:

   1. cf/cf/sm-mbdb-pg.mc
   Hints to incorporate into for your own .mc file for m4 to build .cf

   2. devtools/Site/sm-mbdb-pg.m4
   Hints to incorporate into your own 
      /sendmail-8.13.2/devtools/Site/site.config.m4

   3. libsm/mbdb.c
   This is the modifed /sendmail-8.13.2/libsm/mbdb.c, what
   this patch is all about.
   
   4. sendmail/version.c
   Small change to reflect that the patched Sendmail is patched!


Pre-requists
------------

   1. A running installation of PostgreSQL, containing your virtual
      users.

   2. Your virutal user table should contain the following columns at
      a minimum:
      
          pw_uid: integer
          pw_gid: integer 
          pw_gecos: character varying(128)
          pw_dir:   character varying(128)  
          pw_shell: character varying(64)

Installation
------------

   01. Download sendmail-8.13.2. Visit http://www.sendmail.org/

   02. cd /path/to/workspace

   03. tar zxvf sendmail.8.3.2.tgz

   04. cd sendmail-8.13.2

   05. tar zxvf /path/to/sm-mbdb-pg-8.13.2.tgz

   06. Inspect /path/to/sendmail-8.13.2/devtools/Site/sm-mbdb-pg.m4 to
       build your own site.config.m4.  Take care to specify where your
       PostgreSQL include/lib paths.

   07. Inspect /path/to/sendmail-8.13.2/libsm/mbdb.c YOU MUST edit a
       few things in the "Editable section"

   08. Inspect /path/to/sendmail-8.13.2/cf/cf/sm-mbdb-pg.mc and create
       your own .mc for building your sendmail.cf

   09. cd /path/to/sendmail-8.13.2
   10. sh ./Build
   11. sh ./Build install

And that's all folks.