diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/mailman-admin.tex | 1402 |
1 files changed, 0 insertions, 1402 deletions
diff --git a/doc/mailman-admin.tex b/doc/mailman-admin.tex deleted file mode 100644 index 6a9e3c77..00000000 --- a/doc/mailman-admin.tex +++ /dev/null @@ -1,1402 +0,0 @@ -\documentclass{howto} - -\title{GNU Mailman - List Administration Manual} - -% Increment the release number whenever significant changes are made. -% The author and/or editor can define 'significant' however they like. -\release{1.0} - -% At minimum, give your name and an email address. You can include a -% snail-mail address if you like. -\author{Barry A. Warsaw} -%\authoraddress{barry (at) list dot org} - -\date{\today} % XXX update before tagging release! -\release{2.1} % software release, not documentation -\setreleaseinfo{} % empty for final release -\setshortversion{2.1} % major.minor only for software - -\begin{document} -\maketitle - -% This makes the Abstract go on a separate page in the HTML version; -% if a copyright notice is used, it should go immediately after this. -% -\ifhtml -\chapter*{Front Matter\label{front}} -\fi - -% Copyright statement should go here, if needed. -% ... - -% The abstract should be a paragraph or two long, and describe the -% scope of the document. -\begin{abstract} -\noindent -This document describes the list administrator's interface for GNU -Mailman 2.1. It contains information a list owner would need to -configure their list, either through the web interface or through -email. It also covers the moderator's interface for approving held -messages and subscription notices, and the web interface for creating -new mailing lists. In general, it does not cover the command line -interface to Mailman, installing Mailman, or interacting with Mailman -from the point of view of the user. That information is covered in -other manuals. -\end{abstract} - -\tableofcontents - -\section{Introduction to GNU Mailman} - -GNU Mailman is software that lets you manage electronic mailing lists. -It supports a wide range of mailing list types, such as general -discussion lists and announce-only lists. Mailman has extensive -features for controlling the privacy of your lists, distributing your -list as personalized postings or digests, gatewaying postings to and -from Usenet, and providing automatic bounce detection. Mailman -provides a built-in archiver, multiple natural languages, as well as -advanced content and topic filtering. - -Mailman provides several interfaces to its functionality. Most list -administrators will primarily use the web interface to customize their -lists. There is also a limited email command interface to the -administrative functions, as well as a command line interface if you -have shell access on the Mailman server. This document does not cover -the command line interface; see the GNU Mailman site administrator's -manual for more details. - -\subsection{A List's Email Addresses} - -Every mailing list has a set of email addresses that messages can be -sent to. There's always one address for posting messages to the list, -one address that bounces will be sent to, and addresses for processing -email commands. For example, for a mailing list called -\var{mylist@example.com}, you'd find these addresses: - -\begin{itemize} -\item mylist@example.com -- this is the email address people should - use for new postings to the list. - -\item mylist-join@example.com -- by sending a message to this address, - a new member can request subscription to the list. Both the - \mailheader{Subject} header and body of such a message are - ignored. Note that mylist-subscribe@example.com is an alias for - the -join address. - -\item mylist-leave@example.com -- by sending a message to this address, - a member can request unsubscription from the list. As with the - -join address, the \mailheader{Subject} header and body of the - message is ignored. Note that mylist-unsubscribe@example.com is - an alias for the -leave address. - -\item mylist-owner@example.com -- This address reaches the list owner - and list moderators directly. - -\item mylist-request@example.com -- This address reaches a mail robot - which processes email commands that can be used to set member - subscription options, as well as process other commands. - -\item mylist-bounces@example.com -- This address receives bounces from - members who's addresses have become either temporarily or - permanently inactive. The -bounces address is also a mail robot - that processes bounces and automatically disables or removes - members as configured in the bounce processing settings. Any - bounce messages that are either unrecognized, or do not seem to - contain member addresses, are forwarded to the list - administrators. - -\item mylist-confirm@example.com -- This address is another email - robot, which processes confirmation messages for subscription - and unsubscription requests. -\end{itemize} - -There's also an -admin address which also reaches the list -administrators, but this address only exists for compatibility with -older versions of Mailman. - -\subsection{Administrative Roles} - -There are two primary administrative roles for each mailing list, a -list owner and a list moderator. A list owner is allowed to change -various settings of the list, such as the privacy and archiving -policies, the content filtering settings, etc. The list owner is also -allowed to subscribe or invite members, unsubscribe members, and -change any member's subscription options. - -The list moderator on the other hand, is only allowed to approve or -reject postings and subscription requests. The list moderator can -also do things like clear a member's moderation flag, or add an -address to a list of approved non-member posters. - -Normally, the list owner and list moderator are the same person. In -fact, the list owner can always do all the tasks a list moderator can -do. Access to both the owner's configuration pages, and the -moderation pages are protected by the same password. However, if the -list owner wants to delegate posting and subscription approval -authority to other people, a separate list moderator password can be -set, giving moderators access to the approval pages, but not the -configuration pages. In this setup, list owners can still moderate -the list, of course. - -In the sections that follow, we'll often use the terms list owner and -list administrator interchangably, meaning both roles. When -necessary, we'll distinguish the list moderator explicitly. - -\subsection{A List's Web Pages} - -Every mailing list is also accessible by a number of web pages. Note -that the exact urls is configurable by the site administrator, so they -may be different than what's described below. We'll describe the most -common default configuration, but check with your site administrator -or hosting service for details. - -Mailman provides a set of web pages that list members use to get -information about the list, or manage their membership options. There -are also list archive pages, for browsing an online web-based archive -of the list traffic. These are described in more detail in the GNU -Mailman user's manual. - -Mailman also provides a set of pages for configuring an individual -list, as well as a set of pages for disposing of posting and -subscription requests. - -For a mailing list called \var{mylist} hosted at the domain -\var{lists.example.com}, you would typically access the administrative -pages by going to \code{http://lists.example.com/mailman/admin/mylist}. -The first time you visit this page, you will be presented with a login -page, asking for the list owner's password. When you enter the -password, Mailman will store a session cookie in your browser, so you -don't have to re-authenticate for every action you want to take. This -cookie is stored only until you exit your browser. - -To access the administrative requests page, you'd visit -\code{http://lists.example.com/mailman/admindb/mylist} (note the -\emph{admindb} url as opposed to the \emph{admin} url). Again, the -first time you visit this page, you'll be presented with a login page, -on which you can enter either the list moderator password or the list -owner password. Again, a session cookie is dropped in your browser. -Note also that if you've previously logged in as the list owner, you -do not need to re-login to access the administrative requests page. - -\subsection{Basic Architectural Overview} - -This section will outline the basic architecture of GNU Mailman, such -as how messages are processed by the sytem. Without going into lots -of detail, this information will help you understand how the -configuration options control Mailman's functionality. - -When mail enters the system from your mail server, it is dropped into -one of several Mailman \emph{queues} depending on the address the -message was sent to. For example, if your system has a mailing list -named \var{mylist} and your domain is \var{example.com}, people can -post messages to your list by sending them to -\var{mylist@example.com}. These messages will be dropped into the -\emph{incoming} queue, which is also colloquially called the -\emph{moderate-and-munge} queue. The incoming queue is where most of -the approval process occurs, and it's also where the message is -prepared for sending out to the list membership. - -There are separate queues for the built-in archiver, the bounce -processor, the email command processor, as well as the outgoing email -and news queues. There's also a queue for messages generated by the -Mailman system. Each of these queues typically has one \emph{queue -runner} (or ``qrunner'') that processes messages in the queue. The -qrunners are idle when there are no messages to process. - -Every message in the queues are represented by two files, a message -file and a metadata file. Both of these files share the same base -name, which is a combination of a unique hash and the Unix time that -the message was received. The metadata file has a suffix of -\file{.db} and the message file has a suffix of either \file{.msg} if -stored in plain text, or \file{.pck} if stored in a more efficient -internal representation\footnote{Specifically, a Python pickle}. - -As a message moves through the incoming queue, it performs various -checks on the message, such as whether it matches one of the -moderation criteria, or contains disallowed MIME types. Once a -message is approved for sending to the list membership, the message is -prepared for sending by deleting, adding, or changing message headers, -adding footers, etc. Messages in the incoming queue may also be -stored for appending to digests. - -\section{The List Configuration Pages} - -After logging into the list configuration pages, you'll see the -configuration options for the list, grouped in categories. All the -administrative pages have some common elements. In the upper section, -you'll see two columns labeled ``Configuration Categories''. Some -categories have sub-categories which are only visible when you click -on the category link. The first page you see after logging in will be -the ``General Options'' category. The specific option settings for -each category are described below. - -On the right side of the top section, you'll see a column labeled -``Other Administrative Activities''. Here you'll find some other -things you can do to your list, as well as convenient links to the -list information page and the list archives. Note the big ``Logout'' -link; use this if you're finished configuring your list and don't want -to leave the session cookie active in your browser. - -Below this common header, you'll find a list of this category's -configuration variables, arranged in two columns. In the left column -is a brief description of the option, which also contains a -``details'' link. For many of the variables, more details are -available describing the semantics of the various available settings, -or information on the interaction between this setting and other list -options. Clicking on the details link brings up a page which contains -only the information for that option, as well as a button for -submitting your setting, and a link back to the category page. - -On the right side of the two-column section, you'll see the variable's -current value. Some variables may present a limited set of values, -via radio button or check box arrays. Other variables may present -text entry boxes of one or multiple lines. Most variables control -settings for the operation of the list, but others perform immediate -actions (these are clearly labeled). - -At the bottom of the page, you'll find a ``Submit'' button and a -footer with some more useful links and a few logos. Hitting the -submit button commits your list settings, after they've been -validated. Any invalid values will be ignored and an error message -will be displayed at the top of the resulting page. The results page -will always be the category page that you submitted. - -\subsection{The General Options Category} - -The General Options category is where you can set a variety of -variables that affect basic behavior and public information. In the -descriptions that follow, the variable name is given first, along with -an overview and a description of what that variable controls. - -\subsubsection{General list personality} - -These variables, grouped under the general list personality section, -control some public information about the mailing list. - -\begin{description} -\item[real_name] - Every mailing list has both a \emph{posting name} and a \emph{real - name}. The posting name shows up in urls and in email addresses, - e.g. the \code{mylist} in \code{mylist@example.com}. The posting - name is always presented in lower case, with alphanumeric - characters and no spaces. The list's real name is used in some - public information and email responses, such as in the general - list overview. The real name can differ from the posting name by - case only. For example, if the posting name is \code{mylist}, the - real name can be \code{Posting}. - -\item[owner] - This variable contains a list of email addresses, one address per - line, of the list owners. These addresses are used whenever the - list owners need to be contacted, either by the system or by end - users. Often, these addresses are used in combination with the - \code{moderator} addresses (see below). - -\item[moderator] - This variable contains a list of email addresses, one address per - line, of the list moderators. These addresses are often used in - combination with the \code{owner} addresses. For example, when - you email \code{mylist-owner@example.com}, both the owner and - moderator addresses will receive a copy of the message. - -\item[description] - In the general list overview page, which shows you every available - mailing list, each list is displayed with a short description. - The contents of this variable is that description. Note that in - emails from the mailing list, this description is also used in the - comment section of the \mailheader{To} address. This text should - be relatively short and no longer than one line. - -\item[info] - This variable contains a longer description of the mailing list. - It is included at the top of the list's information page, and it - can contain HTML. However, blank lines will be automatically - converted into paragraph breaks. Preview your HTML though, - because unclosed or invalid HTML can prevent display of parts of - the list information page. - -\item[subject_prefix] - This is a string that will be prepended to the - \mailheader{Subject} header of any message posted to the list. - For example, if a message is posted to the list with a - \mailheader{Subject} like: - - \begin{verbatim} - Subject: This is a message - \end{verbatim} - - and the \code{subject_prefix} is \code{[My List] } (note the - trailing space!), then the message will be received like so: - - \begin{verbatim} - Subject: [My List] This is a message - \end{verbatim} - - If you leave \code{subject_prefix} empty, no prefix will be added - to the \mailheader{Subject}. Mailman is careful not to add a - prefix when the header already has one, as is the case in replies - for example. The prefix can also contain characters in the list's - preferred language. In this case, because of vagarities of the - email standards, you may or may not want to add a trailing space. - -\item[anonymous_list] - This variable allows you to turn on some simple anonymizing - features of Mailman. When you set this option to \emph{Yes}, - Mailman will remove or replace the \mailheader{From}, - \mailheader{Sender}, and \mailheader{Reply-To} fields of any - message posted to the list. - - Note that this option is simply an aid for anonymization, it - doesn't guarantee it. For example, a poster's identity could be - evident in their signature, or in other mail headers, or even in - the style of the content of the message. There's little Mailman - can do about this kind of identity leakage. -\end{description} - -\subsubsection{Reply-To header munging} - -This section controls what happens to the \mailheader{Reply-To} -headers of messages posted through your list. - -Beware! \mailheader{Reply-To} munging is considered a religious issue -and the policies you set here can ignite some of the most heated -off-topic flame wars on your mailing lists. We'll try to stay as -agnostic as possible, but our biases may still peak through. - -\mailheader{Reply-To} is a header that is commonly used to redirect -replies to messages. Exactly what happens when your uses reply to -such a message depends on the mail readers your users use, and what -functions they provide. Usually, there is both a ``reply to sender'' -button and a ``reply to all'' button. If people use these buttons -correctly, you will probably never need to munge -\mailheader{Reply-To}, so the default values should be fine. - -Since an informed decision is always best, here are links to two -articles that discuss the opposing viewpoints in great detail: - -\begin{itemize} - -\item \ulink{Reply-To Munging Considered - Harmful}{http://www.unicom.com/pw/reply-to-harmful.html} -\item \ulink{Reply-To Munging Considered - Useful}{http://www.metasystema.org/essays/reply-to-useful.mhtml} - -\end{itemize} - -The three options in this section work together to provide enough -flexibility to do whatever \mailheader{Reply-To} munging you might -(misguidingly :) feel you need to do. - -\begin{description} - -\item[first_strip_reply_to] - This variable controls whether any \mailheader{Reply-To} header - already present in the posted message should get removed before - any other munging occurs. Stripping this header will be done - regardless of whether or not Mailman will add its own - \mailheader{Reply-To} header to the message. - - If this option is set to \emph{No}, then any existing - \mailheader{Reply-To} header will be retained in the posted - message. If Mailman adds its own header, it will contain - addresses which are the union of the original header and the - Mailman added addresses. The mail standards specify that a - message may only have one \mailheader{Reply-To} header, but that - that header may contain multiple addresses. - -\item[reply_goes_to_list] - This variable controls whether Mailman will add its own - \mailheader{Reply-To} header, and if so, what the value of that - header will be (not counting original header stripping -- see - above). - - When you set this variable to \emph{Poster}, no additional - \mailheader{Reply-To} header will be added by Mailman. This - setting is strongly recommended. - - When you set this variable to \emph{This list}, a - \mailheader{Reply-To} header pointing back to your list's posting - address will be added. - - When you set this variable to \emph{Explicit address}, the value - of the variable \code{reply_to_address} (see below) will be - added. Note that this is one situation where - \mailheader{Reply-To} munging may have a legitimate purpose. Say - you have two lists at your site, an announce list and a discussion - list. The announce list might allow postings only from a small - number of approved users; the general list membership probably - can't post to this list. But you want to allow comments on - announcements to be posted to the general discussion list by any - list member. In this case, you can set the \mailheader{Reply-To} - header for the announce list to point to the discussion list's - posting address. - -\item[reply_to_address] - This is the address that will be added in the - \mailheader{Reply-To} header if \code{reply_goes_to_list} is set - to \emph{Explicit address}. - -\end{description} - -\subsubsection{Umbrella list settings} - -TBD. Note that umbrella lists are deprecated and will be replace with -a better mechanism for Mailman 3.0. - -\subsubsection{Notifications} - -Mailman sends notifications to the list administrators or list members -under a number of different circumstances. Most of these -notifications can be configured in this section, but see the Bounce -Processing and Auto-responder categories for other notifications that -Mailman can send. - -\begin{description} -\item[send_reminders] - By default Mailman sends all list members a monthly password - reminder. This notice serves two purposes. First, it reminds - people about all the lists they may be subscribed to on this - domain, including the lists where their subscription may be - disabled. Second, it reminds people about their passwords for - these lists, as well as the url for their personal options pages, - so that they can more easily configure their subscription options. - - Some people get annoyed with these monthly reminders, and they can - disable the reminders via their subscription options page. For - some lists, the monthly reminders aren't appropriate for any of - the members, so you can disable them list-wide by setting the - \code{send_reminders} variable to \emph{No}. - -\item[welcome_msg] - When new members are subscribed to the list, either by their own - action, or the action of a list administrator, a welcome message - can be sent to them. The welcome message contains some common - boilerplate information, such as the name of the list, - instructions for posting to the list, and the member's - subscription password. You can add additional information to the - welcome message by typing the text into the \code{welcome_msg} - text box. Note that because this text is sent as part of an - email, it should \strong{not} contain HTML. - -\item[send_welcome_msg] - This flag controls whether or not the welcome message is sent to - new subscribers. - -\item[goodbye_msg] - Like the \code{welcome_msg}, a ``goodbye'' message can be sent to - members when they unsubscribe from the list. Unlike the welcome - message, there's no boilerplate for the goodbye message. Enter - the entire goodbye message you'd like unsubscribing members to - receive into the \code{goodbye_msg} text box. - -\item[send_goodbye_msg] - This flag controls whether or not the goodbye message is sent to - unsubscribing members. - -\item[admin_immed_notify] - List moderators get notifications of pending administrative - actions, such as subscription or unsubscription requests that - require moderator approval, or posted messages that are being held - for moderator approval. List moderators will always get a daily - summary of such pending requests, but they can also get immediate - notifications when such a request is made. The - \code{admin_immed_notify} variable controls whether these - immediate notifications are sent or not. It's generally a good - idea to leave this set to \emph{Yes}. - -\item[admin_notify_mchanges] - This variable controls whether the list administrators should get - notifications when members join or leave the list. - -\item[respond_to_post_requests] - This variable controls whether the original sender of a posting - gets a notice when their message is held for moderator approval. - -\end{description} - -\subsubsection{Additional settings} - -This section contains some miscellaneous settings for your mailing -list. - -\begin{description} -\item[emergency] - When this option is enabled, all list traffic is emergency - moderated, i.e. held for moderation. Turn this option on when - your list is experiencing a flamewar and you want a cooling off - period. - -\item[new_member_options] - Each member has a set of subscription options which they can use - to control how they receive messages and otherwise interact with - the list. While the members can change these settings by logging - into their personal options page, you might want to set the - default for a number of the member options. You can do that with - this variable, but see also the other categories for other member - defaults you can set. - - This variable presents a set of checkboxes which control the - defaults for some of the member options. \emph{Conceal the - member's address} specifies whether or not the address is - displayed in the list roster. \emph{Acknowledge the member's - posting} controls whether or not Mailman sends an acknowledgement - to a member when they post a message to the list. \emph{Do not - send a copy of a member's own post} specifies whether a member - posting to the list will get a copy of their own posting. - \emph{Filter out duplicate messages to list members (if possible)} - specifies whether members who are explicitly listed as a recipient - of a message (e.g. via the \mailheader{Cc} header) will also get a - copy from Mailman. - - Of course, members can always override these defaults by making - changes on their membership options page. - -\item[administrivia] - This option specifies whether Mailman will search posted messages - for \emph{admimistrivia}, in other words, email commands which - usually should be posted to the \code{-request} address for the - list. Setting this to \emph{Yes} helps prevent such things as - unsubscribe messages getting erroneously posted to the list. - - If a message seems to contain administrivia, it is held for - moderator approval. - -\item[max_message_size] - This option specifies a maximum message size, in kilobytes, over - which the message will be held for moderator approval. - -\item[host_name] - This option specifies the host name part of email addresses used - by this list. For example, this is the \code{example.com} part of - the posting address \code{mylist@example.com}. - - It's generally not a good idea to change this value, since its - default value is specified when the mailing list is created. - Changing this to an incorrect value could make it difficult to - contact your mailing list. Also not that the url used to visit - the list's pages is not configurable through the web interface. - This is because if you messed it up, you'd have to have the site - administrator fix it. - -\item[include_rfc2369_headers] - \rfc{2369} is an internet standard that describes a bunch of - headers that mailing list managers should add to messages to make - it easier for people to interact with the list. Mail reading - programs which support this standard may provide buttons for easy - access to the list's archives, or for subscribing and - unsubscribing to the list. It's generally a good idea to enable - these headers as it provides for an improved user experience. - These headers are often called the \code{List-*} headers. - - However, not all mail readers are standards compliant yet, and if - you have a large number of members who are using non-compliant - mail readers, they may be annoyed at these headers. You should - first try to educate your members as to why these headers exist, - and how to hide them in their mail clients. As a last resort you - can disable these headers, but this is not recommended. - -\item[include_list_post_header] - The \mailheader{List-Post} header is one of the headers - recommended by \rfc{2369}. However for some announce-only mailing - lists, only a very select group of people are allowed to post to - the list; the general membership is usually not allowed to post to - such lists. For lists of this nature, the \mailheader{List-Post} - header is misleading. Select \emph{No} to disable the inclusion - of this header. (This does not affect the inclusion of the other - \code{List-*} headers.) -\end{description} - -\subsection{The Passwords Category} -As mentioned above, there are two primary administrative roles for -mailing lists. In this category you can specify the password for -these roles. - -The list owner has total control over the configuration of their -mailing list (within some bounds as specified by the site -administrator). Note that on this page, for historical reasons, the -list owner role is described here as the \emph{list administrator}. -You can set the list owner's password by entering it in the password -field on the left. You must type it twice for confirmation. Note -that if you forget this password, the only way for you to get back -into your list's administrative pages is to ask the site administrator -to reset it for you (there's no password reminders for list owners). - -If you want to delegate list moderation to someone else, you can enter -a different moderator password in the field on the right (typed twice -for confirmation). Note that if you aren't going to delegate -moderation, and the same people are going to both configure the list -and moderate postings to the list, don't enter anything into the -moderator password fields. If you do enter a separate moderator -password, be sure to fill in the \code{moderator} variable in the -\emph{General options} category page. - -\subsection{The Language Options Category} -Mailman is multilingual and internationalized, meaning you can set up -your list so that members can interact with it in any of a number of -natural languages. Of course, Mailman won't translate list -postings. :) - -However, if your site administrator has enabled its support, you can -set your list up to support any of about two dozen languages, such as -German, Italian, Japanese, or Spanish. Your list members can then -choose any of your supported languages as their \emph{preferred -language} for interacting with the list. Such things as their member -options page will be displayed in this language. Each mailing list -also has its own \emph{preferred language} which is the language the -list supports if no other language context is known. - -These variables control the language settings for your mailing list: - -\begin{description} -\item[preferred_language] - This is the list's preferred language, which is the language that - the list administrative pages will be displayed in. Also any - messages sent to the list owners by Mailman will be sent in this - language. This option is presented as a drop-down list containing - the language enabled in the \code{available_languages} variable. - -\item[available_languages] - This set of checkboxes contains all the natural languages that - your site administrator has made available to your mailing lists. - Select any language that you'd either like your members to be able - to view the list in, or that you'd like to be able to use in your - list's \code{preferred_language} variable. - -\item[encode_ascii_prefixes] - If your mailing list's preferred language uses a non-ASCII - character set and the \code{subject_prefix} contains non-ASCII - characters, the prefix will always be encoded according to the - relevant standards. However, if your subject prefix contains only - ASCII characters, you may want to set this option to \emph{Never} - to disable prefix encoding. This can make the subject headers - slightly more readable for users with mail readers that don't - properly handle non-ASCII encodings. - - Note however, that if your mailing list receives both encoded and - unencoded subject headers, you might want to choose \emph{As - needed}. Using this setting, Mailman will not encode ASCII - prefixes when the rest of the header contains only ASCII - characters, but if the original header contains non-ASCII - characters, it will encode the prefix. This avoids an ambiguity - in the standards which could cause some mail readers to display - extra, or missing spaces between the prefix and the original - header. -\end{description} - -\subsection{The Membership Management Category} - -The \emph{Membership Management} category is unlike the other -administrative categories. It doesn't contain configuration variables -or list settings. Instead, it presents a number of pages that allow -you to manage the membership of you list. This includes pages for -subscribing and unsubscribing members, and for searching for members, -and for changing various member-specific settings. - -More details on membership management are described in the Membership -Management section. - -\subsection{The Non-digest Options Category} - -Mailman delivers messages to users via two modes. List members can -elect to receive postings in bundles call \emph{digests} one or a few -times a day, or they can receive messages immediately whenever the -message is posted to the list. This latter delivery mode is also -called \emph{non-digest delivery}. There are two administrative -categories available for separately controlling digest and non-digest -delivery. You can even disable one or the other forms of delivery -(but not both). - -Both kinds of delivery can have list-specific headers and footers -added to them which can contain other useful information you want your -list members to see. For example, you can include instructions for -unsubscribing, or a url to the lists digest, or any other information. - -Non-digest deliveries can also be \emph{personalized} which means -certain parts of the message can contain information tailored to the -member receiving the message. For example, the \mailheader{To} header -will contain the address of the member when deliveries are -personalized. Footers and headers can contain personalized -information as well, such as a link to the individual user's options -page. - -In addition, personalized messages will contain extra information that -Mailman can use to unambiguously track bounces from members. -Ordinarily, Mailman does some pattern recognition on bounce messages -to determine list members whose addresses are no longer valid, but -because of the vagaries of mail systems, and the countless forwards -people can put in place, it's often the case that bounce messages -don't contain any useful information in them. Personalized messages -avoid this problem by encoding information in certain headers that -unambiguously identify the recipient of a message. If that message -bounces, Mailman will know exactly which member it was intended for. - -Note that because personalization requires extra system resources, it -must be enabled by the site administrator before you can choose it. - -Here are the variables which control non-digest delivery: - -\begin{description} -\item[nondigestable] - This option controls whether members can receive immediate - delivery or not. If not, they will be forced to receive messages - in digests. You can't disable non-digest delivery if digests are - already disabled. - -\item[personalize] - This option turns on message personalization. - -\item[msg_header] - This text box lets you enter information that will be included in - the header of every non-digest message sent through the - list. - - See below for more information on what can go in the headers and - footers. If you leave this text box empty, no header will be - added. - -\item[msg_footer] - Just like with the header, you can add a footer to every message. - The same rules apply to footers as apply to headers. -\end{description} - -Headers and footers can contain any text you want. For non-English -lists, the headers and footers can contain any character in the -character set of the list's preferred language. The headers and -footers can also contain \emph{substitution variables} which Mailman -will fill in with information taken from the mailing list. These -substitutions are in Python string interpolation format, where -something like \code{\%(list_name)s} is substituted with he name of -the mailing list. Note that the trailing \samp{s} is -required\footnote{The site administrator can configure lists to use a -simpler interpolation format, where \code{\$list_name} or -\code{\$\{list_name\}} would be substituted with the mailing list's -name. Ask your site administrator if the've configured your list this -way.}. - -For example, a footer containing the following text: - -\begin{verbatim} -This is the \%(list_name)s mailing list -Description: \%(description)s -\end{verbatim} - -might get attached to postings like so: - -\begin{verbatim} -This is the Example mailing list -Description: An example of Mailman mailing lists -\end{verbatim} - -Here is the list of substitution variables available for your headers -and footers: - -\begin{description} -\item[real_name] - This is the value of the \code{real_name} configuration variable - in the General options category. - -\item[list_name] - This is the canonical name of the mailing list. In other words - it's the posting address of the list\footnote{For backward - compatibility, the variable \code{_internal_name} is - equivalent.}. - -\item[host_name] - This is the domain name part of the email address for this list. - -\item[web_page_url] - This is the base url for contacting the list via the web. It can - be appended with \code{listinfo/\%(list_name)s} to yield the - general list information page for the mailing list. - -\item[description] - The brief description of the mailing list. - -\item[info] - This is the full description of the mailing list. - -\item[cgiext] - This is the extension added to CGI scripts. It might be the empty - string, \code{.cgi}, or something else depending on how your site - is configured. -\end{description} - -Note that \code{real_name}, \code{host_name}, \code{description}, and -\code{info} substitution variables take their values from the list -configuration variables of the same name. - -When personalization is enabled, the following substitution variables -are also available: - -\begin{description} -\item[user_address] - The address of the recipient of the message, coerced to lower case. - -\item[user_delivered_to] - The case-preserved address that the user subscribed to the mailing - list with\footnote{Usually it makes no difference which of - \code{user_address} and \code{user_delivered_to} is used, but it's - important to remember that they can be different. When they're - different, Mailman always uses the lower case address as the key - to the member's subscription information, but it always delivers - messages to the case-preserved version.}. - -\item[user_password] - The user's password, in clear text. - -\item[user_name] - The user's full name. - -\item[user_optionsurl] - The url to the user's personal options page. -\end{description} - -\subsection{The Digest Options Category} - -Digest delivery is a way to bundle many articles together into one -package, which can be delivered once per day (if there were any posted -articles), or whenever the package is bigger than a specified limit. -Some users may prefer this style of delivery for higher traffic lists -since they will receive fewer messages. - -Mailman supports two standard digest formats, and if digests are -enabled, users can select which of the two formats they receive. One -is MIME digests, where each message is an attachment inside a -\mimetype{multipart/digest}. This format also contains a summary -table of contents, and of course the an optional header and footer, -and it retains most of the headers of the original messages. - -The second type is called ``plaintext'' digests because they are -readable in mail readers that don't support MIME. Actually, they -adhere to the \rfc{1153} digest standard. The retain some, but not -all of the original messages, but can also include a summary and -headers and footers. - -Like non-digest delivery, you can enable or disable digest delivery, -but you cannot disable both types of delivery. You can specify -different headers and footers for digest and non-digest deliveries. -You cannot personalize digest deliveries. - -As list administrator, you may want to send an urgent message to all -list members, bypassing the normal digest bundling. To do this, send -the message with a \mailheader{Urgent} header, where the value of the -header is the list administrator's password. Non-digest members will -receive the message like normal, but digest members will receive the -message immediately\footnote{They'll also receive the message in the -digest.}. - -Here are the variables which control digest delivery: - -\begin{description} -\item[digestable] - The option controls whether members can receive digest deliveries - or not. If not, they will be forced to receive immediate - deliveries. You can't disable digests if non-digests are already - disabled. - -\item[digest_is_default] - Controls which style of delivery is the default for new members. - You can choose \emph{Regular} (non-digest) or \emph{Digest} - delivery. - -\item[mime_is_default_digest] - If a member is allowed to choose digests, this variable controls - which is the default digest style they will receive. \emph{Plain} - digests are \rfc{1153} format as described above. - -\item[digest_size_threshold] - Normally, digest members get at least one message per day, if - there have been any messages posted to the list. However, for - high volume lists, you may want to send out digests when the size - has reached a certain threshold, otherwise, the one digest they - receive could be huge. This variable controls the size threshold - by specifying the maximum digest size in kilobytes. Note that - this threshold isn't exact. Set this variable to zero to specify - that there is no size threshold, in which case no more than one - digest will be sent out per day. - -\item[digest_send_periodic] - This variable actually controls whether or not a digest is sent - daily when the size threshold has not yet been met. If set to - \emph{No}, then digests will only be sent when they are bigger - than \code{digest_size_threshold}. - -\item[digest_header] - This text box lets you enter information that will be included in - the header of every digest message sent through the list. The - same information can go in this header as can go in the - \code{msg_header}, except for the personalization variables. - -\item[digest_footer] - Just like with the header, you can add a footer to every message. - The same rules apply to digest footers as apply to digest headers. - -\item[digest_volume_frequency] - Each digest is numbered with a volume and an issue. This variable - controls how often a new digest volume is sent. When the digest - volume number is incremented, the issue number is reset to 1. - -\item[_new_volume] - This is an action variable, which forces an increment of the - volume number as soon as you submit the form. - -\item[_send_digest_now] - This is another action variable. Select \emph{Yes}, submit the - form, and the current digest is packaged up and sent to digest - members, regardless of size (well, there has to be at least one - message in the digest). -\end{description} - -\subsection{The Privacy Options Category} - -The Privacy category lets you control how much of the list's -information is public, as well as who can send messages to your list. -It also contains some spam detection filters. Note that this section -is not used to control whether your list's archives are public or -private; for that, use the \ref{Archiving options} category. - -There are four sub-categories: -\begin{itemize} -\item Subscription rules -- i.e. the rules for joining and leaving - your mailing list - -\item Sender filters -- the rules for who may post messages to your - list - -\item Recipient filters -- moderation rules based on the recipient of - the message - -\item Spam filters -- some regular expression based rules for header - matching -\end{itemize} - -The sender, recipient, and spam filtering rules are part of the -general list moderation features of Mailman. When a message is posted -to the list, it is matched against a number of criteria, the outcome -of which determines whether the message is reflected to the membership -or not. In general, the outcome is one of four states: - -\begin{itemize} -\item Approved or Accepted -- the message may be sent on to the - members of the mailing list. - -\item Hold -- the message will be held for moderator approval. The - list owners and moderators will then have to explicitly approve - the message before the list members will see it. - -\item Reject -- the message is bounced back to the original sender, - often with a notice containing the reason the message was - rejected. The list members never see rejected messages. - -\item Discard -- the message is simply thrown away without further - processing. -\end{itemize} - -Many of the fields in this section are text boxes accepting addresses, -one per line. Unless otherwise noted, these also accept regular -expressions which will be matched against an address, if the line -begins with a \^ (caret) character. - -\subsubsection{Subscription rules} - -This subcategory controls the rules for exposing the existance of this -list, and for what new members must do in order to subscribe to the -list. - -\begin{description} -\item[advertised] - This option controls whether this list will show up in the list - overview for the site. Normally, an overview contains the name - and short description of every mailing list in the virtual - domain. By setting this variable to \emph{No}, it will not show - up in this overview, nor will it show up in the administrative - overview. The only way then to find the list is to guess (or - know!) its name. - -\item[subscribe_policy] - This option controls the steps that a new member must take to join - the list. The available options may differ based on some defaults - that the site administrator chooses. They are: - - \begin{itemize} - \item None -- No verification is done on the subscribing - member. This is also called \emph{open subscriptions} and is - generally disabled by default. The site administrator must - allow list admins to choose this option; if not, this option - will not be presented to you. - - \item Confirm -- An email confirmation step is required before the - address is added to the list. When a member requests - subscription, either via the web page or by sending a - message to \var{yourlist}\code{-join@example.com}, Mailman - will send a confirmation message to the requesting address. - This mail-back confirmation contains a unique identifier, - which the requester can present to Mailman in order to - confirm their subscription. This can be done either by - replying to the mail-back, or by visiting the url in the - mail-back message. The url points to a page that lets the - user either discard or confirm their request. - - \item Require approval -- All subscription requests are held for - approval of the list moderator. No mail-back confirmation - is sent, but the list admins will recieve a message - indicating that approval is pending. - - \item Confirm and approve -- Here, a mail-back notice must first - be confirmed by the requester. Once confirmed, the list - moderator must then approve the request. This is the most - secure method for users to subscribe since it both verifies - the requesting address, and forces the list moderators to - approve the request. - - \end{itemize} - -\item[unsubscribe_policy] - Specifies whether the list moderator's approval is required for - unsubscription requests. \emph{No} is highly recommended, since - it is exceedingly impolite to not allow people to leave a mailing - list whenever they want (i.e. opt-out). \emph{Yes} is useful in - some specialized contexts; e.g. you may not want to allow - employees to unsubscribe from the company newsletter. - -\item[ban_list] - This contains a list of addresses (or regular expressiosn), one - per line, that are banned from ever subscribing to your mailing - list. If a match occurs during the subscription process, the - request will be automatically rejected, and the requester will get - a rejection notice. You can use this to permanently ban - troublesome posters to a members-only list. - -\item[private_roster] - This specifies who is allowed to view the roster of member - addresses. If you choose \emph{Anyone}, then the list membership - is completely public. You can limit exposure of the roster to - just list members, or just to the list administrators. In the - former case, a user must enter a valid member's address and - password before they can view the roster. In the latter case, a - list administrator's password must be enter; if a matching admin - password is entered, address field is ignored. - -\item[obscure_addresses] - Controls whether some simple obfuscation of addresses is used when - member addresses are included on web pages. This should reduce - the opportunity for email address harvesting by spammers, although - it probably doesn't eliminate it. -\end{description} - -\subsubsection{Sender filters} - -When a message is posted to the list, a series of moderation criteria are -applied to determine the disposition of the message. This section -contains the modeation controls for postings from both members and -non-members. - -\begin{description} -\item[default_member_moderation] - Member postings are held for moderation if their \emph{moderation - flag} is turned on. Note that only the list administrators can - change the value of a member's moderation flag. - - You can control whether new members get their moderation flag - turned on or off by default when they subscribe to the list. By - turning this flag off by default, postings by members will be - allowed without further intervention (barring other restrictions - such as size or implicit recipient lists -- see below). By - turning the flag on, you can quarantine new member postings to - make sure that they meet your criteria for netiquette, topicality, - etc. Once you determine that the new member understands the - community's posting rules, you can turn off their moderation flag - and let their postings go through unstopped. - - E-newsletter style lists can also be set up by using the - moderation flag. By setting the \code{member_moderation_action} - to \emph{Reject}, and by turning off the moderation flag for just - the few approved senders, your list will operate in essentially a - one-way direction. Note that you'd also need to reject or discard - postings from non-members. - -\item[member_moderation_action] - This is the action to take for postings from a member who's - moderation flag is set. For typical discussion lists, you'll - likely set this to \emph{Hold} so that the list moderator will get - a chance to manually approve, reject, or discard the message. For - e-newsletter and announcement lists, you might want to set this to - \emph{Reject} or \emph{Discard}. - - Note that when a moderated member posts to your list, and the - \code{member_moderation_action} is set to \emph{Hold}, the message - will appear on the administrative requests page. When you dispose - of the message, you will be given an opportunity to clear the - moderation flag at the same time. If you're quarantining new - posts, this makes it very convenient to both approve a new - member's post and de-moderate them at the same time. - -\item[member_moderation_notice] - When a member's moderation flag is turned on and - \code{member_moderation_action} is \emph{Reject}, this variable - contains the text sent in the rejection notice. -\end{description} - -The next batch of variables controls what happens when non-members -post messages to the list. Each of these accepts one email address -per line; regular expressions are allowed if the line starts with the -\^ (caret) character. These address lists are always consulted in the -order in which they're presented on this page (i.e. accepts first, -followed by holds, rejections, and discards). - -\begin{description} -\item[accept_these_nonmembers] - Postings from non-members whose addresses match this list are - accepted, barring other list restrictions due to size, implicit - recipients, etc. You might want to add alternative addresses of - approved posters to this list. - -\item[hold_these_nonmembers] - Postings from non-members whose addresses match this list are - held for moderator approval. - -\item[reject_these_nonmembers] - Postings from non-members whose addresses match this list are - rejected, i.e. bounced back to the original sender. There - currently is no way to add additional text to the rejection - message. - -\item[discard_these_nonmembers] - Postings from non-members whose addresses match this list are - discarded, with no bounce back message. You might want to add the - addresses of known spammers to this list. - -\item[generic_nonmember_action] - This variable controls what happens to non-member posts when the - address of the sender doesn't match any of the above four lists. - If you set this to \emph{Hold}, the posting will appear on the - administrative requests page, and you will be given an opportunity - to add the non-member to one of the above four lists at the same - time you dispose of the held message. - -\item[forward_auto_discards] - When messages from non-members are discarded, either because the - sender address matched \code{discard_these_nonmembers}, or because - \code{generic_nonmember_action} is \emph{Discard}, you can choose - whether such messages are forwarded to the lsit administrators or - not. -\end{description} - -\subsubsection{Recipient Filters} - -The variables in this section control various filters based on the -recipient of the message. - -\begin{description} -\item[require_explicit_destination] - This controls whether the mailing list posting address must be - explicitly named in the \mailheader{To} or \mailheader{Cc} - recipient lists. The main reason why it wouldn't is if the - message was blind-carbon-copied (i.e. \mailheader{Bcc}'d) to the - list. Spammers like to do this, but sometimes legitimate messages - are forwarded to the list this way. - - If the list is not explicitly addressed and this setting is turned - on, the message will be held for moderator approval. - -\item[acceptable_aliases] - This is the list of alternative addresses that are acceptable as a - list posting address when \code{require_explicit_destination} is - enabled. This is useful for when there aliases for the main - posting address (e.g. \code{help@example.com} may be an alias for - \code{help-list@example.com}). - -\item[max_num_recipients] - This is the maximum number of explicit recipients that are allowed - on the posted message. Spammers sometimes send messages with lots - of explicit recipients, so setting this number to a reasonable - value may cut down on spam. -\end{description} - -\subsubsection{Spam Filters} - -This section provides some adjuncts to spam fighting tools; it -doesn't replace dedicated anti-spam tools such as SpamAssassin or -Spambayes. - -\begin{description} -\item[bounce_matching_headers] - This variable contains header regular expressions, one per line, - and if any of a message's headers matches one of these patterns, - it will be held for moderation. The format is a colon separated - header and value, where the header is case insensitive and the - value is any valid Python regular expression. Lines that start - with \# are ignored. - - This variable can be used to catch known spammers by writing - regexps that match against \mailheader{To} or \mailheader{Cc} - lines, or known-bad \mailheader{Message-ID}s. Perhaps more useful - though are patterns that match headers added by spam detection - tools higher up in the tool chain. For example, you might - configure SpamAssassin to add an \mailheader{X-Spam-Score} header - with between zero and 5 stars depending on the spam score. Then - you can add a line to this variable like: - - \begin{verbatim} - X-Spam-Score: [*]{3,5} - \end{verbatim} - - This line will match from 3 to 5 stars in the value of this - field. -\end{description} - -\subsection{The Bounce Processing Category} - -These policies control the automatic bounce processing system in -Mailman. Here's an overview of how it works: - -When a bounce is received, Mailman tries to extract two pieces of -information from the message: the address of the member the message -was intended for, and the severity of the problem causing the bounce. -The severity can be either \emph{hard} for fatal errors, or -\emph{soft} for transient errors. When in doubt, a hard severity is -used. - -If no member address can be extracted from the bounce, then the bounce -message is usually discarded. Every member has a \emph{bounce score}, -initialized at zero, and every time we encounter a bounce from a -member we increment that member's score. Hard bounces increment by 1 -while soft bounces increment by 0.5. We only increment the bounce -score once per day, so even if we receive ten hard bounces from a -member per day, their score will increase by only 1 for that day. - -When a member's bounce score is greater than the \emph{bounce score -threshold} (see below), the member's subscription is disabled. Once -disabled, the member will not receive any postings from the list until -their membership is explicitly re-enabled, either by the list -administrator or the user. However, they will receive occasional -reminders that their membership has been disabled, and these reminders -will include information about how to re-enable their membership. You -can control both the number of reminders the member will receive and -the frequency with which these reminders are sent. - -There is one other important configuration variable; after a certain -period of time -- during which no bounces from the member are received --- the bounce information is considered stale and discarded. Thus by -adjusting this value, and the score threshold, you can control how -quickly bouncing members are disabled. You should tune both of these -to the frequency and traffic volume of your list. - -\begin{description} - -\item[bounce_processing] - Specifies whether or not this list should do automatic bounce - processing. - -\item[bounce_score_threshold] - This is the bounce score above which a member's subscription will - be automatically disabled. When the subscription is re-enabled, - their bounce score will be reset to zero. This value can be a - floating point number. - -\item[bounce_info_stale_after] - Thenumber of days after which a member's bounce information is - considered stale. If no new bounces have been received in the - interrim, the bounce score is reset to zero. This value must be - an integer. - -\item[bounce_you_are_disabled_warnings] - The number of notices a disabled member will receive before their - address is removed from the mailing list's roster. Set this to 0 - to immediately remove an address from the list once their bounce - score exceeds the threshold. This value must be an integer. - -\item[bounce_you_are_disabled_warnings_interval] - The number of days between each disabled notification. - -\item[bounce_unrecognized_goes_to_list_owner] - This variable controls whether unrecognized bounces are discarded, - or forwarded on the list administrator. The bounce detector isn't - perfect, although personalization can make it much more accurate. - The list owner may want to receive unrecognized bounces so that - they can manually disable or remove such members. - -\item[bounce_notify_owner_on_disable] - This option controls whether or not the list owner is notified - when a member's subscription is automatically disabled due to - their bounce threshold being reached. - -\item[bounce_notify_owner_on_removal] - This option controls whether or not the list owner is notified - when a member is removed from the list after their disabled - notifications have been exhausted. -\end{description} - -\subsection{The Archiving Options Category} - -Mailman comes with a built-in web-based archiver called -\emph{Pipermail}, although it can be configured to use external, -third party archivers. - -\begin{description} - -\item[archive] - This option tells Mailman whether to archive messages it receives - or not, regardless of whether Pipermail or a third party archiver - is used. Turn this off if you don't want to archive messages. - - Note that senders can control whether their own posts are - archived, on an individual per-message basis. If the posted - message has a \mailheader{X-No-Archive} header (regardless of - value), or a \mailheader{X-Archive} header with a value of - \code{No} (case insensitive), then the message will not be - archived, although it will be treated as normal in all other - ways. - -\item[archive_private] - Controls whether Pipermail archives are private or public. - Private archives require a valid member address and password, or a - list administrator password in order to access them. This - option has no effect when a third party archiver is used. - -\item[archive_volume_frequency] - Controls how Pipermail splits messages in the archive. The most - common option is \emph{Monthly} meaning a new archive volume is - started every month. Very high volume lists may want a shorter - frequency (e.g. \emph{Weekly} or \emph{Daily}) where as lower - volume lists may want a longer frequency (e.g. \emph{Yearly}). - This option has no effect when a third party archiver is used. -\end{description} - -\subsection{The Mail/News Gateway Category} - -Mailman has a sophisticated mail-to-news gateway feature. It can -independently gate messages from news to mail and vice versa, and can -even be used to manage moderated newsgroups. - -\subsection{The Auto-responder Category} -\subsection{The Content Filtering Category} -\subsection{The Topics Category} - -\section{Membership Management} -\section{Tending to Pending Moderator Requests} -\section{Editing the Public HTML Pages} -\section{Deleting the Mailing List} - -\appendix - -\section{This is an Appendix} - -To create an appendix in a Python HOWTO document, use markup like -this: - -\begin{verbatim} -\appendix - -\section{This is an Appendix} - -To create an appendix in a Python HOWTO document, .... - - -\section{This is another} - -Just add another \section{}, but don't say \appendix again. -\end{verbatim} - - -\end{document} |