mailman-2.1.39p1

This README contains unresolved ports variables; replace them before using its commands.

+-----------------------------------------------------------------------
| Running mailman on OpenBSD
+-----------------------------------------------------------------------

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

- Add your MTA and web server user to the _mailmanq group.

- 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 
The OpenBSD ports mailing-list <ports@openbsd.org> 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:  The cgi and mail wrapper programs are logging complaints
             about group mismatch.

   Solution: Add your MTA and web server user to the _mailmanq group.


   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).