Building and configuring the Whitebeam Postgres API

Subject

With release 0.9.30 Whitebeam can be build with native access to the backend Postgres database engine. The new interface provides sophisticated database access over and above that provided, for example, by the PHP library. and allows applications to go far beyond the already powerful functionality provided by the Whitebeam templates. The result is full access to high-performance SQL database technology combined with Whitebeams XML structured page generation.

Consistent with Whitebeams aim to provide an ISP friendly application development environment, Whitebeams Postgres interface can be customised through directives in the Apache configuration file (httpd.conf) allowing the ISP to specify which users can access which databases without having to configure the database for each new user.

Building Whitebeam with Postgres API support

By default the Postgres functions are not included in the Whitebeam build. Whitebeam was originally targetted at ISPs as a simple highly scalable web application environment. In this environment the ISP can provide safe data storage without having to open up databases.

To include Whitebeam with Postgres access, you need to run the configure script with the --enable-pgsql flag defined. With reference to the build instructions, replace

    $ ./configure --with-apache=$APACHE_PATH --with-pgsql=$PGSQL_PATH
  

with...

    $ ./configure --with-apache=$APACHE_PATH --with-pgsql=$PGSQL_PATH --enable-pgsql

All of the other instrustions remain the same.

Configuring virtual servers

Apache is generally configured to support a number of different web applications through 'virtual servers'. The Whitebeam modules allows administrators to configure raw access to Postgres through directives in the Apache configuration file (usually httpd.conf).

A single directive provides this configuration control : RBdbase.

This has been designed as a general purpose directive that will allow Whitebeam to support and control other databases such as mySQL in future. Directives may be placed either outside a virtual server definition, in which case they apply to all virtual servers, or within a virtual server in which case they apply just to that server.

Access is controlled by using multiple directives per server (see below).

The syntax for the directive is as follows:

RBdbase action dbase_type user database machine port

The fields to this directive are:

Note If there are no directives for a particular virtual server and no global directives then Postgres connection requests are always denied

When an application attempts to attach to a database, the paramters are compared to the directives that apply to that virtual server. This will be a combination of 'allow' and 'deny' directives. For access to be granted at least ONE allow directive must succeed and NO deny directives must succeed.

To illustrate with an example. Suppose we wish to give a virtual server access to any database except the core Whitebeam database. The virtual server definition would look something like:

    <VirtualHost 127.0.0.1:80>
      ServerAdmin admin@whitebeam.org
      DocumentRoot /www/sites/whitebeam
      RBClient Whitebeam 1
      ServerName test.whitebeam.org

      RBdbase allow pgsql * * * * 
      RBdbase deny  pgsql * Whitebeam * *
    </VirtualHost>