In addition to its native clients, RefDB also supports optional read access through a web-based search protocol called SRU (Search and Retrieve via URL). There are two options to enable SRU access. We'll first describe a CGI script which is the preferred way but requires a running web server on your system. The subsequent section describes a simpler standalone server for testing purposes and for single-user access.
In order to provide SRU services at your site, you need to add a CGI script to your web server. The following instructions assume that you use Apache as your web server. However, the CGI script will work just fine with any other web server that provides CGI support.
If your web server is already set up to run CGI scripts, you might be all set to run the SRU CGI script as well. If you're not sure, follow the instructions below and check whether the your configuration file already has the relevant entries.
The Apache web server uses a configuration file called httpd.conf. On many systems this file is located in /usr/local/etc/apache. Locate the section starting with "<IfModule mod_alias.c>" and make sure it declares a CGI directory:
ScriptAlias /cgi-bin/ "/usr/local/www/cgi-bin/"
You can choose a different directory, but the directory listed here must exist and be accessible from the account the web server runs in (often "www" or "nobody").
Now you have to allow the execution of CGI scripts in that directory:
<Directory "/usr/local/www/cgi-bin">
AllowOverride None
Options ExecCGI
Order allow,deny
Allow from all
</Directory>
Finally, you have to restart your web browser to let these changes take effect:
~#apachectl restart
First you need to make sure the /cgi-bin/ directory configured above exists and has the proper permissions. Local habits may vary, but you should see something like this:
~#ls -ld /usr/local/www/cgi-bindrwxr-xr-x 2 root wheel 512 Mar 13 14:56 cgi-bin
In the Apache default installation /usr/local/www/cgi-bin is a symbolic link to an example CGI directory. Remove the symlink and create a real directory with the appropriate ownership and permissions instead.
Now copy the scripts/refdbsru CGI script into that directory and make it executable for all:
~#cp refdbsru /usr/local/www/cgi-bin~#chmod a+x /usr/local/www/cgi-bin/refdbsru
All SRU replies are XML files. This is just fine if the requesting agent is a program that intends to further process the data, or to store them somewhere. If the requesting agent is a web browser with a human being in front of it, the plain XML output is a bit hard on the eyes though. It is recommended to provide XSLT stylesheets which can render the XML output in a human-readable HTML format (most current web browsers support XSLT these days). These stylesheets are used by default, unless a user provides the URL of a stylesheet of his own.
Unless you already have a designated folder for system-wide stylesheets, just create one, and make sure it is readable:
~#mkdir -p /usr/local/www/data/styles~#chmod a+r /usr/local/www/data/styles
Now copy the example stylesheets shipped with RefDB (installed in /usr/local/share/refdb/sru) into that directory:
~#cp refdbsru.xsl mods.xsl risx.xsl refdbsru.css /usr/local/www/data/styles
Needless to say, you can tweak all these stylesheets to your heart's content.
Finally you should provide a configuration file called refdbsrurc which usually goes into /usr/local/etc/refdb/. You'll find a preconfigured example file in the same directory which you can copy and edit. Make sure the xslurl variable points to the refdbsru.xsl file that you've just installed. The value of this variable is an absolute or relative URL in the filesystem of the web server. If your setup is as described above, /styles/refdbsru.xsl will work just fine. It is recommended to set the variables starting with zeerex_ to meaningful values. These values determine part of the output of the explain SRU command and are supposed to provide the users of your site with useful information about your SRU service.
From refdbd's point of view, the refdbsru CGI script is just another client. The script therefore requires a similar configuration file like the other clients, and it needs a database account to work with. For the configuration of the script, see the refdbsru reference.
As SRU provides only read access to your databases, it is recommended to create a separate database account for SRU accesses which all SRU users share. If you specify these values in the configuration files, the SRU users will not have to provide any login information. You may want to restrict that account to read access only using the appropriate switch of the adduser command.
Open your favourite web browser and enter the following URL:
localhost/cgi-bin/refdbsru
You should now receive an XML document that describes the RefDB SRU service. If you receive a web server error instead, retrace your steps above and make sure you have restarted the web server before testing. If nothing else helps, please peruse the documentation of your web server. The appropriate document for Apache is the CGI HowTo.
Finally, you should advertize the new service on your web site. Provide a link to "<hostname>/cgi-bin/refdbsru" along with some instructions how to use SRU, as explained in the user manual.
RefDB also provides a standalone web server to run the SRU service. All you need to do in terms of "installation" is to create or edit the SRU configuration file that the standalone server shares with the CGI application. See also the refdb-sruserver reference. Then start the SRU server like this:
~# [perl] refdb-sruserverThe server will run in the foreground until you kill it with Ctrl-c. Now point your web browser to:
localhost:8080
As you can see, the SRU server uses the non-standard port 8080 so it does not interfere with any regular web server. This also means that the standalone SRU server is usually not accessible from a remote computer unless you configure your firewall appropriately. However, as long as you connect locally you should receive the output of the SRU explain command.