**************************************************************************
* Copyright 1995-2001 Perforce Software.
*
* This file is part of WebKeeper, a perforce client apache module.
*
* License is hereby granted to use this software and distribute it
* freely, as long as this copyright notice is retained and modifications
* are clearly marked.
*
* ALL WARRANTIES ARE HEREBY DISCLAIMED.
*
* Last updated: September 27, 2001
*
* $Id: //guest/jason_woodward/perforce/webkeeper/README.WEBKEEP#2 $
*
**************************************************************************
PERFORCE SOFTWARE WEBKEEPER NOTES
Warning:
This is an open-source project, not a product.
WHAT YOU HAVE
This directory contains the generic componentry to build an Apache
Web Server with a Perforce WebKeeper module. This directory includes:
Makefile.apxs makefile for stand-alone apxs build
Makefile.libdir signal to APACI configure
Makefile.tmpl makefile template for APACI configure
README.WEBKEEP this file
libwebkeep.module module definition for APACI configure
mod_webkeep.c the WebKeeper Apache module, C half
mod_webkeep2.cc the WebKeeper Apache module, C++ half
mod_webkeep.h glue between the C and C++ halves
You will also need a Perforce header file and link libraries and
for your platform. They can be found at:
ftp.perforce.com/pub/perforce/r??.?/bin.*/p4api.tar
There may be link dependencies on your operating system/compiler version
and the Perforce API version. Be sure to get the most appropriate build
for your platform. For example, for Linux 6.X and 7.X, get the Perforce
API tarball from bin.linux60x86, rather than from bin.linux52x86. The
usual sign of an incorrect version is unresolved symbols at server link
time.
TO BUILD THE APACHE SERVER
1) Unpack the Perforce libraries.
% cd /usr/local/src # or your favorite location
% mkdir perforce
% cd perforce
% tar xvf /path/to/p4api.tar
Note that there are source files in the p4api.tar ball
that are not related to webkeeper.
2) Unpack the webkeeper module
% cd /path/to/apache/src/module
% tar xvf /path/to/webkeeper/webkeep.tar
% cd webkeep
3) Determine how you wish to build WebKeeper. You can build it as part
of a full Apache build, either statically or as a loadable module, or
you can build it using apxs, particularly useful on systems such as
Red Hat Linux with binary distributions and custom enhancements to the
source base.
3.1) If you plan to build a full Apache tree, do the following:
3.1.1) Fix up the EXTRA_INCLUDES line in Makefile.tmpl to reflect the
path to the Perforce API you unpacked in step 1.
3.1.2) Fix up the LIBS line in libwebkeep.module to reflect the path to
the Perforce API you unpacked in step 1.
3.1.3) Build apache. Any other configuration directives should be added
to the configure command if necessary. If you wish to build WebKeeper
as a shared module, add '--enable-shared=webkeep' to the configure
line, resulting in libwebkeep.so as the loadable module.
% cd /path/to/apache
% ./configure --activate-module=src/modules/webkeep/libwebkeep.a
% cd src
% make
3.1.4) Once comfortable with the build, install.
% cd /path/to/apache/src
% make install
3.2) If you plan to build WebKeeper using apxs, follow these
instructions. On Red Hat, this requires the apache-devel RPM.
3.2.1) Fix up the P4API definition in Makefile.apxs to reflect the path
to the Perforce API you unpacked in step 1.
3.2.2) Build the module with
% make -f Makefile.apxs
3.2.3) Either copy libwebkeep.so to your Apache modules directory and
manually modify the httpd.conf, or use apxs to do this with:
% apxs -i -a -n webkeep libwebkeep.so
This will both install the DSO in your modules directory and modify
httpd.conf to load the module. Note that it does not add the HAVE_*
macro guards used with Red Hat.
TO USE WEBKEEPER
1) Do the necessary steps to get a Perforce server running. See
the admin section of the Perforce manual.
2) Edit the Apache httpd.conf file. These are the directives:
WebKeepPort host:port
Gives the address of the Perforce server.
Default is $P4PORT or host 'perforce', port 1666.
WebKeepUser username
Gives the Perforce user name.
Default is $P4USER or $USERNAME.
WebKeepPasswd password
Gives the user's password.
No default.
WebKeepClient clientname
Gives the Perforce client name.
Default is $P4CLIENT or hostname.
WebKeepAlias uri perforcePath
If the URI begins with uri, strips the intial uri,
replaces it with perforcePath, and then treats the
URI as a WebKeeper request.
WebKeepSync On|Off
"On" causes files to be synced to the client and let's
Apache handle everything else. Useful to allow other
modules to handle the content, particularly if they
are dynamic, such as PHP.
WebKeepDirectoryIndex indexfile [...]
Lists the file names to be tried, in order, for directory
requests, exactly analogous to DirectoryIndex. In fact,
this list should be an exact copy of the list supplied to
DirectoryIndex for consistency.
WebKeepRefresh perforcePath [...]
Causes each perforcePath listed to be synced before the
handling of each request. This should be used to ensure
that files that are required but that never are requested
directly, such as PHP includes and SSI files, are always
available and fresh. Requires a client to be specified.
Client namespace is recommended for perforcePath.
For example:
WebKeepAlias /$ //depot/index.html
WebKeepAlias / //depot/
Maps the URI / to //depot/index.html and the rest of the web
namespace into the corresponding Perforce namespace under //depot.
The $ is necessary to distinguish between initial substring
matches and exact matches.
The '/' at the end of the directory tree mapping is required.
Otherwise, the file name will be appended to the depot name.
You can also use //client/ where client is the name of your
client. If you use //client/, it will map the name through your
client view. You don't have to map the whole namespace. You
could say:
WebKeepAlias /foo/ //depot/
To map only files under /foo/... to the Perforce namespace.
You can have multiple alias lines.
If you test your server and the raw HTML is displayed, it may also
be useful to add
DefaultType text/html
to your configuration.
Notes:
Directory listing is still not yet supported.
EXAMPLE WEBKEEPER CONFIGURATIONS
Most Basic
==========
# Uncomment the following two lines are only necessary if WebKeeper is being
# used as a loadable module.
# LoadModule webkeep_module libexec/libwebkeep.so
# AddModule mod_webkeep.c
# The following configuration for WebKeeper assumes the following:
#
# o that your Perforce server is on host 'perforce' in the local domain
# and listening on the standard port 1666
# o that the web content that you wish to show is located in the depot
# under //depot/htdocs.
# o that a user 'perforce_user' without a password has at least read
# permission to this portion of the depot.
#
# The <IfModule> directive ensures that this configuration is safe,
# although not functional as a Webkeeper server, regardless of whether
# mod_webkeep has been built or loaded into apache.
<IfModule mod_webkeep.c>
WebKeepPort perforce:1666
WebKeepUser perforce_user
WebKeepAlias / //depot/htdocs/
WebKeepDirectoryIndex index.html
DefaultType text/html
</IfModule>
Note:
If, when using a configuration similar to the Most Basic one above,
your browser is able to see http://your.web.server.com/index.html just fine,
but when you try to get http://your.web.server.com/ and your browser asks you to
save the file (and, when you do, the contents of the file are what you expected),
then it is likely because your server's DocumentRoot exists on the filesystem.
For instance, if you used the Most Basic configuration outlined above, and you ALSO
have a DocumentRoot directive set (say DocumentRoot /home/httpd/htdocs) AND the
directory /home/httpd/htdocs exists, then you'll see the behavior outlined in the
previous paragraph. The fix is to set your DocumentRoot to point to a directory
that doesn't exist. Alternatively, if you have NO DocumentRoot directive set in
your httpd.conf, you MAY experience the behavior outlined in the previous paragraph.
The fix here is to add a DocumentRoot directive (pointing to a directory which does
not exist).
Why does this happen? Here are the gory apache-internals details. mod_webkeep
doesn't set a response Content Type when it is the content handler. It relies on mod_mime
to set the content type. However, mod_mime sees '/' as the requested file, which
it translates to DocumentRoot (say, /home/httpd/htdocs). mod_mime then checks to
see what kind of file /home/httpd/htdocs is, sees that it is a directory, and sets
the response Content Type to httpd/unix-directory. Of course, once mod_webkeep
takes care of things, it isn't sending a directory, it is sending //depot/htdocs/index.html,
and is assuming that mod_mime had set the response Content Type properly. So,
why does removing the directory make everything work? If the file doesn't exist,
mod_mime falls back on the DefaultType (text/html).
Sync to Disk to Allow Processing (Red Hat Apache configuration)
===============================================================
<IfDefine HAVE_WEBKEEP>
LoadModule webkeep_module libexec/libwebkeep.so
</IfDefine>
# The following must come after the ClearModuleList directive
<IfDefine HAVE_WEBKEEP>
AddModule mod_webkeep.c
</IfDefine>
<IfModule mod_webkeep.c>
WebKeepPort perforce:1666
WebKeepUser perforce_user
WebKeepAlias / //depot/htdocs/
WebKeepDirectoryIndex index.html
WebKeepClient my_client
WebKeepSync On
</IfModule>
TESTED ON
Red Hat Linux 6.2 x86, Apache 1.3.19, p4api r00.1/bin.linux60x86, static & DSO
Red Hat Linux 7.0 x86, Apache 1.3.19, p4api r00.1/bin.linux60x86, static & DSO
Red Hat Linux 7.1 x86, Apache 1.3.19, p4api r00.1/bin.linux60x86, static & DSO
FreeBSD 3.5.1 x86, Apache 1.3.16, p4api r00.2/bin.freebsd, static & DSO