Sendmail-SQL Files

Sendmail SQL README, Version 8.12.5-4

BUILDING SENDMAIL+MYSQL.

If you are reading this file, then you have probably already obtained the
appropriate patch from http://sourceforge.net/projects/sendmail-sql/

In order to build Sendmail with (My)SQL support (more database engines are
planned in future), you will need to do roughly the following:

tar -C <your sendmail root> -zxvf sendmail-<version>.tar.gz
cp sendmail+mysql-<version>.patch <your sendmail root>
cd <your sendmail root>
patch -p1 < sendmail+mysql-<version>.patch

If there are any errors that stop the patch, the you may need to retry with -p0
in your patch incantation.

If the patch fails due to files that do not exist, and the patch cannot add to
them, then delete all of the sendmail source, untar it again, do
"touch <missing file>", and then re-apply the patch.

Once the patch has applied correctly, without error, then you will need to
compile Sendmail as normal, with the "./Build" script (or with "make", for
earlier versions of sendmail?).

Watch out during the compilation for "-DMYSQL_MAP". If you do not see that
during the compilation, you will need to add it into the Makefile manually,
as it should always be there, and yet that definition has escaped from some
versions of the Sendmail SQL patch.

If you do not see "-DMYSQL_MAP", Sendmail will (probably) compile okay, but
you'll get "map class mysql not available" (or similar) when you try and
utilise MySQL maps.

CONFIGURATION.

The main configuration file for Sendmail-SQL is found in /etc/mail/mail.conf,
for versions up to 8.11.2(?), and thereafter /etc/mail/sqlmail.conf.

Its format is thus:

#############################
# MySQL Config for Sendmail #
#############################

MysqlHost               <mysql host>
MysqlUsername           <mysql userame>
MysqlPassword           <mysql password>
MysqlDatabase           <mysql database>
MysqlUserTable          <user table>
MysqlAliasTable         <alias table>
MysqlMapTable           <tables used for maps>
MysqlLHSColumn          <lhs column for the aliases table>
MysqlRHSColumn          <rhs column for the aliases table>

Where the "user" table is equivalent to /etc/passwd under Sendmail-SQL, and
the "alias" table is equivalent to /etc/[mail/]aliases under Sendmail-SQL,
and the LHS and RHS are equivalent to respective sections of the aliases file.

The "MysqlMapTable" defines the default(s?) table(s?) for Sendmail-SQL to try
for a class mapping.

This file should be viewed as a file defining defaults, as most of the options
in this file can be overriden on a per class-definition basis, as below.

SENDMAIL CONFIGURATION

If you are using m4 to configure your sendmail implementation, then you should 
read through all the following to work out what you are going to require, and 
read the m4 configuration section below. If you are not using m4, then you 
should add in the appropriate configuration directives directly into
/etc/sendmail.cf (may be /etc/mail/sendmail.cf or other location).

ALIASES CLASS

The details in the defaults file define how Sendmail-SQL handles the aliases
class.

OTHER CLASSES

The new feature that it is 0.2.3 is that now you can have 
a MySQL class for any kinda marco like the F class.

Ex: Qw -Hlocalhost -Dmail -Tdomain

You can store any kinda marco data in MySQL like in any F class
for exif you have a table like that, it will assign all those values
the the w marco so instead of the sendmail.cw file you can have the
following table:

+--------------------+
| domain             |
+--------------------+
| altavista.com      |
| virtualdomain1.com |
| yahoo.com          |
| mydomain.net       |
+--------------------+

or like that:

+--------------------+
| SpamList           |
+--------------------+
| altavista.com      |
| virtualdomain1.com |
| yahoo.com          |
| mydomain.net       |
+--------------------+
 and the you just use it like F or C classes:

Q{SpamList} -Hlocalhost -Dmail -TSpam

for the Q( MySQL ) class you can only have a simple table
with 1 column.

The passwordand username are taken only from /etc/sendmail_mysql.con
( for now )

The options:

-H -> hostname
-D -> database name
-T -> table name
-U -> MySQL username to access the database.

for the rest please read the prvious READMEs
A full and more comprehencive doc is to come

OTHER MAPS

You can also define maps (which you can use for transforms, whereas you can only
perform lookups on a class), using Sendmail-SQL.

For example, this section of table will map several subdomains of ore.org to
the root domain ore.org:

+----------------+---------+
| lhs            | rhs     |
+----------------+---------+
| a.ore.org      | ore.org |
| b.ore.org      | ore.org |
| c.ore.org      | ore.org |
+----------------+---------+

The following options exist in Sendmail-SQL class definitions (note the extras):

-H -> hostname
-D -> database name
-T -> table name
-U -> MySQL username to access the database.
-L -> LHS column in the table
-R -> RHS column in the table

So, you would use the following configuration line, for example to access the
above table structure for the "virtuser" class:

Kvirtuser mysql -Mvirtuser -Llhs -Rrhs -Dsendmail -Hlocalhost -U<mysql user>

M4 CONFIGURATION.

At this stage, m4 configuration for Sendmail SQL is in its infancy, even more
so than the whole project.

There is no support for Sendmail-SQL mysql-alias configuration via m4, since
there is no support for generating /etc/mail/sqlmail.conf, etc. via m4.

However, if you wish to utilise SQL maps and classes, you can use the following
m4 lines in your /etc/mail/sendmail.mc file, and use the appropriate m4
incantation to generate /etc/sendmail.cf from it:

m4 /etc/mail/sendmail.cw > /etc/sendmail.cf

The following can be adapted to your particular needs, but should generate
mysql maps in your sendmail.cf:

FEATURE(`genericstable',`mysql -Mgenericstable')dnl
FEATURE(`virtusertable',`mysql -Mvirtuser -Llhs -Rrhs -Dsendmail')dnl
FEATURE(`mailertable',`mysql -Mmailertable -Ldomain -Rmapping -Dsendmail')dnl

Sendmail SQL classes are currently not supported at all via m4 configuration.

TESTING/DEBUGGING.

Once you have built your Sendmail SQL binaries, and created your test
configuration file (you didn't overwrite your main sendmail.cf with this yet,
right??), you can test them using "sendmail -bt".

To test a map, use "/map <map name> <address>" in sendmail's test mode:

[root@akasha SOURCES]# sendmail -bt
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
> /map virtuser webmaster@ore.org
map_lookup: virtuser (nospam@ore.org) no match (68)
> [CONTROL+D TO EXIT]

To test the entire routing of a mail, use "3,0 <address>" while in test mode.

ADVICE.

You can configure your primary MX server to run Sendmail-SQL, and your backup
to run the same, using MySQL replication between the two.

However, for various reasons, if your connectivity isn't very, very good indeed,
and your servers absolutely rock solid, replication can freeze and die, and
leave your servers out of sync horribly.

Also, if MySQL dies on either server, you are in the same situation, so it is
probably worth considering taking a dump of your MySQL databases into flat
files on a regular basis, and also keeping the original definitions of your
file classes in your sendmail.cf.

Bear in mind that for any one class/map, you can have multiple different 
definitions, which can both be used. Although the one you define first is
(probably) the one which will take precedence.

CHANGES

0.2.3b Doc file submitted to Sourceforge by Paul Khavine, 24/07/1999.

8.12.5 Doc file updates, Kev Green, 22/10/2002.
   - Added information on m4 configuration, building the patch, debugging,
     maps, and general advice section.