$OpenBSD: README,v 1.2 2010/11/10 07:36:44 ajacoutot Exp $
Throughout this document $mailmandir is the directory mailman is installed
in. This defaults to ${TRUEPREFIX}/lib/mailman. Most of this text is
taken from the file INSTALL of the mailman distribution, with some
OpenBSD specific comments added. It's a good time to become root, now.
1) Final Steps for Installation
- Configure your web server to give $mailmandir/cgi-bin permission to
run CGI scripts by adding
ScriptAlias /mailman/ "$mailmandir/cgi-bin/"
to /var/www/conf/httpd.conf. There is also a <Directory> directive
you should have a look at.
- Copy the Mailman, Python, GNU and OpenBSD 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. You want
to copy $mailmandir/icons/mailman.jpg, $mailmandir/icons/PythonPowered.png,
$mailmandir/icons/gnu-head-tiny.jpg, $mailmandir/icons/mm-icon.png
and /var/www/htdocs/openbsd_pb.gif to this directory.
You then want to add a line to your $mailmandir/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/ "/var/spool/mailman/archives/public/"
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 "/var/spool/mailman/archives/public/">
AddDefaultCharset Off
</Directory>
Now restart your web server.
- Create a "site-wide" mailing list. This is the one that password
reminders, error reports and warnings 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), too. As of mailman 2.1.x this list is
mandatory. You won't be able to run 'mailmanctl' without it.
% bin/newlist mailman
Follow the prompts, and see the README file for more information.
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. Add $mailmandir/cron/crontab.in as a
crontab entry by executing these commands:
% cd $mailmandir/cron
% crontab -u _mailman crontab.in
- Start the Mailman qrunner daemon, by executing the following
from the $mailmandir directory:
% bin/mailmanctl start
If you want to start Mailman every time you reboot your system,
enable the rc script.
- Look to see if there is special instructions about hooking your
MTA up to Mailman. If so, there will be a README.<yourMTA> file
in $mailmandir/../../share/doc/mailman.
- Change the values for DEFAULT_EMAIL_HOST and DEFAULT_URL_HOST.
These are set to 'locahost' 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)
2) Customize Mailman
- The file $mailmandir/Mailman/Defaults.py contains a number of
defaults for your installation. If any of these are incorrect,
override them in $mailmandir/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
(you need to configure your lists through the web admin
interface or through the command line script bin/config_list).
The (un-)install process will not (delete/)overwrite an existing
mm_cfg.py file so you can freely make changes to it.
Note: Do *not* change HOME_DIR or MAILMAN_DIR. These are set
automatically by the configure script.
- Create the site password using:
% $mailmandir/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.
3) Getting started
See the README file under the section "CREATE YOUR FIRST LIST" for
a quick introduction to creating an initial test list.
4) Troubleshooting
If you encounter problems with running Mailman, first check the
"Common Problems" section, below. If your problem is not covered
there, check the file FAQ. Then check for a log entry from Mailman
in your syslog.
If you encounter an error, send an error report to
mailman-users@python.org or if it is a port specific problem, mail the
${MAINTAINER} directly or ask on ports@openbsd.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 and version of Python.
5) 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
$mailmandir/cgi-bin/
2) Restarted the web server properly.
Consult your web server's documentation for instructions
on how to do these things.
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 3 above for
more information.
Problem: I use Postfix for my MTA and the mail wrapper programs
are logging complaints about the wrong GID.
Solution: Install mailman with the following command:
% FLAVOR=postfix make install
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 ($mailmandir/mail/wrapper) to the directory
identifying executables allowed to run under smrsh. Have
a look at the manpage of smrsh(8).
