diff options
| -rw-r--r-- | doc/mailman-admin.tex | 484 |
1 files changed, 484 insertions, 0 deletions
diff --git a/doc/mailman-admin.tex b/doc/mailman-admin.tex new file mode 100644 index 000000000..ea77dcd23 --- /dev/null +++ b/doc/mailman-admin.tex @@ -0,0 +1,484 @@ +\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@zope.com} + +\date{\today} % XXX update before tagging release! +\release{2.1} % software release, not documentation +\setreleaseinfo{b4} % 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. + +The other thing you'll see in the upper section is the emergency +moderation checkbox. This is described in more detail in the +emergency moderation section. + +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} + +\subsection{The Passwords Category} +\subsection{the Language Options Category} +\subsection{The Membership Management Category} +\subsection{The Non-digest Options Category} +\subsection{The Digest Options Category} +\subsection{The Privacy Options Category} +\subsection{The Bounce Processing Category} +\subsection{The Archiving Options Category} +\subsection{The Mail <-> News Gateway Category} +\subsection{The Auto-responder Category} +\subsection{The Content Filtering Category} +\subsection{The Topics Category} +\subsection{Emergency Moderation} + +\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} |