Mangle differently
[mspang/vmailman.git] / doc / mailman-admin.tex
1 \documentclass{howto}
2
3 \title{GNU Mailman - List Administration Manual}
4
5 % Increment the release number whenever significant changes are made.
6 % The author and/or editor can define 'significant' however they like.
7 \release{1.0}
8
9 % At minimum, give your name and an email address.  You can include a
10 % snail-mail address if you like.
11 \author{Barry A. Warsaw}
12 %\authoraddress{barry@zope.com}
13
14 \date{\today}                   % XXX update before tagging release!
15 \release{2.1}                   % software release, not documentation
16 \setreleaseinfo{}               % empty for final release
17 \setshortversion{2.1}           % major.minor only for software
18
19 \begin{document}
20 \maketitle
21
22 % This makes the Abstract go on a separate page in the HTML version;
23 % if a copyright notice is used, it should go immediately after this.
24 %
25 \ifhtml
26 \chapter*{Front Matter\label{front}}
27 \fi
28
29 % Copyright statement should go here, if needed.
30 % ...
31
32 % The abstract should be a paragraph or two long, and describe the
33 % scope of the document.
34 \begin{abstract}
35 \noindent
36 This document describes the list administrator's interface for GNU
37 Mailman 2.1.  It contains information a list owner would need to
38 configure their list, either through the web interface or through
39 email.  It also covers the moderator's interface for approving held
40 messages and subscription notices, and the web interface for creating
41 new mailing lists.  In general, it does not cover the command line
42 interface to Mailman, installing Mailman, or interacting with Mailman
43 from the point of view of the user.  That information is covered in
44 other manuals.
45 \end{abstract}
46
47 \tableofcontents
48
49 \section{Introduction to GNU Mailman}
50
51 GNU Mailman is software that lets you manage electronic mailing lists.
52 It supports a wide range of mailing list types, such as general
53 discussion lists and announce-only lists.  Mailman has extensive
54 features for controlling the privacy of your lists, distributing your
55 list as personalized postings or digests, gatewaying postings to and
56 from Usenet, and providing automatic bounce detection.  Mailman
57 provides a built-in archiver, multiple natural languages, as well as
58 advanced content and topic filtering.
59
60 Mailman provides several interfaces to its functionality.  Most list
61 administrators will primarily use the web interface to customize their
62 lists.  There is also a limited email command interface to the
63 administrative functions, as well as a command line interface if you
64 have shell access on the Mailman server.  This document does not cover
65 the command line interface; see the GNU Mailman site administrator's
66 manual for more details.
67
68 \subsection{A List's Email Addresses}
69
70 Every mailing list has a set of email addresses that messages can be
71 sent to.  There's always one address for posting messages to the list,
72 one address that bounces will be sent to, and addresses for processing
73 email commands.  For example, for a mailing list called
74 \var{mylist@example.com}, you'd find these addresses:
75
76 \begin{itemize}
77 \item mylist@example.com -- this is the email address people should
78       use for new postings to the list.
79
80 \item mylist-join@example.com -- by sending a message to this address,
81       a new member can request subscription to the list.  Both the
82       \mailheader{Subject} header and body of such a message are
83       ignored.  Note that mylist-subscribe@example.com is an alias for
84       the -join address.
85
86 \item mylist-leave@example.com -- by sending a message to this address,
87       a member can request unsubscription from the list.  As with the
88       -join address, the \mailheader{Subject} header and body of the
89       message is ignored.  Note that mylist-unsubscribe@example.com is
90       an alias for the -leave address.
91
92 \item mylist-owner@example.com -- This address reaches the list owner
93       and list moderators directly.
94
95 \item mylist-request@example.com -- This address reaches a mail robot
96       which processes email commands that can be used to set member
97       subscription options, as well as process other commands.
98
99 \item mylist-bounces@example.com -- This address receives bounces from
100       members who's addresses have become either temporarily or
101       permanently inactive.  The -bounces address is also a mail robot
102       that processes bounces and automatically disables or removes
103       members as configured in the bounce processing settings.  Any
104       bounce messages that are either unrecognized, or do not seem to
105       contain member addresses, are forwarded to the list
106       administrators.
107
108 \item mylist-confirm@example.com -- This address is another email
109       robot, which processes confirmation messages for subscription
110       and unsubscription requests.
111 \end{itemize}
112
113 There's also an -admin address which also reaches the list
114 administrators, but this address only exists for compatibility with
115 older versions of Mailman.
116
117 \subsection{Administrative Roles}
118
119 There are two primary administrative roles for each mailing list, a
120 list owner and a list moderator.  A list owner is allowed to change
121 various settings of the list, such as the privacy and archiving
122 policies, the content filtering settings, etc.  The list owner is also
123 allowed to subscribe or invite members, unsubscribe members, and
124 change any member's subscription options.
125
126 The list moderator on the other hand, is only allowed to approve or
127 reject postings and subscription requests.  The list moderator can
128 also do things like clear a member's moderation flag, or add an
129 address to a list of approved non-member posters.
130
131 Normally, the list owner and list moderator are the same person.  In
132 fact, the list owner can always do all the tasks a list moderator can
133 do.  Access to both the owner's configuration pages, and the
134 moderation pages are protected by the same password.  However, if the
135 list owner wants to delegate posting and subscription approval
136 authority to other people, a separate list moderator password can be
137 set, giving moderators access to the approval pages, but not the
138 configuration pages.  In this setup, list owners can still moderate
139 the list, of course.
140
141 In the sections that follow, we'll often use the terms list owner and
142 list administrator interchangably, meaning both roles.  When
143 necessary, we'll distinguish the list moderator explicitly.
144
145 \subsection{A List's Web Pages}
146
147 Every mailing list is also accessible by a number of web pages.  Note
148 that the exact urls is configurable by the site administrator, so they
149 may be different than what's described below.  We'll describe the most
150 common default configuration, but check with your site administrator
151 or hosting service for details.
152
153 Mailman provides a set of web pages that list members use to get
154 information about the list, or manage their membership options.  There
155 are also list archive pages, for browsing an online web-based archive
156 of the list traffic.  These are described in more detail in the GNU
157 Mailman user's manual.
158
159 Mailman also provides a set of pages for configuring an individual
160 list, as well as a set of pages for disposing of posting and
161 subscription requests.
162
163 For a mailing list called \var{mylist} hosted at the domain
164 \var{lists.example.com}, you would typically access the administrative
165 pages by going to \code{http://lists.example.com/mailman/admin/mylist}.
166 The first time you visit this page, you will be presented with a login
167 page, asking for the list owner's password.  When you enter the
168 password, Mailman will store a session cookie in your browser, so you
169 don't have to re-authenticate for every action you want to take.  This
170 cookie is stored only until you exit your browser.
171
172 To access the administrative requests page, you'd visit
173 \code{http://lists.example.com/mailman/admindb/mylist} (note the
174 \emph{admindb} url as opposed to the \emph{admin} url).  Again, the
175 first time you visit this page, you'll be presented with a login page,
176 on which you can enter either the list moderator password or the list
177 owner password.  Again, a session cookie is dropped in your browser.
178 Note also that if you've previously logged in as the list owner, you
179 do not need to re-login to access the administrative requests page.
180
181 \subsection{Basic Architectural Overview}
182
183 This section will outline the basic architecture of GNU Mailman, such
184 as how messages are processed by the sytem.  Without going into lots
185 of detail, this information will help you understand how the
186 configuration options control Mailman's functionality.
187
188 When mail enters the system from your mail server, it is dropped into
189 one of several Mailman \emph{queues} depending on the address the
190 message was sent to.  For example, if your system has a mailing list
191 named \var{mylist} and your domain is \var{example.com}, people can
192 post messages to your list by sending them to
193 \var{mylist@example.com}.  These messages will be dropped into the
194 \emph{incoming} queue, which is also colloquially called the
195 \emph{moderate-and-munge} queue.  The incoming queue is where most of
196 the approval process occurs, and it's also where the message is
197 prepared for sending out to the list membership.
198
199 There are separate queues for the built-in archiver, the bounce
200 processor, the email command processor, as well as the outgoing email
201 and news queues.  There's also a queue for messages generated by the
202 Mailman system.  Each of these queues typically has one \emph{queue
203 runner} (or ``qrunner'') that processes messages in the queue.  The
204 qrunners are idle when there are no messages to process.
205
206 Every message in the queues are represented by two files, a message
207 file and a metadata file.  Both of these files share the same base
208 name, which is a combination of a unique hash and the Unix time that
209 the message was received.  The metadata file has a suffix of
210 \file{.db} and the message file has a suffix of either \file{.msg} if
211 stored in plain text, or \file{.pck} if stored in a more efficient
212 internal representation\footnote{Specifically, a Python pickle}.
213
214 As a message moves through the incoming queue, it performs various
215 checks on the message, such as whether it matches one of the
216 moderation criteria, or contains disallowed MIME types.  Once a
217 message is approved for sending to the list membership, the message is
218 prepared for sending by deleting, adding, or changing message headers,
219 adding footers, etc.  Messages in the incoming queue may also be
220 stored for appending to digests.
221
222 \section{The List Configuration Pages}
223
224 After logging into the list configuration pages, you'll see the
225 configuration options for the list, grouped in categories.  All the
226 administrative pages have some common elements.  In the upper section,
227 you'll see two columns labeled ``Configuration Categories''.  Some
228 categories have sub-categories which are only visible when you click
229 on the category link.  The first page you see after logging in will be
230 the ``General Options'' category.  The specific option settings for
231 each category are described below.
232
233 On the right side of the top section, you'll see a column labeled
234 ``Other Administrative Activities''.  Here you'll find some other
235 things you can do to your list, as well as convenient links to the
236 list information page and the list archives.  Note the big ``Logout''
237 link; use this if you're finished configuring your list and don't want
238 to leave the session cookie active in your browser.
239
240 Below this common header, you'll find a list of this category's
241 configuration variables, arranged in two columns.  In the left column
242 is a brief description of the option, which also contains a
243 ``details'' link.  For many of the variables, more details are
244 available describing the semantics of the various available settings,
245 or information on the interaction between this setting and other list
246 options.  Clicking on the details link brings up a page which contains
247 only the information for that option, as well as a button for
248 submitting your setting, and a link back to the category page.
249
250 On the right side of the two-column section, you'll see the variable's
251 current value.  Some variables may present a limited set of values,
252 via radio button or check box arrays.  Other variables may present
253 text entry boxes of one or multiple lines.  Most variables control
254 settings for the operation of the list, but others perform immediate
255 actions (these are clearly labeled).
256
257 At the bottom of the page, you'll find a ``Submit'' button and a
258 footer with some more useful links and a few logos.  Hitting the
259 submit button commits your list settings, after they've been
260 validated.  Any invalid values will be ignored and an error message
261 will be displayed at the top of the resulting page.  The results page
262 will always be the category page that you submitted.
263
264 \subsection{The General Options Category}
265
266 The General Options category is where you can set a variety of
267 variables that affect basic behavior and public information.  In the
268 descriptions that follow, the variable name is given first, along with
269 an overview and a description of what that variable controls.
270
271 \subsubsection{General list personality}
272
273 These variables, grouped under the general list personality section,
274 control some public information about the mailing list.
275
276 \begin{description}
277 \item[real_name]
278     Every mailing list has both a \emph{posting name} and a \emph{real
279     name}.  The posting name shows up in urls and in email addresses,
280     e.g. the \code{mylist} in \code{mylist@example.com}.  The posting
281     name is always presented in lower case, with alphanumeric
282     characters and no spaces.  The list's real name is used in some
283     public information and email responses, such as in the general
284     list overview.  The real name can differ from the posting name by
285     case only.  For example, if the posting name is \code{mylist}, the
286     real name can be \code{Posting}.
287
288 \item[owner]
289     This variable contains a list of email addresses, one address per
290     line, of the list owners.  These addresses are used whenever the
291     list owners need to be contacted, either by the system or by end
292     users.  Often, these addresses are used in combination with the
293     \code{moderator} addresses (see below).
294
295 \item[moderator]
296     This variable contains a list of email addresses, one address per
297     line, of the list moderators.  These addresses are often used in
298     combination with the \code{owner} addresses.  For example, when
299     you email \code{mylist-owner@example.com}, both the owner and
300     moderator addresses will receive a copy of the message.
301
302 \item[description]
303     In the general list overview page, which shows you every available
304     mailing list, each list is displayed with a short description.
305     The contents of this variable is that description.  Note that in
306     emails from the mailing list, this description is also used in the
307     comment section of the \mailheader{To} address.  This text should
308     be relatively short and no longer than one line.
309
310 \item[info]
311     This variable contains a longer description of the mailing list.
312     It is included at the top of the list's information page, and it
313     can contain HTML.  However, blank lines will be automatically
314     converted into paragraph breaks.  Preview your HTML though,
315     because unclosed or invalid HTML can prevent display of parts of
316     the list information page.
317
318 \item[subject_prefix]
319     This is a string that will be prepended to the
320     \mailheader{Subject} header of any message posted to the list.
321     For example, if a message is posted to the list with a
322     \mailheader{Subject} like:
323
324     \begin{verbatim}
325     Subject: This is a message
326     \end{verbatim}
327
328     and the \code{subject_prefix} is \code{[My List] } (note the
329     trailing space!), then the message will be received like so:
330
331     \begin{verbatim}
332     Subject: [My List] This is a message
333     \end{verbatim}
334
335     If you leave \code{subject_prefix} empty, no prefix will be added
336     to the \mailheader{Subject}.  Mailman is careful not to add a
337     prefix when the header already has one, as is the case in replies
338     for example.  The prefix can also contain characters in the list's
339     preferred language.  In this case, because of vagarities of the
340     email standards, you may or may not want to add a trailing space.
341
342 \item[anonymous_list]
343     This variable allows you to turn on some simple anonymizing
344     features of Mailman.  When you set this option to \emph{Yes},
345     Mailman will remove or replace the \mailheader{From},
346     \mailheader{Sender}, and \mailheader{Reply-To} fields of any
347     message posted to the list.
348
349     Note that this option is simply an aid for anonymization, it
350     doesn't guarantee it.  For example, a poster's identity could be
351     evident in their signature, or in other mail headers, or even in
352     the style of the content of the message.  There's little Mailman
353     can do about this kind of identity leakage.
354 \end{description}
355
356 \subsubsection{Reply-To header munging}
357
358 This section controls what happens to the \mailheader{Reply-To}
359 headers of messages posted through your list.
360
361 Beware!  \mailheader{Reply-To} munging is considered a religious issue
362 and the policies you set here can ignite some of the most heated
363 off-topic flame wars on your mailing lists.  We'll try to stay as
364 agnostic as possible, but our biases may still peak through.
365
366 \mailheader{Reply-To} is a header that is commonly used to redirect
367 replies to messages.  Exactly what happens when your uses reply to
368 such a message depends on the mail readers your users use, and what
369 functions they provide.  Usually, there is both a ``reply to sender''
370 button and a ``reply to all'' button.  If people use these buttons
371 correctly, you will probably never need to munge
372 \mailheader{Reply-To}, so the default values should be fine.
373
374 Since an informed decision is always best, here are links to two
375 articles that discuss the opposing viewpoints in great detail:
376
377 \begin{itemize}
378
379 \item \ulink{Reply-To Munging Considered
380       Harmful}{http://www.unicom.com/pw/reply-to-harmful.html}
381 \item \ulink{Reply-To Munging Considered
382       Useful}{http://www.metasystema.org/essays/reply-to-useful.mhtml}
383
384 \end{itemize}
385
386 The three options in this section work together to provide enough
387 flexibility to do whatever \mailheader{Reply-To} munging you might
388 (misguidingly :) feel you need to do.
389
390 \begin{description}
391
392 \item[first_strip_reply_to]
393     This variable controls whether any \mailheader{Reply-To} header
394     already present in the posted message should get removed before
395     any other munging occurs.  Stripping this header will be done
396     regardless of whether or not Mailman will add its own
397     \mailheader{Reply-To} header to the message.
398
399     If this option is set to \emph{No}, then any existing
400     \mailheader{Reply-To} header will be retained in the posted
401     message.  If Mailman adds its own header, it will contain
402     addresses which are the union of the original header and the
403     Mailman added addresses.  The mail standards specify that a
404     message may only have one \mailheader{Reply-To} header, but that
405     that header may contain multiple addresses.
406
407 \item[reply_goes_to_list]
408     This variable controls whether Mailman will add its own
409     \mailheader{Reply-To} header, and if so, what the value of that
410     header will be (not counting original header stripping -- see
411     above).
412
413     When you set this variable to \emph{Poster}, no additional
414     \mailheader{Reply-To} header will be added by Mailman.  This
415     setting is strongly recommended.
416
417     When you set this variable to \emph{This list}, a
418     \mailheader{Reply-To} header pointing back to your list's posting
419     address will be added.
420
421     When you set this variable to \emph{Explicit address}, the value
422     of the variable \code{reply_to_address} (see below) will be
423     added.  Note that this is one situation where
424     \mailheader{Reply-To} munging may have a legitimate purpose.  Say
425     you have two lists at your site, an announce list and a discussion
426     list.  The announce list might allow postings only from a small
427     number of approved users; the general list membership probably
428     can't post to this list.  But you want to allow comments on
429     announcements to be posted to the general discussion list by any
430     list member.  In this case, you can set the \mailheader{Reply-To}
431     header for the announce list to point to the discussion list's
432     posting address.
433
434 \item[reply_to_address]
435     This is the address that will be added in the
436     \mailheader{Reply-To} header if \code{reply_goes_to_list} is set
437     to \emph{Explicit address}.
438
439 \end{description}
440
441 \subsubsection{Umbrella list settings}
442
443 TBD.  Note that umbrella lists are deprecated and will be replace with
444 a better mechanism for Mailman 3.0.
445
446 \subsubsection{Notifications}
447
448 Mailman sends notifications to the list administrators or list members
449 under a number of different circumstances.  Most of these
450 notifications can be configured in this section, but see the Bounce
451 Processing and Auto-responder categories for other notifications that
452 Mailman can send.
453
454 \begin{description}
455 \item[send_reminders]
456     By default Mailman sends all list members a monthly password
457     reminder.  This notice serves two purposes.  First, it reminds
458     people about all the lists they may be subscribed to on this
459     domain, including the lists where their subscription may be
460     disabled.  Second, it reminds people about their passwords for
461     these lists, as well as the url for their personal options pages,
462     so that they can more easily configure their subscription options.
463
464     Some people get annoyed with these monthly reminders, and they can
465     disable the reminders via their subscription options page.  For
466     some lists, the monthly reminders aren't appropriate for any of
467     the members, so you can disable them list-wide by setting the
468     \code{send_reminders} variable to \emph{No}.
469
470 \item[welcome_msg]
471     When new members are subscribed to the list, either by their own
472     action, or the action of a list administrator, a welcome message
473     can be sent to them.  The welcome message contains some common
474     boilerplate information, such as the name of the list,
475     instructions for posting to the list, and the member's
476     subscription password.  You can add additional information to the
477     welcome message by typing the text into the \code{welcome_msg}
478     text box.  Note that because this text is sent as part of an
479     email, it should \strong{not} contain HTML.
480
481 \item[send_welcome_msg]
482     This flag controls whether or not the welcome message is sent to
483     new subscribers.
484
485 \item[goodbye_msg]
486     Like the \code{welcome_msg}, a ``goodbye'' message can be sent to
487     members when they unsubscribe from the list.  Unlike the welcome
488     message, there's no boilerplate for the goodbye message.  Enter
489     the entire goodbye message you'd like unsubscribing members to
490     receive into the \code{goodbye_msg} text box.
491
492 \item[send_goodbye_msg]
493     This flag controls whether or not the goodbye message is sent to
494     unsubscribing members.
495
496 \item[admin_immed_notify]
497     List moderators get notifications of pending administrative
498     actions, such as subscription or unsubscription requests that
499     require moderator approval, or posted messages that are being held
500     for moderator approval.  List moderators will always get a daily
501     summary of such pending requests, but they can also get immediate
502     notifications when such a request is made.  The
503     \code{admin_immed_notify} variable controls whether these
504     immediate notifications are sent or not.  It's generally a good
505     idea to leave this set to \emph{Yes}.
506
507 \item[admin_notify_mchanges]
508     This variable controls whether the list administrators should get
509     notifications when members join or leave the list.
510
511 \item[respond_to_post_requests]
512     This variable controls whether the original sender of a posting
513     gets a notice when their message is held for moderator approval.
514
515 \end{description}
516
517 \subsubsection{Additional settings}
518
519 This section contains some miscellaneous settings for your mailing
520 list.
521
522 \begin{description}
523 \item[emergency]
524     When this option is enabled, all list traffic is emergency
525     moderated, i.e. held for moderation.  Turn this option on when
526     your list is experiencing a flamewar and you want a cooling off
527     period.
528
529 \item[new_member_options]
530     Each member has a set of subscription options which they can use
531     to control how they receive messages and otherwise interact with
532     the list.  While the members can change these settings by logging
533     into their personal options page, you might want to set the
534     default for a number of the member options.  You can do that with
535     this variable, but see also the other categories for other member
536     defaults you can set.
537
538     This variable presents a set of checkboxes which control the
539     defaults for some of the member options.  \emph{Conceal the
540     member's address} specifies whether or not the address is
541     displayed in the list roster.  \emph{Acknowledge the member's
542     posting} controls whether or not Mailman sends an acknowledgement
543     to a member when they post a message to the list.  \emph{Do not
544     send a copy of a member's own post} specifies whether a member
545     posting to the list will get a copy of their own posting.
546     \emph{Filter out duplicate messages to list members (if possible)}
547     specifies whether members who are explicitly listed as a recipient
548     of a message (e.g. via the \mailheader{Cc} header) will also get a
549     copy from Mailman.
550
551     Of course, members can always override these defaults by making
552     changes on their membership options page.
553
554 \item[administrivia]
555     This option specifies whether Mailman will search posted messages
556     for \emph{admimistrivia}, in other words, email commands which
557     usually should be posted to the \code{-request} address for the
558     list.  Setting this to \emph{Yes} helps prevent such things as
559     unsubscribe messages getting erroneously posted to the list.
560
561     If a message seems to contain administrivia, it is held for
562     moderator approval.
563
564 \item[max_message_size]
565     This option specifies a maximum message size, in kilobytes, over
566     which the message will be held for moderator approval.
567
568 \item[host_name]
569     This option specifies the host name part of email addresses used
570     by this list.  For example, this is the \code{example.com} part of
571     the posting address \code{mylist@example.com}.
572
573     It's generally not a good idea to change this value, since its
574     default value is specified when the mailing list is created.
575     Changing this to an incorrect value could make it difficult to
576     contact your mailing list.  Also not that the url used to visit
577     the list's pages is not configurable through the web interface.
578     This is because if you messed it up, you'd have to have the site
579     administrator fix it.
580
581 \item[include_rfc2369_headers]
582     \rfc{2369} is an internet standard that describes a bunch of
583     headers that mailing list managers should add to messages to make
584     it easier for people to interact with the list.  Mail reading
585     programs which support this standard may provide buttons for easy
586     access to the list's archives, or for subscribing and
587     unsubscribing to the list.  It's generally a good idea to enable
588     these headers as it provides for an improved user experience.
589     These headers are often called the \code{List-*} headers.
590
591     However, not all mail readers are standards compliant yet, and if
592     you have a large number of members who are using non-compliant
593     mail readers, they may be annoyed at these headers.  You should
594     first try to educate your members as to why these headers exist,
595     and how to hide them in their mail clients.  As a last resort you
596     can disable these headers, but this is not recommended.
597
598 \item[include_list_post_header]
599     The \mailheader{List-Post} header is one of the headers
600     recommended by \rfc{2369}.  However for some announce-only mailing
601     lists, only a very select group of people are allowed to post to
602     the list; the general membership is usually not allowed to post to
603     such lists.  For lists of this nature, the \mailheader{List-Post}
604     header is misleading.  Select \emph{No} to disable the inclusion
605     of this header. (This does not affect the inclusion of the other
606     \code{List-*} headers.)
607 \end{description}
608
609 \subsection{The Passwords Category}
610 As mentioned above, there are two primary administrative roles for
611 mailing lists.  In this category you can specify the password for
612 these roles.
613
614 The list owner has total control over the configuration of their
615 mailing list (within some bounds as specified by the site
616 administrator).  Note that on this page, for historical reasons, the
617 list owner role is described here as the \emph{list administrator}.
618 You can set the list owner's password by entering it in the password
619 field on the left.  You must type it twice for confirmation.  Note
620 that if you forget this password, the only way for you to get back
621 into your list's administrative pages is to ask the site administrator
622 to reset it for you (there's no password reminders for list owners).
623
624 If you want to delegate list moderation to someone else, you can enter
625 a different moderator password in the field on the right (typed twice
626 for confirmation).  Note that if you aren't going to delegate
627 moderation, and the same people are going to both configure the list
628 and moderate postings to the list, don't enter anything into the
629 moderator password fields.  If you do enter a separate moderator
630 password, be sure to fill in the \code{moderator} variable in the
631 \emph{General options} category page. 
632
633 \subsection{The Language Options Category}
634 Mailman is multilingual and internationalized, meaning you can set up
635 your list so that members can interact with it in any of a number of
636 natural languages.  Of course, Mailman won't translate list
637 postings. :)
638
639 However, if your site administrator has enabled its support, you can
640 set your list up to support any of about two dozen languages, such as
641 German, Italian, Japanese, or Spanish.  Your list members can then
642 choose any of your supported languages as their \emph{preferred
643 language} for interacting with the list.  Such things as their member
644 options page will be displayed in this language.  Each mailing list
645 also has its own \emph{preferred language} which is the language the
646 list supports if no other language context is known.
647
648 These variables control the language settings for your mailing list:
649
650 \begin{description}
651 \item[preferred_language]
652     This is the list's preferred language, which is the language that
653     the list administrative pages will be displayed in.  Also any
654     messages sent to the list owners by Mailman will be sent in this
655     language.  This option is presented as a drop-down list containing
656     the language enabled in the \code{available_languages} variable.
657
658 \item[available_languages]
659     This set of checkboxes contains all the natural languages that
660     your site administrator has made available to your mailing lists.
661     Select any language that you'd either like your members to be able
662     to view the list in, or that you'd like to be able to use in your
663     list's \code{preferred_language} variable.
664
665 \item[encode_ascii_prefixes]
666     If your mailing list's preferred language uses a non-ASCII
667     character set and the \code{subject_prefix} contains non-ASCII
668     characters, the prefix will always be encoded according to the
669     relevant standards.  However, if your subject prefix contains only
670     ASCII characters, you may want to set this option to \emph{Never}
671     to disable prefix encoding.  This can make the subject headers
672     slightly more readable for users with mail readers that don't
673     properly handle non-ASCII encodings.
674
675     Note however, that if your mailing list receives both encoded and
676     unencoded subject headers, you might want to choose \emph{As
677     needed}.  Using this setting, Mailman will not encode ASCII
678     prefixes when the rest of the header contains only ASCII
679     characters, but if the original header contains non-ASCII
680     characters, it will encode the prefix.  This avoids an ambiguity
681     in the standards which could cause some mail readers to display
682     extra, or missing spaces between the prefix and the original
683     header.
684 \end{description}
685
686 \subsection{The Membership Management Category}
687
688 The \emph{Membership Management} category is unlike the other
689 administrative categories.  It doesn't contain configuration variables
690 or list settings.  Instead, it presents a number of pages that allow
691 you to manage the membership of you list.  This includes pages for
692 subscribing and unsubscribing members, and for searching for members,
693 and for changing various member-specific settings.
694
695 More details on membership management are described in the Membership
696 Management section.
697
698 \subsection{The Non-digest Options Category}
699
700 Mailman delivers messages to users via two modes.  List members can
701 elect to receive postings in bundles call \emph{digests} one or a few
702 times a day, or they can receive messages immediately whenever the
703 message is posted to the list.  This latter delivery mode is also
704 called \emph{non-digest delivery}.  There are two administrative
705 categories available for separately controlling digest and non-digest
706 delivery.  You can even disable one or the other forms of delivery
707 (but not both).
708
709 Both kinds of delivery can have list-specific headers and footers
710 added to them which can contain other useful information you want your
711 list members to see.  For example, you can include instructions for
712 unsubscribing, or a url to the lists digest, or any other information.
713
714 Non-digest deliveries can also be \emph{personalized} which means
715 certain parts of the message can contain information tailored to the
716 member receiving the message.  For example, the \mailheader{To} header
717 will contain the address of the member when deliveries are
718 personalized.  Footers and headers can contain personalized
719 information as well, such as a link to the individual user's options
720 page.
721
722 In addition, personalized messages will contain extra information that
723 Mailman can use to unambiguously track bounces from members.
724 Ordinarily, Mailman does some pattern recognition on bounce messages
725 to determine list members whose addresses are no longer valid, but
726 because of the vagaries of mail systems, and the countless forwards
727 people can put in place, it's often the case that bounce messages
728 don't contain any useful information in them.  Personalized messages
729 avoid this problem by encoding information in certain headers that
730 unambiguously identify the recipient of a message.  If that message
731 bounces, Mailman will know exactly which member it was intended for.
732
733 Note that because personalization requires extra system resources, it
734 must be enabled by the site administrator before you can choose it.
735
736 Here are the variables which control non-digest delivery:
737
738 \begin{description}
739 \item[nondigestable]
740     This option controls whether members can receive immediate
741     delivery or not.  If not, they will be forced to receive messages
742     in digests.  You can't disable non-digest delivery if digests are
743     already disabled.
744
745 \item[personalize]
746     This option turns on message personalization.
747
748 \item[msg_header]
749     This text box lets you enter information that will be included in
750     the header of every non-digest message sent through the
751     list.
752
753     See below for more information on what can go in the headers and
754     footers.  If you leave this text box empty, no header will be
755     added.
756
757 \item[msg_footer]
758     Just like with the header, you can add a footer to every message.
759     The same rules apply to footers as apply to headers.
760 \end{description}
761
762 Headers and footers can contain any text you want.  For non-English
763 lists, the headers and footers can contain any character in the
764 character set of the list's preferred language.  The headers and
765 footers can also contain \emph{substitution variables} which Mailman
766 will fill in with information taken from the mailing list.  These
767 substitutions are in Python string interpolation format, where
768 something like \code{\%(list_name)s} is substituted with he name of
769 the mailing list.  Note that the trailing \samp{s} is
770 required\footnote{The site administrator can configure lists to use a
771 simpler interpolation format, where \code{\$list_name} or
772 \code{\$\{list_name\}} would be substituted with the mailing list's
773 name.  Ask your site administrator if the've configured your list this
774 way.}.
775
776 For example, a footer containing the following text:
777
778 \begin{verbatim}
779 This is the \%(list_name)s mailing list
780 Description: \%(description)s
781 \end{verbatim}
782
783 might get attached to postings like so:
784
785 \begin{verbatim}
786 This is the Example mailing list
787 Description: An example of Mailman mailing lists
788 \end{verbatim}
789
790 Here is the list of substitution variables available for your headers
791 and footers:
792
793 \begin{description}
794 \item[real_name]
795     This is the value of the \code{real_name} configuration variable
796     in the General options category.
797
798 \item[list_name]
799     This is the canonical name of the mailing list.  In other words
800     it's the posting address of the list\footnote{For backward
801     compatibility, the variable \code{_internal_name} is
802     equivalent.}.
803
804 \item[host_name]
805     This is the domain name part of the email address for this list.
806
807 \item[web_page_url]
808     This is the base url for contacting the list via the web.  It can
809     be appended with \code{listinfo/\%(list_name)s} to yield the
810     general list information page for the mailing list.
811
812 \item[description]
813     The brief description of the mailing list.
814
815 \item[info]
816     This is the full description of the mailing list.
817
818 \item[cgiext]
819     This is the extension added to CGI scripts.  It might be the empty
820     string, \code{.cgi}, or something else depending on how your site
821     is configured.
822 \end{description}
823
824 Note that \code{real_name}, \code{host_name}, \code{description}, and
825 \code{info} substitution variables take their values from the list
826 configuration variables of the same name.
827
828 When personalization is enabled, the following substitution variables
829 are also available:
830
831 \begin{description}
832 \item[user_address]
833     The address of the recipient of the message, coerced to lower case.
834
835 \item[user_delivered_to]
836     The case-preserved address that the user subscribed to the mailing
837     list with\footnote{Usually it makes no difference which of
838     \code{user_address} and \code{user_delivered_to} is used, but it's
839     important to remember that they can be different.  When they're
840     different, Mailman always uses the lower case address as the key
841     to the member's subscription information, but it always delivers
842     messages to the case-preserved version.}.
843
844 \item[user_password]
845     The user's password, in clear text.
846
847 \item[user_name]
848     The user's full name.
849
850 \item[user_optionsurl]
851     The url to the user's personal options page.
852 \end{description}
853
854 \subsection{The Digest Options Category}
855
856 Digest delivery is a way to bundle many articles together into one
857 package, which can be delivered once per day (if there were any posted
858 articles), or whenever the package is bigger than a specified limit.
859 Some users may prefer this style of delivery for higher traffic lists
860 since they will receive fewer messages.
861
862 Mailman supports two standard digest formats, and if digests are
863 enabled, users can select which of the two formats they receive.  One
864 is MIME digests, where each message is an attachment inside a
865 \mimetype{multipart/digest}.  This format also contains a summary
866 table of contents, and of course the an optional header and footer,
867 and it retains most of the headers of the original messages.
868
869 The second type is called ``plaintext'' digests because they are
870 readable in mail readers that don't support MIME.  Actually, they
871 adhere to the \rfc{1153} digest standard.  The retain some, but not
872 all of the original messages, but can also include a summary and
873 headers and footers.
874
875 Like non-digest delivery, you can enable or disable digest delivery,
876 but you cannot disable both types of delivery.  You can specify
877 different headers and footers for digest and non-digest deliveries.
878 You cannot personalize digest deliveries.
879
880 As list administrator, you may want to send an urgent message to all
881 list members, bypassing the normal digest bundling.  To do this, send
882 the message with a \mailheader{Urgent} header, where the value of the
883 header is the list administrator's password.  Non-digest members will
884 receive the message like normal, but digest members will receive the
885 message immediately\footnote{They'll also receive the message in the
886 digest.}.
887
888 Here are the variables which control digest delivery:
889
890 \begin{description}
891 \item[digestable]
892     The option controls whether members can receive digest deliveries
893     or not.  If not, they will be forced to receive immediate
894     deliveries.  You can't disable digests if non-digests are already
895     disabled.
896
897 \item[digest_is_default]
898     Controls which style of delivery is the default for new members.
899     You can choose \emph{Regular} (non-digest) or \emph{Digest}
900     delivery.
901
902 \item[mime_is_default_digest]
903     If a member is allowed to choose digests, this variable controls
904     which is the default digest style they will receive.  \emph{Plain}
905     digests are \rfc{1153} format as described above.
906
907 \item[digest_size_threshold]
908     Normally, digest members get at least one message per day, if
909     there have been any messages posted to the list.  However, for
910     high volume lists, you may want to send out digests when the size
911     has reached a certain threshold, otherwise, the one digest they
912     receive could be huge.  This variable controls the size threshold
913     by specifying the maximum digest size in kilobytes.  Note that
914     this threshold isn't exact.  Set this variable to zero to specify
915     that there is no size threshold, in which case no more than one
916     digest will be sent out per day.
917
918 \item[digest_send_periodic]
919     This variable actually controls whether or not a digest is sent
920     daily when the size threshold has not yet been met.  If set to
921     \emph{No}, then digests will only be sent when they are bigger
922     than \code{digest_size_threshold}.
923
924 \item[digest_header]
925     This text box lets you enter information that will be included in
926     the header of every digest message sent through the list.  The
927     same information can go in this header as can go in the
928     \code{msg_header}, except for the personalization variables.
929
930 \item[digest_footer]
931     Just like with the header, you can add a footer to every message.
932     The same rules apply to digest footers as apply to digest headers.
933     
934 \item[digest_volume_frequency]
935     Each digest is numbered with a volume and an issue.  This variable
936     controls how often a new digest volume is sent.  When the digest
937     volume number is incremented, the issue number is reset to 1.
938
939 \item[_new_volume]
940     This is an action variable, which forces an increment of the
941     volume number as soon as you submit the form.
942
943 \item[_send_digest_now]
944     This is another action variable.  Select \emph{Yes}, submit the
945     form, and the current digest is packaged up and sent to digest
946     members, regardless of size (well, there has to be at least one
947     message in the digest).
948 \end{description}
949
950 \subsection{The Privacy Options Category}
951
952 The Privacy category lets you control how much of the list's
953 information is public, as well as who can send messages to your list.
954 It also contains some spam detection filters.  Note that this section
955 is not used to control whether your list's archives are public or
956 private; for that, use the \ref{Archiving options} category.
957
958 There are four sub-categories:
959 \begin{itemize}
960 \item Subscription rules -- i.e. the rules for joining and leaving
961       your mailing list
962
963 \item Sender filters -- the rules for who may post messages to your
964       list
965
966 \item Recipient filters -- moderation rules based on the recipient of
967       the message
968
969 \item Spam filters -- some regular expression based rules for header
970       matching
971 \end{itemize}
972
973 The sender, recipient, and spam filtering rules are part of the
974 general list moderation features of Mailman.  When a message is posted
975 to the list, it is matched against a number of criteria, the outcome
976 of which determines whether the message is reflected to the membership
977 or not.  In general, the outcome is one of four states:
978
979 \begin{itemize}
980 \item Approved or Accepted -- the message may be sent on to the
981       members of the mailing list.
982
983 \item Hold -- the message will be held for moderator approval.  The
984       list owners and moderators will then have to explicitly approve
985       the message before the list members will see it.
986
987 \item Reject -- the message is bounced back to the original sender,
988       often with a notice containing the reason the message was
989       rejected.  The list members never see rejected messages.
990
991 \item Discard -- the message is simply thrown away without further
992       processing.
993 \end{itemize}
994
995 Many of the fields in this section are text boxes accepting addresses,
996 one per line.  Unless otherwise noted, these also accept regular
997 expressions which will be matched against an address, if the line
998 begins with a \^ (caret) character.
999
1000 \subsubsection{Subscription rules}
1001
1002 This subcategory controls the rules for exposing the existance of this
1003 list, and for what new members must do in order to subscribe to the
1004 list.
1005
1006 \begin{description}
1007 \item[advertised]
1008     This option controls whether this list will show up in the list
1009     overview for the site.  Normally, an overview contains the name
1010     and short description of every mailing list in the virtual
1011     domain.  By setting this variable to \emph{No}, it will not show
1012     up in this overview, nor will it show up in the administrative
1013     overview.  The only way then to find the list is to guess (or
1014     know!) its name.
1015
1016 \item[subscribe_policy]
1017     This option controls the steps that a new member must take to join
1018     the list.  The available options may differ based on some defaults
1019     that the site administrator chooses.  They are:
1020
1021     \begin{itemize}
1022     \item None -- No verification is done on the subscribing
1023           member. This is also called \emph{open subscriptions} and is
1024           generally disabled by default.  The site administrator must
1025           allow list admins to choose this option; if not, this option
1026           will not be presented to you.
1027
1028     \item Confirm -- An email confirmation step is required before the
1029           address is added to the list.  When a member requests
1030           subscription, either via the web page or by sending a
1031           message to \var{yourlist}\code{-join@example.com}, Mailman
1032           will send a confirmation message to the requesting address.
1033           This mail-back confirmation contains a unique identifier,
1034           which the requester can present to Mailman in order to
1035           confirm their subscription.  This can be done either by
1036           replying to the mail-back, or by visiting the url in the
1037           mail-back message.  The url points to a page that lets the
1038           user either discard or confirm their request.
1039
1040     \item Require approval -- All subscription requests are held for
1041           approval of the list moderator.  No mail-back confirmation
1042           is sent, but the list admins will recieve a message
1043           indicating that approval is pending.
1044
1045     \item Confirm and approve -- Here, a mail-back notice must first
1046           be confirmed by the requester.  Once confirmed, the list
1047           moderator must then approve the request.  This is the most
1048           secure method for users to subscribe since it both verifies
1049           the requesting address, and forces the list moderators to
1050           approve the request.
1051
1052     \end{itemize}
1053
1054 \item[unsubscribe_policy]
1055     Specifies whether the list moderator's approval is required for
1056     unsubscription requests.  \emph{No} is highly recommended, since
1057     it is exceedingly impolite to not allow people to leave a mailing
1058     list whenever they want (i.e. opt-out).  \emph{Yes} is useful in
1059     some specialized contexts; e.g. you may not want to allow
1060     employees to unsubscribe from the company newsletter.
1061
1062 \item[ban_list]
1063     This contains a list of addresses (or regular expressiosn), one
1064     per line, that are banned from ever subscribing to your mailing
1065     list.  If a match occurs during the subscription process, the
1066     request will be automatically rejected, and the requester will get
1067     a rejection notice.  You can use this to permanently ban
1068     troublesome posters to a members-only list.
1069
1070 \item[private_roster]
1071     This specifies who is allowed to view the roster of member
1072     addresses.  If you choose \emph{Anyone}, then the list membership
1073     is completely public.  You can limit exposure of the roster to
1074     just list members, or just to the list administrators.  In the
1075     former case, a user must enter a valid member's address and
1076     password before they can view the roster.  In the latter case, a
1077     list administrator's password must be enter; if a matching admin
1078     password is entered, address field is ignored.
1079
1080 \item[obscure_addresses]
1081     Controls whether some simple obfuscation of addresses is used when
1082     member addresses are included on web pages.  This should reduce
1083     the opportunity for email address harvesting by spammers, although
1084     it probably doesn't eliminate it.
1085 \end{description}
1086
1087 \subsubsection{Sender filters}
1088
1089 When a message is posted to the list, a series of moderation criteria are
1090 applied to determine the disposition of the message.  This section
1091 contains the modeation controls for postings from both members and
1092 non-members.
1093
1094 \begin{description}
1095 \item[default_member_moderation]
1096     Member postings are held for moderation if their \emph{moderation
1097     flag} is turned on.  Note that only the list administrators can
1098     change the value of a member's moderation flag.
1099
1100     You can control whether new members get their moderation flag
1101     turned on or off by default when they subscribe to the list.  By
1102     turning this flag off by default, postings by members will be
1103     allowed without further intervention (barring other restrictions
1104     such as size or implicit recipient lists -- see below).  By
1105     turning the flag on, you can quarantine new member postings to
1106     make sure that they meet your criteria for netiquette, topicality,
1107     etc.  Once you determine that the new member understands the
1108     community's posting rules, you can turn off their moderation flag
1109     and let their postings go through unstopped.
1110
1111     E-newsletter style lists can also be set up by using the
1112     moderation flag.  By setting the \code{member_moderation_action}
1113     to \emph{Reject}, and by turning off the moderation flag for just
1114     the few approved senders, your list will operate in essentially a
1115     one-way direction.  Note that you'd also need to reject or discard
1116     postings from non-members.
1117
1118 \item[member_moderation_action]
1119     This is the action to take for postings from a member who's
1120     moderation flag is set.  For typical discussion lists, you'll
1121     likely set this to \emph{Hold} so that the list moderator will get
1122     a chance to manually approve, reject, or discard the message.  For
1123     e-newsletter and announcement lists, you might want to set this to
1124     \emph{Reject} or \emph{Discard}.
1125
1126     Note that when a moderated member posts to your list, and the
1127     \code{member_moderation_action} is set to \emph{Hold}, the message
1128     will appear on the administrative requests page.  When you dispose
1129     of the message, you will be given an opportunity to clear the
1130     moderation flag at the same time.   If you're quarantining new
1131     posts, this makes it very convenient to both approve a new
1132     member's post and de-moderate them at the same time.
1133
1134 \item[member_moderation_notice]
1135     When a member's moderation flag is turned on and
1136     \code{member_moderation_action} is \emph{Reject}, this variable
1137     contains the text sent in the rejection notice.
1138 \end{description}
1139
1140 The next batch of variables controls what happens when non-members
1141 post messages to the list.  Each of these accepts one email address
1142 per line; regular expressions are allowed if the line starts with the
1143 \^ (caret) character.  These address lists are always consulted in the
1144 order in which they're presented on this page (i.e. accepts first,
1145 followed by holds, rejections, and discards).
1146
1147 \begin{description}
1148 \item[accept_these_nonmembers]
1149     Postings from non-members whose addresses match this list are
1150     accepted, barring other list restrictions due to size, implicit
1151     recipients, etc.  You might want to add alternative addresses of
1152     approved posters to this list.
1153
1154 \item[hold_these_nonmembers]
1155     Postings from non-members whose addresses match this list are
1156     held for moderator approval.
1157
1158 \item[reject_these_nonmembers]
1159     Postings from non-members whose addresses match this list are
1160     rejected, i.e. bounced back to the original sender.  There
1161     currently is no way to add additional text to the rejection
1162     message.
1163
1164 \item[discard_these_nonmembers]
1165     Postings from non-members whose addresses match this list are
1166     discarded, with no bounce back message.  You might want to add the
1167     addresses of known spammers to this list.
1168
1169 \item[generic_nonmember_action]
1170     This variable controls what happens to non-member posts when the
1171     address of the sender doesn't match any of the above four lists.
1172     If you set this to \emph{Hold}, the posting will appear on the
1173     administrative requests page, and you will be given an opportunity
1174     to add the non-member to one of the above four lists at the same
1175     time you dispose of the held message.
1176
1177 \item[forward_auto_discards]
1178     When messages from non-members are discarded, either because the
1179     sender address matched \code{discard_these_nonmembers}, or because
1180     \code{generic_nonmember_action} is \emph{Discard}, you can choose
1181     whether such messages are forwarded to the lsit administrators or
1182     not.
1183 \end{description}
1184
1185 \subsubsection{Recipient Filters}
1186
1187 The variables in this section control various filters based on the
1188 recipient of the message.
1189
1190 \begin{description}
1191 \item[require_explicit_destination]
1192     This controls whether the mailing list posting address must be
1193     explicitly named in the \mailheader{To} or \mailheader{Cc}
1194     recipient lists.  The main reason why it wouldn't is if the
1195     message was blind-carbon-copied (i.e. \mailheader{Bcc}'d) to the
1196     list.  Spammers like to do this, but sometimes legitimate messages
1197     are forwarded to the list this way.
1198
1199     If the list is not explicitly addressed and this setting is turned
1200     on, the message will be held for moderator approval.
1201
1202 \item[acceptable_aliases]
1203     This is the list of alternative addresses that are acceptable as a
1204     list posting address when \code{require_explicit_destination} is
1205     enabled.  This is useful for when there aliases for the main
1206     posting address (e.g. \code{help@example.com} may be an alias for
1207     \code{help-list@example.com}).
1208
1209 \item[max_num_recipients]
1210     This is the maximum number of explicit recipients that are allowed
1211     on the posted message.  Spammers sometimes send messages with lots
1212     of explicit recipients, so setting this number to a reasonable
1213     value may cut down on spam.
1214 \end{description}
1215
1216 \subsubsection{Spam Filters}
1217
1218 This section provides some adjuncts to spam fighting tools; it
1219 doesn't replace dedicated anti-spam tools such as SpamAssassin or
1220 Spambayes.
1221
1222 \begin{description}
1223 \item[bounce_matching_headers]
1224     This variable contains header regular expressions, one per line,
1225     and if any of a message's headers matches one of these patterns,
1226     it will be held for moderation.  The format is a colon separated
1227     header and value, where the header is case insensitive and the
1228     value is any valid Python regular expression.  Lines that start
1229     with \# are ignored.
1230
1231     This variable can be used to catch known spammers by writing
1232     regexps that match against \mailheader{To} or \mailheader{Cc}
1233     lines, or known-bad \mailheader{Message-ID}s.  Perhaps more useful
1234     though are patterns that match headers added by spam detection
1235     tools higher up in the tool chain.  For example, you might
1236     configure SpamAssassin to add an \mailheader{X-Spam-Score} header
1237     with between zero and 5 stars depending on the spam score.  Then
1238     you can add a line to this variable like:
1239
1240     \begin{verbatim}
1241     X-Spam-Score: [*]{3,5}
1242     \end{verbatim}
1243
1244     This line will match from 3 to 5 stars in the value of this
1245     field.
1246 \end{description}
1247
1248 \subsection{The Bounce Processing Category}
1249
1250 These policies control the automatic bounce processing system in
1251 Mailman.  Here's an overview of how it works:
1252
1253 When a bounce is received, Mailman tries to extract two pieces of
1254 information from the message: the address of the member the message
1255 was intended for, and the severity of the problem causing the bounce.
1256 The severity can be either \emph{hard} for fatal errors, or
1257 \emph{soft} for transient errors.  When in doubt, a hard severity is
1258 used.
1259
1260 If no member address can be extracted from the bounce, then the bounce
1261 message is usually discarded.  Every member has a \emph{bounce score},
1262 initialized at zero, and every time we encounter a bounce from a
1263 member we increment that member's score.  Hard bounces increment by 1
1264 while soft bounces increment by 0.5.  We only increment the bounce
1265 score once per day, so even if we receive ten hard bounces from a
1266 member per day, their score will increase by only 1 for that day.
1267
1268 When a member's bounce score is greater than the \emph{bounce score
1269 threshold} (see below), the member's subscription is disabled.  Once
1270 disabled, the member will not receive any postings from the list until
1271 their membership is explicitly re-enabled, either by the list
1272 administrator or the user.  However, they will receive occasional
1273 reminders that their membership has been disabled, and these reminders
1274 will include information about how to re-enable their membership.  You
1275 can control both the number of reminders the member will receive and
1276 the frequency with which these reminders are sent.
1277
1278 There is one other important configuration variable; after a certain
1279 period of time -- during which no bounces from the member are received
1280 -- the bounce information is considered stale and discarded.  Thus by
1281 adjusting this value, and the score threshold, you can control how
1282 quickly bouncing members are disabled.  You should tune both of these
1283 to the frequency and traffic volume of your list.
1284
1285 \begin{description}
1286
1287 \item[bounce_processing]
1288     Specifies whether or not this list should do automatic bounce
1289     processing.
1290
1291 \item[bounce_score_threshold]
1292     This is the bounce score above which a member's subscription will
1293     be automatically disabled.  When the subscription is re-enabled,
1294     their bounce score will be reset to zero.  This value can be a
1295     floating point number.
1296
1297 \item[bounce_info_stale_after]
1298     Thenumber of days after which a member's bounce information is
1299     considered stale.  If no new bounces have been received in the
1300     interrim, the bounce score is reset to zero.  This value must be
1301     an integer.
1302
1303 \item[bounce_you_are_disabled_warnings]
1304     The number of notices a disabled member will receive before their
1305     address is removed from the mailing list's roster.  Set this to 0
1306     to immediately remove an address from the list once their bounce
1307     score exceeds the threshold.  This value must be an integer.
1308
1309 \item[bounce_you_are_disabled_warnings_interval]
1310     The number of days between each disabled notification.
1311
1312 \item[bounce_unrecognized_goes_to_list_owner]
1313     This variable controls whether unrecognized bounces are discarded,
1314     or forwarded on the list administrator.  The bounce detector isn't
1315     perfect, although personalization can make it much more accurate.
1316     The list owner may want to receive unrecognized bounces so that
1317     they can manually disable or remove such members.
1318
1319 \item[bounce_notify_owner_on_disable]
1320     This option controls whether or not the list owner is notified
1321     when a member's subscription is automatically disabled due to
1322     their bounce threshold being reached.
1323
1324 \item[bounce_notify_owner_on_removal]
1325     This option controls whether or not the list owner is notified
1326     when a member is removed from the list after their disabled
1327     notifications have been exhausted.
1328 \end{description}
1329
1330 \subsection{The Archiving Options Category}
1331
1332 Mailman comes with a built-in web-based archiver called
1333 \emph{Pipermail}, although it can be configured to use external,
1334 third party archivers.
1335
1336 \begin{description}
1337
1338 \item[archive]
1339     This option tells Mailman whether to archive messages it receives
1340     or not, regardless of whether Pipermail or a third party archiver
1341     is used.  Turn this off if you don't want to archive messages.
1342
1343     Note that senders can control whether their own posts are
1344     archived, on an individual per-message basis.  If the posted
1345     message has a \mailheader{X-No-Archive} header (regardless of
1346     value), or a \mailheader{X-Archive} header with a value of
1347     \code{No} (case insensitive), then the message will not be
1348     archived, although it will be treated as normal in all other
1349     ways.
1350
1351 \item[archive_private]
1352     Controls whether Pipermail archives are private or public.
1353     Private archives require a valid member address and password, or a
1354     list administrator password in order to access them.  This
1355     option has no effect when a third party archiver is used.
1356
1357 \item[archive_volume_frequency]
1358     Controls how Pipermail splits messages in the archive.  The most
1359     common option is \emph{Monthly} meaning a new archive volume is
1360     started every month.  Very high volume lists may want a shorter
1361     frequency (e.g. \emph{Weekly} or \emph{Daily}) where as lower
1362     volume lists may want a longer frequency (e.g. \emph{Yearly}).
1363     This option has no effect when a third party archiver is used.
1364 \end{description}
1365
1366 \subsection{The Mail/News Gateway Category}
1367
1368 Mailman has a sophisticated mail-to-news gateway feature.  It can
1369 independently gate messages from news to mail and vice versa, and can
1370 even be used to manage moderated newsgroups.
1371
1372 \subsection{The Auto-responder Category}
1373 \subsection{The Content Filtering Category}
1374 \subsection{The Topics Category}
1375
1376 \section{Membership Management}
1377 \section{Tending to Pending Moderator Requests}
1378 \section{Editing the Public HTML Pages}
1379 \section{Deleting the Mailing List}
1380
1381 \appendix
1382
1383 \section{This is an Appendix}
1384
1385 To create an appendix in a Python HOWTO document, use markup like
1386 this:
1387
1388 \begin{verbatim}
1389 \appendix
1390
1391 \section{This is an Appendix}
1392
1393 To create an appendix in a Python HOWTO document, ....
1394
1395
1396 \section{This is another}
1397
1398 Just add another \section{}, but don't say \appendix again.
1399 \end{verbatim}
1400
1401
1402 \end{document}