diff options
Diffstat (limited to 'contrib/README.mm-handler')
| -rw-r--r-- | contrib/README.mm-handler | 215 |
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 $ |