<chapter id="proxy">
- <!-- $Id: proxy.xml,v 1.1 2002-10-08 11:55:57 adam Exp $ -->
+ <!-- $Id: proxy.xml,v 1.2 2002-10-21 13:37:31 adam Exp $ -->
<title>YAZ Proxy</title>
- <para>
- About YAZ Proxy.
- </para>
-</chapter>
+ <para>
+ The YAZ proxy is a transparent Z39.50 to Z39.50 gateway.
+ It is useful for debugging Z39.50 software, redirect
+ Z39.50 packages through firewalls, etc.
+ </para>
+ <para>
+ Furthermore, the proxy offers facilities that often
+ boost performance for "connection-less" Z39.50 clients such
+ as web gateways.
+ </para>
+ <para>
+ Unlike most other "server" software the proxy runs single-threaded,
+ single-process. Every I/O operation
+ is non-blocking so it is light-weight and very fast.
+ It does not store "state" information on the hard drive
+ except the log files you want.
+ </para>
+ <section><title>Specifying the backend target</title>
+ <para>
+ When a Z39.50 client session is accepted by the proxy, the proxy
+ determines the backend target by the following rules:
+ <orderedlist>
+ <listitem>
+ <para> If the Initialize Request PDU from the client
+ includes OtherInformation, with OID,
+ <literal>1.2.840.10003.10.1000.81.1</literal>, that
+ specifies the target.
+ </para>
+ </listitem>
+ <listitem>
+ <para> Otherwise, the Proxy uses the default target if given.
+ (option <literal>-t</literal>).
+ </para>
+ </listitem>
+ <listitem>
+ <para> Otherwise, the proxy closes the connection with
+ the client.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+ <section><title>Keep-alive facility for Stateless clients</title>
+ <para>
+ Stateless clients may generate a cookie for a Z39.50
+ session which is sent to the proxy as part of PDUs.
+ In this case, the proxy will keep the Z39.50 session alive
+ to the backend target even the connection from the client
+ to the proxy is closed. When the client contacts the
+ proxy again it will re-issue the cookie and reuse the
+ Z39.50 connection with the backend target. Note that there is not
+ guarantee that the Z39.50 is kept forever to the backend
+ target, since the proxy will shut it down after certain
+ idle time. So in effect, the connection from the client's
+ point of view should be considered stateless.
+ </para>
+ <para>
+ As for the target specification, the OtherInformation
+ area is used to hold the cookie with OID
+ <literal>1.2.840.10003.10.1000.81.2</literal>.
+ </para>
+ </section>
+
+ <section><title>Query Caching</title>
+ <para>
+ Simple stateless clients often sends identical Z39.50 searches
+ in a relatively short period of time (full-list, next-page,
+ single full-record, etc). And for many targets, it's
+ much more expensive to produce a new result set than
+ reuse and existing one.
+ </para>
+ <para>
+ The proxy tries to solve that by storing the last query for each
+ backend target. So when an identical query is received that
+ is turned into Present Requests rather than new Search Requests.
+ </para>
+ <para>
+ This optimization should work for any Z39.50 client and/or
+ target. The target does not have to support named result sets.
+ </para>
+
+ </section>
+
+ <section><title>Other optimizations</title>
+ <para>
+ We've had some plans to support caching of result set records,
+ but this had not yet been implemented.
+ </para>
+ </section>
+ <section><title>Proxy usage</title>
+ <para>
+ </para>
+ <refentry id="yaz-proxy">
+ <refmeta>
+ <refentrytitle>yaz-proxy</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>yaz-proxy</refname>
+ <refpurpose>Z39.50 proxy</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>yaz-proxy</command>
+ <arg choice="opt">-a <replaceable>fname</replaceable></arg>
+ <arg choice="opt">-c <replaceable>num</replaceable></arg>
+ <arg choice="opt">-v <replaceable>level</replaceable></arg>
+ <arg choice="opt">-t <replaceable>target</replaceable></arg>
+ <arg choice="opt">-u <replaceable>auth</replaceable></arg>
+ <arg choice="opt">-o <replaceable>level</replaceable></arg>
+ <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1><title>DESCRIPTION</title>
+ <para>
+ The proxy is a daemon on its own and runs standalone (no
+ inetd support). The host:port specifies host address and
+ listening port respectively. Use <literal>@</literal>
+ for ANY address.
+ </para>
+ </refsect1>
+ <refsect1><title>OPTIONS</title>
+ <variablelist>
+ <varlistentry><term>-a <replaceable>fname</replaceable></term>
+ <listitem><para>
+ APDU log.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-c <replaceable>num</replaceable></term>
+ <listitem><para>
+ Specifies maximum number of connections to be cached.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-v <replaceable>level</replaceable></term>
+ <listitem><para>
+ Debug level (like YAZ).
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-t <replaceable>target</replaceable></term>
+ <listitem><para>
+ Default target.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-t <replaceable>target</replaceable></term>
+ <listitem><para>
+ Authentication info sent to the backend target.
+ Useful if you happen to have an internal target that does
+ require authentication or if the client software does not allow
+ you to set it.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>-o <replaceable>level</replaceable></term>
+ <listitem><para>
+ Sets level for optimization. Use zero to disable; non-zero
+ to enable. Handling for this is not fully implemented;
+ we will probably use a bitmask to enable/disable specific
+ features.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>EXAMPLES</title>
+ <para>
+ The following starts the proxy so that it listens on port
+ 9000. The default backend target is LOC.
+ <screen>
+ $ yaz-proxy -t z3950.loc.gov:7090 @:9000
+ </screen>
+ The LOC target is sometimes very slow. You can connect to
+ it using yaz-client as follows:
+ <screen>
+$ yaz-client localhost:9000/voyager
+Connecting...Ok.
+Sent initrequest.
+Connection accepted by target.
+ID : 34
+Name : Voyager LMS - Z39.50 Server
+Version: 1.13
+Options: search present
+Elapsed: 7.131197
+Z> f computer
+Sent searchRequest.
+Received SearchResponse.
+Search was a success.
+Number of hits: 10000
+records returned: 0
+Elapsed: 6.695174
+Z> f computer
+Sent searchRequest.
+Received SearchResponse.
+Search was a success.
+Number of hits: 10000
+records returned: 0
+Elapsed: 0.001417
+ </screen>
+ In this test, the second search was more than 4000 times faster
+ than the first.
+ </para>
+ <para>
+ The YAZ client allows you to set the backend target in
+ the Initialize Request using option -p. To connect to
+ Index Data's target you could use:
+ <screen>
+ yaz-client -p indexdata.dk localhost:9000/gils
+ </screen>
+ </para>
+ </refsect1>
+ </refentry>
+ </section>
+ </chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
- sgml-parent-document: "zebra.xml"
+ sgml-parent-document: "yaz++.xml"
sgml-local-catalogs: nil
sgml-namecase-general:t
End:
projects / yazpp-moved-to-github.git / commitdiff