/usr/share/doc/refdb/refdb-manual/ch04s10.html is in refdb-doc 1.0.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SRU support</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch04.html" title="Chapter 4. Installation" /><link rel="prev" href="ch04s09.html" title="Testing your installation" /><link rel="next" href="ch04s11.html" title="Install the PHP interface" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SRU support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s09.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Installation</th><td width="20%" align="right"> <a accesskey="n" href="ch04s11.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-install-sru"></a>SRU support</h2></div></div></div><p>In addition to its native clients, RefDB also supports optional read access through a web-based search protocol called <a class="ulink" href="http://www.loc.gov/standards/sru/" target="_top">SRU</a> (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.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-srucgi"></a>Setting up SRU support as a CGI program</h3></div></div></div><p>In order to provide SRU services at your site, you need to add a <a class="ulink" href="http://hoohoo.ncsa.uiuc.edu/cgi/" target="_top">CGI</a> script to your web server. The following instructions assume that you use <a class="ulink" href="http://httpd.apache.org/" target="_top">Apache</a> as your web server. However, the CGI script will work just fine with any other web server that provides CGI support.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-configure-apache"></a>Configure your web server</h4></div></div></div><p>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.</p><p>The Apache web server uses a configuration file called <code class="filename">httpd.conf</code>. On many systems this file is located in <code class="filename">/usr/local/etc/apache</code>. Locate the section starting with "<IfModule mod_alias.c>" and make sure it declares a CGI directory:</p><pre class="programlisting">
ScriptAlias /cgi-bin/ "/usr/local/www/cgi-bin/"
</pre><p>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").</p><p>Now you have to allow the execution of CGI scripts in that directory:</p><pre class="programlisting">
<Directory "/usr/local/www/cgi-bin">
AllowOverride None
Options ExecCGI
Order allow,deny
Allow from all
</Directory>
</pre><p>Finally, you have to restart your web browser to let these changes take effect:</p><pre class="screen"><code class="prompt">~# </code><strong class="userinput"><code>apachectl restart</code></strong></pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-install-cgi-script"></a>Install the SRU CGI script</h4></div></div></div><p>First you need to make sure the <code class="filename">/cgi-bin/</code> directory configured above exists and has the proper permissions. Local habits may vary, but you should see something like this:</p><pre class="screen"><code class="prompt">~# </code><strong class="userinput"><code>ls -ld /usr/local/www/cgi-bin</code></strong>
drwxr-xr-x 2 root wheel 512 Mar 13 14:56 cgi-bin
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>In the Apache default installation <code class="filename">/usr/local/www/cgi-bin</code> is a symbolic link to an example CGI directory. Remove the symlink and create a real directory with the appropriate ownership and permissions instead.</p></div><p>Now copy the <code class="filename">scripts/refdbsru</code> CGI script into that directory and make it executable for all:</p><pre class="screen"><code class="prompt">~# </code><strong class="userinput"><code>cp refdbsru /usr/local/www/cgi-bin</code></strong>
<code class="prompt">~# </code><strong class="userinput"><code>chmod a+x /usr/local/www/cgi-bin/refdbsru</code></strong>
</pre><p>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.</p><p>Unless you already have a designated folder for system-wide stylesheets, just create one, and make sure it is readable:</p><pre class="screen"><code class="prompt">~# </code><strong class="userinput"><code>mkdir -p /usr/local/www/data/styles</code></strong>
<code class="prompt">~# </code><strong class="userinput"><code>chmod a+r /usr/local/www/data/styles</code></strong>
</pre><p>Now copy the example stylesheets shipped with RefDB (installed in <code class="filename">/usr/local/share/refdb/sru</code>) into that directory:</p><pre class="screen"><code class="prompt">~# </code><strong class="userinput"><code>cp refdbsru.xsl mods.xsl risx.xsl refdbsru.css /usr/local/www/data/styles</code></strong>
</pre><p>Needless to say, you can tweak all these stylesheets to your heart's content.</p><p>Finally you should provide a configuration file called <code class="filename">refdbsrurc</code> which usually goes into <code class="filename">/usr/local/etc/refdb/</code>. You'll find a preconfigured example file in the same directory which you can copy and edit. Make sure the <code class="varname">xslurl</code> variable points to the <code class="filename">refdbsru.xsl</code> 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, <em class="replaceable"><code>/styles/refdbsru.xsl</code></em> will work just fine. It is recommended to set the variables starting with <code class="varname">zeerex_</code> to meaningful values. These values determine part of the output of the <span class="command"><strong>explain</strong></span> SRU command and are supposed to provide the users of your site with useful information about your SRU service.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-tune-cgi-script"></a>Tune the SRU CGI script</h4></div></div></div><p>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 <a class="link" href="re04.html" title="refdbsru">refdbsru reference</a>.</p><p>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 <a class="link" href="re06.html#app-a-command-adduser" title="adduser">adduser</a> command.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-test-cgi-script"></a>Test the SRU CGI script</h4></div></div></div><p>Open your favourite web browser and enter the following URL:</p><pre class="screen">localhost/cgi-bin/refdbsru</pre><p>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 <a class="ulink" href="http://httpd.apache.org/docs/2.0/howto/cgi.html" target="_top">CGI HowTo</a>.</p><p>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 <a class="link" href="ch11.html" title="Chapter 11. RefDB SRU interface">user manual</a>.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-srustandalone"></a>Setting up SRU support using a standalone web server</h3></div></div></div><p>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 <a class="link" href="ch04s10.html#sect-srucgi" title="Setting up SRU support as a CGI program">CGI application</a>. See also the <a class="link" href="re05.html" title="refdb-sruserver">refdb-sruserver reference</a>. Then start the SRU server like this:</p><pre class="screen"><code class="prompt">~# </code>[perl] refdb-sruserver</pre><p>The server will run in the foreground until you kill it with <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>c</strong></span>. Now point your web browser to:</p><pre class="screen">localhost:8080</pre><p>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.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s11.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Testing your installation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Install the PHP interface</td></tr></table></div></body></html>
|