<chapter id="proxy">
<title>The YAZ Proxy</title>
<para>
- The YAZ proxy is a transparent Z39.50-to-Z39.50 gateway. That is,
- it is a Z39.50 server which has as its back-end a Z39.50 client
- that forwards requests on to another server (known as the
- <firstterm>backend target</firstterm>.)
+ The YAZ proxy is a transparent SRW/SRU/Z39.50-to-Z39.50 gateway.
+ That is, it is a SRW/SRU/Z39.50 server which has as its back-end a
+ Z39.50 client that forwards requests on to another server (known as
+ the <firstterm>backend target</firstterm>.)
</para>
<para>
- The YAZ Proxy is useful for debugging Z39.50 software, logging
+ -- 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
boost performance for connectionless Z39.50 clients such
start it up. It will work exactly as usual, but all the packets
will be sent via the proxy, which will generate a log like this:
</para>
- <screen>
+ <screen><![CDATA[
decode choice
initRequest {
referenceId OCTETSTRING(len=4) 69 6E 69 74
}
}
}
+]]>
</screen>
</section>
<section id="proxy-target">
<title>Specifying the Backend Target</title>
<para>
- When the proxy accepts a Z39.50 client session, it
- determines the backend target by the following rules:
+ When the proxy receives a Z39.50 Initialize Request from a Z39.50
+ client, it determines the backend target by the following rules:
<orderedlist>
<listitem>
- <para> If the <literal>InitializeRequest</literal> PDU from the
+ <para>If the <literal>InitializeRequest</literal> PDU from the
client includes an
<link linkend="otherinfo-encoding"><literal>otherInfo</literal></link>
element with OID
usual YAZ address format (typically
<literal>tcp:<parameter>hostname</parameter>:<parameter>port</parameter></literal>)
as described in
- <ulink url="http://www.indexdata.dk/yaz/doc/comstack.addresses.php"
+ <ulink url="http://www.indexdata.dk/yaz/doc/comstack.addresses.tkl"
>the Addresses section of the YAZ manual</ulink>.
</para>
</listitem>
<listitem>
- <para> Otherwise, the Proxy uses the default target, if one was
+ <para>Otherwise, the Proxy uses the default target, if one was
specified on the command-line with the <literal>-t</literal>
option. A default target can also be specified in the
XML Config file.
</para>
</listitem>
<listitem>
- <para> Otherwise, the proxy closes the connection with
+ <para>Otherwise, the proxy closes the connection with
the client.
</para>
</listitem>
<para>
When a client reconnects, query and record caching works better, if the
proxy assigns it to the same backend as before. And the result set
- (if any) is re-used. To achive this, Index Data defined a session
+ (if any) is re-used. To achieve this, Index Data defined a session
cookie which identifies the backend session.
</para>
<para>
client. Finally, the proxy may convert records.
</para>
<para>
- In the current version the only supported conversion is
- MARC21/USMARC in MARC-8 charset to MARCXML in UTF-8. Future version of
- the proxy may do other record/charset conversions.
+ The proxy can convert from MARC to MARCXML and thereby offer an
+ XML version of any MARC record as long as it is ISO2709 encoded.
+ If the proxy is compiled with libXSLT support it can also
+ perform XSLT on XML.
</para>
</section>
<section id="proxy-config-file">
<title>Proxy Configuration File</title>
<para>
- The Proxy as an option may read a configuration file using option
+ The Proxy may read a configuration file using option
<literal>-c</literal> followed by the filename of a config file.
</para>
<para>
- The config file is in XML format. The YAZ proxy must be compiled
- with <ulink url="http://www.xmlsoft.org/">libxml2</ulink> support in
+ The config file is XML based. The YAZ proxy must be compiled
+ with <ulink url="http://www.xmlsoft.org/">libxml2</ulink> and
+ <ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> support in
order for the config file facility to be enabled.
</para>
<tip>
<title>Configuration: target</title>
<para>
The element <literal>target</literal> which may be repeated zero
- or more times with parent elemtn <literal>proxy</literal> contains
+ or more times with parent element <literal>proxy</literal> contains
information about each backend target.
The <literal>target</literal> element have two attributes:
<literal>name</literal> which holds the logical name of the backend
<para>
<screen>
<?xml version="1.0"?>
- <!-- $Id -->
<proxy>
<target name="server1" default="1">
<!-- description of server1 .. -->
measures the number of bytes transferred within the last minute.
The <literal>pdu</literal> is the number of requests in the last
minute. The <literal>retrieve</literal> holds the maximum records to
- be retrived in one Present Request.
+ be retrieved in one Present Request.
</para>
<para>
If a bandwidth/pdu limit is reached the proxy will postpone the
or a particular record syntax request from the client.
</para>
<para>
- The <literal>syntax</literal> has one equired attribute:
+ The <literal>syntax</literal> has one required attribute:
<literal>type</literal> which is the Preferred Record Syntax.
</para>
<para>
<literal>type</literal> should be XML. The proxy will use
preferred record syntax USMARC/MARC21 against the backend target.
</para>
- <para>To accept USMARC and offer MARCXML XML recors but reject
- all other requests the following configuaration could be used:
+ <para>To accept USMARC and offer MARCXML XML records but reject
+ all other requests the following configuration could be used:
<screen>
<proxy>
<target name="mytarget">
- <syntax type="usmarc"/>
- <syntax type="xml" marcxml="1"/>
- <syntax type="*" error="238"/>
+ <syntax type="usmarc"/>
+ <syntax type="xml" marcxml="1"/>
+ <syntax type="*" error="238"/>
</target>
</proxy>
</screen>
a target session is shut down.
</para>
<para>
- This can also be specified on the command line bt using option
+ This can also be specified on the command line by using option
<literal>-T</literal>. Refer to <xref linkend="proxy-usage"/>.
</para>
</section>
</para>
</tip>
</section>
-
+
+ <section id="proxy-config-log">
+ <title>Configuration: log</title>
+ <para>
+ The element <literal>log</literal> is the child of element
+ <literal>proxy</literal> and specifies what to be logged by the
+ proxy.
+ </para>
+ <para>
+ Specify the log file with command-line option <literal>-l</literal>.
+ </para>
+ <para>
+ The text of the <literal>log</literal> element is a sequence of
+ options separated by white space. See the table below:
+ <table frame="top"><title>Logging options</title>
+ <tgroup cols="2">
+ <colspec colwidth="1*" colname="option"/>
+ <colspec colwidth="2*" colname="description"/>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>client-apdu</literal></entry>
+ <entry>
+ Log APDUs as reported by YAZ for the
+ communication between the client and the proxy.
+ This facility is equivalent to the APDU logging that
+ happens when using option <literal>-a</literal>, however
+ this tells the proxy to log in the same file as given
+ by <literal>-l</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>server-apdu</literal></entry>
+ <entry>
+ Log APDUs as reported by YAZ for the
+ communication between the proxy and the server (backend).
+ </entry>
+ </row>
+ <row>
+ <entry><literal>clients-requests</literal></entry>
+ <entry>
+ Log a brief description about requests transferred between
+ the client and the proxy. The name of the request and the size
+ of the APDU is logged.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>server-requests</literal></entry>
+ <entry>
+ Log a brief description about requests transferred between
+ the proxy and the server (backend). The name of the request
+ and the size of the APDU is logged.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ To log communication in details between the proxy and the backend, th
+ following configuration could be used:
+ <screen><![CDATA[
+ <target name="mytarget">
+ <log>server-apdu server-requests</log>
+ </target>
+]]>
+ </screen>
+ </para>
+ </section>
+
</section>
<section id="proxy-usage">
<title>Proxy Usage</title>
sgml-namecase-general:t
End:
-->
-
\ No newline at end of file
+