Contributed by David Champion <dgc@uchicago.edu>
See also ../README.SENDMAIL

What?
-----
Mm-handler is a mail delivery agent (MDA) -- a "mailer", in Sendmail
lingo. Its function is to assume authority for messages destined to
Mailman lists, so that they're off sendmail's hands, and you (the site
administrator) don't need to maintain databases of aliases and such. It
takes a small bit of work to set up, but once that's done, you'll never
need to mess with aliases for Mailman's sake again.

When?
-----
The only further catch is that mm-handler is only really useful when
it mostly "owns" its mail domain (the hostname part after an e-mail
address's "@" symbol) -- when you can dedicate the mail domain to
Mailman. If you have a limited set of exceptions -- a few users, for
example -- you can still use it, but for sites with a dynamic or even
mix of users (or forwarders) and lists, it might not gain you much.

How do you know whether mm-handler is appropriate for you? Let's look
at some examples. If you're running lists off your primary DNS domain
name, you probably have a mix of lists and users in your namespace. Take
python.org, for example: it hosts Mailman lists, and it hosts users'
personal accounts. There aren't a whole bunch of either, but the ratio
is probably fairly near 1:1. Mm-handler is not very useful here, because
there's no simple way to separate user addresses from list addresses --
not to mention that mm-handler is written in perl, so that's just bad
form.

This begs two different, complementary situations. A hypothetical
domain, incidents.int, is used mostly for mailing lists. It's a
front-end site, and not a general user mail service. There might be
a couple of user addresses -- system administrators and such -- but
these are few in number and easily adjusted manually by the site
administrator. The 250 mailing lists at the site are much more dynamic,
and a much bigger pain to keep track of by editing an alias file. This
site can easily benefit from mm-handler.

Inversely, mail.aero, another hypothetical domain, provides POP mail
service to employees of the aerospace industry. Its addresses are
almost entirely users, although it maintains a few mailing lists for
convenience. This site has nothing to gain from mm-handler. It's much
easier to maintain an alias file of 10 lists than to dedicate the domain
to Mailman, and put all 10,000 aerospace workers in a user table.

Those are the trickier cases. The case where mm-handler really works
best is when you can dedicate a single hostname under your DNS domain
to mailing lists, and host no user accounts there. At the University of
Chicago, we do this with listhost.uchicago.edu. SourceForge does this,
too, although I don't believe they use Sendmail.

If your site is like that, you should read on.

How?
----
Set-up isn't all that complicated. I've included a file here called
"mailman.mc". This is the m4 file that I use on my list server, and you
can likely use it with few changes at your site. It's well-annotated;
the rationale for each parameter (or set of parameters) is provided in
m4 (ahem) comments.

So, the simple steps are as follows:

1. Copy mailman.mc, and make any changes you need at your site. You
   DEFINITELY need some changes. There are hostnames in there that you
   need to adjust, and chances are that you'll need to change some other
   parameters (like the host OS), too. [1]

2. Install mm-handler. Because my server's sendmail-related files live
   in /etc/mail, I keep mm-handler there, too. YMMV.

3. Edit mm-handler, and make any changes you need at your site. You
   probably want to change $MMWRAPPER and $MMLISTDIR at line 14, and you
   *might* want to take a look at the helpful boilerplate text beginning
   at line 64. (This text is sent whenever someone tries to send mail to
   a nonexistent list address on your mail domain.)

4. You should set up a virtusertable. (See mailman.mc for an
   explanation.) There's an example of a good, minimal virtusertable
   in this distribution. The virtusertable begins as a text file named
   "virtusertable", stored in the same directory as all the other
   Sendmail files, but it's converted to a map file for Sendmail's use.
   Install the virtusertable, and (re)make the map file. [2]

5. You absolutely must have a mailertable, or all of this goes nowhere.
   Like virtusertable, the mailertable is a map that begins as text and
   gets converted. It's named "mailertable", and it's probably pretty
   simple. Mine looks like this:

	listtest.uchicago.edu	mailman:listtest.uchicago.edu

   This says: assign all incoming mail (that was not intercepted by the
   virtusertable) and that is in the listtest.uchicago.edu domain to the
   "mailman" mailer, and tell the "mailman" mailer that the hostname
   we're using is "listtest.uchicago.edu". You can support multiple
   virtual hosts using mm-handler just by placing corresponding lines in
   mailertable.

   Be sure to make this map, too!

6. The mailer definition (see the end of mailman.mc, or your own .mc
   file) for mm-handler sets the user/group that mm-handler will run
   under. (I use mailman:other.) Be sure that mm-handler is executable
   by this user or group. You almost certainly need the user to be the
   same as the Mailman user, and this user is almost always called
   "mailman", so you probably shouldn't change the defaults.

7. Generate your new sendmail.cf file. See the sendmail documentation if
   you're not familiar with this procedure. [1]

8. Stop sendmail on your list server, if you haven't already. Install
   the new sendmail.cf file wherever your sendmail.cf file belongs.
   (This depends on how sendmail was compiled, but most systems support
   using /etc/sendmail.cf.)

9. Cross your fingers and restart sendmail.

A. Barry warns that Mailman now needs you to modify your
   Mailman/mm_cfg.py file, adding this line:

	MTA = None

   This tells Mailman that it doesn't need to do anything special when
   it creates or deletes mailing lists through the web.  For more
   information, take a look at the comments for this variable in your
   Defaults.py file (but never edit this file -- always edit mm_cfg.py
   instead!).

That's it! With any luck, you're fully functional.

--
[1] The .mc file is the standard, supported way of configuring sendmail.
    I'm not going to get into this here, and I'm not going to tell
    you how to write raw sendmail.cf stuff, because if you need to do
    it this way then you need something more comprehensive than I can
    provide. If you need help with the .mc -> .cf process, I recommend
    these links:

	http://www.sendmail.org/~ca/email/setup1.html
	http://www.sendmail.org/~ca/email/doc8.9/README.cf.html
	http://www.hserus.net/sendmail.html

[2] This is often done with something like "makemap hash
    /etc/virtusertable </etc/virtusertable", but it could be different
    on your server. Consult the sendmail documentation if you do not
    know.


The following note is provided by Kevin McNamee <kevin.mcnamee(at)symsoft.se>
regarding solving a problem with mail to list addresses being rejected for
"user unknown".  Reference:
<http://mail.python.org/pipermail/mailman-users/2006-February/049235.html>


"User unknown" analysis
=======================
If the "user unknown" problem arises, then sendmail is not 
recognising your domain as a "mailman" domain. 
The problem could be that your mailman.mydomain.com is defined as a 
CNAME not a real DNS record. 

A hint from a tutorial about Masquerading:
http://www.feep.net/sendmail/tutorial/config/masquerading.html
"This address must be an address record in DNS, not simply
a CNAME, or the remote end will canonicalize the address back 
to the original name."

First confirm the problem
# sendmail -bv testlist<at>mailman.mydomain.com
testlist<at>mailman.mydomain.com... User unknown

Then confirm that mailertable is operational
# sendmail -d -bv jbloggs<at>hotmail.com | egrep "map_rewrite|mailertable"
map_lookup(host, hotmail.com) => host_map_lookup(hotmail.com) =>
map_rewrite(hotmail.com), av =
map_rewrite => hotmail.com.
map_lookup(mailertable, hotmail.com) => NOT FOUND (0)
map_lookup(mailertable, .com) => NOT FOUND (0)
map_lookup(mailertable, .) => NOT FOUND (0)

Then confirm that your domain (CNAME) is being canonicalised:
# sendmail -d -bv testlist<at>mailman.mydomain.com | egrep
"map_rewrite|mailertable"
map_lookup(host, mailman.mydomain.com) =>
host_map_lookup(mailman.mydomain.com) => map_rewrite(aserver.mydomain.com),
av =
map_rewrite => aserver.mydomain.com.

Sendmail has done an nslookup and found the real name of your domain which
would not match your settings in mailertable (if sendmail got that far).

If you remove the CNAME and create a real subdomain, then the problem will
go away:
# sendmail -bv testlist<at>mailman.mydomain.com
testlist<at>mailman.mydomain.com... deliverable: mailer mailman, host
testlist<at>mailman.mydomain.com, user testlist

You will still need to create a new CNAME in your sub-domain for Apache to
work.

Conclusion:
It is very important to make clear in the Mailman installation instructions
that a REAL subdomain is needed. Those of us not familiar with DNS (or
sendmail for that matter) can succeed in getting the whole Mailman
installation working including the (Apache) web-interface and subscription
management using just a CNAME and then wonder why we cannot send mail to our
list. Hope this is of use.

Ed. note: the above "conclusion" applies in this mm-handler case, but it
normally does not apply if list mail is delivered via aliases.

--
$Id: README.mm-handler 7782 2006-02-20 03:39:53Z msapiro $
