324 lines
14 KiB
Plaintext
324 lines
14 KiB
Plaintext
$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/
|