The start of a manual for list administrators. Written in Python

mkhowto format, you'll need the Python documentation tool chain to
produce the pdf or html (but that's easy if you have Python's source
distro).

Contributions are welcome!  I'll keep working on this during ball
games, though. :)

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}