Chapter 7. Configuring the RefDB-lite gateway server

Chapter 7. Configuring the RefDB-lite gateway server
Prev		Next

Although installation of the RefDB-lite CGI gateway script is trivial, there are a number of reasonably intuitive, but essential prerequisites.

For testing, you need a client computer with XSLT capability and both the DocBook and RefDB-lite stylesheets installed and your DocBook XML source document, including citations.
You need a second computer running an HTTP server, such as Apache. This computer must have the RefDB client program refdbc installed and operational.
You need a third computer running the RefDB refdbd daemon process and hosting the SQL based bibliographic reference-database.

Installing RefDB is beyond the scope of this document. Consult the RefDB manual (Hoenicka, 2005c) for details.

In actual fact, all three of those processes can be run concurrently on the same computer, communicating via the loopback (lo) ethernet interface. This would be the securest scenario. Then, your RefDB CGI interface would be accessed via the localhost address, for example:

 <xsl:param name="refdb.server.address"
   select="'http://localhost/refdb/refdb-lite-server.cgi'" />

Assuming your prerequisites are in place, and fully operational, you need to install the RefDB-lite server script and configure your HTTP server to enable CGI execution permissions in the scripts installation directory.

On your HTTP server computer, create a directory such as /usr/local/share/refdb/www/
Copy the RefDB-lite server script, refdb-lite/www/server/refdb-lite-server.cgi to the directory /usr/local/share/refdb/www/. It has to be executable (chmod 555 refdb-lite-server.cgi).
Configure your HTTP server to serve files and enable CGI execution of .cgi files in the /usr/local/share/refdb/www/ directory. For the Apache2 server running on a Debian GNU/Linux box, this ammounts to adding the following to iether /etc/apache2/httpd.conf or, better, a file in the /etc/apache2/sites-enabled/ directory, such as 000-default:
```
 
    Alias /refdb/ "/usr/local/share/refdb/www/"

    <Directory "/usr/local/share/refdb/www/refdb-lite">
        Options  +ExecCGI
        AddHandler cgi-script .cgi
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>
 
```
Follow that with /etc/init.d/apache2 restart and you should be away!

	Warning
	You use this script at your risk! Potentially it is a very large security hole. Tread carefully. Read the source code. Figure out how to do it better!

Server Operation

To communicate with the RefDB refdbc client, the XSLT client should first provide a username and database password. This info is stored in a /tmp/refdb-sid* filename to provide persistence of state over repeated transactions. Sadly, the temporary file permissions currently permit all bonafide user accounts on the server to read them (You thought I was joking about the security thing didn't you!).

Worse than that, under a heavy HTTP server load, it is possible that your HTTP server thread could be reallocated to service a different HTTP client address and in doing so, reallocate your session state file to the new client. You'll know when it happens, because your RefDB references won't resolve and the stylesheet processing will abort with a message saying you aren't recognised any more.

I would like to think that people who properly knew what they were doing could improve on this relatively easily.

Prev		Next
Chapter 6. Possible Customisations	Home	Chapter 8. Example Document Structures