aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--INSTALL604
-rw-r--r--README54
-rw-r--r--README.BSD27
-rw-r--r--README.LINUX56
-rw-r--r--README.MACOSX36
-rw-r--r--README.POSTFIX222
-rw-r--r--README.SENDMAIL80
-rw-r--r--doc/mailman-install.tex1134
8 files changed, 1136 insertions, 1077 deletions
diff --git a/INSTALL b/INSTALL
index 63eb0b60..8a3ab134 100644
--- a/INSTALL
+++ b/INSTALL
@@ -2,608 +2,8 @@ Mailman - The GNU Mailing List Management System
Copyright (C) 1998-2004 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-This file contains installation instructions for GNU Mailman, which is
-configured using the standard GNU autoconf software. You first need
-to prepare your system as outlined in the sections below, and then
-configure and install the Mailman software.
-
-UPGRADING: Upgrading is usually as easy as just installing the new
-version over the existing installation. However, you should read the
-notes in the file UPGRADING for important information before you
-upgrade.
-
-The GNU Mailman website is at http://www.list.org
-
-GNU Mailman can be downloaded from
-http://sf.net/project/showfiles.php?group_id=103
-
-
-0. Installation requirements
-
- You must have a mail server (MTA) that you can send messages to,
- and a web server that supports the CGI/1.1 API. Apache makes a
- fine choice for web server, and MTAs such as Postfix, Exim,
- Sendmail, and qmail should work just fine.
-
- You will need an ANSI C compiler to build Mailman's security
- wrappers. The GNU C compiler gcc 2.8.1 or later is known to work
- well. For more information about obtaining gcc, see
-
- http://gcc.gnu.org
-
- You must have the Python interpreter installed somewhere on your
- system. Currently Python 2.1 or newer is required, with the
- latest patch release on any specific branch being recommended. As
- of this writing (10-Nov-2003) that is Python 2.1.3, Python 2.2.3,
- and Python 2.3.2.
-
- For information about obtaining Python source code, RPM packages,
- or pre-compiled binaries please see:
-
- http://www.python.org
-
- If you are building Python from source, you should be fine with
- the standard "./configure ; make install" for most Unix-like
- OSes. If you run "make test", you'll see a bunch of tests skipped
- -- don't worry, you probably won't need them. Mailman tries to
- stick to the basics that compile on most systems.
-
- If there is a README.<yourMTA> file that describes your mail
- server (MTA), read it now. Some MTAs can be integrated more
- seamlessly with Mailman for support of some advanced features
- (like creation and removal of lists through-the-web). Examples
- are Exim and Postfix. Setup instructions for specific MTAs are
- contained in these README files.
-
-
-1. System setup
-
- You will need to be root to perform the steps in this section.
-
- Before installing the Mailman software, you need to prepare your
- system by adding certain users and groups.
-
- - Add a new user called `mailman'. Typically this is added to
- your /etc/passwd file. If username `mailman' is already in use,
- choose something else unique and see the --with-username flag
- below.
-
- - Add a new group called `mailman'. Typically this is added to
- your /etc/group file. The Mailman files will be installed under
- the `mailman' group, with the set-group-id bit. Mailman's
- security is based on group-ownership permissions, so it is
- important to get this step right. If groupname `mailman' is
- already in use, choose something else unique and see the
- --with-groupname below. The mailman user created in the
- previous step must be a member of this group.
-
- - Create an installation directory (called $prefix in the
- documentation that follows). All of the Mailman files will be
- installed under $prefix. Run "configure --help" for ways to
- split the installation based on read-only vs. read/write files.
-
- The default installation directory for Mailman 2.1 is
- /usr/local/mailman. It used to be /home/mailman for all
- versions prior to Mailman 2.1alpha2. You can override the
- default by using the --prefix option to configure (see below).
- If you're upgrading from a version previous to Mailman 2.1, you
- will need to use --prefix unless you move your mailing lists
- (this can be a wise upgrade strategy).
-
- Watch out if your site does something like mount /usr/local with
- the nosuid option. This will break Mailman, which relies on
- set-gid programs for its security. If this describes your
- environment, simply install Mailman in a location that allows
- setgid programs.
-
- Make sure the install directory is set to group `mailman' (or
- whatever you're going to specify as --with-groupname) and has
- the setgid bit set (but see README.BSD if you're on a BSD
- system). You probably also want to guarantee that this
- directory is readable and executable by everyone. For example,
- these shell commands will accomplish this:
-
- % cd $prefix
- % chgrp mailman .
- % chmod a+rx,g+ws .
-
- You are now ready to configure and install the Mailman software.
-
-
-2. Running configure
-
- TAKE SPECIAL NOTE OF THE --with-mail-gid AND --with-cgi-gid
- OPTIONS BELOW. YOU WILL PROBABLY NEED TO USE THESE!
-
- You should 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 mailman, but you could. However, make sure that the login
- used is a member of the mailman group as that that group has write
- permissions to the $prefix directory made in the previous step.
-
- Make sure that you have write permissions to the target
- installation directory, and 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 configure script. Usually you can just cd to the
- directory you unpacked the Mailman source tarball into, and run
- configure with no arguments:
-
- % cd mailman-<version>
- % ./configure
- % make install
-
- The following options allow you to customize your Mailman
- installation.
-
- --prefix=<dir>
- Standard GNU configure option which changes the base
- directory that Mailman is installed into. By default
- $prefix is /usr/local/mailman. This directory must
- already exist, and be set up as described in section 1
- above.
-
- --exec-prefix=<dir>
- Standard GNU configure option which lets you specify a
- different installation directory for architecture
- dependent binaries.
-
- --with-var-prefix=<dir>
- Store mutable data under <dir> instead of under the prefix
- or exec_prefix. Examples of such data include the list archives
- and list settings database.
-
- --with-python=</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 $PATH. Note that when running
- the scripts from the command line, the first Python
- interpreter found on $PATH is always used.
-
- --with-username=<username-or-uid>
- Specify a different username than `mailman' to use as a
- default. Use this only if the username `mailman' is
- already in use by somebody (e.g. Mark Ailman's login
- name). This switch can take an integer user id or a user
- name. Be sure your $prefix directory is owned by this
- user.
-
- --with-groupname=<groupname-or-gid>
- Specify a different groupname than `mailman' to use as a
- default. Use this only if the groupname `mailman' is
- already in use. This switch can take an integer group id
- or a group name. Be sure your $prefix directory is
- group-owned by this group.
-
- --with-mail-gid=<group-or-groups>
- Specify an alternative group for running scripts via the
- mail wrapper. <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
- `mailman other mail daemon'.
-
- 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
- sendmail, the sendmail.cf configuration file designates
- the group id of sendmail processes using the "DefaultUser"
- option. (If commented out, it still may be indicating the
- default...)
-
- Check your MTA's documentation and configuration files to
- find the right value for this switch.
-
- --with-cgi-gid=<group-or-groups>
- Specify an alternative group for running scripts via the
- CGI wrapper. <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
- `www www-data nobody'.
-
- 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.
-
- If you're using Apache, check the values for the `Group'
- option in your httpd.conf file.
-
- --with-cgi-ext=<extension>
- Specify an extension for cgi-bin programs. The CGI
- wrappers placed in $PREFIX/cgi-bin will have this
- extension (some web servers require an extension).
- <extension> must include the dot.
-
- --with-mailhost
- Specify the fully qualified host name part for outgoing email.
- After the installation is complete, this value can be overriden in
- $prefix/Mailman/mm_cfg.py.
-
- --with-urlhost
- Specify the fully qualified host name part of urls. After the
- installation is complete, this value can be overriden in
- $prefix/Mailman/mm_cfg.py.
-
- --with-gcc=no
- Don't use gcc, even if it is found. In this case, `cc'
- must be found on your $PATH.
-
-
-3. Check your installation
-
- After you've run "make install", you can check that your
- installation has all the correct permissions and group ownerships
- by running the check_perms script:
-
- - cd to $prefix
-
- - Run bin/check_perms
-
- Don't try to run bin/check_perms from the source directory; it
- will only run from the install (i.e. $prefix) 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 check_perms to fix the problems (probably the easiest
- solution):
-
- - You need to become the user that did the installation (and that
- owns all the files in $prefix), or root.
-
- - Run bin/check_perms -f
-
- - Repeat previous step until no more errors are reported!
-
-
-4. Final system set-up
-
- 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 MTA and web server 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 Mailman/LockFile.py; the constant
- CLOCK_SLOP helps the locking mechanism compensate for clock skew
- in this type of environment.
-
- - Configure your web server to give $prefix/cgi-bin permission to
- run CGI scripts. You probably need to be root to do this.
-
- The line you should add might look something like the following
- (with the real absolute directory substituted for $prefix, of
- course):
-
- Exec /mailman/* $prefix/cgi-bin/*
- or:
- ScriptAlias /mailman/ $prefix/cgi-bin/
-
- Consult your web server's documentation for details.
-
- - You want to be very sure that the user id under which your CGI
- scripts run is *not* in the `mailman' group you created above,
- otherwise private archives will be accessible to anyone.
-
- - Copy the Mailman, Python, and GNU logos to a location accessible
- to your web server. E.g. with Apache, you've usually got an
- `icons' directory that you can drop the images into. For
- example:
-
- % cp $prefix/icons/*.{jpg,png} /path/to/apache/icons
-
- You then want to add a line to your $prefix/Mailman/mm_cfg.py
- file which sets the base URL for the logos. For example:
-
- IMAGE_LOGOS = '/images/'
-
- The default value for IMAGE_LOGOS is '/icons/'. Read the
- comment in Defaults.py.in for details.
-
- - Configure your web server to point to the Pipermail public
- mailing list archives:
-
- For example, in Apache:
-
- Alias /pipermail/ $varprefix/archives/public/
-
- where $varprefix is usually $prefix unless you've used the
- --with-var-prefix option to configure.
-
- Consult your web server's documentation for details. 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 FollowSymLinks
- option.
-
- Also, 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:
-
- <Directory "/usr/local/mailman/archives/public/">
- AddDefaultCharset Off
- </Directory>
-
- Now restart your web server.
-
- - Create a "site-wide" mailing list. This is the one that
- password reminders will appear to come from. Usually this
- should be the "mailman" mailing list, but if you need to change
- this, be sure to change the MAILMAN_SITE_LIST variable in
- mm_cfg.py (see below).
-
- % bin/newlist mailman
-
- Follow the prompts, and see the README file for more
- information.
-
- Now configure your site list. There is a convenient template
- for a generic site list in data/sitelist.cfg to help you with
- this. The template can be applied to your site list by running:
-
- % bin/config_list -i data/sitelist.cfg mailman
-
- Before doing this, review the configuration options in the
- template (note that many options are not changed by
- sitelist.cfg). After you do this, be sure you review the
- configurations via the admin pages for this list.
-
- Be sure to subscribe yourself to the site list, but use the
- admin interface because mailback subscription confirmations
- won't work at this point.
-
- - Set up the crontab entries. Mailman runs a number of cron jobs
- for its basic functionality. 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 -u option, you must be
- root to do this next step. Add $prefix/cron/crontab.in as a
- crontab entry by executing these commands:
-
- % cd $prefix/cron
- % crontab -u mailman crontab.in
-
- If you used the --with-username option, use that user name
- instead of mailman for the -u argument value. If your crontab
- does not support the -u option, try these commands:
-
- % cd $prefix/cron
- % su - mailman
- % crontab crontab.in
-
- - Start the Mailman qrunner daemon, by executing the following
- from the $prefix directory:
-
- % bin/mailmanctl start
-
- If you want to start Mailman every time you reboot your system,
- and your OS supports the chkconfig command (e.g. RedHat and
- Mandrake Linuxes) you can simply do the following (as root, from
- the Mailman install directory):
-
- % cp scripts/mailman /etc/init.d/mailman
- % chkconfig --add mailman
-
- (Note that /etc/init.d may be /etc/rc.d/init.d on some systems.)
-
- On Debian, you probably want to use
-
- % update-rc.d mailman defaults
-
- instead of chkconfig.
-
- For Unixes that don't support chkconfig, simply copy
- scripts/mailman as above:
-
- % cp scripts/mailman /etc/init.d/mailman
-
- then set up the following symbolic links, again as root:
-
- % 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
-
- - Check the values for DEFAULT_EMAIL_HOST and DEFAULT_URL_HOST in
- Defaults.py. Make any necessary changes in the mm_cfg.py file.
- Note that if you change either of these two values, you'll want
- to add the following afterwards in the mm_cfg.py file:
-
- add_virtualhost(DEFAULT_URL_HOST, DEFAULT_EMAIL_HOST)
-
- Note that you will want to run bin/fix_url.py to change the domain
- of an existing list.
-
-
-5. Customize Mailman
-
- You should do these steps using the account you installed Mailman
- under in section 2 above.
-
- - The file $prefix/Mailman/Defaults.py contains a number of
- defaults for your installation. If any of these are incorrect,
- override them in $prefix/Mailman/mm_cfg.py, NOT IN Defaults.py!
- See the comments in Defaults.py for details. Once a list is
- created, editing many of these variables will have no effect.
- At that point, you'll need to configure your lists through the
- web admin interface or through the command line script
- bin/withlist or bin/config_list.
-
- The install process will not overwrite an existing mm_cfg.py
- file so you can freely make changes to this file.
-
- Note: Do *not* change HOME_DIR or MAILMAN_DIR. These are set
- automatically by the configure script.
-
- - Create the site password using:
-
- % $prefix/bin/mmsitepass <your-site-password>
-
- This password can be used anywhere that individual user or
- mailing list administrator passwords are required, giving the
- mailman site administrator the ability to adjust these things
- when necessary.
-
- You may also want to create a password for the site-wide "list
- creator" role (someone other than the site administrator who as
- privileges to create and remove lists through the web). Use the
- -c option to mmsitepass to set this.
-
-
-6. Getting started
-
- See the README file under the section "CREATE YOUR FIRST LIST" for
- a quick introduction to creating an initial test list.
-
-
-7. Troubleshooting
-
- If you encounter problems with running Mailman, first check the
- "Common Problems" section, below. If your problem is not covered
- there, check both the FAQ file and the online FAQ Wizard. Also
- check for errors your syslog files and in the $prefix/logs/error
- file.
-
- Where syslog lives on your particular machine may vary. It may be
- in /var/log/maillog. It may also be in /var/log/syslog. On many
- machines, syslog files live in /adm/log/ instead of /var/log.
-
- If you encounter an error, send an error report to
- mailman-users@python.org. Include a description of what you're
- doing to cause the problem, and the relevant lines from your
- syslog. Also include information on your operating system, which
- version of Python you're using, and which version of Mailman
- you're installing.
-
-
-8. Common Problems
-
- Problem: All Mailman web pages give a 404 File not found error.
-
- Solution: Your web server has not been set up properly for handling
- Mailman's cgi commands. Make sure you've:
-
- 1) Configured the web server to give permissions to
- $prefix/cgi-bin
- 2) Restarted the web server properly.
-
- Consult your web server's documentation for instructions
- on how to do these things.
-
-
- Problem: All Mailman web pages give an "Internal Server Error".
-
- Solution: The likely problem is that you are using the wrong GID or
- UID for CGI scripts. Check your syslog. If you see, for
- example, a line like:
-
- Attempt to exec script with invalid gid 51, expected 99
-
- You need to reinstall Mailman, and specify $CGI_GID to be 51,
- as described in the installation instructions.
-
-
- Problem: I send mail to the list, and get back mail saying the
- list is not found!
-
- Solution: You probably didn't add the necessary aliases to the system
- alias database, given to you when you ran the newlist
- command. If you did add them, you likely did not update
- the alias database, or your system requires you to run
- newaliases explicitly. Refer to section 5 above for
- more information.
-
-
- Problem: I send mail to the list, and get back mail saying,
- "unknown mailer error".
-
- Solution: The likely problem is that you are using the wrong GID or
- UID for mail. Check your syslog. If you see, for
- example, a line like:
-
- Attempt to exec script with invalid gid 51, expected 99
-
- You need to reinstall Mailman, and specify $MAIL_GID to
- be 51, as described in the installation
- instructions. see notes on Postfix below, as by default
- it will create these problems on installation.
-
-
- Problem: I use Postfix for my MTA and the mail wrapper programs
- are logging complaints about the wrong GID.
-
- Solution: Create a separate aliases file for Postfix in its
- main.cf config file under the variable "alias_maps". Put
- the file somewhere in Mailman's home directory, or
- somewhere else where the user mailman has write access
- to it; *as user mailman* call Postfix's "postalias" on the
- alias file.
-
- % postalias <the alias file>
-
- Also as user mailman, run
-
- % python -c'import os; print os.getgid()'
-
- This should print out the group id that Mailman should
- be configured to expect when the mail wrapper programs
- are run. Call it "thegid". Rebuild Mailman with
-
- % ./configure --with-mail-gid=thegid
-
- See also the README.POSTFIX file for more information on
- connecting Postfix and Mailman.
-
-
- Problem: I send mail to the list, and get back mail saying,
- "sh: mailman not available for sendmail programs"
-
- Solution: Your system uses sendmail restricted shell (smrsh). You
- need to configure smrsh by creating a symbolic link from
- the mail wrapper ($prefix/mail/mailman) to the directory
- identifying executables allowed to run under smrsh.
-
- Some common names for this directory are
- /var/admin/sm.bin, /usr/admin/sm.bin or /etc/smrsh.
-
- Note that on Debian Linux, the system makes
- /usr/lib/sm.bin, which is wrong, you will need to create
- the directory /usr/admin/sm.bin and add the link there.
- Note further any aliases newaliases spits out will need
- to be adjusted to point to the secure link to the
- wrapper.
-
-
- Problem: I messed up when I called configure. How do I clean
- things up and re-install?
-
- Solution: % make clean
- % ./configure --with-the-right-options
- % make install
+For installation or upgrading instructions, please see the
+doc/mailman-install/index.html file.
diff --git a/README b/README
index 287a0dfd..b2758703 100644
--- a/README
+++ b/README
@@ -114,60 +114,6 @@ REQUIREMENTS
fancy plugins.
-CREATE YOUR FIRST LIST
-
- These instructions assume that you've installed and configured Mailman
- according to the instructions in the INSTALL file. To create and test
- your first list, try the following:
-
- - First, initialize the site administrator's password by cd'ing to the
- install directory (by default /usr/local/mailman) and typing
-
- % bin/mmsitepass
- New site password: [yourpassword]
- Again to confirm password: [yourpassword]
- Password changed.
-
- - Visit the url:
-
- http://my.dom.ain/mailman/create
-
- Fill out the form as described in the on-screen instructions, and in the
- "List creator's password" field, type the password you entered above.
- Type your own email address for the "Initial list owner address", and
- select "Yes" to notify the list administrator.
-
- - Hit "Create List"
-
- - Check your email for a message from Mailman informing you that your new
- mailing list was created.
-
- - NOTE: You should consult the README for the specific MTA you are using.
- Most can be set up to provide through-the-web creation of mailing lists,
- but each configuration is different.
-
- - Now visit the list's admin page (either by following the link on the web
- page or entering the link from the email Mailman just sent you).
- Typically the url will be something like
-
- http://my.dom.ain/mailman/admin/mysitelist
-
- Type in the list's password and click on "Let me in..."
-
- - Click on "Membership Management" and then on "Mass Subscription".
-
- - Enter your email address in the big text field, and click on "Submit
- Your Changes"
-
- - Now go to your email and send a message to yourlist@my.dom.ain. Within
- a minute or two you should see your message reflected back to you via
- Mailman.
-
- Congratulations! You've just set up and tested your first Mailman mailing
- list. If you had any problems along the way, please see the section below
- on FOR MORE INFORMATION.
-
-
FOR MORE INFORMATION
The online documentation can be found in
diff --git a/README.BSD b/README.BSD
deleted file mode 100644
index f5b6a0eb..00000000
--- a/README.BSD
+++ /dev/null
@@ -1,27 +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
-
-BSD ISSUES
-
-1. Vivek Khera writes that BSD does nightly security scans for setuid
- file changes. Setgid directories also come up on the scan when
- they change. He says that setgid bit is not necessary on BSD
- systems because group ownership is automatically inherited on files
- created in directories. On other Un*xes, 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 DIRSETGID variable to make, like so:
-
- % make DIRSETGID=: install
-
- This turns off the chmod g+s on each directory as they are
- installed.
-
-
-
-Local Variables:
-mode: text
-indent-tabs-mode: nil
-End:
diff --git a/README.LINUX b/README.LINUX
deleted file mode 100644
index eb410785..00000000
--- a/README.LINUX
+++ /dev/null
@@ -1,56 +0,0 @@
-Mailman - The GNU Mailing List Management System
-Copyright (C) 1998-2003 by the Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-
-GNU/LINUX ISSUES
-
- GNU/Linux seems to be the most popular platform on which to run
- Mailman. Here are some hints on getting Mailman to run on Linux:
-
- If you are getting errors with hard link creations and/or you are using
- a special secure kernel (securelinux/openwall/grsecurity), see
- contrib/README.check_perms_grsecurity.
-
- Note that if you are using Linux Mandrake in secure mode, you are probably
- concerned by this.
-
- Apparently Mandrake 9.0 changed the permissions on gcc, so if you
- build as the mailman user, you need to be sure mailman is in the
- cctools group.
-
-
-PYTHON PACKAGES
-
- Note that 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 python2.2-dev package. On Redhat, you probably need the
- 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:
-
- Traceback (most recent call last):
- File "bin/update", line 44, in ?
- import paths
- ImportError: No module named paths
- make: *** [update] Error 1
-
- If this happens, install the Python development package and try
- "configure ; make install" again.
-
- This problem can manifest itself in other Linux distributions in
- different ways, although usually it appears as ImportErrors.
-
-
-
-Local Variables:
-mode: text
-indent-tabs-mode: nil
-End:
diff --git a/README.MACOSX b/README.MACOSX
deleted file mode 100644
index f1397a7c..00000000
--- a/README.MACOSX
+++ /dev/null
@@ -1,36 +0,0 @@
-Mailman - The GNU Mailing List Management System
-Copyright (C) 2002-2004 by the Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-
-MacOSX ISSUES
-
- Mailman should run on MacOSX, although I have not personally had
- time to try it yet. Here are some pointers we've collected on
- getting Mailman to run on MacOSX.
-
- - 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.
-
- - David B. O'Donnell has a web page describing his configuration
- of Mailman 2.0.13 and Postfix on MacOSX Server.
-
- http://www.afp548.com/Articles/mail/python-mailman.html
-
- - Kathleen Webb posted her experiences in getting Mailman running
- on Jaguar using Sendmail.
-
- http://mail.python.org/pipermail/mailman-users/2002-October/022944.html
-
- - Apple has a tech document about a problem you might encounter running
- Mailman on Mac OS X Server 10.3:
-
- http://docs.info.apple.com/article.html?artnum=107889
-
-
-
-Local Variables:
-mode: text
-indent-tabs-mode: nil
-End:
diff --git a/README.POSTFIX b/README.POSTFIX
deleted file mode 100644
index d5da5d57..00000000
--- a/README.POSTFIX
+++ /dev/null
@@ -1,222 +0,0 @@
-Mailman - The GNU Mailing List Management System
-Copyright (C) 2001-2004 by the Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-
-GENERAL SETUP INFORMATION
-
- Mailman should work pretty much out of the box with a standard
- Postfix installation. As of this writing I've tested it with
- Postfix 19991231 up to pl13, 200010228 up to pl08, and up to
- Postfix 2.0.15.
-
- By default, Postfix treats -owner and -request addresses
- specially. Since we want Postfix to deliver such messages to
- Mailman, you should turn off this option by adding this to your
- main.cf file:
-
- owner_request_special = no
-
- In order to support Mailman's optional VERP delivery, you will
- want to disable luser_relay (the default) and you will want to set
- recipient_delimiter for extended address semantics. You should
- comment out any luser_relay value in your main.cf and just go with
- the defaults. Also, add this to your main.cf file:
-
- recipient_delimiter = +
-
- Using + as the delimiter works well with the default values for
- VERP_FORMAT and VERP_REGEXP in 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
- 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 main.cf file:
-
- unknown_local_recipient_reject_code = 550
-
- Finally, if you are using Postfix-style virtual domains, read the
- section on virtual domain support below.
-
-
-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. /usr/local/mailman. If that's not
- the case, adjust the instructions according to your use of
- configure's --prefix and --with-var-prefix options.
-
- - If you are using virtual domains and you want Mailman to honor
- your virtual domains, read the section below first!
-
- - Add this to the bottom of the $prefix/Mailman/mm_cfg.py file:
-
- MTA = 'Postfix'
-
- The MTA variable names a module in Mailman/MTA which contains the
- MTA-specific functions to be executed when a list is created or
- removed.
-
- - Look at the Defaults.py file for the variables POSTFIX_ALIAS_CMD
- and POSTFIX_MAP_CMD command. Make sure these point to your
- postalias and postmap programs respectively. Remember that if
- you need to make changes, do it in mm_cfg.py.
-
- - Run the genaliases script to initialize your aliases file.
-
- % cd /usr/local/mailman
- % bin/genaliases
-
- Make sure that the owner of the data/aliases and data/aliases.db
- file is `mailman' and that the group owner for those files is
- `mailman'. E.g.:
-
- % su
- % chown mailman:mailman data/aliases*
-
- - Hack your Postfix's main.cf file to include the following path
- in your alias_maps variable:
-
- /usr/local/mailman/data/aliases
-
- (no trailing .db). Do not include this in your alias_database
- variable. This is because you do not want Postfix's newaliases
- command to modify Mailman's aliases.db file, but you do want
- Postfix to consult aliases.db when looking for local addresses.
-
- You probably want to use a hash: style database for this entry.
- Here's an example:
-
- alias_maps = hash:/etc/postfix/aliases,
- hash:/usr/local/mailman/data/aliases
-
- - When you configure Mailman, use the --with-mail-gid=mailman
- switch (actually, this will be the default if you configured
- Mailman after adding the `mailman' owner). Because the owner of
- the aliases.db file is `mailman', Postfix will execute Mailman's
- wrapper program as uid and gid mailman.
-
- That's it! One caveat: when you add or remove a list, the
- aliases.db file will updated, but it will not automatically run
- "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 aliases.db file and update its tables. I consider this a
- minor inconvenience.
-
-
-VIRTUAL DOMAINS
-
- 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,
- /usr/local/mailman/data/virtual-mailman. It will also use postmap
- to create the 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 virtual(5)
- manpage). Note that it's your responsibility to include the
- "virtual-alias.domain anything" line as described manpage; Mailman
- will not include this line in virtual-mailman. I highly encourage
- you to make sure your virtual alias domains are working properly
- before integrating with Mailman.
-
- Next, add a path to Postfix's virtual_alias_maps variable,
- pointing to the virtual-mailman file, e.g.:
-
- virtual_alias_maps = <your normal virtual alias files>,
- hash:/usr/local/mailman/data/virtual-mailman
-
- assuming you've installed Mailman in the default location. If
- you're using an older version of Postfix which doesn't have the
- virtual_alias_maps variable, use the virtual_maps variable
- instead.
-
- Next, in your mm_cfg.py file, you will want to set the variable
- 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 host_name attribute of
- mailing lists objects, and must be an exact match.
-
- Here's an example:
-
- Let's say I've set up Postfix to handle the virtual domains
- dom1.ain, dom2.ain, and dom3.ain. Let's say further that in
- main.cf you've got the following settings:
-
- 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
-
- Let's say further that in virtual-dom1, you've got the following
- lines:
-
- dom1.ain IGNORE
- @dom1.ain @mail.dom1.ain
-
- This tells Postfix to deliver anything addressed to dom1.ain to
- the same mailbox at mail.dom1.com, its default destination.
-
- In this case you would not include dom1.ain in
- POSTFIX_STYLE_VIRTUAL_DOMAINS because otherwise Mailman will write
- entries for mailing lists in the dom1.ain domain as
-
- mylist@dom1.ain mylist
- mylist-request@dom1.ain mylist-request
- # and so on...
-
- The more specific entries trump your more general entries, thus
- breaking the delivery of any dom1.ain mailing list.
-
- However, you would include dom2.ain and dom3.ain in mm_cfg.py:
-
- POSTFIX_STYLE_VIRTUAL_DOMAINS = ['dom2.ain', 'dom3.ain']
-
- Now, any list that Mailman creates in either of those two domains,
- will have the correct entries written to
- /usr/local/mailman/data/virtual-mailman
-
- As above with the data/aliases* files, you want to make sure that
- both data/virtual-mailman and data/virtual-mailman.db are user and
- group owned by the `mailman' user/group. So to get things
- started, set up your virtual domains, run bin/genaliases, and
- check the ownerships of the files. From here on out, you should
- be good to go.
-
-
-AN ALTERNATIVE APPROACH
-
- Fil <fil@rezo.net> has an alternative approach based on virtual
- maps and regular expressions, as described at:
-
- (French) http://listes.rezo.net/comment.php
- (English) http://listes.rezo.net/how.php
-
- 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 mylist@lists.dom.ain instead of mylist@dom.ain.
-
- I have not extensively tested this approach however.
-
-
-
-Local Variables:
-mode: text
-indent-tabs-mode: nil
-End:
diff --git a/README.SENDMAIL b/README.SENDMAIL
deleted file mode 100644
index 3d9a8138..00000000
--- a/README.SENDMAIL
+++ /dev/null
@@ -1,80 +0,0 @@
-Mailman - The GNU Mailing List Management System
-Copyright (C) 1998-2004 by the Free Software Foundation, Inc.
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-SECURITY NOTE
-
- You may be tempted to set the DELIVERY_MODULE configuration
- variable in mm_cfg.py to `Sendmail' when using the Sendmail MTA.
- Don't. The Sendmail.py module is misnamed -- it's really a
- command line based message handoff scheme as opposed to the SMTP
- scheme used in SMTPDirect (the default). Sendmail.py has known
- security holes and is provided as a proof-of-concept only. If you
- are having problems using SMTPDirect.py please fix those instead
- of using Sendmail.py, or you may open your system up to security
- exploits.
-
-
-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 filter 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 doing this is to:
-
- - Find out where your Sendmail executes its smrsh wrapper
-
- % grep smrsh /etc/mail/sendmail.cf
-
- - Figure out where smrsh expects symlinks for allowable filter
- programs. At the very beginning of the following output you will
- see a full path to some directory, e.g. /var/adm/sm.bin or similar:
-
- % strings $path_to_smrsh | less
-
- - cd into /var/adm/sm.bin, or where ever it happens to reside on your
- system, such as /etc/smrsh, /var/smrsh or /usr/local/smrsh.
-
- % cd /var/adm/sm.bin
-
- - create a symbolic link to Mailman's wrapper program
-
- % ln -s /usr/local/mailman/mail/mailman mailman
-
-
-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 contrib directory, you will find four files
-
- mm-handler.readme - an explanation of how to set everything up
- mm-handler - the mail delivery agent (MDA)
- mailman.mc - a toy configuration file sample
- virtusertable - a sample for RFC 2142 address exceptions
-
-
-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 localhost (i.e. 127.0.0.1) to the SMTP port of
- Sendmail, you should be sure to configure Sendmail /not/ to do DNS
- verification synchronously for localhost connections.
-
-
-
-Local Variables:
-mode: text
-indent-tabs-mode: nil
-End:
diff --git a/doc/mailman-install.tex b/doc/mailman-install.tex
new file mode 100644
index 00000000..0c6aa2ad
--- /dev/null
+++ b/doc/mailman-install.tex
@@ -0,0 +1,1134 @@
+\documentclass{howto}
+
+\title{GNU Mailman - Installation Manual}
+\author{Barry Warsaw}
+\authoraddress{\email{barry(at)python.org}}
+
+\date{\today}
+\release{2.1} % software release, not documentation
+\setreleaseinfo{} % empty for final release
+\setshortversion{2.1} % major.minor only for software
+
+\begin{document}
+
+\maketitle
+
+% This makes the Abstract go on a separate page in the HTML version;
+% if a copyright notice is used, it should go immediately after this.
+%
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+\begin{abstract}
+\noindent
+This document describes how to install GNU Mailman on a POSIX-based system
+such as \UNIX{}, MacOSX, or GNU/Linux. It will cover basic installation
+instructions, as well as guidelines for integrating Mailman with your web and
+mail servers.
+
+The GNU Mailman website is at \url{http://www.list.org}
+\end{abstract}
+
+% The ugly "%begin{latexonly}" pseudo-environment supresses the table
+% of contents for HTML generation.
+%
+%begin{latexonly}
+\tableofcontents
+%end{latexonly}
+
+
+\section{Installation Requirements}
+
+GNU Mailman works on most POSIX-based systems such as \UNIX{}, MacOSX, or
+GNU/Linux. It does not currently work on Windows. You must have a mail
+server that you can send messages to, and a web server that supports the
+CGI/1.1 API. \ulink{Apache}{http://httpd.apache.org} makes a fine choice for
+web server, and mail servers such as
+\ulink{Postfix}{http://www.postfix.org},
+\ulink{Exim}{http://www.exim.org},
+\ulink{Sendmail}{http://www.sendmail.org}, and
+\ulink{qmail}{http://cr.yp.to/qmail.html} should
+work just fine.
+
+To install Mailman from source, you will need an ANSI C compiler to build
+Mailman's security wrappers. The
+\ulink{GNU C compiler gcc}{http://gcc.gnu.org} 2.8.1 or later is known
+to work well.
+
+You must have the \ulink{Python}{http://www.python.org} interpreter installed
+somewhere on your system. Mailman 2.1 requires Python 2.1 or newer, although
+Python 2.3 or newer is recommended.
+
+\section{Setting 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}
+
+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{Creating 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{Building and installing\label{building}}
+
+\subsection{Running \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}
+
+\section{Setting 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{Setting 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.
+
+By default, Postfix treats \code{-owner} and \code{-request} addresses
+specially. Since you want Postfix to deliver such messages to Mailman, you
+should turn off this option by adding this to your \file{main.cf} file:
+
+\begin{verbatim}
+ owner_request_special = no
+\end{verbatim}
+
+In order to support Mailman's optional VERP delivery, you will want to disable
+\code{luser_relay} (the default) and you will want to set
+\code{recipient_delimiter} for extended address semantics. You should comment
+out any \code{luser_relay} value in your \file{main.cf} and just go with the
+defaults. Also, add this to your \file{main.cf} file:
+
+\begin{verbatim}
+ recipient_delimiter = +
+\end{verbatim}
+
+Using \samp{+} as the delimiter works well with the default values for
+\var{VERP_FORMAT} and \var{VERP_REGEXP} in \file{Defaults.py}.
+
+When attempting to deliver a message to a non-existent local address, Postfix
+may return a 450 error code. Since this is a transient error code, Mailman
+will continue to attempt to deliver the message for
+\var{DELIVERY_RETRY_PERIOD} -- 5 days by default. You might want to set
+Postfix up so that it returns permanent error codes for non-existent local
+users by adding the following to your \file{main.cf} file:
+
+\begin{verbatim}
+ unknown_local_recipient_reject_code = 550
+\end{verbatim}
+
+Finally, if you are using Postfix-style virtual domains, read the section on
+virtual domain support below.
+
+\subsubsection{Integrating Postfix and Mailman}
+
+You can integrate Postfix and Mailman such that when new lists are created, or
+lists are removed, Postfix's alias database will be automatically updated.
+The following are the steps you need to take to make this work.
+
+In the description below, we assume that you've installed Mailman in the
+default location, i.e. \file{/usr/local/mailman}. If that's not the case,
+adjust the instructions according to your use of \program{configure}'s
+\longprogramopt{prefix} and \longprogramopt{with-var-prefix} options.
+
+\begin{notice}[note]
+If you are using virtual domains and you want Mailman to honor your virtual
+domains, read the \ref{postfix-virtual} section below first!
+\end{notice}
+
+\begin{itemize}
+\item Add this to the bottom of the \file{\var{\$prefix}/Mailman/mm_cfg.py}
+ file:
+
+ \begin{verbatim}
+ MTA = 'Postfix'
+ \end{verbatim}
+
+ The MTA variable names a module in the \file{Mailman/MTA} directory
+ which contains the mail server-specific functions to be executed when a
+ list is created or removed.
+
+\item Look at the \file{Defaults.py} file for the variables
+ \var{POSTFIX_ALIAS_CMD} and \var{POSTFIX_MAP_CMD} command. Make sure
+ these point to your \program{postalias} and \program{postmap} programs
+ respectively. Remember that if you need to make changes, do it in
+ \file{mm_cfg.py}.
+
+\item Run the \program{bin/genaliases} script to initialize your
+ \file{aliases} file.
+
+ \begin{verbatim}
+ % cd /usr/local/mailman
+ % bin/genaliases
+ \end{verbatim}
+
+ Make sure that the owner of the \file{data/aliases} and
+ \file{data/aliases.db} file is \code{mailman} and that the group owner
+ for those files is \code{mailman}, or whatever user and group you used
+ in the configure command:
+
+ \begin{verbatim}
+ % su
+ % chown mailman:mailman data/aliases*
+ \end{verbatim}
+
+\item Hack your Postfix's \file{main.cf} file to include the following path in
+ your \var{alias_maps} variable:
+
+ \begin{verbatim}
+ /usr/local/mailman/data/aliases
+ \end{verbatim}
+
+ Note that there should be no trailing \code{.db}. Do not include this
+ in your \var{alias_database} variable. This is because you do not want
+ Postfix's \program{newaliases} command to modify Mailman's
+ \file{aliases.db} file, but you do want Postfix to consult
+ \file{aliases.db} when looking for local addresses.
+
+ You probably want to use a \code{hash:} style database for this entry.
+ Here's an example:
+
+ \begin{verbatim}
+ alias_maps = hash:/etc/postfix/aliases,
+ hash:/usr/local/mailman/data/aliases
+ \end{verbatim}
+
+\item When you configure Mailman, use the
+ \longprogramopt{with-mail-gid=mailman} switch; this will be the default
+ if you configured Mailman after adding the \code{mailman} owner.
+ Because the owner of the \file{aliases.db} file is \code{mailman},
+ Postfix will execute Mailman's wrapper program as uid and gid
+ \code{mailman}.
+
+\end{itemize}
+
+That's it! One caveat: when you add or remove a list, the \file{aliases.db}
+file will updated, but it will not automatically run \program{postfix reload}.
+This is because you need to be root to run this and suid-root scripts are not
+secure. The only effect of this is that it will take about a minute for
+Postfix to notice the change to the \file{aliases.db} file and update its
+tables.
+
+\subsubsection{Virtual domains\label{postfix-virtual}}
+
+Postfix 2.0 supports ``virtual alias domains'', essentially what used to be
+called ``Postfix-style virtual domains'' in earlier Postfix versions. To make
+virtual alias domains work with Mailman, you need to do some setup in both
+Postfix and Mailman. Mailman will write all virtual alias mappings to a file
+called, by default, \file{/usr/local/mailman/data/virtual-mailman}. It will
+also use \program{postmap} to create the \program{virtual-mailman.db} file
+that Postfix will actually use.
+
+First, you need to set up the Postfix virtual alias domains as described in
+the Postfix documentation (see Postfix's \code{virtual(5)} manpage). Note
+that it's your responsibility to include the \code{virtual-alias.domain
+anything} line as described manpage; Mailman will not include this line in
+\file{virtual-mailman}. You are highly encouraged to make sure your virtual
+alias domains are working properly before integrating with Mailman.
+
+Next, add a path to Postfix's \var{virtual_alias_maps} variable, pointing to
+the virtual-mailman file, e.g.:
+
+\begin{verbatim}
+ virtual_alias_maps = <your normal virtual alias files>,
+ hash:/usr/local/mailman/data/virtual-mailman
+\end{verbatim}
+
+assuming you've installed Mailman in the default location. If you're using an
+older version of Postfix which doesn't have the \var{virtual_alias_maps}
+variable, use the \var{virtual_maps} variable instead.
+
+Next, in your \file{mm_cfg.py} file, you will want to set the variable
+\var{POSTFIX_STYLE_VIRTUAL_DOMAINS} to the list of virtual domains that Mailman
+should update. This may not be all of the virtual alias domains that your
+Postfix installation supports! The values in this list will be matched
+against the \var{host_name} attribute of mailing lists objects, and must be an
+exact match.
+
+Here's an example. Say that Postfix is configured to handle the virtual
+domains \code{dom1.ain}, \code{dom2.ain}, and \code{dom3.ain}, and further
+that in your \file{main.cf} file you've got the following settings:
+
+\begin{verbatim}
+ myhostname = mail.dom1.ain
+ mydomain = dom1.ain
+ mydestination = $myhostname, localhost.$mydomain
+ virtual_alias_maps =
+ hash:/some/path/to/virtual-dom1,
+ hash:/some/path/to/virtual-dom2,
+ hash:/some/path/to/virtual-dom2
+\end{verbatim}
+
+If in your \file{virtual-dom1} file, you've got the following lines:
+
+\begin{verbatim}
+ dom1.ain IGNORE
+ @dom1.ain @mail.dom1.ain
+\end{verbatim}
+
+this tells Postfix to deliver anything addressed to \code{dom1.ain} to the
+same mailbox at \code{mail.dom1.com}, its default destination.
+
+In this case you would not include \code{dom1.ain} in
+\var{POSTFIX_STYLE_VIRTUAL_DOMAINS} because otherwise Mailman will write
+entries for mailing lists in the dom1.ain domain as
+
+\begin{verbatim}
+ mylist@dom1.ain mylist
+ mylist-request@dom1.ain mylist-request
+ # and so on...
+\end{verbatim}
+
+The more specific entries trump your more general entries, thus breaking the
+delivery of any \code{dom1.ain} mailing list.
+
+However, you would include \code{dom2.ain} and \code{dom3.ain} in
+\file{mm_cfg.py}:
+
+\begin{verbatim}
+ POSTFIX_STYLE_VIRTUAL_DOMAINS = ['dom2.ain', 'dom3.ain']
+\end{verbatim}
+
+Now, any list that Mailman creates in either of those two domains, will have
+the correct entries written to \file{/usr/local/mailman/data/virtual-mailman}.
+
+As above with the \file{data/aliases*} files, you want to make sure that both
+\file{data/virtual-mailman} and \file{data/virtual-mailman.db} are user and
+group owned by \code{mailman}.
+
+\subsubsection{An alternative approach}
+
+Fil \email{fil@rezo.net} has an alternative approach based on virtual maps and
+regular expressions, as described at:
+
+\begin{itemize}
+\item (French) \url{http://listes.rezo.net/comment.php}
+\item (English) \url{http://listes.rezo.net/how.php}
+\end{itemize}
+
+This is a good (and simpler) alternative if you don't mind exposing an
+additional hostname in the domain part of the addresses people will use to
+contact your list. I.e. if people should use \code{mylist@lists.dom.ain}
+instead of \code{mylist@dom.ain}.
+
+\subsection{Using the Exim mail server}
+
+\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}
+
+\subsection{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{Setting 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{Starting 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{mm_cfg.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{Customizing 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
+using the account you installed Mailman under in the \ref{building} section.
+
+\begin{itemize}
+\item The file \file{\var{\$prefix/Mailman/Defaults.py}} contains a number of
+ defaults for your installation. If any of these are incorrect, override
+ them in \file{\var{\$prefix}/Mailman/mm_cfg.py}, \strong{not} in the
+ \file{Defaults.py} file! See the comments in \file{Defaults.py} for
+ details. Once a list is created, editing many of these variables will
+ have no effect. At that point, you'll need to configure your lists
+ through the web administration interface or through the command line
+ scripts \program{bin/withlist} and \program{bin/config_list}.
+
+ The install process will never overwrite an existing \file{mm_cfg.py}
+ file so you can freely make changes to this file.
+
+ \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}
+\item Create the site password. Use this command:
+
+\begin{verbatim}
+ % $prefix/bin/mmsitepass <your-site-password>
+\end{verbatim}
+
+ This password can be used anywhere that individual user or mailing list
+ administrator passwords are required, giving the mailman site
+ administrator the ability to adjust these things when necessary.
+
+ You may also want to create a password for the site-wide ``list creator''
+ role. The list creator is someone other than the site administrator who
+ has privileges to create and remove lists through the web interface. Use
+ the \programopt{-c} option to \program{mmsitepass} to set this.
+
+\end{itemize}
+
+\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 integration 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; 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}
+
+\end{document}