-*- README -*-
$Id: README,v 1.9 2000/07/19 20:31:56 ckyc Exp $
LibWeb-0.02 - A Perl library/toolkit for building Web applications.
Copyright (c) 2000 Colin Kong.
See LibWeb::Core, COPYING and LICENSE for usage and distribution rights.
____________________________________________________________________
| |
| CONTENTS |
|--------------------------------------------------------------------|
| |
| * Dependencies of libweb |
| |
| * Features |
| |
| * Installation |
| |
| * A note on ``make test'' |
| |
| * After installation: running sample scripts |
| |
| * Security issues |
| |
| * Uninstallation |
| |
| * If you have problems |
| |
|____________________________________________________________________|
DEPENDENCIES OF LIBWEB
----------------------
The following non-standard perl's libraries are required,
* Digest
http://search.cpan.org/search?dist=Digest-MD5
* Crypt::CBC
http://search.cpan.org/search?dist=Crypt-CBC
* Crypt::Blowfish (recommended)
http://search.cpan.org/search?dist=Crypt-Blowfish
or Crypt::DES
http://search.cpan.org/search?dist=Crypt-DES
or Crypt::IDEA
http://search.cpan.org/search?dist=Crypt-IDEA
* DBI
http://search.cpan.org/search?dist=DBI
* the specific DBD for your database, e.g. Msql-Mysql
http://search.cpan.org/search?dist=Msql-Mysql-modules
* Mail::Sendmail, you definitely need this if your server doesn't have
sendmail (most unix servers have sendmail)
http://search.cpan.org/search?dist=Mail-Sendmail
You need none of the above mentioned libraries if you are not going to
use the user/session management and database APIs of LibWeb, namely
LibWeb::Admin, LibWeb::Crypt, LibWeb::Database, LibWeb::Digest and
LibWeb::Session.
LibWeb currently does not have mod_perl support.
FEATURES
--------
LibWeb is a Perl library/toolkit for building community web
site/applications.
Features:
* Members and sessions management (authentication via cookies),
* concise, database independent and easy to use database API with
enhanced MySQL support (planning),
* template-driven, dynamic HTML page generation without using
PHP/ASP/SSI/Javascript, and
* HTML widgets and themes.
INSTALLATION
------------
In short, on your command line,
perl Makefile.PL
make
make test
make install
This will install the LibWeb package to standard locations
on your machine. You can check the values of these standard
variables on your system with
perl '-V:install.*'
And to check the sequence in which the library directories
are searched by perl, run
perl -le 'print join $/, @INC'
If the above doesn't work for you (for instance, you do not have make
on your machine), try:
cp -R LibWeb /usr/local/lib/perl5
[ or cp it to other standard perl place on your machine ]
If the above still doesn't work for you (for instance, you do not have
shell access to your server), try upload the whole thing and its
contents of the directory called ``LibWeb'' via ftp or any other means
that are available to you to your server.
For installing into non-standard location, use the PREFIX and
LIB attribute. PREFIX and LIB can be used to set several
INSTALL* attributes in one go. The quickest way to install
LibWeb into a non-standard place might be (I recommend this)
perl Makefile.PL LIB=~/path_to/my_lib
This will install the module's architecture-independent files
into ~/path_to/my_lib, the architecture-dependent files
into ~/path_to/my_lib/$archname/auto.
Another way to specify many INSTALL directories with a single
parameter is PREFIX.
perl Makefile.PL PREFIX=~
This will replace the string specified by $Config{prefix} in
all $Config{install*} values.
Read Perl's Config, ExtUtils::MakeMaker and ExtUtils::MM_Unix
manpage for more information.
A NOTE ON ``make test''
-----------------------
``make test'' may generate some non-test or dependencies related
error messages if perl cannot find/load any necessary perl
library. By default, ``make test'' will look for modules in
these locations,
1. '..','../blib/lib','../blib/arch' (with respect to ./t), and
2. the standard @INC.
To check the standard @INC in which the library directories
are searched by perl, run
perl -le 'print join $/, @INC'
``make test'' simply prepends 1. to the standard @INC.
If 1 and 2 do not cover the paths into which you have installed perl's
standard library and LibWeb's dependencies (e.g. Crypt::Blowfish and
DBI ...etc. See the DEPENDENCIES section of this README for more
information), you have to change the ``use lib ...'' line on top of
every ./t/*.t test script either manually or perform the following
stunt (replace YOUR_LIB_PATH according to your needs),
perl -i -p -e "s|use lib |use lib 'YOUR_LIB_PATH',|;" ./t/*.t
then you can run or re-run ``make test''.
If your perl is too old, for example, 5.004_04 built, you may get the
following kind of error messages,
Ambiguous use of...
This is probably harmless and you can still use LibWeb.
AFTER INSTALLATION: RUNNING SAMPLE SCRIPTS
------------------------------------------
Eight samples can be found in ./eg,
o MyHTML.pm
o MyTheme.pm
o USER_LOG.sql
o USER_PROFILE.sql
o dot_lwrc
o lm.cgi
o lw.cgi
o style.css
To use LibWeb and run the sample scripts,
1. You must first edit dot_lwrc, chmod 600 it and make it Web
inaccessible. Depends on the user as which you run your web server
and cgi scripts, the web server may not have enough privilege to read
your 600 chmoded dot_lwrc, if this is the case, try chmod 640 or 644
(but you run the risk of exposing the security sensitive data in your
dot_lwrc; please e-mail me if there is a better way to solve the
problem, thanks in advance).
2. This step can be ignored if you are not going to use the
users/sessions management and database APIs of LibWeb (namely
LibWeb::Admin, LibWeb::Crypt, LibWeb::Database, LibWeb::Digest and
LibWeb::Session). Create the USER_PROFILE and USER_LOG table. For
example if your database is MySQL and `your_db_name' is your
database's name,
mysql -p your_db_name < USER_LOG.sql
mysql -p your_db_name < USR_PROFILE.sql
This will create both the USER_LOG AND USER_PROFILE tables. If you
want to otherwise change the table names, edit these scripts before
creating the tables and also you have to edit LibWeb's rc file
accordingly since `USER_LOG' and `USER_PROFILE' are the defaults in
the rc file. If you have enough privilege, you should create a
separate database for LibWeb and then create the two tables.
3. After you have configured the rc file (e.g. dot_lwrc) and created
the database tables, you should edit `lw.cgi', upload it to your
cgi-bin, chmod 755 it and run it by using a browser. What to edit in
`lw.cgi'? First, edit the first line so that it points to the perl
interpreter on your server; for example, replace
#!/usr/bin/perl -w
with
#!/usr/local/bin/perl -w
and finally edit several variables between the line ``# Begin edit.''
and the line ``# End edit.''.
4. `lm.cgi' is a sample login script. Edit and run it as you have
done with `lw.cgi'. `lm.cgi' can be invoked via a browser in two main
ways, one for logging in and another for logging out,
http://www.your_site.org/cgi-bin/lm.cgi
and
http://www.your_site.org/cgi-bin/lm.cgi?.a=logout
5. MyHTML.pm is a sample perl class. It demonstrates how to (ISA)
make a sub-class of LibWeb::HTML::Default to customize the HTML
display of Libweb applications. Read the man page for
LibWeb::HTML::Default for details.
6. MyTheme.pm is a sample perl class. It demonstrated how to (ISA)
make a sub-class of LibWeb::Themes::Default to write your own theme.
7. style.css is for cascading style sheet layout for your Web pages.
I picked this one as an example because it makes your Web pages look
good under both Linux's and Windows's Web browsers. It is a modified
version of the style sheet used at www.freebsdzine.org.
Source codes for other full-blown LibWeb applications are available at
http://leaps.sourceforge.net
SECURITY ISSUES
---------------
LibWeb's user and session management (authentication via cookie) is
vulnerable to the recently found ``redirect'' attack. The only fix I
can think of is to check the referer of HTTP header rigorously.
However this is not implemented in LibWeb-0.01 because ``referer'' can
easily be faked too. Hopefully this can be resolved in future releases.
A discussion of the ``redirect'' attack is available at
http://lwn.net/2000/features/Redirect.phtml
You should frequently change the values for following attributes in
the rc file,
MAC_KEY
CIPHER_KEY
DIGEST_KEY
If people know the values of all these keys, they can create a bogus
authentication cookie themselves and fool the LibWeb's authentication
scheme. So change these values frequently as you would with any
password. I do not know how long those keys should be since it's not
very clearly documented in the Crypt and Digest modules used by
LibWeb. For my site, I make them reasonably long (no rigorous
definition). I would really appreciate any comment and suggestion on
that and other not yet addressed security issues.
UNINSTALLATION
--------------
In short, on your command line (after ``make install''),
make uninstall
if you have installed LibWeb into standard place (i.e. you
have typed `perl Makefile.PL'), or
make Uninstall
if you have installed LibWeb into non-standard places (i.e.
you have typed something like
`perl Makefile.PL LIB=~/path_to/my_lib').
I believe in both cases an apology will be printed to you
saying that you have to remove the installed files manually.
Hopefully this will be resolved in next release of LibWeb.
I am sorry. Any good perl modules packager?
IF YOU HAVE PROBLEMS
--------------------
First, read the FAQ and messages on message boards at
http://libweb.sourceforge.net
If you can't fix it your self please post details to
libweb-devel@lists.sourceforge.net
You can also cc them to me at
colin.kong@toronto.edu
Please include IF POSSIBLE:
1. A complete log of a complete build, e.g.:
perl Makefile.PL (do a make realclean first)
make
make test
make test TEST_VERBOSE=1 (if any of the t/* tests fail)
2. The output of perl -V