$Id: README,v 1.2 2000/09/25 17:57:21 guy Exp $
=================
| ezmlm-web-2.1 |
=================
Contents
========
I. Copyright Stuff
II. Some Background
III. Requirements
IV. Files
V. Installation
VI. Notes
VII. Multi-level list access
VIII. Language Portability
IX. Bugs && Bug Reports
X. Acknowledgements
XI. Availability
I. Copyright Stuff - essentially the FreeBSD licence ...
==================
ezmlm-web - version 2.1 - 25/09/2000
Copyright (C) 1998, Guy Antony Halse, All Rights Reserved.
Please send bug reports and comments to guy-ezmlm@rucus.ru.ac.za
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither name Guy Antony Halse nor the names of any contributors may be used
to endorse or promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
II. Some Background
===================
The need for ezmlm-web arose from the fact that we host many student
societies on our system. These societies usually have a virtual host for web
and email, which is administered by a computer rep from the society. These
computer reps often have little or no knowledge of Unix and so we needed a
user friendly system that would let the create and maintain mailing lists
(such as members@foo.soc.ru.ac.za, committee@foo.soc.ru.ac.za, etc).
Since I am never keen to re-invent the wheel, I had a look at Steve Peterson's
script (http://virtation.com/qmail/ml-sub), which allows people to subscribe
and unsubscribe from mailing lists using a form->email gateway. This is fine
for putting on a web page saying "here come and join our mailing list", but
doesn't really allow you to administrate a list.
Security of mailing lists was a concern, as we really didn't want
unauthorised people to be able to alter some users list. Ezmlm-web itself
implements no security checks (apart from un-tainting input) and so relies
on the web server to do this (re-inventing the wheel again :). We use an
Apache webserver, so one can control access to a directory using a .htaccess
file or in the access.conf file. ApacheWeek have a good article on doing
this at http://www.apacheweek.com/features/userauth. I also give examples
later in this document.
This version of ezmlm-web (2.0) is based to a large extent on previous
versions that I have developed. It has however been totally re-written to
make use of the Mail::Ezmlm perl module I wrote. At the same time it was
updated and extended to include the new features of ezmlm-idx. It includes
many new features that have been suggested to me over the last few months,
and hopefully is now useful to a much larger group of people.
III. Requirements
=================
This version of ezmlm-web requires the following;
* qmail v1.03
* ezmlm v0.53 (idx v0.40)
* Perl v5.004 and the following modules;
+ Mail::Ezmlm v0.03
+ Mail::Address v1.15
+ CGI v2.6
+ CGI::Carp v1.06
+ DB_File v1.65
+ Getopt::Std v4.1
+ File::Find v?
+ File::Copy v2.02
The version number indicates the version of the module that ezmlm-web was
developed with. Earlier versions may work, but then they haven't been
tested. Have a look on http://www.CPAN.org/, http://www.qmail.org/, and
http://www.ezmlm.org/ for anything you are missing.
IV. Files
=========
In this distribution you should find 8 files;
README This file. Provides some background information, notes on
installation, etc. Not needed to run ezmlm-web.
CHANGES The change history. Not needed to run ezmlm-web
TODO This file is a list of things I intend doing in future
versions of ezmlm-web. That is if there are any future
versions :) Not needed to run ezmlm-web.
ezmlm-web.cgi The ezmlm-web script proper. This program requires that
you have perl5 installed on your machine and that your web
server is capable of running CGI scripts.
index.c A C wrapper to allow ezmlm-web.cgi to run suid. Not
strictly necessary if your setup allows perl scripts to
run suid, but I prefer using wrappers anyway. It needs to
be edited and compiled to suit your system. Not needed to
run ezmlm-web.
htaccess.sample A sample Apache .htaccess file for controlling access to
the mailing lists. If you use another web server, you will
have to work this bit out for yourself.
webusers.sample A sample webusers file for multi-level access control.
V. Installation
===============
1. Copy ezmlm-web.cgi to some publically readable directory. It does not
have to be in a path accessible to your web server, but any user with a
mailing list must be able to run it (Check the read and execute rights
on both the file and directory). We put our copy in
/usr/local/bin ...
3. Edit the ezmlmwebrc file and alter the variables at the top to suit
your particular system. In particular, you will probably have to change
the $ENV{'PATH'} variable. Be particularly careful about what you set
as the path. Too much is a security risk and too little will cause the
script to malfunction. Version 2.0 requires that the following programs
be accessible in your path; mv, rm
Also be careful about the $LIST_DIR variable. This script assumes that
all users store their mailing lists in the same sub directory of the
home directory (eg ~/lists). You can override this for an individual
user by recompiling the C wrapper to call ezmlm-web.cgi with a -d
option.
Other configurable options are documented in the ezmlmwebrc file
itself. I have tried to keep the amount of information that you need to
supply to a minimum and also make reasonable guesses about default
values.
4. Edit the index.c file and change the path to the path of your copy
of ezmlm-web.cgi. Then compile this file. You can do this by issuing
the command; gcc -o index.cgi index.c
5. For every user/virtual host that needs to manage mailing lists, you
need to create a SUID (user not root!!) copy of index.cgi (see
chmod(1) for details). These need to reside somewhere accessible by
the web server. I suggest that you put them in a sub directory (see
about security) of each user/virtual host's home directory (eg
/home/luser/public_html/ezmlm for Apache on Redhat).
The copies don't actually have to be called index.cgi, but it is nice
for web servers that can resolve a cgi script as an index page (see the
srm.conf file in Apache). It is important to make sure that whichever
directory you choose to put them can i: Execute CGI Scripts and ii: Be
access controlled (here I mean both web and user access) by some method
(eg .htaccess, access.conf for Apache).
6. Install some method of securing access to the page. The following
information is applicable to Apache web servers ... Detailed
information on user authentication can be obtained from the Apache
documentation (http://www.apache.org) and ApacheWeek
(http://www.apacheweek.com/features/userauth)
6.1 Ensure that your Apache setup will allow .htaccess file to control
access in the directory that contains. This is controlled by the
AllowOverride tag in access.conf. (Also ensure you have the
necessary Apache modules installed)
6.2 Create a htpasswd file. This is done using the htpasswd command that
comes with Apache. Its command line syntax is;
htpasswd [-c] passwordfile username
You need to put the passwordfile somewhere that is not accessible by
people through the web, and create an entry for each user you want
to have access ... See the ApacheWeek article for more details.
6.3 Create a .htaccess file in the directory that contains index.cgi.
Note that using Apache's built in access control, you can only control
access to directories, not individual files, hence the need for a
sub-directory in step 5.
The format of the .htaccess file should be along the lines of this;
AuthName EZ Mailing List Manager
AuthType Basic
AuthUserFile /path/to/passwordfile
require valid-user # or require user username
Again, see the ApacheWeek article for details.
7. Test the installation through the web. You should be asked for a
username and password (supplied in 6.2) and then be presented with a
screen entitled EZ Mailing List Manger. You can then try to create and
edit mailing lists ... Have Fun :)
VI. Notes
=========
* There is a function to delete mailing lists, but I really don't like the
idea. The only reason I put it in is that bvi@rucus asked for it.
If you set $UNSAFE_RD = 0 (the default) in the config section, the
ezmlm-web won't actually delete the list. In this case it moves the <list>
to .<list> and all the associated .qmail files to a sub-directory called
deleted.qmail/ (In the users home directory. This is by far a safer way
(since you can restore lists) and therefore I recommend it.
* The HTML interface has been tested using Nutscrape, Internet Exploder, and
Lynx. If anyone uses anything else and has problems, please let me know.
* I suggest that you make use of custom ezmlmwebrc files rather than using
the -d command line switches - it makes fault diagnosis easier ...
* Please see the section on languages below.
VII. Multi-Level Access
=======================
Ezmlm-web has a multi-level access system. This depends on a file called
webusers being present in $LIST_DIR. If the file is not present, then any
valid user has access to all lists. If, however, this file exists a number
of constraints come into place.
- The webusers file is scanned for either the list name (case insensitive) or
an ALL (case sensitive) entry.
- The list entry (or ALL) is scanned for the current user (as set in
$REMOTE_USER) or an ALL entry.
- If any valid match is made, then the user is allowed to edit the list.
Otherwise the user is politely told to go away ;-)
If list creation is allowed and the webusers file exists, then the person who
creates the list is the default owner. As of yet there is no way to add users
through the web interface, but I intend to do this eventually.
The format of a webusers file is as follows;
list1: user1, user2, user3
ALL: user1, user2
list2: ALL
ie; listname colon (:) and a comma (,) separated list of users. Spaces are
ignored but each list must appear on a new line.
Once this file exists, the ezmlm-web script will allow the list users to
configure their access lists along with any other options.
Oh, and BTW, list creation through the web can now be disabled. The way to do
this is to compile the wrapper calling ezmlm-web.cgi with a -c switch. See the
example index.c file for more details.
VIII. Language Portablity
=========================
One of the great new features of version 2.0 is that it is essentially
language independant (okay, not quite, but is 99% of the way there). Most of
the fixed strings, help, etc is defined in the RC file and thus can be
altered to suite a particular locale, language or even your own taste.
If anyone gets round to writing full templates for languages I would
appreciate it if you would do two things;
Firstly, make them public and announce them on the ezmlm@lists.cr.yp.to
mailing list so that others may benefit.
Secondly, please mail me a copy (guy-ezmlm@rucus.ru.ac.za) so that I may use
them in any future releases of ezmlm-web.
IX. Bugs && Bug Reports
=======================
I don't know of any bugs, but then this is a rewrite and a first release. It
has been tested reasonably well, but not exhaustively. I know it works on
FreeBSD 4.0-STABLE, FreeBSD 3.4-RELEASE, RedHat 5.1 and Redhat 6.0 all using
an Apache web server, but I would be interested to know whether it works on
other OSs and with other web servers. This version is far less dependent on
the OS than previous versions so I don't see any reason why it shouldn't.
Please mail bug reports and comments to guy-ezmlm@rucus.ru.ac.za
X. Acknowledgements
===================
* Keith Burdis (keith@rucus.ru.ac.za) - For constantly bugging me and
ensuring that I actually got round to writing some code :)
* Bryan Kilian (bryan@rucus.ru.ac.za) and the administrators of the
Litestep mailing list - For helping beta test and putting up with me
pestering them.
* Several societies at Rhodes. For switching to my web interface and so
unknowingly helping to beta test it.
* Barry Irwin (bvi@moria.org) - For trusting me and moving the Grahamstown
Foundation over to qmail and ezmlm - yet another beta tester :-)
* David Summers (david@summersoft.fay.ar.us) - For some ideas. And for
offering to make up an RPM version. I hope the offer still exists for
version 2.0 :-)
* Glen Stewart (glen_stewart@associate.com) - For a multitude of ideas.
* Fred Lindberg (lindberg@id.wustl.edu) for his useful posts to the
mailing list, suggestions, help, etc
* Galen Johnson (gjohnson@totalsports.net) - For some ideas on bugfixes.
XI. Availability
=================
The latest version of ezmlm-web will always be available on;
ftp://rucus.ru.ac.za/pub/mail/ezmlm/
More information on ezmlm-web and developments to ezmlm-web can be found at;
http://rucus.ru.ac.za/~guy/ezmlm/
