Added note from Kevin McNamee.

Renamed from mm-handler.readme.

1 files changed, 215 insertions, 0 deletions

diff --git a/contrib/README.mm-handler b/contrib/README.mm-handler
new file mode 100644
index 00000000..1dee515f
--- /dev/null
+++ b/contrib/README.mm-handler
@@ -0,0 +1,215 @@
+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 $