Whitebeam 1.3.23 is currently available as a source code distribution for Unix. There is also an older
binary distribution for Microsoft Windows platforms that is not currently being actively maintained.
Upgrading from earier versions of Whitebeam
From version 0.9.35 we've modified the Postgres database schema slightly. The most significant
change from previous versions is that we no longer use Postgres Large Objects to hold file
objects. This is a requirements to support replication (we've not found a replication system that can
deal with Large Objects!).
This does mean that old databases must be migrated to the new schema. This is fairly straightforward,
We've put together some notes to help you
What we're building
These instructions will build a shared object for the Apache web-server (version 1.3.x or 2.x) and will install
. the Whitebeam Apache module and the associated application modules (templates).
Note the build instructions from version 0.9.35 have been significantly simplified from
The instructions use specific versions of various components to illustrate the entire
build process. You should adjust these instructions for more recent versions as necessary!
Things you'll need
download or otherwise obtain the following modules:
You will need the following applications installed on you server. For most operating systems the
standard distributions will include suitable versions of these applications. If necessary download
Your Apache installation can of course include other Apache modules. We'd recommend including SSL if it's not already present.
With Apache and Postgres installed on your system, you'll also need to download the Whitebeam source tree:
Whitebeam is written in C/C++ and to build you'll also need a
GNU C++ tool chain. Again this is generally available as part
of your standard Linux distribution.
# Assuming Apache and Postgres are installed
# Extract Whitebeam
$ tar zxcfp whitebeam_0_9_37.tar.gz
$ cd whitebeam_0_9_37
# Now with the rest of the build.
# Note: You need to have the Postgres server include files available under the standard
# Postgres include directory in order to build native Postgres support (--enable-pgsql).
# Some binary installations include these, and they appear to be included in a standard
# build of PostreSQL version 8 Beta releases. For version 7.4.x, you may need to build
# from source and include all header files using :
# gmake install-all-headers
# If you don't have these headers or do not want native Postgres supoport in Whitebeam
# then leave --enable-pgsql from the configure line.
# Configure Whitebeam with native Postgres functionality built into the system. If configure
# fails to find the necessary files use ./configure --help
$ ./configure --enable-pgsql
# Build Whitebeam
# Change to 'root' to install Whitebeam
$ gmake install
# The standard install path for Whitebeam is /var/whitebeam. The Apache shared object file
# will be installed into /var/whitebeam/lib, which can be referenced from httpd.conf
Building on any UNIX like platform uses a GNU autoconf
configure script to configure the distribution.
In theory, this means Whitebeam should build on a wide range of platforms.
- Ensure you have the GNU Make utility on your system - On Linux
systems this will likely be the default make utility, on BSD systems
it may need to be installed seperately, and will probably be called
- You need to have a recent copy of openSSL installed on your system. If you haven't then see the link earlier in this document.
- In a convenient working directory untar Whitebeam
$ tar zxvfp whitebeam_0_9_37.tar.gz
$ cd whitebeam_0_9_37
- Configure Whitebeam, including native Postgres support:
$ ./configure --enable-pgsql
Whitebeam should find Apache and Postgres. In this case
we asume Postgres is in it's default installation directory. Alternatively you can use the options --with-apache=<path to Apache> and
--with-pgsql=<path to postgres> to locate the source tree without having to build
Note: You need to have the Postgres server include files available under the standard
Postgres include directory in order to build native Postgres support (--enable-pgsql).
Some binary installations include these, and they appear to be included in a standard
build of PostreSQL version 8 Beta releases. For version 7.4.x, you may need to build
from source and include all header files using :
If you don't have these headers or do not want native Postgres supoport in Whitebeam
then leave --enable-pgsql from the configure line.
- Make the Whitebeam libraries and binaries. This will build Apache - but we need to do this
again to build the shared object for Whitebeam.
- Next, you will probably need to su to root in order to install the Whitebeam files in your local system directories:
# gmake install
The build/install sequence will by default install all of Whitebeam into /var/whitebeam. This directory has the following
Contains the executable binaries for the Whitebeam templates and for
the Whitebeam replication engine
Contains XML syntax definition files for XML based template communications, for the Presentation Engine markup
and for HTML itself.
Contains XML service specifications for the various template services.
Contains static link Whitebeam libraries and the shared library Apache module. You can directly reference
the shared library from the Apache httpd.,conf file using /var/whitebeam/lib/libwhitebeam1.so (for Apache 1.3.x)
If your attempt to build Whitebeam fails, please
tell us, including the exact version of the OS, the ouput of configure and make.
A full version of Apache, including an httpd.conf.default configured with Whitebeam configuration directives, and a copy of the Whitebeam htdocs tree should have been installed in the configured Apache ServerRoot.
For further details see the Getting Started page.
An OLDER version of Whitebeam is currently available as a binary distribution for Microsoft Windows platforms (Windows 98, ME, 2000, XP). Whitebeam is a
dynamically loaded module in the windows environment.
The primary target for the Whitebeam module is Unix, the windows distribution is a port of that environment. The Windows
distribution has not had the same level of use or testing as the Unix environment and as such should be considered an
evaluation environment only at this time.
We're not currently making Whitebeam binaries available for Windows - primarily because of a lack of skill in this area.
We'd love a little help from someone with some time available to get a cygwin environment build!
What you need....
To install the Windows version of Whitebeam you will need to download the following files.
Installing Windows Binary Distribution
- Install the Apache binary installation by executiong the downloaded file. Install this in
the default locations (c:\program files\Apache Group).
- Unzip the Whitebeam archive into the same directory that you installed Apache. The
archive adds the additional Whitebeam files to the Apache tree. So if you installed
Apache in "c:\program files\Apache Group" - the default location - then unzip into that
- If you've unzipped the archive to the right location there will be a directory called 'whitebeam'
directly under the Apache install directory. i.e. c:\program files\Apache Group\Apache\Whitebeam.
Configuring Apache with Whitebeam
Whitebeam under Windows operates as a dynamically loaded Apache module. The module is configured
through the standard Apache configuration file (conf/httpd.conf by default). The Whitebeam archive
installs a default httpd.conf with the following characteristics:
- Correctly load the Whitebeam module.
- Configures Apache to attach to port 8080
- Adds a handler for '.rhtm' files. All files with this extension are handled by the
- Configures Whitebeam to attach to the context server on
the local machine - on port 9501.
IF you install in a non default directory then you will have to modify the 'ServerRoot' and 'DocumentRoot'
paths in httpd.conf
If you want to keep the contents of the current httpd.conf then you must
copy it before you overlay the Whitebeam archive.
If you have an existing httpd.conf file you want to use then the following modifications will configure
it to use the Whitebeam module:
- Add the following 'LoadModule' directive:
LoadModule whitebeam-module modules/mod_whitebeam.so
- To operate the Whitebeam module requires a context template
to execute on some machine on your network. For a simple environment
this can be the same machine as that running Apache. The Whtebeam
module needs to know where the context template is executing! Add
the following directive to the httpd.conf file:
RBTemplate context tcp "127.0.0.1:9501"
This tells Whtiebeam that the context server is running on the
local machine - attached to port 9501.
- Whitebeam has separate configuration for each virtual server. Each virtual server must
have an RBClient directive. For each existing virtual server (and the default server)
add the following directive :
RBClient xxxxxx 1
where xxxxxx is a unique client name. The '1' is the Whitebeam 'mode' for this server -
either '0' for operational or '1' for test. Generally each client will have two seperate
servers - one test - one operational. The Whitebeam module works slightly differently in each
mode, for example more rigorous XML rules are applied in test mode, page failure is treated
differently. For evaluation purposes - use the test instance.
The whitebeam module provides session tracking facilities. This
functionality makes use of a 'context template' that stores the session data independently of the machine running
Apache - which in turn means multiple Apache servers can use a single context store - imrpoving the scaleablity of
a solution using Whitebeam.
In the windows environment the Context Template is available as 'context.exe' - installed in
Apache/whitebeam/context.exe. To run the context sever execute the following command from a
Windows command prompt.
cd apache/whitebeamcontext :9501
'9501' is the TCP port number on which the server will listen for Apache/Whitebeam requests. This number
must match the port specified in the httpd.conf RBTemplate directive.
To make sure the template is working, use the '-v' option. This will cause the template to display information
about each request it receives from Apache.
By default the context server deletes session data that has not been accessed within 30 minutes. This
timeout can be altered on the command line by specifying '-ct=minutes' where 'minutes' is the timeout. For example:
context -v -ct=120 :9501
will execute the context server on port 9501 - with a session timeout period of 2 hours.
The windows implementation of the context server stores all context information in the processors memory -
relying on virtual memory to store information. This is fine for small sites - and certainly for evaluation. For
a largedata centre this strategy is limited and a better solution is to implement the context interface to
store context information on disk. Whitebeam includes a context implementation for Unix that does this using
the DBM libraries - at the present time we have not ported this to Windows (Any volunteers?).
At one command prompt start the context server with the command:
cd apache/whitebeamcontext -v :9501
The Default installation over-writes the standard httpd.conf with a Whitebeam example
file. This creates a single server on the machine running Apache - connected to TCP port
8080. The contents of this server are in Apache/htdocs - the document root for the
default (and only) server. On the machine running Apache - start a web browser and
This should bring up the Whitebeam homepage. If it does then Apache is
correctly executing mod_whitebeam. If so the Contratulations. If not then check
the contents of the Apache configuration file.