=================
| ezmlm-web-1.0 |
=================

Contents
========
   I.	Copyright Stuff
  II.	Some Background
 III.	Requirements
  IV.	Files
   V.	Installation
  VI.	Notes
 VII.	Bugs && Bug Reports
VIII.	Acknowledgements


I. Copyright Stuff
==================
ezmlm-web - version 1.0 - 01/08/1998

Copyright (C) 1998, Guy Antony Halse, All Rights Reserved.
Please send bug reports and comments to guy-ezmlm@rucus.ru.ac.za

This set of programs is free for non-commercial use; you can redistribute it
and/or modify it under the terms of the GNU General Public License (version 2 
or later) as published by the Free Software Foundation. This program is 
distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
PARTICULAR PURPOSE.  See the GNU General Public License for more details. 

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 (1.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 perl5 features and the CGI perl module. At the same time it was
updated and extended to include the new features of ezmlm-idx.

III. Requirements
=================
This version of ezmlm-web requires the following;

* qmail v1.02
* ezmlm-idx v0.53
* Perl v5.001 and the following modules;
  + CGI v2.6 (available at ftp://ftp-genome.wi.mit.edu/pub/software/WWW/)
  + CGI::Carp v1.06
  + Getopt::Std v4.1

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 5 files;

README		This file. Provides some background information, notes on
		installation, etc. 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	A sample Apache .htaccess file for contolling access to the
		mailing lists. If you use another web server, you will have
		to work this bit out for yourself.

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 ezmlm-web.cgi file and alter the variables at the top to
	suit your particular system. In particular, you will probably have
	to change the $ENV{'PATH'} and $DEFAULT_HOST variables. Be 
	particularly carefull about what you set as the path. Too much is a 
	security risk and too little will cause the script to malfunction.
	Version 1.0 requires that the following programs be accessable in
	your path; ezmlm-make, ezmlm-list, ezmlm-sub, ezmlm-unsub, rm, mv

	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 script 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 accessable 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 contolled 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 artical for details.

7.	Test the installation through the web. You should be asked for a
	username and password (suppied 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 retore lists) and therefore I recomend 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.

VII. 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 exaustively exaustively. I know it 
works on FreeBSD 3.0, RedHat 4.2 and RedHat 5.1 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

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