Integrate Qmail instructions into the install manual.

2 files changed, 217 insertions, 199 deletions

diff --git a/README.QMAIL b/README.QMAIL
deleted file mode 100644
index e7a800fc..00000000
--- a/README.QMAIL
+++ /dev/null
@@ -1,186 +0,0 @@
-Mailman - The GNU Mailing List Management System
-Copyright (C) 1998,1999,2000,2001,2002 by the Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-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).
-
-- You might need to set the mail-gid user to either "qmail", "mailman", or
-  "nofiles" by using the --with-mail-gid configure option.
-
-  BN: it highly depends on your mail storing policy.  For example if
-  you use the simple ~alias/.qmail-* files, you can use `id -g alias`.
-  But if you use /var/qmail/users, the specified mail gid can be
-  used.
-
-  If you are going to be directing virtual domains directly to the
-  "mailman" user (using "virtualdomains" on a list-only domain, for
-  example), you will have to use --with-mail-gid=<gid of mailman user's group>
-  This is incompatible with having list aliases in ~alias, unless that alias
-  simply forwards to "mailman-listname*".
-
-- If there is a user `mailman' on your system, the alias
-  `mailman-owner' will work only in ~mailman.  You have to do a "touch
-  .qmail-owner" in ~mailman directory to create this alias.
-
-  NB: An alternative, IMHO better solution is to `chown root
-  ~mailman', that will stop qmail from considering `mailman' to be a
-  user to whom mail can be delivered.  (See `man 8 qmail-getpw'.)
-
-- 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
-  `-' in them.  Putting .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 /var/qmail/users/assign file:
-
-  +zope-:alias:112:11:/var/qmail/alias:-:zope-:
-  .
-
-  where in this case the listname is e.g. zope-users.
-
-  NB: Alternatively, you could host the lists on a virtual domain, and
-  use the /var/qmail/control/virtualdomains file to put the mailman
-  user in charge of this virtual domain.
-
-- BN: If inbound messages are delivered by another user than mailman,
-  it's necessary to allow it to access ~mailman.  Be sure that
-  ~mailman has group writing access and setgid bit is set.  Then put
-  the delivering user to mailman group, and you can deny access to
-  ~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.  NB: E.g. make an additional "A" DNS record for the
-  virtual mailserver pointing to your IP address, add the line
-  `lists.kva.hu:mailman' to /var/qmail/control/virtualdomains and a
-  `lists.kva.hu' line to /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:
-      .qmail              => mailman@...'s letters
-      .qmail-owner        => mailman-owner's letters
-
-
-  For list aliases, you can either create them manually:
-      .qmail-list         => posts to the 'list' list
-      .qmail-list-admin   => posts to the 'list's owner
-      .qmail-list-request => requests to 'list'
-      etc
-
-  or for automatic list alias handling (when using the lists.kva.hu virtual
-  as above), see "contrib/qmail-to-mailman.py" in the Mailman distribution.
-  Modify the "~mailman/.qmail-default" to include:
-
-      |/path/to/python /path/to/qmail-to-mailman.py
-
-  and new lists will automatically be picked up.
-
-- 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 
-  /etc/hosts.allow file:
-
-  tcp-env: 127. 10.205.200 : setenv RELAYCLIENT
-
-  where 10.205.200. is your IP address block.  If you use tcpserver, then you
-  need something like the following in your /etc/tcp.smtp file:
-
-  10.205.200.:allow,RELAYCLIENT=""
-  127.:allow,RELAYCLIENT=""
-
-- BN: Bigger /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.
-
-- More information about setting up qmail and relaying can be found in 
-  the qmail documentation.
-
-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 "contrib/qmail-to-mailman.py"):
-
-This script is for the Mailman 2.0 series:
-#!/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
-
-This script is for the Mailman 2.1 series:
-Note: this is for a new Mailman 2.1 installation.  Users upgrading from
-      Mailman 2.0 would most likely change /usr/local/mailman to
-      /home/mailman.  If in doubt, refer to the --prefix option passed to
-      configure during compile time.
-
-#!/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
-
-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 mm_cfg.py file:
-
-VERP_FORMAT = '%(bounces)s-+%(mailbox)s=%(host)s'
-VERP_REGEXP = r'^(?P<bounces>.*?)-\+(?P<mailbox>[^=]+)=(?P<host>[^@]+)@.*$'
-
-The second option is a patch on SourceForge located at:
-
-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.
-
-VIRTUAL MAIL SERVER
-
-As mentioned in the ISSUES area for a virtual mail server, a patch under
-testing is located at:
-
-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.
-
-MORE INFORMATION
-
-You might be interested in some information on modifying footers that
-Norbert Bollow has written about Mailman and qmail, available here:
-
-    http://mailman.cis.to/qmail-verh/
-
-
-Local Variables:
-mode: text
-indent-tabs-mode: nil
-End:
diff --git a/doc/mailman-install.tex b/doc/mailman-install.tex
index 9b188462..84c9c2f7 100644
--- a/doc/mailman-install.tex
+++ b/doc/mailman-install.tex
@@ -27,6 +27,7 @@ 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}
 
@@ -60,13 +61,13 @@ 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{Setting up your system}
+\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{Adding the group and user}
+\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
@@ -92,7 +93,7 @@ accounts.  Check your system's manual pages for details:
     % useradd -c''GNU Mailman'' -s /no/shell -d /no/home -g mailman mailman
 \end{verbatim}
 
-\subsection{Creating the installation directory\label{create-install-dir}}
+\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
@@ -130,9 +131,9 @@ commands will accomplish this:
 
 You are now ready to configure and install the Mailman software.
 
-\section{Building and installing\label{building}}
+\section{Build and install Mailman\label{building}}
 
-\subsection{Running \program{configure}}
+\subsection{Run \program{configure}}
 
 Before you can install Mailman, you must run \program{configure} to set
 various installation options your system might need.
@@ -282,7 +283,7 @@ to fix the problems (probably the easiest solution):
 \item Repeat previous step until no more errors are reported!
 \end{itemize}
 
-\section{Setting up your web server}
+\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
@@ -367,7 +368,7 @@ Here's an example for Apache, based on the standard installation directories:
 
 Now restart your web server.
 
-\section{Setting up your mail server\label{mail-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
@@ -830,7 +831,6 @@ 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
@@ -1039,9 +1039,213 @@ performance.  Since Mailman usually connects via \code{localhost}
 Sendmail to \strong{not} do DNS verification synchronously for localhost
 connections.
 
-\subsection{Using the Qmail mail server}
+\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}
+          |/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/}
 
-\subsection{Create a site-wide mailing list}
+\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
@@ -1073,7 +1277,7 @@ site list's configuration via the admin pages.
 
 You should also subscribe yourself to the site list.
 
-\section{Setting up cron}
+\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
@@ -1101,7 +1305,7 @@ crontab does not support the \programopt{-u} option, try these commands:
     % crontab crontab.in
 \end{verbatim}
 
-\section{Starting the Mailman qrunner}
+\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
@@ -1173,7 +1377,7 @@ in the \file{mm_cfg.py} file:
 You will want to run the \program{bin/fix_url.py} to change the domain of any
 existing lists.
 
-\section{Customizing Mailman\label{customizing}}
+\section{Customize Mailman\label{customizing}}
 
 Now that Mailman is all set up, there are a few site-wide configurations you
 can make before you start creating mailing lists.  You should do these steps