ezmlm-web/INSTALL

149 lines
5.4 KiB
Plaintext

The following notes will guide you through the installation of ezmlm-web:
OVERVIEW:
0 - important notes
1 - get it
2 - install executable and shared files
3 - configuration file
4 - compile cgi wrapper
5 - install cgi wrapper
6 - [optional] configure access control (http authentication)
7 - css stylesheet file
8 - final test
9 - any problems?
------------------------------------------------------------------------------
0. IMPORTANT: you need the perl module Mail::Ezmlm and others to use
ezmlm-web! The file README contains the complete list of necessary
modules.
Additionally (since v3.0) you have to install clearsilver (a templating
engine). See INSTALL.clearsilver for details.
1. Choose a distribution form
1a) source installation
Get ezmlm-web and extract the archive:
tar xzf ezmlm-web-3.x.tar.gz
(for source installation continue with step 2)
1b) debian package
This is the (by far) most convenient way to install ezmlm-web.
Read debian-releated/README.Debian for details.
(debian users may stop reading here)
2. Execute the following lines to install the cgi script and the shared data
files to the appropriate locations.
perl Makefile.PL
make
make install
3. Edit the examples/ezmlmwebrc.dist file and alter the variables to suit
your particular system.
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.
Finally, copy the ezmlmwebrc file to one of
the following places:
1) the home directory of the user that runs ezmlm-web.cgi (~/.ezmlmwebrc)
2) the directory, that contains your cgi binary (index.cgi)
3) /etc/ezmlm-web/ezmlmwebrc
4) /etc/ezmlm/ezmlmwebrc [deprecated]
(ezmlm-web will look for it in these places in the given order)
4. For every user/virtual host that needs to manage mailing lists, you
need to create a suid wrapper owned by the user whom the mailing lists
belong to. This wrapper needs to reside somewhere accessible by
the web server. I suggest that you put it in a sub directory
of each user/virtual host's home directory (eg.
/home/luser/public_html/ezmlm for Apache).
Create a suid wrapper by issuing the following command:
ezmlm-web-make-suid
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. 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 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
You may use examples/htaccess.dist as a template.
Again, see the ApacheWeek article for details.
7. Copy the stylesheet file (/usr/local/share/ezmlm-web/css/default.css)
to a location of your choice. It has to be accessible by an URL - maybe
a place like "/var/www/ezmlm-web.css" could be appropriate.
Now you may have to change the "HTML_CSS_FILE" setting in your
ezmlmwebrc file. This value is a URL - not the local filename.
8. Test the installation with your favourite web browser. 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 :)
If you do not see a colorful screen, then you did not set the HTML_CSS_FILE
option correctly in ezmlmwebrc. Check it again.
If anything failes - take a look at the web server's error log
(e.g. /var/log/apache/error.log).
9. If you have any problems:
- take a look at https://systemausfall.org/toolforge/ezmlm-web
- send me an email: ezmlm-web@sumpfralle.de
- subscribe to the mailinglist: ezmlm-web-subscribe@lists.systemausfall.org
- report a bug at https://systemausfall.org/trac/ezmlm-web