Apply 79_archiver_slash.patch
[mspang/vmailman.git] / contrib / README.mm-handler
1 Contributed by David Champion <dgc@uchicago.edu>
2 See also ../README.SENDMAIL
3
4 What?
5 -----
6 Mm-handler is a mail delivery agent (MDA) -- a "mailer", in Sendmail
7 lingo. Its function is to assume authority for messages destined to
8 Mailman lists, so that they're off sendmail's hands, and you (the site
9 administrator) don't need to maintain databases of aliases and such. It
10 takes a small bit of work to set up, but once that's done, you'll never
11 need to mess with aliases for Mailman's sake again.
12
13 When?
14 -----
15 The only further catch is that mm-handler is only really useful when
16 it mostly "owns" its mail domain (the hostname part after an e-mail
17 address's "@" symbol) -- when you can dedicate the mail domain to
18 Mailman. If you have a limited set of exceptions -- a few users, for
19 example -- you can still use it, but for sites with a dynamic or even
20 mix of users (or forwarders) and lists, it might not gain you much.
21
22 How do you know whether mm-handler is appropriate for you? Let's look
23 at some examples. If you're running lists off your primary DNS domain
24 name, you probably have a mix of lists and users in your namespace. Take
25 python.org, for example: it hosts Mailman lists, and it hosts users'
26 personal accounts. There aren't a whole bunch of either, but the ratio
27 is probably fairly near 1:1. Mm-handler is not very useful here, because
28 there's no simple way to separate user addresses from list addresses --
29 not to mention that mm-handler is written in perl, so that's just bad
30 form.
31
32 This begs two different, complementary situations. A hypothetical
33 domain, incidents.int, is used mostly for mailing lists. It's a
34 front-end site, and not a general user mail service. There might be
35 a couple of user addresses -- system administrators and such -- but
36 these are few in number and easily adjusted manually by the site
37 administrator. The 250 mailing lists at the site are much more dynamic,
38 and a much bigger pain to keep track of by editing an alias file. This
39 site can easily benefit from mm-handler.
40
41 Inversely, mail.aero, another hypothetical domain, provides POP mail
42 service to employees of the aerospace industry. Its addresses are
43 almost entirely users, although it maintains a few mailing lists for
44 convenience. This site has nothing to gain from mm-handler. It's much
45 easier to maintain an alias file of 10 lists than to dedicate the domain
46 to Mailman, and put all 10,000 aerospace workers in a user table.
47
48 Those are the trickier cases. The case where mm-handler really works
49 best is when you can dedicate a single hostname under your DNS domain
50 to mailing lists, and host no user accounts there. At the University of
51 Chicago, we do this with listhost.uchicago.edu. SourceForge does this,
52 too, although I don't believe they use Sendmail.
53
54 If your site is like that, you should read on.
55
56 How?
57 ----
58 Set-up isn't all that complicated. I've included a file here called
59 "mailman.mc". This is the m4 file that I use on my list server, and you
60 can likely use it with few changes at your site. It's well-annotated;
61 the rationale for each parameter (or set of parameters) is provided in
62 m4 (ahem) comments.
63
64 So, the simple steps are as follows:
65
66 1. Copy mailman.mc, and make any changes you need at your site. You
67    DEFINITELY need some changes. There are hostnames in there that you
68    need to adjust, and chances are that you'll need to change some other
69    parameters (like the host OS), too. [1]
70
71 2. Install mm-handler. Because my server's sendmail-related files live
72    in /etc/mail, I keep mm-handler there, too. YMMV.
73
74 3. Edit mm-handler, and make any changes you need at your site. You
75    probably want to change $MMWRAPPER and $MMLISTDIR at line 14, and you
76    *might* want to take a look at the helpful boilerplate text beginning
77    at line 64. (This text is sent whenever someone tries to send mail to
78    a nonexistent list address on your mail domain.)
79
80 4. You should set up a virtusertable. (See mailman.mc for an
81    explanation.) There's an example of a good, minimal virtusertable
82    in this distribution. The virtusertable begins as a text file named
83    "virtusertable", stored in the same directory as all the other
84    Sendmail files, but it's converted to a map file for Sendmail's use.
85    Install the virtusertable, and (re)make the map file. [2]
86
87 5. You absolutely must have a mailertable, or all of this goes nowhere.
88    Like virtusertable, the mailertable is a map that begins as text and
89    gets converted. It's named "mailertable", and it's probably pretty
90    simple. Mine looks like this:
91
92         listtest.uchicago.edu   mailman:listtest.uchicago.edu
93
94    This says: assign all incoming mail (that was not intercepted by the
95    virtusertable) and that is in the listtest.uchicago.edu domain to the
96    "mailman" mailer, and tell the "mailman" mailer that the hostname
97    we're using is "listtest.uchicago.edu". You can support multiple
98    virtual hosts using mm-handler just by placing corresponding lines in
99    mailertable.
100
101    Be sure to make this map, too!
102
103 6. The mailer definition (see the end of mailman.mc, or your own .mc
104    file) for mm-handler sets the user/group that mm-handler will run
105    under. (I use mailman:other.) Be sure that mm-handler is executable
106    by this user or group. You almost certainly need the user to be the
107    same as the Mailman user, and this user is almost always called
108    "mailman", so you probably shouldn't change the defaults.
109
110 7. Generate your new sendmail.cf file. See the sendmail documentation if
111    you're not familiar with this procedure. [1]
112
113 8. Stop sendmail on your list server, if you haven't already. Install
114    the new sendmail.cf file wherever your sendmail.cf file belongs.
115    (This depends on how sendmail was compiled, but most systems support
116    using /etc/sendmail.cf.)
117
118 9. Cross your fingers and restart sendmail.
119
120 A. Barry warns that Mailman now needs you to modify your
121    Mailman/mm_cfg.py file, adding this line:
122
123         MTA = None
124
125    This tells Mailman that it doesn't need to do anything special when
126    it creates or deletes mailing lists through the web.  For more
127    information, take a look at the comments for this variable in your
128    Defaults.py file (but never edit this file -- always edit mm_cfg.py
129    instead!).
130
131 That's it! With any luck, you're fully functional.
132
133 --
134 [1] The .mc file is the standard, supported way of configuring sendmail.
135     I'm not going to get into this here, and I'm not going to tell
136     you how to write raw sendmail.cf stuff, because if you need to do
137     it this way then you need something more comprehensive than I can
138     provide. If you need help with the .mc -> .cf process, I recommend
139     these links:
140
141         http://www.sendmail.org/~ca/email/setup1.html
142         http://www.sendmail.org/~ca/email/doc8.9/README.cf.html
143         http://www.hserus.net/sendmail.html
144
145 [2] This is often done with something like "makemap hash
146     /etc/virtusertable </etc/virtusertable", but it could be different
147     on your server. Consult the sendmail documentation if you do not
148     know.
149
150
151 The following note is provided by Kevin McNamee <kevin.mcnamee(at)symsoft.se>
152 regarding solving a problem with mail to list addresses being rejected for
153 "user unknown".  Reference:
154 <http://mail.python.org/pipermail/mailman-users/2006-February/049235.html>
155
156
157 "User unknown" analysis
158 =======================
159 If the "user unknown" problem arises, then sendmail is not 
160 recognising your domain as a "mailman" domain. 
161 The problem could be that your mailman.mydomain.com is defined as a 
162 CNAME not a real DNS record. 
163
164 A hint from a tutorial about Masquerading:
165 http://www.feep.net/sendmail/tutorial/config/masquerading.html
166 "This address must be an address record in DNS, not simply
167 a CNAME, or the remote end will canonicalize the address back 
168 to the original name."
169
170 First confirm the problem
171 # sendmail -bv testlist<at>mailman.mydomain.com
172 testlist<at>mailman.mydomain.com... User unknown
173
174 Then confirm that mailertable is operational
175 # sendmail -d -bv jbloggs<at>hotmail.com | egrep "map_rewrite|mailertable"
176 map_lookup(host, hotmail.com) => host_map_lookup(hotmail.com) =>
177 map_rewrite(hotmail.com), av =
178 map_rewrite => hotmail.com.
179 map_lookup(mailertable, hotmail.com) => NOT FOUND (0)
180 map_lookup(mailertable, .com) => NOT FOUND (0)
181 map_lookup(mailertable, .) => NOT FOUND (0)
182
183 Then confirm that your domain (CNAME) is being canonicalised:
184 # sendmail -d -bv testlist<at>mailman.mydomain.com | egrep
185 "map_rewrite|mailertable"
186 map_lookup(host, mailman.mydomain.com) =>
187 host_map_lookup(mailman.mydomain.com) => map_rewrite(aserver.mydomain.com),
188 av =
189 map_rewrite => aserver.mydomain.com.
190
191 Sendmail has done an nslookup and found the real name of your domain which
192 would not match your settings in mailertable (if sendmail got that far).
193
194 If you remove the CNAME and create a real subdomain, then the problem will
195 go away:
196 # sendmail -bv testlist<at>mailman.mydomain.com
197 testlist<at>mailman.mydomain.com... deliverable: mailer mailman, host
198 testlist<at>mailman.mydomain.com, user testlist
199
200 You will still need to create a new CNAME in your sub-domain for Apache to
201 work.
202
203 Conclusion:
204 It is very important to make clear in the Mailman installation instructions
205 that a REAL subdomain is needed. Those of us not familiar with DNS (or
206 sendmail for that matter) can succeed in getting the whole Mailman
207 installation working including the (Apache) web-interface and subscription
208 management using just a CNAME and then wonder why we cannot send mail to our
209 list. Hope this is of use.
210
211 Ed. note: the above "conclusion" applies in this mm-handler case, but it
212 normally does not apply if list mail is delivered via aliases.
213
214 --
215 $Id: README.mm-handler 7782 2006-02-20 03:39:53Z msapiro $