Apply 80_fix_string_search.patch
[mspang/vmailman.git] / FAQ
1 Mailman - The GNU Mailing List Management System
2 Copyright (C) 1998-2005 by the Free Software Foundation, Inc.
3 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
4
5 Note: We're migrating the FAQ to an on-line interactive system called
6       "FAQ Wizard".  To see the Mailman FAQ Wizard in action, go to
7       http://www.python.org/cgi-bin/faqw-mm.py
8
9 FREQUENTLY ASKED QUESTIONS
10
11 Q. How do you spell this program?
12
13 A. You spell it "Mailman", with a leading capital "M" and a lowercase
14    second "m".  It is incorrect to spell it "MailMan" (i.e. you should
15    not use StudlyCaps).
16
17 Q. I'm getting really terrible performance for outgoing messages.  It
18    seems that if the MTA has trouble resolving DNS for any recipients,
19    qrunner just gets really slow clearing the queue.  Any ideas?
20
21 A. What's likely happening is that your MTA is doing DNS resolution on
22    recipients for messages delivered locally (i.e. from Mailman to
23    your MTA via SMTPDirect.py).  This is a Bad Thing.  You need to
24    turn off synchronous DNS resolution for messages originating from
25    the local host.
26
27    In Exim, the value to edit is receiver_verify_hosts.  See
28    README.EXIM for details.  Other MTAs have (of course) different
29    parameters and defaults that control this.  First check the README
30    file for your MTA and then consult your MTA's own documentation.
31
32 Q. My list members are complaining about Mailman's List-* headers!
33    What can I do about this?
34
35 A. These headers are described in RFC 2369 and are added by Mailman
36    for the long-term benefit of end-users.  While discouraged, the
37    list admin can disable these via the General Options page.  See
38    also README.USERAGENT for more information.
39
40 Q. Can I put the user's address in the footer that Mailman adds to
41    each message?
42
43 A. Yes, in Mailman 2.1.  The site admin needs to enable personalization by
44    setting the following variable in the mm_cfg.py file:
45
46     OWNERS_CAN_ENABLE_PERSONALIZATION = Yes
47
48    Once this is done, list admins can enable personalization for regular
49    delivery members (digest deliveries can't be personalized currently).  A
50    personalized list can include the user's address in the footer.
51
52 Q. My users hate HTML in their email and for security reasons, I want
53    to strip out all MIME attachments.  How can I do this?
54
55 A. Mailman 2.1 has this feature built-in.  See the Content Filtering
56    Options page in the admin interface.
57
58 Q. What if I get "document contains no data" from the web server, or
59    mail isn't getting delivered, or I see "Premature end of script
60    headers" or "Mailman CGI error!!!"
61
62 A. The most likely cause of this is that the GID that is compiled into
63    the C wrappers does not match the GID that your Web server invokes
64    CGI scripts with.  Note that a similar error could occur if your
65    mail system invokes filter programs under a GID that does not match
66    the one compiled into the C mail wrapper.
67
68    To fix this you will need to re-configure Mailman using the
69    --with-cgi-gid and --with-mail-gid options.  See the INSTALL file
70    for details.
71
72    These errors are logged to syslog and they do not show up in the
73    Mailman log files.  Problems with the CGI wrapper do get reported
74    in the web browser though (unless STEALTH_MODE is enabled), and
75    include the expected GID, so that should help a lot.
76
77    You may want to have syslog running and configured to log the
78    mail.error log class somewhere; on Solaris systems, the line
79
80        mail.debug                /var/log/syslog
81
82    causes the messages to go to them in /var/log/syslog, for example.
83    (The distributed syslog.conf forwards the message to the loghost,
84    when present.  See the syslog man page for more details.)
85
86    If your system is set like this, and you get a failure trying to
87    visit the mailman/listinfo web page, and it's due to a UID or GID
88    mismatch, then you should get an entry at the end of
89    /var/log/syslog identifying the expected and received values.
90
91    If you are not getting any log messages in syslog, or in Mailman's
92    own log files, but messages are still not being delivered, then it
93    is likely that qrunner is not running (qrunner is the process that
94    handles all mail in the system).  In Mailman 2.0, qrunner was
95    invoked from cron so make sure your crontab entries for the
96    `mailman' user have been installed.  In Mailman 2.1, qrunner is
97    started with the bin/mailmanctl script, which can be invoked
98    manually, or merged with your OS's init scripts.
99
100 Q. What should I check periodically?
101
102 A. Many of the scripts have their standard error logged to
103    $prefix/logs/error, and some of the modules write caught errors
104    there, as well, so you should check there at least occasionally to
105    look for bugs in the code and problems in your setup.
106
107    You may want to periodically check the other log files in the logs/
108    directory, perhaps occasionally rotating them with something like
109    the Linux logrotate script.
110
111 Q. I can't access the public archives.  Why?
112
113 A. If you are using Apache, you must make sure that FollowSymLinks is
114    enabled for the path to the public archives.  Note that the actual
115    archives always reside in the private tree, and only when archives
116    are public, is the symlink followed. See this archive message for
117    more details:
118
119    http://mail.python.org/pipermail/mailman-users/1998-November/000150.html
120
121 Q. Still having problems?  Running QMail?
122
123 A. Make sure that you are using "preline" before calling the "mailman"
124    wrapper:
125
126        |preline /home/mailman/mail/mailman post listname
127
128    "preline" adds a Unix-style "From " header which the archiver requires.
129    You can fix the archive mbox files by adding:
130
131        From somebody Mon Oct  9 12:27:34 MDT 2000
132
133    before every message and re-running the archive command
134    "bin/arch listname".  The archives should now exist.  See README.QMAIL
135    for more information.
136
137 Q. Still having problems?  Running on GNU/Linux?
138
139 A. See the README.LINUX file.
140
141 Q. I want to get rid of some messages in my archive.  How do I do
142    this?
143
144 A. David Rocher posts the following recipe:
145
146    * remove $prefix/archives/private/<listname>
147    * edit $prefix/archives/private/<listname>.mbox/<listname>.mbox [optional]
148    * run $prefix/bin/arch <listname>
149
150 Q. How secure are the authentication mechanisms used in Mailman's web
151    interface?
152
153 A. If your Mailman installation run on an SSL-enabled web server
154    (i.e. you access the Mailman web pages with "https://..." URLs),
155    you should be as safe as SSL itself is.
156
157    However, most Mailman installation run under standard,
158    encryption-unaware servers.  There's nothing wrong with that for
159    most applications, but a sufficiently determined cracker *could*
160    get unauthorized access by:
161
162    * Packet sniffing: The password used to do the initial
163      authentication for any non-public Mailman page is sent as clear
164      text over the net.  If you consider this to be a big problem, you
165      really should use an SSL-enabled server.
166
167    * Stealing a valid cookie: After successful password
168      authentication, Mailman sends a "cookie" back to the user's
169      browser.  This cookie will be used for "automatic" authentication
170      when browsing further within the list's protected pages.  Mailman
171      employs "session cookies" which are set until you quit your
172      browser or explicitly log out.
173
174      Gaining access to the user's cookie (e.g. by being able to read
175      the user's browser cookie database, or by means of packet
176      sniffing, or maybe even by some broken browser offering all it's
177      cookies to any and all sites the user accesses), and at the same
178      time being able to fulfill the other criteria for using the
179      cookie could result in unauthorized access.
180
181      Note that this problem is more easily exploited when users browse
182      the web via proxies -- in that case, the cookie would be valid
183      for any connections made through that proxy, and not just for
184      connections made from the particular machine the user happens to
185      be accessing the proxy from.
186
187    * Getting access to the user's terminal: This is really just
188      another kind of cookie stealing.  The short cookie expiration
189      time is supposed to help defeat this problem.  It can be
190      considered the price to pay for the convenience of not having to
191      type the password in every time.
192
193 Q. I want to backup my lists.  What do I need to save?
194
195 A. See this FAQ wizard entry:
196    http://www.python.org/cgi-bin/faqw-mm.py?req=show&file=faq04.006.htp
197
198 Q. How do I rename a list?
199
200 A. Renaming a list is currently a bit of a pain to do completely
201    correctly, especially if you want to make sure that the old list
202    contacts are automatically forwarded to the new list.  This ought
203    to be easier. :(
204
205    The biggest problem you have is how to stop mail and web traffic to
206    your list during the transition, and what to do about any mail
207    undelivered to the old list after the move.  I don't think there
208    are any foolproof steps, but here's how you can reduce the risk:
209
210    - Temporarily disable qrunner.  To do this, you need to edit the
211      user `mailman's crontab entry.  Execute the following command,
212      commenting out the qrunner line when you're dropped into your
213      editor.  Then save the file and quit the editor.
214
215      % crontab -u mailman -e
216
217    - Turn off your mail server.  This is mostly harmless since remote
218      MTAs will just keep retrying until you turn it back on, and it's
219      not going to be off for very long.
220
221    - Next turn off your web server if possible.  This of course means
222      your entire site will be off-line while you make the switch and
223      this may not be acceptable to you.  The next best suggestion is
224      to set up your permanent redirects now for the list you're
225      moving.  This means that anybody looking for the list under its
226      old name will be redirected to the new name, but they'll get
227      errors until you've completed the move.
228
229      Let's say the old name is "oldname" and the new name is
230      "newname".  Here are some Apache directives that will do the
231      trick, though YMMV:
232
233      RedirectMatch permanent /mailman/(.*)/oldname(.*) http://www.dom.ain/mailman/$1/newname$2
234      RedirectMatch permanent /pipermail/oldname(.*)    http://www.dom.ain/pipermail/newname$1
235
236      Add these to your httpd.conf file and restart Apache.
237
238    - Now cd to the directory where you've installed Mailman.  Let's
239      say it's /usr/local/mailman:
240
241      % cd /usr/local/mailman
242
243      and cd to the `lists' subdirectory:
244
245      % cd lists
246
247      You should now see the directory `oldname'.  Move this to
248      `newname':
249
250      % mv oldname newname
251
252    - Now cd to the private archives directory:
253
254      % cd ../archives/private
255
256      You will need to move the oldname's .mbox directory, and the
257      .mbox file within that directory.  Don't worry about the public
258      archives; the next few steps will take care of them without
259      requiring you to fiddle around in the file system:
260
261      % mv oldname.mbox newname.mbox
262      % mv newname.mbox/oldname.mbox newname.mbox/newname.mbox
263
264    - You now need to run the `bin/move_list' script to update some of
265      the internal archiver paths.  IMPORTANT: Skip this step if you
266      are using Mailman 2.1!
267
268      % cd ../..
269      % bin/move_list newname
270
271    - You should now regenerate the public archives:
272
273      % bin/arch newname
274
275    - You'll likely need to change some of your list's configuration
276      options, especially if you want to accept postings addressed to
277      the old list on the new list.  Visit the admin interface for your
278      new list:
279
280      o Go to the General options
281
282      o Change the "real_name" option to reflect the new list's name,
283        e.g. "Newname"
284
285      o Change the subject prefix to reflect the new list's name,
286        e.g. "[Newname] " (yes, that's a trailing space character).
287
288      o Optionally, update other configuration fields like info,
289        description, or welcome_msg.  YMMV.
290
291      o Save your changes
292
293      o Go to the Privacy options
294
295      o Add the old list's address to acceptable_aliases.
296        E.g. "oldname@dom.ain".  This way, (after the /etc/aliases
297        changes described below) messages posted to the old list will
298        not be held by the new list for "implicit destination"
299        approval.
300
301      o Save your changes
302
303    - Now you want to update your /etc/aliases file to include the
304      aliases for the new list, and forwards for the old list to the
305      new list.  Note that these instructions are for Sendmail style
306      alias files, adjust to the specifics of how your MTA is set up.
307
308      o Find the lines defining the aliases for your old list's name
309
310      o Copy and paste them just below the originals.
311
312      o Change all the references of "oldname" to "newname" in the
313        pasted stanza.
314
315      o Now change the targets of the original aliases to forward to
316        the new aliases.  When you're done, you will end up with
317        /etc/aliases entries like the following (YMMV):
318
319        XXX This needs updating for MM2.1!
320
321        # Forward the oldname list to the newname list
322        oldname:         newname@dom.ain
323        oldname-request: newname-request@dom.ain
324        oldname-admin:   newname-admin@dom.ain
325        oldname-owner:   newname-owner@dom.ain
326
327        newname:         "|/usr/local/mailman/mail/mailman post newname"
328        newname-admin:   "|/usr/local/mailman/mail/mailman mailowner newname"
329        newname-request: "|/usr/local/mailman/mail/mailman mailcmd newname"
330        newname-owner:   newname-admin
331
332      o Run newaliases
333
334    - Before you restart everything, you want to make one last check.
335      You're looking for files in the qfiles/ directory that may have
336      been addressed to the old list but weren't delivered before you
337      renamed the list.  Do something like the following:
338
339      % cd /usr/local/mailman/qfiles
340      % grep oldname *.msg
341
342      If you get no hits, skip to the next step, you've got nothing to
343      worry about.
344
345      If you did get hits, then things get complicated.  I warn you
346      that the rest of this step is untested. :(
347
348      For each of the .msg files that were destined for the old list,
349      you need to change the corresponding .db file.  Unfortunately
350      there's no easy way to do this.  Anyway...
351
352      Save the following Python code in a file called 'hackdb.py':
353
354      -------------------------hackdb.py
355      import sys
356      import marshal
357      fp = open(sys.argv[1])
358      d = marshal.load(fp)
359      fp.close()
360      d['listname'] = sys.argv[2]
361      fp = open(sys.argv[1], 'w')
362      marshal.dump(d, fp)
363      fp.close()
364      -------------------------
365
366      And then for each file that matched your grep above, do the
367      following:
368
369      % python hackdb.py reallylonghexfilenamematch1.db newname
370
371    - It's now safe to turn your MTA back on.
372
373    - Turn your qrunner back on by running
374
375      % crontab -u mailman -e
376
377      again and this time uncommenting the qrunner line.  Save the file
378      and quit your editor.
379
380    - Rejoice, you're done.  Send $100,000 in shiny new pennies to the
381      Mailman cabal as your downpayment toward making this easier for
382      the next list you have to rename. :)
383
384
385 \f
386 Local Variables:
387 mode: text
388 indent-tabs-mode: nil
389 End: