1 files changed, 1803 insertions, 0 deletions

diff --git a/docs/howtos/mailman-install.tex b/docs/howtos/mailman-install.tex
new file mode 100644
index 000000000..a0dcbea20
--- /dev/null
+++ b/docs/howtos/mailman-install.tex
@@ -0,0 +1,1803 @@
+\documentclass{howto}
+
+\title{GNU Mailman - Installation Manual}
+\author{Barry Warsaw}
+\authoraddress{\email{barry(at)python.org}}
+
+\date{\today}
+\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
+
+\begin{abstract}
+\noindent
+This document describes how to install GNU Mailman on a POSIX-based system
+such as \UNIX{}, MacOSX, or GNU/Linux.  It will cover basic installation
+instructions, as well as guidelines for integrating Mailman with your web and
+mail servers.
+
+\noindent
+The GNU Mailman website is at \url{http://www.list.org}
+\end{abstract}
+
+% The ugly "%begin{latexonly}" pseudo-environment supresses the table
+% of contents for HTML generation.
+%
+%begin{latexonly}
+\tableofcontents
+%end{latexonly}
+
+
+\section{Installation Requirements}
+
+GNU Mailman works on most POSIX-based systems such as \UNIX{}, MacOSX, or
+GNU/Linux.  It does not currently work on Windows.  You must have a mail
+server that you can send messages to, and a web server that supports the
+CGI/1.1 API.  \ulink{Apache}{http://httpd.apache.org} makes a fine choice for
+web server, and mail servers such as
+\ulink{Postfix}{http://www.postfix.org},
+\ulink{Exim}{http://www.exim.org},
+\ulink{Sendmail}{http://www.sendmail.org}, and
+\ulink{qmail}{http://cr.yp.to/qmail.html} should
+work just fine.
+
+To install Mailman from source, you will need an ANSI C compiler to build
+Mailman's security wrappers.  The
+\ulink{GNU C compiler gcc}{http://gcc.gnu.org} 2.8.1 or later is known
+to work well.
+
+You must have the \ulink{Python}{http://www.python.org} interpreter installed
+somewhere on your system.  Mailman 2.1 requires Python 2.1 or newer, although
+Python 2.3 or newer is recommended.
+
+\section{Set up your system}
+
+Before installing Mailman, you need to prepare your system by adding certain
+users and groups.  You will need to have root privileges to perform the steps
+in this section.
+
+\subsection{Add the group and user}
+
+Mailman requires a unique user and group name which will own its files, and
+under which its processes will run.  Mailman's basic security is based on
+group ownership permissions, so it's important to get this step
+right\footnote{You will be able to check and repair your permissions after
+installation is complete.}.  Typically, you will add a new user and a new
+group, both called \code{mailman}.  The \code{mailman} user must be a member
+of the \code{mailman} group.  Mailman will be installed under the
+\code{mailman} user and group, with the set-group-id (setgid) bit enabled.
+
+If these names are already in use, you can choose different user and group
+names, as long as you remember these when you run \program{configure}.  If you
+choose a different unique user name, you will have to specify this with
+\program{configure}'s \longprogramopt{with-username} option, and if you choose
+a different group name, you will have to specify this with
+\program{configure}'s \longprogramopt{with-groupname} option.
+
+On Linux systems, you can use the following commands to create these
+accounts.  Check your system's manual pages for details:
+
+\begin{verbatim}
+    % groupadd mailman
+    % useradd -c''GNU Mailman'' -s /no/shell -d /no/home -g mailman mailman
+\end{verbatim}
+
+\subsection{Create the installation directory\label{create-install-dir}}
+Typically, Mailman is installed into a single directory, which includes both
+the Mailman source code and the run-time list and archive data.  It is
+possible to split the static program files from the variable data files and
+install them in separate directories.  This section will describe the
+available options.
+
+The default is to install all of Mailman to
+\file{/usr/local/mailman}\footnote{This is the default for Mailman 2.1.
+Earlier versions of Mailman installed everything under \file{/home/mailman} by
+default.}.  You can change this base installation directory (referred to here
+as \var{\$prefix}) by specifying the directory with the
+\longprogramopt{prefix} \program{configure} option.  If you're upgrading from
+a previous version of Mailman, you may want to use the \longprogramopt{prefix}
+option unless you move your mailing lists.
+
+\begin{notice}[warning]
+You cannot install Mailman on a filesystem that is mounted with the
+\code{nosuid} option.  This will break Mailman, which relies on setgid
+programs for its security.  If this describes your environment, simply install
+Mailman in a location that allows setgid programs.
+\end{notice}
+
+Make sure the installation directory is set to group \code{mailman} (or
+whatever you're going to specify with \longprogramopt{with-groupname}) and has
+the setgid bit set\footnote{BSD users should see the \ref{bsd-issues} section
+for additional information.}.  You probably also want to guarantee that this
+directory is readable and executable by everyone.  For example, these shell
+commands will accomplish this:
+
+\begin{verbatim}
+    % cd $prefix
+    % chgrp mailman .
+    % chmod a+rx,g+ws .
+\end{verbatim}
+
+You are now ready to configure and install the Mailman software.
+
+\section{Build and install Mailman\label{building}}
+
+\subsection{Run \program{configure}}
+
+Before you can install Mailman, you must run \program{configure} to set
+various installation options your system might need.
+
+\begin{notice}[note]
+Take special note of the \longprogramopt{with-mail-gid} and
+\longprogramopt{with-cgi-gid} options below.  You will probably need to use
+these.
+\end{notice}
+
+You should \strong{not} be root while performing the steps in this section.
+Do them under your own login, or whatever account you typically use to install
+software.  You do not need to do these steps as user \code{mailman}, but you
+could.  However, make sure that the login used is a member of the
+\code{mailman} group as that that group has write permissions to the
+\var{\$prefix} directory made in the previous step.  You must also have
+permission to create a setgid file in the file system where it resides (NFS
+and other mounts can be configured to inhibit setgid settings).
+
+If you've installed other GNU software, you should be familiar with the
+\program{configure} script.  Usually you can just \program{cd} to the
+directory you unpacked the Mailman source tarball into, and run
+\program{configure} with no arguments:
+
+\begin{verbatim}
+  % cd mailman-<version>
+  % ./configure
+  % make install
+\end{verbatim}
+
+The following options allow you to customize your Mailman
+installation.
+
+\begin{description}
+\item[\longprogramopt{prefix}=\var{dir}]
+    Standard GNU configure option which changes the base directory that
+    Mailman is installed into.  By default \var{\$prefix} is
+    \file{/usr/local/mailman}.  This directory must already exist, and be set
+    up as described in \ref{create-install-dir}.
+
+\item[\longprogramopt{exec-prefix}=\var{dir}]
+    Standard GNU configure option which lets you specify a different
+    installation directory for architecture dependent binaries.
+
+\item[\longprogramopt{with-var-prefix}=\var{dir}]
+    Store mutable data under \var{dir} instead of under the \var{\$prefix} or
+    \var{\$exec_prefix}.  Examples of such data include the list archives and
+    list settings database.
+
+\item[\longprogramopt{with-python}=\file{/path/to/python}]
+    Specify an alternative Python interpreter to use for the wrapper programs.
+    The default is to use the interpreter found first on your shell's
+    \var{\$PATH}.
+
+\item[\longprogramopt{with-username}=\var{username-or-uid}]
+    Specify a different username than \code{mailman}.  The value of this
+    option can be an integer user id or a user name.  Be sure your
+    \var{\$prefix} directory is owned by this user.
+
+\item[\longprogramopt{with-groupname}=\var{groupname-or-gid}]
+    Specify a different groupname than \code{mailman}.  The value of this
+    option can be an integer group id or a group name.  Be sure your
+    \var{\$prefix} directory is group-owned by this group.
+
+\item[\longprogramopt{with-mail-gid}=\var{group-or-groups}]
+    Specify an alternative group for running scripts via the mail wrapper.
+    \var{group-or-groups} can be a list of one or more integer group ids or
+    symbolic group names.  The first value in the list that resolves to an
+    existing group is used.  By default, the value is the list \code{mailman},
+    \code{other}, \code{mail}, and \code{daemon}.
+
+    \begin{notice}[note]
+    This is highly system dependent and you must get this right, because the
+    group id is compiled into the mail wrapper program for added security.  On
+    systems using \program{sendmail}, the \file{sendmail.cf} configuration
+    file designates the group id of \program{sendmail} processes using the
+    \var{DefaultUser} option.  (If commented out, it still may be indicating
+    the default...)
+    \end{notice}
+
+    Check your mail server's documentation and configuration files to find the
+    right value for this switch.
+
+\item[\longprogramopt{with-cgi-gid}=\var{group-or-groups}]
+    Specify an alternative group for running scripts via the CGI wrapper.
+    \var{group-or-groups} can be a list of one or more integer group ids or
+    symbolic group names.  The first value in the list that resolves to an
+    existing group is used.  By default, the value is the the list
+    \code{www}, \code{www-data}, and \code{nobody}.
+
+    \begin{notice}[note]
+    The proper value for this is dependent on your web server configuration.
+    You must get this right, because the group id is compiled into the CGI
+    wrapper program for added security, and no Mailman CGI scripts will run if
+    this is incorrect.
+    \end{notice}
+
+    If you're using Apache, check the values for the \var{Group} option in
+    your \file{httpd.conf} file.
+
+\item[\longprogramopt{with-cgi-ext}=\var{extension}]
+    Specify an extension for cgi-bin programs.  The CGI wrappers placed in
+    \file{\var{\$prefix}/cgi-bin} will have this extension (some web servers
+    require an extension).  \var{extension} must include the leading dot.
+
+\item[\longprogramopt{with-mailhost}=\var{hostname}]
+    Specify the fully qualified host name part for outgoing email.  After the
+    installation is complete, this value can be overriden in
+    \file{\var{\$prefix}/Mailman/mm_cfg.py}.
+
+\item[\longprogramopt{with-urlhost}=\var{hostname}]
+    Specify the fully qualified host name part of urls.  After the
+    installation is complete, this value can be overriden in
+    \file{\var{\$prefix}/Mailman/mm_cfg.py}.
+
+\item[\longprogramopt{with-gcc}=no]
+    Don't use gcc, even if it is found.  In this case, \program{cc} must be
+    found on your \var{\$PATH}.
+
+\end{description}
+
+\subsection{Make and install}
+
+Once you've run \program{configure}, you can simply run \program{make}, then
+\program{make install} to build and install Mailman.
+
+\section{Check your installation}
+
+After you've run \program{make install}, you should check that your
+installation has all the correct permissions and group ownerships by running
+the \program{check_perms} script.  First change to the installation
+(i.e. \var{\$prefix}) directory, then run the \program{bin/check_perms}
+program.  Don't try to run bin/check_perms from the source directory; it will
+only run from the installation directory.
+
+If this reports no problems, then it's very likely <wink> that your
+installation is set up correctly.  If it reports problems, then you can either
+fix them manually, re-run the installation, or use \program{bin/check_perms}
+to fix the problems (probably the easiest solution):
+
+\begin{itemize}
+\item You need to become the user that did the installation, and that owns all
+      the files in \var{\$prefix}, or root.
+
+\item Run \program{bin/check_perms -f}
+
+\item Repeat previous step until no more errors are reported!
+\end{itemize}
+
+\begin{notice}[warning]
+If you're running Mailman on a shared multiuser system, and you have mailing
+lists with private archives, you may want to hide the private archive
+directory from other users on your system.  In that case, you should drop the
+other execute permission (o-x) from the \file{archives/private} directory.
+However, the web server process must be able to follow the symbolic link in
+public directory, otherwise your public Pipermail archives will not work.  To
+set this up, become root and run the following commands:
+
+\begin{verbatim}
+# cd <prefix>/archives
+# chown <web-server-user> private
+# chmod o-x private
+\end{verbatim}
+
+You need to know what user your web server runs as.  It may be \code{www},
+\code{apache}, \code{httpd} or \code{nobody}, depending on your server's
+configuration.
+\end{notice}
+
+\section{Set up your web server}
+
+Congratulations!  You've installed the Mailman software.  To get everything
+running you need to hook Mailman up to both your web server and your mail
+system.
+
+If you plan on running your mail and web servers on different machines,
+sharing Mailman installations via NFS, be sure that the clocks on those two
+machines are synchronized closely.  You might take a look at the file
+\file{Mailman/LockFile.py}; the constant \var{CLOCK_SLOP} helps the locking
+mechanism compensate for clock skew in this type of environment.
+
+This section describes some of the things you need to do to connect Mailman's
+web interface to your web server.  The instructions here are somewhat geared
+toward the Apache web server, so you should consult your web server
+documentation for details.
+
+You must configure your web server to enable CGI script permission in the
+\file{\var{\$prefix}/cgi-bin} to run CGI scripts.  The line you should add
+might look something like the following, with the real absolute directory
+substituted for \var{\$prefix}, of course:
+
+\begin{verbatim}
+    Exec        /mailman/*      $prefix/cgi-bin/*
+\end{verbatim}
+% $ - emacs turd
+
+  or:
+
+\begin{verbatim}
+    ScriptAlias /mailman/       $prefix/cgi-bin/
+\end{verbatim}
+% $ - emacs turd
+
+\begin{notice}[warning]
+You want to be very sure that the user id under which your CGI scripts run is
+\strong{not} in the \code{mailman} group you created above, otherwise private
+archives will be accessible to anyone.
+\end{notice}
+
+Copy the Mailman, Python, and GNU logos to a location accessible to your web
+server.  E.g. with Apache, you've usually got an \file{icons} directory that
+you can drop the images into.  For example:
+
+\begin{verbatim}
+    % cp $prefix/icons/*.{jpg,png} /path/to/apache/icons
+\end{verbatim}
+
+You then want to add a line to your \file{\var{\$prefix}/Mailman/mm_cfg.py}
+file which sets the base URL for the logos.  For example:
+
+\begin{verbatim}
+  IMAGE_LOGOS = '/images/'
+\end{verbatim}
+
+The default value for \var{IMAGE_LOGOS} is \file{/icons/}.  Read the comment
+in \file{Defaults.py.in} for details.
+
+Configure your web server to point to the Pipermail public mailing list
+archives.  For example, in Apache:
+
+\begin{verbatim}
+    Alias   /pipermail/     $varprefix/archives/public/
+\end{verbatim}
+% $ - emacs turd
+
+where \var{\$varprefix} is usually \var{\$prefix} unless you've used the
+\longprogramopt{with-var-prefix} option to \program{configure}.  Also be
+sure to configure your web server to follow symbolic links in this directory,
+otherwise public Pipermail archives won't be accessible.  For Apache users,
+consult the \var{FollowSymLinks} option.
+
+If you're going to be supporting internationalized public archives, you will
+probably want to turn off any default charset directive for the Pipermail
+directory, otherwise your multilingual archive pages won't show up correctly.
+Here's an example for Apache, based on the standard installation directories:
+
+\begin{verbatim}
+    <Directory "/usr/local/mailman/archives/public/">
+        AddDefaultCharset Off
+    </Directory>
+\end{verbatim}
+
+Now restart your web server.
+
+\section{Set up your mail server\label{mail-server}}
+
+This section describes some of the things you need to do to connect Mailman's
+email interface to your mail server.  The instructions here are different for
+each mail server; if your mail server is not described in the following
+subsections, try to generalize from the existing documentation, and consider
+contributing documentation updates to the Mailman developers.
+
+\subsection{Using the Postfix mail server}
+
+Mailman should work pretty much out of the box with a standard Postfix
+installation.  It has been tested with various Postfix versions up to and
+including Postfix 2.1.5.
+
+In order to support Mailman's optional VERP delivery, you will want to disable
+\code{luser_relay} (the default) and you will want to set
+\code{recipient_delimiter} for extended address semantics.  You should comment
+out any \code{luser_relay} value in your \file{main.cf} and just go with the
+defaults.  Also, add this to your \file{main.cf} file:
+
+\begin{verbatim}
+    recipient_delimiter = +
+\end{verbatim}
+
+Using \samp{+} as the delimiter works well with the default values for
+\var{VERP_FORMAT} and \var{VERP_REGEXP} in \file{Defaults.py}.
+
+When attempting to deliver a message to a non-existent local address, Postfix
+may return a 450 error code.  Since this is a transient error code, Mailman
+will continue to attempt to deliver the message for
+\var{DELIVERY_RETRY_PERIOD} -- 5 days by default.  You might want to set
+Postfix up so that it returns permanent error codes for non-existent local
+users by adding the following to your \file{main.cf} file:
+
+\begin{verbatim}
+    unknown_local_recipient_reject_code = 550
+\end{verbatim}
+
+Finally, if you are using Postfix-style virtual domains, read the section on
+virtual domain support below.
+
+\subsubsection{Integrating Postfix and Mailman}
+
+You can integrate Postfix and Mailman such that when new lists are created, or
+lists are removed, Postfix's alias database will be automatically updated.
+The following are the steps you need to take to make this work.
+
+In the description below, we assume that you've installed Mailman in the
+default location, i.e. \file{/usr/local/mailman}.  If that's not the case,
+adjust the instructions according to your use of \program{configure}'s
+\longprogramopt{prefix} and \longprogramopt{with-var-prefix} options.
+
+\begin{notice}[note]
+If you are using virtual domains and you want Mailman to honor your virtual
+domains, read the \ref{postfix-virtual} section below first!
+\end{notice}
+
+\begin{itemize}
+\item Add this to the bottom of the \file{\var{\$prefix}/Mailman/mm_cfg.py}
+      file:
+
+      \begin{verbatim}
+        MTA = 'Postfix'
+      \end{verbatim}
+
+      The MTA variable names a module in the \file{Mailman/MTA} directory
+      which contains the mail server-specific functions to be executed when a
+      list is created or removed.
+
+\item Look at the \file{Defaults.py} file for the variables
+      \var{POSTFIX_ALIAS_CMD} and \var{POSTFIX_MAP_CMD} command.  Make sure
+      these point to your \program{postalias} and \program{postmap} programs
+      respectively.  Remember that if you need to make changes, do it in
+      \file{mm_cfg.py}.
+
+\item Run the \program{bin/genaliases} script to initialize your
+      \file{aliases} file.
+
+      \begin{verbatim}
+        % cd /usr/local/mailman
+        % bin/genaliases
+      \end{verbatim}
+
+      Make sure that the owner of the \file{data/aliases} and
+      \file{data/aliases.db} file is \code{mailman} and that the group owner
+      for those files is \code{mailman}, or whatever user and group you used
+      in the configure command:
+
+      \begin{verbatim}
+        % su
+        % chown mailman:mailman data/aliases*
+      \end{verbatim}
+
+\item Hack your Postfix's \file{main.cf} file to include the following path in
+      your \var{alias_maps} variable:
+
+      \begin{verbatim}
+          /usr/local/mailman/data/aliases
+      \end{verbatim}
+
+      Note that there should be no trailing \code{.db}.  Do not include this
+      in your \var{alias_database} variable.  This is because you do not want
+      Postfix's \program{newaliases} command to modify Mailman's
+      \file{aliases.db} file, but you do want Postfix to consult
+      \file{aliases.db} when looking for local addresses.
+
+      You probably want to use a \code{hash:} style database for this entry.
+      Here's an example:
+
+      \begin{verbatim}
+        alias_maps = hash:/etc/postfix/aliases,
+            hash:/usr/local/mailman/data/aliases
+      \end{verbatim}
+
+\item When you configure Mailman, use the
+      \longprogramopt{with-mail-gid=mailman} switch; this will be the default
+      if you configured Mailman after adding the \code{mailman} owner.
+      Because the owner of the \file{aliases.db} file is \code{mailman},
+      Postfix will execute Mailman's wrapper program as uid and gid
+      \code{mailman}.
+
+\end{itemize}
+
+That's it!  One caveat: when you add or remove a list, the \file{aliases.db}
+file will updated, but it will not automatically run \program{postfix reload}.
+This is because you need to be root to run this and suid-root scripts are not
+secure.  The only effect of this is that it will take about a minute for
+Postfix to notice the change to the \file{aliases.db} file and update its
+tables.
+
+\subsubsection{Virtual domains\label{postfix-virtual}}
+
+Postfix 2.0 supports ``virtual alias domains'', essentially what used to be
+called ``Postfix-style virtual domains'' in earlier Postfix versions.  To make
+virtual alias domains work with Mailman, you need to do some setup in both
+Postfix and Mailman.  Mailman will write all virtual alias mappings to a file
+called, by default, \file{/usr/local/mailman/data/virtual-mailman}.  It will
+also use \program{postmap} to create the \program{virtual-mailman.db} file
+that Postfix will actually use.
+
+First, you need to set up the Postfix virtual alias domains as described in
+the Postfix documentation (see Postfix's \code{virtual(5)} manpage).  Note
+that it's your responsibility to include the \code{virtual-alias.domain
+anything} line as described manpage; Mailman will not include this line in
+\file{virtual-mailman}.  You are highly encouraged to make sure your virtual
+alias domains are working properly before integrating with Mailman.
+
+Next, add a path to Postfix's \var{virtual_alias_maps} variable, pointing to
+the virtual-mailman file, e.g.:
+
+\begin{verbatim}
+    virtual_alias_maps = <your normal virtual alias files>,
+        hash:/usr/local/mailman/data/virtual-mailman
+\end{verbatim}
+
+assuming you've installed Mailman in the default location.  If you're using an
+older version of Postfix which doesn't have the \var{virtual_alias_maps}
+variable, use the \var{virtual_maps} variable instead.
+
+Next, in your \file{mm_cfg.py} file, you will want to set the variable
+\var{POSTFIX_STYLE_VIRTUAL_DOMAINS} to the list of virtual domains that Mailman
+should update.  This may not be all of the virtual alias domains that your
+Postfix installation supports!  The values in this list will be matched
+against the \var{host_name} attribute of mailing lists objects, and must be an
+exact match.
+
+Here's an example.  Say that Postfix is configured to handle the virtual
+domains \code{dom1.ain}, \code{dom2.ain}, and \code{dom3.ain}, and further
+that in your \file{main.cf} file you've got the following settings:
+
+\begin{verbatim}
+    myhostname = mail.dom1.ain
+    mydomain = dom1.ain
+    mydestination = $myhostname, localhost.$mydomain
+    virtual_alias_maps =
+        hash:/some/path/to/virtual-dom1,
+        hash:/some/path/to/virtual-dom2,
+        hash:/some/path/to/virtual-dom2
+\end{verbatim}
+
+If in your \file{virtual-dom1} file, you've got the following lines:
+
+\begin{verbatim}
+    dom1.ain  IGNORE
+    @dom1.ain @mail.dom1.ain
+\end{verbatim}
+
+this tells Postfix to deliver anything addressed to \code{dom1.ain} to the
+same mailbox at \code{mail.dom1.com}, its default destination.
+
+In this case you would not include \code{dom1.ain} in
+\var{POSTFIX_STYLE_VIRTUAL_DOMAINS} because otherwise Mailman will write
+entries for mailing lists in the dom1.ain domain as
+
+\begin{verbatim}
+    mylist@dom1.ain         mylist
+    mylist-request@dom1.ain mylist-request
+    # and so on...
+\end{verbatim}
+
+The more specific entries trump your more general entries, thus breaking the
+delivery of any \code{dom1.ain} mailing list.
+
+However, you would include \code{dom2.ain} and \code{dom3.ain} in
+\file{mm_cfg.py}:
+
+\begin{verbatim}
+    POSTFIX_STYLE_VIRTUAL_DOMAINS = ['dom2.ain', 'dom3.ain']
+\end{verbatim}
+
+Now, any list that Mailman creates in either of those two domains, will have
+the correct entries written to \file{/usr/local/mailman/data/virtual-mailman}.
+
+As above with the \file{data/aliases*} files, you want to make sure that both
+\file{data/virtual-mailman} and \file{data/virtual-mailman.db} are user and
+group owned by \code{mailman}.
+
+\subsubsection{An alternative approach}
+
+Fil \email{fil@rezo.net} has an alternative approach based on virtual maps and
+regular expressions, as described at:
+
+\begin{itemize}
+\item (French)  \url{http://listes.rezo.net/comment.php}
+\item (English) \url{http://listes.rezo.net/how.php}
+\end{itemize}
+
+This is a good (and simpler) alternative if you don't mind exposing an
+additional hostname in the domain part of the addresses people will use to
+contact your list.  I.e. if people should use \code{mylist@lists.dom.ain}
+instead of \code{mylist@dom.ain}.
+
+\subsection{Using the Exim mail server}
+
+\begin{notice}[note]
+This section is derived from Nigel Metheringham's ``HOWTO - Using Exim and
+Mailman together'', which covers Mailman 2.0.x and Exim 3.  It has been
+updated to cover Mailman 2.1 and Exim 4.  The original document is here:
+\url{http://www.exim.org/howto/mailman.html}.
+\end{notice}
+
+There is no Mailman configuration needed other than the standard options
+detailed in the Mailman install documentation.  The Exim configuration is
+transparent to Mailman.  The user and group settings for Mailman must match
+those in the config fragments given below.
+
+\subsubsection{Exim configuration}
+
+The Exim configuration is built so that a list created within Mailman
+automatically appears to Exim without the need for defining any additional
+aliases.
+
+The drawback of this configuration is that it will work poorly on systems
+supporting lists in several different mail domains.  While Mailman handles
+virtual domains, it does not yet support having two distinct lists with the
+same name in different virtual domains, using the same Mailman installation.
+This will eventually change.  (But see below for a variation on this scheme
+that should accommodate virtual domains better.)
+
+The configuration file excerpts below are for use in an already functional
+Exim configuration, which accepts mail for the domain in which the list
+resides.  If this domain is separate from the others handled by your Exim
+configuration, then you'll need to:
+
+\begin{itemize}
+\item add the list domain, ``my.list.domain'' to \var{local_domains}
+
+\item add a ``domains=my.list.domain'' option to the director (router) for the
+      list
+
+\item (optional) exclude that domain from your other directors (routers)
+\end{itemize}
+
+\begin{notice}[note]
+The instructions in this document should work with either Exim 3 or Exim 4.
+In Exim 3, you must have a \var{local_domains} configuration setting; in Exim
+4, you most likely have a \var{local_domains} domainlist.  If you don't, you
+probably know what you're doing and can adjust accordingly.  Similarly, in
+Exim 4 the concept of ``directors'' has disappeared -- there are only routers
+now.  So if you're using Exim 4, whenever this document says ``director'',
+read ``router''.
+\end{notice}
+
+Whether you are using Exim 3 or Exim 4, you will need to add some macros to
+the main section of your Exim config file.  You will also need to define one
+new transport.  With Exim 3, you'll need to add a new director; with Exim 4, a
+new router plays the same role.
+
+Finally, the configuration supplied here should allow co-habiting Mailman 2.0
+and 2.1 installations, with the proviso that you'll probably want to use
+\code{mm21} in place of \code{mailman} -- e.g., \var{MM21_HOME},
+\var{mm21_transport}, etc.
+
+\subsubsection{Main configuration settings}
+
+First, you need to add some macros to the top of your Exim config file.  These
+just make the director (router) and transport below a bit cleaner.  Obviously,
+you'll need to edit these based on how you configured and installed Mailman.
+
+\begin{verbatim}
+    # Home dir for your Mailman installation -- aka Mailman's prefix
+    # directory.
+    MAILMAN_HOME=/usr/local/mailman
+    MAILMAN_WRAP=MAILMAN_HOME/mail/mailman
+
+    # User and group for Mailman, should match your --with-mail-gid
+    # switch to Mailman's configure script.
+    MAILMAN_USER=mailman
+    MAILMAN_GROUP=mailman
+\end{verbatim}
+
+\subsubsection{Transport for Exim 3\label{exim3-transport}}
+
+Add this to the transports section of your Exim config file,
+i.e. somewhere between the first and second ``end'' line:
+
+\begin{verbatim}
+  mailman_transport:
+    driver = pipe
+    command = MAILMAN_WRAP \
+              '${if def:local_part_suffix \
+                    {${sg{$local_part_suffix}{-(\\w+)(\\+.*)?}{\$1}}} \
+                    {post}}' \
+              $local_part
+    current_directory = MAILMAN_HOME
+    home_directory = MAILMAN_HOME
+    user = MAILMAN_USER
+    group = MAILMAN_GROUP
+\end{verbatim}
+
+\subsubsection{Director for Exim 3}
+
+If you're using Exim 3, you'll need to add the following director to your
+config file (directors go between the second and third ``end'' lines).  Also,
+don't forget that order matters -- e.g. you can make Mailman lists take
+precedence over system aliases by putting this director in front of your
+aliasfile director, or vice-versa.
+
+\begin{verbatim}
+  # Handle all addresses related to a list 'foo': the posting address.
+  # Automatically detects list existence by looking
+  # for lists/$local_part/config.pck under MAILMAN_HOME.
+  mailman_director:
+    driver = smartuser
+    require_files = MAILMAN_HOME/lists/$local_part/config.pck
+    suffix_optional
+    suffix = -bounces : -bounces+* : \
+             -confirm+* : -join : -leave : \
+             -owner : -request : -admin
+    transport = mailman_transport
+\end{verbatim}
+
+\subsubsection{Router for Exim 4}
+
+In Exim 4, there's no such thing as directors -- you need to add a new router
+instead.  Also, the canonical order of the configuration file was changed so
+routers come before transports, so the router for Exim 4 comes first here.
+Put this router somewhere after the ``begin routers'' line of your config
+file, and remember that order matters.
+
+\begin{verbatim}
+  mailman_router:
+    driver = accept
+    require_files = MAILMAN_HOME/lists/$local_part/config.pck
+    local_part_suffix_optional
+    local_part_suffix = -bounces : -bounces+* : \
+                        -confirm+* : -join : -leave : \
+                        -owner : -request : -admin
+    transport = mailman_transport
+\end{verbatim}
+% $ - emacs turds
+
+\subsubsection{Transports for Exim 4}
+
+The transport for Exim 4 is the same as for Exim 3 (see \ref{exim3-transport};
+just copy the transport given above to somewhere under the ``begin
+transports'' line of your Exim config file.
+
+\subsubsection{Additional notes}
+
+Exim should be configured to allow reasonable volume -- e.g. don't set
+\var{max_recipients} down to a silly value -- and with normal degrees of
+security -- specifically, be sure to allow relaying from 127.0.0.1, but pretty
+much nothing else.  Parallel deliveries and other tweaks can also be used if
+you like; experiment with your setup to see what works.  Delay warning
+messages should be switched off or configured to only happen for non-list
+mail, unless you like receiving tons of mail when some random host is down.
+
+\subsubsection{Problems}
+
+\begin{itemize}
+
+\item Mailman will send as many \code{MAIL FROM}/\code{RCPT TO} as it needs.
+      It may result in more than 10 or 100 messages sent in one connection,
+      which will exceed the default value of Exim's
+      \var{smtp_accept_queue_per_connection} value.  This is bad because it
+      will cause Exim to switch into queue mode and severely delay delivery of
+      your list messages.  The way to fix this is to set Mailman's
+      \var{SMTP_MAX_SESSIONS_PER_CONNECTION} (in
+      \file{\var{\$prefix}/Mailman/mm_cfg.py}) to a smaller value than Exim's
+      \var{smtp_accept_queue_per_connection}.
+
+\item Mailman should ignore Exim delay warning messages, even though Exim
+      should never send this to list messages.  Mailman 2.1's general bounce
+      detection and VERP support should greatly improve the bounce detector's
+      hit rates.
+
+\item List existence is determined by the existence of a \file{config.pck}
+      file for a list.  If you delete lists by foul means, be aware of this.
+
+\item If you are getting Exim or Mailman complaining about user ids when you
+      send mail to a list, check that the \var{MAILMAN_USER} and
+      \var{MAILMAN_GROUP} match those of Mailman itself (i.e. what were used
+      in the \program{configure} script).  Also make sure you do not have
+      aliases in the main alias file for the list.
+\end{itemize}
+
+\subsubsection{Receiver Verification}
+
+Exim's receiver verification feature is very useful -- it lets Exim reject
+unrouteable addresses at SMTP time.  However, this is most useful for
+externally-originating mail that is addressed to mail in one of your local
+domains.  For Mailman list traffic, mail originates on your server, and is
+addressed to random external domains that are not under your control.
+Furthermore, each message is addressed to many recipients
+-- up to 500 if you use Mailman's default configuration and don't tweak
+\var{SMTP_MAX_RCPTS}.
+
+Doing receiver verification on Mailman list traffic is a recipe for trouble.
+In particular, Exim will attempt to route every recipient addresses in
+outgoing Mailman list posts.  Even though this requires nothing more than a
+few DNS lookups for each address, it can still introduce significant delays.
+Therefore, you should disable recipient verification for Mailman traffic.
+
+Under Exim 3, put this in your main configuration section:
+
+\begin{verbatim}
+    receiver_verify_hosts = !127.0.0.1
+\end{verbatim}
+
+Under Exim 4, this is probably already taken care of for you by the default
+recipient verification ACL statement (in the \code{RCPT TO} ACL):
+
+\begin{verbatim}
+  accept  domains       = +local_domains
+          endpass
+          message       = unknown user
+          verify        = recipient
+\end{verbatim}
+
+which only does recipient verification on addresses in your domain.  (That's
+not exactly the same as doing recipient verification only on messages coming
+from non-127.0.0.1 hosts, but it should do the trick for Mailman.)
+
+\subsubsection{SMTP Callback}
+
+Exim's SMTP callback feature is an even more powerful way to detect bogus
+sender addresses than normal sender verification.  Unfortunately, lots of
+servers send bounce messages with a bogus address in the header, and there are
+plenty that send bounces with bogus envelope senders (even though they're
+supposed to just use an empty envelope sender for bounces).
+
+In order to ensure that Mailman can disable/remove bouncing addresses, you
+generally want to receive bounces for Mailman lists, even if those bounces are
+themselves not bounceable.  Thus, you might want to disable SMTP callback on
+bounce messages.
+
+With Exim 4, you can accomplish this using something like the following in
+your \code{RCPT TO} ACL:
+
+\begin{verbatim}
+  # Accept bounces to lists even if callbacks or other checks would fail
+  warn     message      = X-WhitelistedRCPT-nohdrfromcallback: Yes
+           condition    = \
+           ${if and {{match{$local_part}{(.*)-bounces\+.*}} \
+                     {exists {MAILMAN_HOME/lists/$1/config.pck}}} \
+                {yes}{no}}
+                {yes}{no}}
+
+  accept   condition    = \
+           ${if and {{match{$local_part}{(.*)-bounces\+.*}} \
+                     {exists {MAILMAN_HOME/lists/$1/config.pck}}} \
+                {yes}{no}}
+                {yes}{no}}
+
+  # Now, check sender address with SMTP callback.
+  deny   !verify = sender/callout=90s
+\end{verbatim}
+
+If you also do SMTP callbacks on header addresses, you'll want something like
+this in your \code{DATA} ACL:
+
+\begin{verbatim}
+  deny   !condition = $header_X-WhitelistedRCPT-nohdrfromcallback:
+         !verify = header_sender/callout=90s
+\end{verbatim}
+% $ - emacs turd
+
+\subsubsection{Doing VERP with Exim and Mailman}
+
+VERP will send one email, with a separate envelope sender (return path), for
+each of your subscribers -- read the information in
+\file{\var{\$prefix}/Mailman/Defaults.py} for the options that start with VERP.
+In a nutshell, all you need to do to enable VERP with Exim is to add these lines to \file{\var{\$prefix}/Mailman/mm_cfg.py}:
+
+\begin{verbatim}
+    VERP_PASSWORD_REMINDERS = Yes
+    VERP_PERSONALIZED_DELIVERIES = Yes
+    VERP_DELIVERY_INTERVAL = Yes
+    VERP_CONFIRMATIONS = Yes
+\end{verbatim}
+
+(The director (router) above is smart enough to deal with VERP bounces.)
+
+\subsubsection{Virtual Domains}
+
+One approach to handling virtual domains is to use a separate Mailman
+installation for each virtual domain.  Currently, this is the only way to have
+lists with the same name in different virtual domains handled by the same
+machine.
+
+In this case, the \var{MAILMAN_HOME} and \var{MAILMAN_WRAP} macros are useless
+-- you can remove them.  Change your director (router) to something like this:
+
+\begin{verbatim}
+  require_files = /virtual/${domain}/mailman/lists/${lc:$local_part}/config.pck
+\end{verbatim}
+% $ - emacs turd
+
+and change your transport like this:
+
+\begin{verbatim}
+  command = /virtual/${domain}/mailman/mail/mailman \
+            ${if def:local_part_suffix \
+                 {${sg{$local_part_suffix}{-(\\w+)(\\+.*)?}{\$1}}}
+                 {post}} \
+              $local_part
+  current_directory = /virtual/${domain}/mailman
+  home_directory = /virtual/${domain}/mailman
+\end{verbatim}
+% $ - emacs turd
+
+\subsubsection{List Verification}
+
+This is how a set of address tests for the Exim lists look on a working
+system.  The list in question is \email{quixote-users@mems-exchange.org}, and
+these commands were run on the \code{mems-exchange.org} mail server ("\% "
+indicates the Unix shell prompt):
+
+\begin{verbatim}
+  % exim -bt quixote-users
+  quixote-users@mems-exchange.org
+    router = mailman_main_router, transport = mailman_transport
+
+  % exim -bt quixote-users-request
+  quixote-users-request@mems-exchange.org
+    router = mailman_router, transport = mailman_transport
+
+  % exim -bt quixote-users-bounces
+  quixote-users-bounces@mems-exchange.org
+    router = mailman_router, transport = mailman_transport
+
+  % exim -bt quixote-users-bounces+luser=example.com
+  quixote-users-bounces+luser=example.com@mems-exchange.org
+    router = mailman_router, transport = mailman_transport
+\end{verbatim}
+
+If your \program{exim -bt} output looks something like this, that's a start:
+at least it means Exim will pass the right messages to the right Mailman
+commands.  It by no means guarantees that your Exim/Mailman installation is
+functioning perfectly, though!
+
+\subsubsection{Document History}
+
+Originally written by Nigel Metheringham \email{postmaster@exim.org}.  Updated
+by Marc Merlin \email{marc_soft@merlins.org} for Mailman 2.1, Exim 4.
+Overhauled/reformatted/clarified/simplified by Greg Ward
+\email{gward@python.net}.
+
+\subsection{Using the Sendmail mail server}
+
+\begin{notice}[warning]
+You may be tempted to set the \var{DELIVERY_MODULE} configuration variable in
+\file{mm_cfg.py} to \code{'Sendmail'} when using the Sendmail mail server.
+\strong{Don't}.  The \file{Sendmail.py} module is misnamed -- it's really a
+command line based message handoff scheme as opposed to the SMTP scheme used
+in \file{SMTPDirect.py} (the default).  \file{Sendmail.py} has known security
+holes and is provided as a proof-of-concept only\footnote{In fact, in later
+versions of Mailman, this module is explicitly sabotaged.  You have to know
+what you're doing in order to re-enable it.}.  If you are having problems
+using \file{SMTPDirect.py} fix those instead of using \file{Sendmail.py}, or
+you may open your system up to security exploits.
+\end{notice}
+
+\subsubsection{Sendmail ``smrsh'' compatibility}
+
+Many newer versions of Sendmail come with a restricted execution utility
+called ``smrsh'', which limits the executables that Sendmail will allow to be
+used as mail programs.  You need to explicitly allow Mailman's wrapper program
+to be used with smrsh or Mailman will not work.  If mail is not getting
+delivered to Mailman's wrapper program and you're getting an ``operating
+system error'' in your mail syslog, this could be your problem.
+
+One good way of enabling this is:
+
+\begin{itemize}
+    \item Find out where your Sendmail executes its smrsh wrapper
+
+          \begin{verbatim}
+            % grep smrsh /etc/mail/sendmail.cf
+          \end{verbatim}
+
+    \item Figure out where smrsh expects symlinks for allowable mail
+          programs.  At the very beginning of the following output you will
+          see a full path to some directory, e.g. \file{/var/adm/sm.bin} or
+          similar:
+
+          \begin{verbatim}
+            % strings $path_to_smrsh | less
+          \end{verbatim}
+
+    \item cd into \file{/var/adm/sm.bin}, or where ever it happens to reside
+          on your system -- alternatives include \file{/etc/smrsh},
+          \file{/var/smrsh} and \file{/usr/local/smrsh}.
+
+          \begin{verbatim}
+            % cd /var/adm/sm.bin
+          \end{verbatim}
+
+    \item Create a symbolic link to Mailman's wrapper program:
+
+          \begin{verbatim}
+            % ln -s /usr/local/mailman/mail/mailman mailman
+          \end{verbatim}
+\end{itemize}
+
+\subsubsection{Integrating Sendmail and Mailman}
+
+David Champion has contributed a recipe for more closely integrating Sendmail
+and Mailman, such that Sendmail will automatically recognize and deliver to
+new mailing lists as they are created, without having to manually edit alias
+tables.
+
+In the \file{contrib} directory of Mailman's source distribution, you will
+find four files:
+
+\begin{itemize}
+\item \file{mm-handler.readme} - an explanation of how to set everything up
+\item \file{mm-handler}        - the mail delivery agent (MDA)
+\item \file{mailman.mc}        - a toy configuration file sample
+\item \file{virtusertable}     - a sample for RFC 2142 address exceptions
+\end{itemize}
+
+\subsubsection{Performance notes}
+
+One of the surest performance killers for Sendmail users is when Sendmail is
+configured to synchronously verify the recipient's host via DNS.  If it does
+this for messages posted to it from Mailman, you will get horrible
+performance.  Since Mailman usually connects via \code{localhost}
+(i.e. 127.0.0.1) to the SMTP port of Sendmail, you should be sure to configure
+Sendmail to \strong{not} do DNS verification synchronously for localhost
+connections.
+
+\subsection{Using the Qmail mail server\label{qmail-issues}}
+
+There are some issues that users of the qmail mail transport agent have
+encountered.  None of the core maintainers use qmail, so all of this
+information has been contributed by the Mailman user community, especially
+Martin Preishuber and Christian Tismer, with notes by Balazs Nagy (BN) and
+Norbert Bollow (NB).
+
+\begin{itemize}
+\item You might need to set the mail-gid user to either \code{qmail},
+      \code{mailman}, or \code{nofiles} by using the
+      \longprogramopt{with-mail-gid} \program{configure} option.
+
+      \emph{BN:} it highly depends on your mail storing policy.  For example
+      if you use the simple \file{\~{}alias/.qmail-*} files, you can use
+      \program{`id -g alias`}.  But if you use \file{/var/qmail/users}, the
+      specified mail gid can be used.
+
+      If you are going to be directing virtual domains directly to the
+      \code{mailman} user (using ``virtualdomains'' on a list-only domain, for
+      example), you will have to use \longprogramopt{with-mail-gid}=\var{gid
+      of mailman user's group}.  This is incompatible with having list aliases
+      in \file{\~{}alias}, unless that alias simply forwards to
+      \code{mailman-listname*}.
+
+\item If there is a user \code{mailman} on your system, the alias
+      \code{mailman-owner} will work only in \file{\~{}mailman}.  You have to do
+      a \program{touch .qmail-owner} in \file{\~{}mailman} directory to create
+      this alias.
+
+      \emph{NB:} An alternative, IMHO better solution is to \program{chown
+      root \~{}mailman}, that will stop qmail from considering \code{mailman} to
+      be a user to whom mail can be delivered.  (See ``man 8 qmail-getpw''.)
+
+\item In a related issue, if you have any users with the same name as one of
+      your mailing lists, you will have problems if list names contain
+      \samp{-} in them.  Putting \file{.qmail} redirections into the user's
+      home directory doesn't work because the Mailman wrappers will not get
+      spawned with the proper GID.  The solution is to put the following lines
+      in the \file{/var/qmail/users/assign} file:
+
+\begin{verbatim}
+  +zope-:alias:112:11:/var/qmail/alias:-:zope-:
+  .
+\end{verbatim}
+
+      where in this case the listname is e.g. \code{zope-users}.
+
+      \emph{NB:} Alternatively, you could host the lists on a virtual domain,
+      and use the \file{/var/qmail/control/virtualdomains} file to put the
+      \code{mailman} user in charge of this virtual domain.
+
+\item \emph{BN:}If inbound messages are delivered by another user than
+      \code{mailman}, it's necessary to allow it to access \file{\~{}mailman}.
+      Be sure that \file{\~{}mailman} has group writing access and setgid bit is
+      set.  Then put the delivering user to \code{mailman} group, and you can
+      deny access to \file{\~{}mailman} to others.  Be sure that you can do the
+      same with the WWW service.
+
+      By the way the best thing is to make a virtual mail server to handle all
+      of the mail.  \emph{NB:} E.g. make an additional "A" DNS record for the
+      virtual mailserver pointing to your IP address, add the line
+      \code{lists.kva.hu:mailman} to \file{/var/qmail/control/virtualdomains}
+      and a \code{lists.kva.hu} line to \file{/var/qmail/control/rcpthosts}
+      file.  Don't forget to HUP the qmail-send after modifying
+      ``virtualdomains''.  Then every mail to lists.kva.hu will arrive to
+      mail.kva.hu's mailman user.
+
+      Then make your aliases:
+
+\begin{verbatim}
+          .qmail              => mailman@...'s letters
+          .qmail-owner        => mailman-owner's letters
+\end{verbatim}
+
+      For list aliases, you can either create them manually:
+
+\begin{verbatim}
+          .qmail-list         => posts to the 'list' list
+          .qmail-list-admin   => posts to the 'list's owner
+          .qmail-list-request => requests to 'list'
+          etc
+\end{verbatim}
+
+      or for automatic list alias handling (when using the lists.kva.hu
+      virtual as above), see \file{contrib/qmail-to-mailman.py} in the Mailman
+      source distribution.  Modify the \file{\~{}mailman/.qmail-default} to
+      include:
+
+\begin{verbatim}
+          |preline /path/to/python /path/to/qmail-to-mailman.py
+\end{verbatim}
+
+      and new lists will automatically be picked up.
+
+\item You have to make sure that the localhost can relay.  If you start qmail
+      via inetd and tcpenv, you need some line the following in your
+      \file{/etc/hosts.allow} file:
+
+\begin{verbatim}
+      tcp-env: 127. 10.205.200. : setenv RELAYCLIENT
+\end{verbatim}
+
+      where 10.205.200. is your IP address block.  If you use tcpserver, then
+      you need something like the following in your \file{/etc/tcp.smtp} file:
+
+\begin{verbatim}
+      10.205.200.:allow,RELAYCLIENT=""
+      127.:allow,RELAYCLIENT=""
+\end{verbatim}
+
+\item \emph{BN:} Bigger \file{/var/qmail/control/concurrencyremote} values
+      work better sending outbound messages, within reason.  Unless you know
+      your system can handle it (many if not most cannot) this should not be
+      set to a value greater than 120.
+
+\item More information about setting up qmail and relaying can be found in the
+      qmail documentation.
+\end{itemize}
+
+\emph{BN:} Last but not least, here's a little script to generate aliases to
+your lists (if for some reason you can/will not have them automatically picked
+up using \file{contrib/qmail-to-mailman.py}):
+
+This script is for the Mailman 2.0 series:
+
+\begin{verbatim}
+#!/bin/sh
+if [ $# = 1 ]; then
+    i=$1
+    echo Making links to $i in the current directory...
+    echo "|preline /home/mailman/mail/mailman post $i" > .qmail-$i
+    echo "|preline /home/mailman/mail/mailman mailowner $i" > .qmail-$i-admin
+    echo "|preline /home/mailman/mail/mailman mailowner $i" > .qmail-$i-owner
+    echo "|preline /home/mailman/mail/mailman mailowner $i" > .qmail-owner-$i
+    echo "|preline /home/mailman/mail/mailman mailcmd $i" > .qmail-$i-request
+fi
+\end{verbatim}
+% $ - emacs turd
+
+\begin{notice}[note]
+This is for a new Mailman 2.1 installation.  Users upgrading from
+Mailman 2.0 would most likely change \file{/usr/local/mailman} to
+\file{/home/mailman}.  If in doubt, refer to the \longprogramopt{prefix}
+option passed to \program{configure} during compile time.
+\end{notice}
+
+\begin{verbatim}
+#!/bin/sh
+if [ $# = 1 ]; then
+    i=$1
+    echo Making links to $i in the current directory...
+    echo "|preline /usr/local/mailman/mail/mailman post $i" > .qmail-$i
+    echo "|preline /usr/local/mailman/mail/mailman admin $i" > .qmail-$i-admin
+    echo "|preline /usr/local/mailman/mail/mailman bounces $i" > .qmail-$i-bounces
+    # The following line is for VERP
+    # echo "|preline /usr/local/mailman/mail/mailman bounces $i" > .qmail-$i-bounces-default
+    echo "|preline /usr/local/mailman/mail/mailman confirm $i" > .qmail-$i-confirm
+    echo "|preline /usr/local/mailman/mail/mailman join $i" > .qmail-$i-join
+    echo "|preline /usr/local/mailman/mail/mailman leave $i" > .qmail-$i-leave
+    echo "|preline /usr/local/mailman/mail/mailman owner $i" > .qmail-$i-owner
+    echo "|preline /usr/local/mailman/mail/mailman request $i" > .qmail-$i-request
+    echo "|preline /usr/local/mailman/mail/mailman subscribe $i" > .qmail-$i-subscribe
+    echo "|preline /usr/local/mailman/mail/mailman unsubscribe $i" > .qmail-$i-unsubscribe
+fi
+\end{verbatim}
+% $ - emacs turd
+
+\subsubsection{Information on VERP}
+
+You will note in the alias generating script for 2.1 above, there is a line
+for VERP that has been commented out.  If you are interested in VERP there are
+two options.  The first option is to allow Mailman to do the VERP formatting.
+To activate this, uncomment that line and add the following lines to your
+\file{mm_cfg.py} file:
+
+\begin{verbatim}
+    VERP_FORMAT = '%(bounces)s-+%(mailbox)s=%(host)s'
+    VERP_REGEXP = r'^(?P<bounces>.*?)-\+(?P<mailbox>[^=]+)=(?P<host>[^@]+)@.*$'
+\end{verbatim}
+% $ - emacs turd
+
+The second option is a patch on SourceForge located at:
+
+\url{http://sourceforge.net/tracker/?func=detail\&atid=300103\&aid=645513\&group_id=103}
+
+This patch currently needs more testing and might best be suitable for
+developers or people well familiar with qmail.  Having said that, this patch
+is the more qmail-friendly approach resulting in large performance gains.
+
+\subsubsection{Virtual mail server}
+
+As mentioned in the \ref{qmail-issues} section for a virtual mail server, a
+patch under testing is located at:
+
+\url{http://sf.net/tracker/index.php?func=detail\&aid=621257\&group_id=103\&atid=300103}
+
+Again, this patch is for people familiar with their qmail installation.
+
+\subsubsection{More information}
+
+You might be interested in some information on modifying footers that Norbert
+Bollow has written about Mailman and qmail, available here:
+
+    \url{http://mailman.cis.to/qmail-verh/}
+
+\section{Review your site defaults\label{customizing}}
+
+Mailman has a large number of site-wide configuration options which you should
+now review and change according to your needs.  Some of the options control
+how Mailman interacts with your environment, and other options select defaults
+for newly created lists\footnote{In general, changing the list defaults
+described in this section will not affect any already created lists.  To make
+changes after a list has been created, use the web interface or the command
+line scripts, such as \program{bin/withlist} and \program{bin/config_list}.}.
+There are system tuning parameters and integration options.
+
+The full set of site-wide defaults lives in the
+\file{\var{\$prefix}/Mailman/Defaults.py} file, however you should
+\strong{never} modify this file!  Instead, change the \file{mm_cfg.py} file in
+that same directory.  You only need to add values to \file{mm_cfg.py} that are
+different than the defaults in \file{Defaults.py}, and future Mailman upgrades
+are guaranteed never to touch your \file{mm_cfg.py} file.
+
+The \file{Defaults.py} file is documented extensively, so the options are not
+described here.  The \file{Defaults.py} and \file{mm_cfg.py} are both
+\ulink{Python}{http://www.python.org} files so valid Python syntax must be
+maintained or your Mailman installation will break.
+
+\begin{notice}[note]
+Do \strong{not} change the \var{HOME_DIR} or \var{MAILMAN_DIR} variables.
+These are set automatically by the \program{configure} script, and you will
+break your Mailman installation by if you change these.
+\end{notice}
+
+You should make any changes to \file{mm_cfg.py} using the account you
+installed Mailman under in the \ref{building} section.
+
+\section{Create a site-wide mailing list}
+
+After you have completed the integration of Mailman and your mail server, you
+need to create a ``site-wide'' mailing list.  This is the one that password
+reminders will appear to come from, and it is required for proper Mailman
+operation.  Usually this should be a list called \code{mailman}, but if you
+need to change this, be sure to change the \var{MAILMAN_SITE_LIST} variable in
+\file{mm_cfg.py}.  You can create the site list with this command, following
+the prompts:
+
+\begin{verbatim}
+    % bin/newlist mailman
+\end{verbatim}
+
+Now configure your site list.  There is a convenient template for a generic
+site list in the installation directory, under \file{data/sitelist.cfg} which
+can help you with this.  You should review the configuration options in the
+template, but note that any options not named in the \file{sitelist.cfg} file
+won't be changed.
+
+The template can be applied to your site list by
+running:
+
+\begin{verbatim}
+    % bin/config_list -i data/sitelist.cfg mailman
+\end{verbatim}
+
+After applying the \file{sitelist.cfg} options, be sure you review the
+site list's configuration via the admin pages.
+
+You should also subscribe yourself to the site list.
+
+\section{Set up cron}
+
+Several Mailman features occur on a regular schedule, so you must set up
+\program{cron} to run the right programs at the right time\footnote{Note that
+if you're upgrading from a previous version of Mailman, you'll want to install
+the new crontab, but be careful if you're running multiple Mailman
+installations on your site!  Changing the crontab could mess with other
+parallel Mailman installations.}.
+
+If your version of crontab supports the \programopt{-u} option, you must be
+root to do this next step.  Add \file{\var{\$prefix}/cron/crontab.in} as a
+crontab entry by executing these commands:
+
+\begin{verbatim}
+    % cd $prefix/cron
+    % crontab -u mailman crontab.in
+\end{verbatim}
+
+If you used the \longprogramopt{with-username} option, use that user name
+instead of \code{mailman} for the \programopt{-u} argument value.  If your
+crontab does not support the \programopt{-u} option, try these commands:
+
+\begin{verbatim}
+    % cd $prefix/cron
+    % su - mailman
+    % crontab crontab.in
+\end{verbatim}
+
+\section{Start the Mailman qrunner}
+
+Mailman depends on a process called the ``qrunner'' to delivery all
+email messages it sees.  You must start the qrunner by executing the following
+command from the \var{\$prefix} directory:
+
+\begin{verbatim}
+    % bin/mailmanctl start
+\end{verbatim}
+
+You probably want to start Mailman every time you reboot your system.  Exactly
+how to do this depends on your operating system.  If your OS supports the
+\program{chkconfig} command (e.g. RedHat and Mandrake Linuxes) you can
+do the following (as root, from the Mailman install directory):
+
+\begin{verbatim}
+    % cp scripts/mailman /etc/init.d/mailman
+    % chkconfig --add mailman
+\end{verbatim}
+
+Note that \file{/etc/init.d} may be \file{/etc/rc.d/init.d} on some systems.
+
+On Gentoo Linux, you can do the following:
+
+\begin{verbatim}
+    % cp scripts/mailman /etc/init.d/mailman
+    % rc-update add mailman default
+\end{verbatim}
+
+On Debian, you probably want to use:
+
+\begin{verbatim}
+    % update-rc.d mailman defaults
+\end{verbatim}
+
+For \UNIX{}es that don't support \program{chkconfig}, you might try the
+following set of commands:
+
+\begin{verbatim}
+    % cp scripts/mailman /etc/init.d/mailman
+    % cp misc/mailman /etc/init.d
+    % cd /etc/rc.d/rc0.d
+    % ln -s ../init.d/mailman K12mailman
+    % cd ../rc1.d
+    % ln -s ../init.d/mailman K12mailman
+    % cd ../rc2.d
+    % ln -s ../init.d/mailman S98mailman
+    % cd ../rc3.d
+    % ln -s ../init.d/mailman S98mailman
+    % cd ../rc4.d
+    % ln -s ../init.d/mailman S98mailman
+    % cd ../rc5.d
+    % ln -s ../init.d/mailman S98mailman
+    % cd ../rc6.d
+    % ln -s ../init.d/mailman K12mailman
+\end{verbatim}
+
+\section{Check the hostname settings}
+
+You should check the values for \var{DEFAULT_EMAIL_HOST} and
+\var{DEFAULT_URL_HOST} in \file{Defaults.py}.  Make any necessary changes in
+the \file{mm_cfg.py} file, \strong{not} in the \file{Defaults.py} file.  If you
+change either of these two values, you'll want to add the following afterwards
+in the \file{mm_cfg.py} file:
+
+\begin{verbatim}
+    add_virtualhost(DEFAULT_URL_HOST, DEFAULT_EMAIL_HOST)
+\end{verbatim}
+
+You will want to run the \program{bin/fix_url.py} to change the domain of any
+existing lists.
+
+\section{Create the site password}
+
+There are two site-wide passwords that you can create from the command line,
+using the \program{bin/mmsitepass} script.  The first is the ``site password''
+which can be used anywhere a password is required in the system.  The site
+password will get you into the administration page for any list, and it can be
+used to log in as any user.  Think \code{root} for a Unix system, so pick this
+password wisely!
+
+The second password is a site-wide ``list creator'' password.  You can use
+this to delegate the ability to create new mailing lists without providing all
+the privileges of the site password.  Of course, the owner of the site
+password can also create new mailing lists, but the list creator password is
+limited to just that special role.
+
+To set the site password, use this command:
+
+\begin{verbatim}
+    % $prefix/bin/mmsitepass <your-site-password>
+\end{verbatim}
+
+To set the list creator password, use this command:
+
+\begin{verbatim}
+    % $prefix/bin/mmsitepass -c <list-creator-password>
+\end{verbatim}
+
+It is okay not to set a list creator password, but you probably do want a site
+password.
+
+\section{Create your first mailing list}
+
+For more detailed information about using Mailman, including creating and
+configuring mailing lists, see the Mailman List Adminstration Manual.  These
+instructions provide a quick guide to creating your first mailing list via the
+web interface:
+
+\begin{itemize}
+\item Start by visiting the url \code{http://my.dom.ain/mailman/create}.
+
+\item Fill out the form as described in the on-screen instructions, and in the
+      ``List creator's password'' field, type the password you entered in
+      section \ref{customizing}.  Type your own email address for the
+      ``Initial list owner address'', and select ``Yes'' to notify the list
+      administrator.
+
+\item Click on the ``Create List'' button.
+
+\item Check your email for a message from Mailman informing you that your new
+      mailing list was created.
+
+\item Now visit the list's administration page, either by following the link
+      on the confirmation web page or clicking on the link from the email
+      Mailman just sent you.  Typically the url will be something like
+      \code{http://my.dom.ain/mailman/admin/mylist}.
+
+\item Type in the list's password and click on ``Let me in...''
+
+\item Click on ``Membership Management'' and then on ``Mass Subscription''.
+
+\item Enter your email address in the big text field, and click on ``Submit
+      Your Changes''.
+
+\item Now go to your email and send a message to \code{mylist@my.dom.ain}.
+      Within a minute or two you should see your message reflected back to you
+      via Mailman.
+\end{itemize}
+
+Congratulations!  You've just set up and tested your first Mailman mailing
+list.  If you had any problems along the way, please see the
+\ref{troubleshooting} section.
+
+\section{Troubleshooting\label{troubleshooting}}
+
+If you encounter problems with running Mailman, first check the question and
+answer section below.  If your problem is not covered there, check the
+\ulink{online help}{http://www.list.org/help.html}, including the
+\ulink{FAQ}{http://www.list.org/faq.html} and the
+\ulink{interactive FAQ wizard}{http://www.python.org/cgi-bin/faqw-mm.py}.
+
+Also check for errors in your syslog files, your mail and web server log files
+and in Mailman's \file{\var{\$prefix}/logs/error} file.  If you're still
+having problems, you should send a message to the
+\email{mailman-users@python.org} mailing list\footnote{You must subscribe to
+this mailing list in order to post to it, but the mailing list's archives are
+publicly visible.}; see
+\url{http://mail.python.org/mailman/listinfo/mailman-users} for more
+information.
+
+Be sure to including information on your operating system, which version of
+Python you're using, and which version of Mailman you're installing.
+
+Here is a list of some common questions and answers:
+
+\begin{itemize}
+
+\item \strong{Problem:} All Mailman web pages give a 404 File not found
+      error.
+
+      \strong{Solution:} Your web server has not been set up properly for
+      handling Mailman's CGI programs.  Make sure you have:
+
+      \begin{enumerate}
+      \item configured the web server to give permissions to
+            \file{\var{\$prefix}/cgi-bin}
+
+      \item restarted the web server properly.
+      \end{enumerate}
+
+      Consult your web server's documentation for instructions on how to do
+      check these issues.
+
+\item \strong{Problem:} All Mailman web pages give an "Internal Server
+      Error".
+
+      \strong{Solution:} The likely problem is that you are using the wrong
+      user or group for the CGI scripts.  Check your web server's log files.
+      If you see a line like
+
+      \begin{verbatim}
+            Attempt to exec script with invalid gid 51, expected 99
+      \end{verbatim}
+
+      you will need to reinstall Mailman, specifying the proper CGI group id,
+      as described in the \label{building} section.
+
+\item \strong{Problem:} I send mail to the list, and get back mail saying the
+       list is not found!
+
+      \strong{Solution:} You probably didn't add the necessary aliases to the
+      system alias database, or you didn't properly integrate Mailman with
+      your mail server.  Perhaps you didn't update the alias database, or your
+      system requires you to run \program{newaliases} explicitly.  Refer to
+      your server specific instructions in the \ref{mail-server} section.
+
+\item \strong{Problem:} I send mail to the list, and get back mail saying,
+      ``unknown mailer error''.
+
+      \strong{Solution:} The likely problem is that you are using the wrong
+      user or group id for the mail wrappers.  Check your mail server's log
+      files; if you see a line like
+
+      \begin{verbatim}
+            Attempt to exec script with invalid gid 51, expected 99
+      \end{verbatim}
+
+      you will need to reinstall Mailman, specifying the proper mail group id
+      as described in the \label{building} section.
+
+\item \strong{Problem:} I use Postfix as my mail server and the mail wrapper
+      programs are logging complaints about the wrong GID.
+
+      \strong{Solution:} Make sure the \file{\var{\$prefix}/data/aliases.db}
+      file is user owned by \code{mailman} (or whatever user name you used
+      in the \program{configure} command).  If this file is not user owned by
+      \code{mailman}, Postfix will not run the mail programs as the correct
+      user.
+
+\item \strong{Problem:} I use Sendmail as my mail server, and when I send mail
+      to the list, I get back mail saying, ``sh: mailman not available for
+      sendmail programs''.
+
+      \strong{Solution:} Your system uses the Sendmail restricted shell
+      (smrsh). You need to configure smrsh by creating a symbolic link from
+      the mail wrapper (\file{\var{\$prefix}/mail/mailman}) to the directory
+      identifying executables allowed to run under smrsh.
+
+      Some common names for this directory are \file{/var/admin/sm.bin},
+      \file{/usr/admin/sm.bin} or \file{/etc/smrsh}.
+
+      Note that on Debian Linux, the system makes \file{/usr/lib/sm.bin},
+      which is wrong, you will need to create the directory
+      \file{/usr/admin/sm.bin} and add the link there.  Note further any
+      aliases \program{newaliases} spits out will need to be adjusted to point
+      to the secure link to the wrapper.
+
+\item \strong{Problem:}  I messed up when I called \program{configure}.  How
+      do I clean things up and re-install?
+
+      \strong{Solution:}
+
+      \begin{verbatim}
+        % make clean
+        % ./configure --with-the-right-options
+        % make install
+      \end{verbatim}
+
+\end{itemize}
+
+\section{Platform and operating system notes}
+
+Generally, Mailman runs on any POSIX-based system, such as Solaris, the
+various BSD variants, Linux systems, MacOSX, and other generic \UNIX{}
+systems.  It doesn't run on Windows.  For the most part, the generic
+instructions given in this document should be sufficient to get Mailman
+working on any supported platform.  Some operating systems have additional
+recommended installation or configuration instructions.
+
+\subsection{GNU/Linux issues}
+
+Linux seems to be the most popular platform for running Mailman.  Here are
+some hints on getting Mailman to run on Linux:
+
+\begin{itemize}
+\item If you are getting errors with hard link creations and/or you are using
+      a special secure kernel (securelinux/openwall/grsecurity), see the file
+      \file{contrib/README.check_perms_grsecurity} in the Mailman source
+      distribution.
+
+      Note that if you are using Linux Mandrake in secure mode, you are
+      probably concerned by this.
+
+\item Apparently Mandrake 9.0 changed the permissions on gcc, so if you build
+      as the \code{mailman} user, you need to be sure \code{mailman} is in the
+      \code{cctools} group.
+
+\item If you installed Python from your Linux distribution's package manager
+      (e.g. .rpms for Redhat-derived systems or .deb for Debian), you must
+      install the ``development'' package of Python, or you may not get
+      everything you need.
+
+      For example, using Python 2.2 on Debian, you will need to install the
+      \code{python2.2-dev} package.  On Redhat, you probably need the
+      \code{python2-devel} package.
+
+      If you install Python from source, you should be fine.
+
+      One symptom of this problem, although for unknown reasons, is that you
+      might get an error such as this during your install:
+
+      \begin{verbatim}
+          Traceback (most recent call last):
+            File "bin/update", line 44, in ?
+              import paths
+          ImportError: No module named paths
+          make: *** [update] Error 1
+      \end{verbatim}
+
+      If this happens, install the Python development package and try
+      \program{configure} and \program{make install} again.  Or install the
+      latest version of Python from source, available from
+      \url{http://www.python.org}.
+
+      This problem can manifest itself in other Linux distributions in
+      different ways, although usually it appears as \code{ImportErrors}.
+\end{itemize}
+
+\subsection{BSD issues\label{bsd-issues}}
+
+Vivek Khera writes that some BSDs do nightly security scans for setuid file
+changes.  setgid directories also come up on the scan when they change.  Also,
+the setgid bit is not necessary on BSD systems because group ownership is
+automatically inherited on files created in directories.  On other \UNIX{}es,
+this only happens when the directory has the setgid bit turned on.
+
+To install without turning on the setgid bit on directories, simply pass in
+the \var{DIRSETGID} variable to \program{make}, after you've run
+\program{configure}:
+
+\begin{verbatim}
+    % make DIRSETGID=: install
+\end{verbatim}
+
+This disables the \program{chmod g+s} command on installed directories.
+
+\subsection{MacOSX issues}
+
+Many people run Mailman on MacOSX.  Here are some pointers that have been
+collected on getting Mailman to run on MacOSX.
+
+\begin{itemize}
+\item Jaguar (MacOSX 10.2) comes with Python 2.2.  While this isn't the very
+      latest stable version of Python, it ought to be sufficient to run
+      Mailman 2.1.
+
+\item David B. O'Donnell has a web page describing his configuration of
+      Mailman 2.0.13 and Postfix on MacOSX Server.
+
+      \url{http://www.afp548.com/Articles/mail/python-mailman.html}
+
+\item Kathleen Webb posted her experiences in getting Mailman running on
+      Jaguar using Sendmail.
+
+      \url{http://mail.python.org/pipermail/mailman-users/2002-October/022944.html}
+
+\item Panther server (MacOSX 10.3) comes with Mailman; Your operating system
+      should contain documentation that will help you, and Apple has a tech
+      document about a problem you might encounter running Mailman on Mac OS X
+      Server 10.3:
+
+      \url{http://docs.info.apple.com/article.html?artnum=107889}
+\end{itemize}
+
+Terry Allen provides the following detailed instructions on running Mailman on
+the 'client' version of OSX, or in earlier versions of OSX:
+
+Mac OSX 10.3 and onwards has the basics for a successful Mailman installation.
+Users of earlier versions of Mac OSX contains Sendmail and those users should
+look at the Sendmail installation section for tips.  You should follow the
+basic installation steps as described earlier in this manual, substituting as
+appropriate, the steps outlined in this section.
+
+By default, Mac OSX 10.3 'client' version does not have a fully functional
+version of Postfix.  Setting up a working MTA such as Postfix is beyond the
+scope of this guide and you should refer to \url{http://www.postfix.org} for
+tips on getting Postfix running.  An easy way to set Postfix up is to install
+and run Postfix Enabler, a stand-alone tool for configuring Postfix on Mac
+OSX, available from 
+\url{http://www.roadstead.com/weblog/Tutorials/PostfixEnabler.html}.
+
+Likewise, Mac OSX 'client' version from 10.1 onwards includes a working Apache
+webserver.  This is switched on using the System Preferences control panel
+under the 'Sharing tab'.  A useful tool for configuring the Apache on Mac OSX
+is Webmin, which can be obtained from
+\url{http://www.webmin.com}.
+
+Webmin can also perform configuration for other system tasks, including
+Postfix, adding jobs to your crontab, adding user and groups, plus adding
+startup and shutdown jobs.
+
+In a stock installation of OSX, the requirement for Mailman is to have Python
+installed.  Python is not installed by default, so it is advised that you
+install the developer's tools package, which may have been provided with your
+system.  It can also be downloaded from the Apple developer site at
+\url{http://connect.apple.com}.  Not only is the developer tools package an
+essential requirement for installing Mailman, but it will come in handy at a
+later date should you need other tools.  The developer's tools are also know
+by the name XCode tools.
+
+As a minimum, the Python version should be 2.2, but 2.3 is recommended.
+
+If you wish to add a user and group using the command line in OSX instead of
+via Webmin or another GUI interface, open your terminal application and follow
+the commands as indicated below - do not type the comments following the
+\samp{\#} since they are just notes:
+
+\begin{verbatim}
+sudo tcsh
+niutil -create / /users/mailman
+niutil -createprop / /users/mailman name mailman
+# Note that xxx is a free user ID number on your system
+niutil -createprop / /users/mailman uid xxx
+niutil -createprop / /users/mailman home /usr/local/mailman
+mkdir -p /usr/local/mailman
+niutil -createprop / /users/mailman shell /bin/tcsh
+passwd mailman
+# To prevent malicious hacking, supply a secure password here
+niutil -create / /groups/mailman
+niutil -createprop / /groups/mailman name mailman
+# Note that xxx is a free group ID number on your system
+niutil -createprop / /groups/mailman gid xxx
+niutil -createprop / /groups/mailman passwd '*'
+niutil -createprop / /groups/mailman users 'mailman'
+chown mailman:mailman /usr/local/mailman
+cd /usr/local/mailman
+chmod a+rx,g+ws .
+exit
+su mailman
+\end{verbatim}
+
+For setting up Apache on OSX to handle Mailman, the steps are almost identical
+and the configuration file on a stock Mac OSX Client version is stored in the
+nearly standard location of \file{/etc/httpd/httpd.conf}.
+
+The \ulink{AFP548.com}{http://www.afp548.com} site has a time-saving automated startup item creator for
+Mailman, which can be found at 
+\url{http://www.afp548.com/Software/MailmanStartup.tar.gz}
+
+To install it, copy it into your \file{/Library/StartupItems} directory. As
+the root or superuser, from the terminal, enter the following:
+
+\begin{verbatim}
+gunzip MailmanStartup.tar.gz
+tar xvf MailmanStartup.tar
+\end{verbatim}
+
+It will create the startup item for you so that when you reboot, Mailman will
+start up.
+
+\end{document}