diff options
Diffstat (limited to 'doc/mailman-install.tex')
| -rw-r--r-- | doc/mailman-install.tex | 1808 |
1 files changed, 0 insertions, 1808 deletions
diff --git a/doc/mailman-install.tex b/doc/mailman-install.tex deleted file mode 100644 index efc9a5e3..00000000 --- a/doc/mailman-install.tex +++ /dev/null @@ -1,1808 +0,0 @@ -\documentclass{howto} - -\title{GNU Mailman - Installation Manual} -\author{Barry Warsaw} -\authoraddress{\email{barry (at) list dot 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} - -\emph{Please note that the information on this page may be out of date.} -Check for the -\ulink{latest installation information}{http://wiki.list.org/x/bAM} on the -\ulink{Mailman wiki}{http://wiki.list.org}. - -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} works well. - -You must have the \ulink{Python}{http://www.python.org} interpreter installed -somewhere on your system. As of this writing, Python 2.4.4 is recommended, -but see the wiki page above for the latest information. - -\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}, that the group owner - for those files is \code{mailman}, or whatever user and group you used - in the configure command, and that both files are group writable: - - \begin{verbatim} - % su - % chown mailman:mailman data/aliases* - % chmod g+w 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} |