</para>
</section>
<section id="proxy-target">
- <title>Specifying the Backend Server</title>
+ <title>Choosing the Backend Server</title>
<para>
When the proxy receives a Z39.50 Initialize Request from a Z39.50
client, it determines the backend server by the following rules:
</listitem>
</orderedlist>
</para>
+ <para>
+ If the proxy receives an SRW/SRU request, the following rules are used.
+ <orderedlist>
+ <listitem>
+ <para>If default target has Explain information with a
+ <literal>database</literal> that matches the path of the
+ HTTP request of SRW/SRU that backend server is used for
+ SRW/SRU operation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Otherwise the service will return HTTP 404 (Not found).
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <note>
+ <para>
+ We know it is stupid to only check for explain in default target.
+ It means that it is only possible to offer one SRW/SRU server.
+ We expect to improve that in the next version of the YAZ proxy.
+ </para>
+ </note>
</section>
<section id="proxy-keepalive">
<title>Keep-alive Facility</title>
<ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> support in
order for the config file facility to be enabled.
</para>
+ <para>
+ See <xref linkend="yazproxy-schema"/> for an XML schema
+ for the configuration.
+ </para>
<tip>
<para>To check for a config file to be well-formed, the yazproxy may
be invoked without specifying a listening port, i.e.
<literal>characterInfo</literal> of the <literal>information</literal>
choice.
</para>
- </section>
+ </section>
+ <section id="yazproxy-schema">
+ <title>YAZ Proxy Configuration Schema</title>
+ <para>
+ Here an XML Schema for the YAZ proxy configuration file.
+ The schema, <filename>yazproxy.xsd</filename> is located in sub
+ directory <filename>etc</filename> of the distribution.
+ </para>
+ <screen><![CDATA[
+ <?xml version="1.0"?>
+<!-- XML Schema for YAZ proxy config file.
+ $Id: reference.xml,v 1.3 2004-04-20 23:49:48 adam Exp $
+-->
+<xs:schema
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns:exp="http://explain.z3950.org/dtd/2.0/"
+ xmlns="http://indexdata.dk/yazproxy/schema/0.8/"
+ targetNamespace="http://indexdata.dk/yazproxy/schema/0.8/"
+ >
+ <xs:import namespace="http://explain.z3950.org/dtd/2.0/"
+ schemaLocation="zeerex-2.0.xsd"/>
+ <xs:element name="proxy">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="target" minOccurs="0" maxOccurs="unbounded"/>
+ <xs:element ref="max-clients" minOccurs="0"/>
+ <xs:element ref="log" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="target">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="url" minOccurs="0" maxOccurs="unbounded"/>
+ <xs:element ref="target-timeout" minOccurs="0"/>
+ <xs:element ref="client-timeout" minOccurs="0"/>
+ <xs:element ref="keepalive" minOccurs="0"/>
+ <xs:element ref="limit" minOccurs="0"/>
+ <xs:element ref="attribute" minOccurs="0" maxOccurs="unbounded"/>
+ <xs:element ref="syntax" minOccurs="0" maxOccurs="unbounded"/>
+ <xs:element ref="preinit" minOccurs="0"/>
+ <xs:element name="exp:explain" minOccurs="0"/>
+ <xs:element ref="cql2rpn" minOccurs="0"/>
+ </xs:sequence>
+ <xs:attribute name="default" type="xs:string" use="optional"/>
+ <xs:attribute name="name" type="xs:string"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="url" type="xs:string"/>
+ <xs:element name="target-timeout" type="xs:integer"/>
+ <xs:element name="client-timeout" type="xs:integer"/>
+ <xs:element name="bandwidth" type="xs:integer"/>
+ <xs:element name="pdu" type="xs:integer"/>
+ <xs:element name="retrieve" type="xs:integer"/>
+ <xs:element name="preinit" type="xs:integer"/>
+ <xs:element name="cql2rpn" type="xs:string"/>
+
+ <xs:element name="keepalive">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="bandwidth" minOccurs="0"/>
+ <xs:element ref="pdu" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ <xs:element name="limit">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element ref="bandwidth" minOccurs="0"/>
+ <xs:element ref="pdu" minOccurs="0"/>
+ <xs:element ref="retrieve" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="attribute">
+ <xs:complexType>
+ <xs:attribute name="type" type="xs:string"/>
+ <xs:attribute name="value" type="xs:string"/>
+ <xs:attribute name="error" type="xs:integer"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="syntax">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="title" type="xs:string" minOccurs="0"/>
+ <xs:element name="name" type="xs:string" minOccurs="0"
+ maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute name="error" type="xs:string" minOccurs="0"/>
+ <xs:attribute name="type" type="xs:string" minOccurs="0"/>
+ <xs:attribute name="marcxml" type="xs:string" minOccurs="0"/>
+ <xs:attribute name="identifier" type="xs:string" minOccurs="0"/>
+ <xs:attribute name="stylesheet" type="xs:string" minOccurs="0"/>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="max-clients" type="xs:integer"/>
+ <xs:element name="log" type="xs:string"/>
+
+</xs:schema>
+
+]]>
+ </screen>
+ </section>
</chapter>
<!-- Keep this comment at the end of the file
This chapter includes a few examples.
</para>
<para>
- -- All config directives --
- -- SRW/SRU ..
- -- Example config
- -- Mention XSLT conversion
- </para>
- <para>
The YAZ Proxy is useful for debugging SRW/SRU/Z39.50 software, logging
APDUs, redirecting Z39.50 packages through firewalls, etc.
Furthermore, it offers facilities that often
</screen>
</example>
- <example id="example-firewall">
- <title>Exposing a Z39.50 server behind a firewall</title>
+ <example id="first-config">
+ <title>Using a configuration file</title>
+ <para>
+ In <xref linkend="example-apdu-logging"/> the default backend server
+ was specified by a command line option. The same proxy behavior can
+ be achieved by creating a configuration with the following contents:
+ <screen><![CDATA[
+ <?xml version="1.0"?>
+ <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
+ <target name="foo" default="1">
+ <url>foo.bar.com:18398</url>
+ <log>client-apdu</log>
+ </target>
+ <target name="*">
+ </target>
+ </proxy>
+]]>
+ </screen>
+ </para>
<para>
- ..
+ The proxy is started with
+ <screen><![CDATA[
+ yazproxy -c config.xml @:9000
+]]>
+ </screen>
+ </para>
+ <para>
+ The last target section is used for all servers except foo.
+ Had the the last section been omitted, then
+ <emphasis>only</emphasis> foo could be reached via the proxy.
</para>
</example>
<example id="example-srw-service">
<title>Offering SRW/SRU/Z39.50 service</title>
<para>
- ..
+ In order to offer SRW/SRU service we must be specify sufficient
+ information to allow the proxy to convert from SRW/SRU to Z39.50.
+ This involves CQL to Type-1 (also called RPN/PQF), since most
+ Z39.50 servers do not support CQL. The conversion
+ is specified by the <literal>cql2rpn</literal> element.
+ </para>
+ <para>
+ We must also ensure that the
+ server can return at least one kind of XML record (Dublin-Core
+ recommended).
+ </para>
+ <para>
+ An explain record for the SRW/SRU service must also be created.
+ </para>
+ <para>
+ The following is a relatively simple configuration file for
+ such a service. This service lives on <literal>indexdata.dk</literal>,
+ port 9000. The database is <literal>gils</literal>. The
+ backend server is also <literal>indexdata.dk</literal> (port 210) as
+ given by <literal>url</literal>.
+ </para>
+ <para>
+ The server may return USMARC/MARC21 (Z39.50/SRW/SRU) and
+ MARCXML (SRW/SRU only) as specified by the
+ <link linkend="proxy-config-syntax">syntax</link> elements.
+ </para>
+ <screen><![CDATA[
+<?xml version="1.0"?>
+<!-- $Id: using.xml,v 1.3 2004-04-20 23:49:48 adam Exp $ -->
+<proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
+ <target name="bagel">
+ <url>indexdata.dk</url>
+ <target-timeout>240</target-timeout>
+ <client-timeout>180</client-timeout>
+ <attribute type="1" value="1-11,13-1016"/>
+ <attribute type="1" value="*" error="114"/>
+ <syntax type="usmarc"/>
+ <syntax type="none"/>
+ <syntax type="xml" marcxml="1"
+ identifier="info:srw/schema/1/marcxml-v1.1" >
+ <name>marcxml</name>
+ </syntax>
+ <syntax type="*" error="238"/>
+ <preinit>0</preinit>
+ <explain xmlns="http://explain.z3950.org/dtd/2.0/">
+ <serverInfo>
+ <host>indexdata.dk</host>
+ <port>9000</port>
+ <database>gils</database>
+ </serverInfo>
+ </explain>
+ <cql2rpn>pqf.properties</cql2rpn>
+ </target>
+</proxy>
+]]>
+ </screen>
+ <para>
+ The conversion from CQL to RPN is specified by the
+ <link linkend="proxy-config-cql2rpn">cql2rpn</link> element.
+ <filename>pqf.properties</filename>.
+ A complete BATH/DC conversion file
+ <filename>pqf.properties</filename> is
+ part of yazproxy in sub direcory <filename>etc</filename>.
+ </para>
+ <para>
+ Explain information is embedded in the configuration file.
+ Note that in this example,only a few mandatory
+ explain elements are specified. A well-behaving server should describe
+ index sets, indexes, record schemas as well.
</para>
</example>
-
</chapter>
<!-- Keep this comment at the end of the file
<?xml version="1.0"?>
-<!-- $Id: config.xml,v 1.2 2004-04-19 13:42:52 adam Exp $ -->
+<!-- $Id: config.xml,v 1.3 2004-04-20 23:49:49 adam Exp $ -->
<proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
- <target name="bagel">
+ <target name="bagel" default="1">
<url>indexdata.dk</url>
<target-timeout>240</target-timeout>
<client-timeout>180</client-timeout>
<pdu>50</pdu>
<retrieve>100</retrieve>
</limit>
- <attribute type="1" value="1-11,13-1010"/>
+ <attribute type="1" value="1-11,13-1016"/>
<attribute type="1" value="*" error="114"/>
<syntax type="opac"/>
<syntax type="usmarc"/>
</explain>
<cql2rpn>pqf.properties</cql2rpn>
</target>
- <target default="1" name="localhost">
+ <target name="localhost">
<url>localhost:9999</url>
<target-timeout>300</target-timeout>
<client-timeout>180</client-timeout>
projects / yazproxy-moved-to-github.git / commitdiff