doc/proxy.xml

   1 <chapter id="proxy">
   2   <!-- $Id: proxy.xml,v 1.2 2002-10-21 13:37:31 adam Exp $ -->
   3  <title>YAZ Proxy</title>
   4   <para>
   5    The YAZ proxy is a transparent Z39.50 to Z39.50 gateway.
   6    It is useful for debugging Z39.50 software, redirect
   7    Z39.50 packages through firewalls, etc.
   8   </para>
   9   <para>
  10    Furthermore, the proxy offers facilities that often
  11    boost performance for "connection-less" Z39.50 clients such
  12    as web gateways.
  13   </para>
  14   <para>
  15    Unlike most other "server" software the proxy runs single-threaded,
  16    single-process. Every I/O operation
  17    is non-blocking so it is light-weight and very fast.
  18    It does not store "state" information on the hard drive
  19    except the log files you want.
  20   </para>
  21   <section><title>Specifying the backend target</title>
  22    <para>
  23     When a Z39.50 client session is accepted by the proxy, the proxy
  24     determines the backend target by the following rules:
  25     <orderedlist>
  26      <listitem>
  27       <para> If the Initialize Request PDU from the client
  28        includes OtherInformation, with OID,
  29        <literal>1.2.840.10003.10.1000.81.1</literal>, that
  30        specifies the target.
  31       </para>
  32      </listitem>
  33      <listitem>
  34       <para> Otherwise, the Proxy uses the default target if given.
  35        (option <literal>-t</literal>).
  36       </para>
  37      </listitem>
  38      <listitem>
  39       <para> Otherwise, the proxy closes the connection with
  40        the client.
  41       </para>
  42      </listitem>
  43     </orderedlist>
  44    </para>
  45   </section>
  46   <section><title>Keep-alive facility for Stateless clients</title>
  47    <para>
  48     Stateless clients may generate a cookie for a Z39.50
  49     session which is sent to the proxy as part of PDUs.
  50     In this case, the proxy will keep the Z39.50 session alive
  51     to the backend target even the connection from the client
  52     to the proxy is closed. When the client contacts the
  53     proxy again it will re-issue the cookie and reuse the
  54     Z39.50 connection with the backend target. Note that there is not
  55     guarantee that the Z39.50 is kept forever to the backend
  56     target, since the proxy will shut it down after certain
  57     idle time. So in effect, the connection from the client's
  58     point of view should be considered stateless.
  59    </para>
  60    <para>
  61     As for the target specification, the OtherInformation
  62     area is used to hold the cookie with OID
  63     <literal>1.2.840.10003.10.1000.81.2</literal>.
  64    </para>
  65   </section>
  66
  67   <section><title>Query Caching</title>
  68    <para>
  69     Simple stateless clients often sends identical Z39.50 searches
  70     in a relatively short period of time (full-list, next-page,
  71     single full-record, etc). And for many targets, it's
  72     much more expensive to produce a new result set than
  73     reuse and existing one.
  74    </para>
  75    <para>
  76     The proxy tries to solve that by storing the last query for each
  77     backend target. So when an identical query is received that
  78     is turned into Present Requests rather than new Search Requests.
  79    </para>
  80    <para>
  81     This optimization should work for any Z39.50 client and/or
  82     target. The target does not have to support named result sets.
  83    </para>
  84
  85   </section>
  86
  87   <section><title>Other optimizations</title>
  88    <para>
  89     We've had some plans to support caching of result set records,
  90     but this had not yet been implemented.
  91    </para>
  92   </section>
  93   <section><title>Proxy usage</title>
  94    <para>
  95    </para>
  96    <refentry id="yaz-proxy">
  97     <refmeta>
  98      <refentrytitle>yaz-proxy</refentrytitle>
  99      <manvolnum>8</manvolnum>
 100     </refmeta>
 101     <refnamediv>
 102      <refname>yaz-proxy</refname>
 103      <refpurpose>Z39.50 proxy</refpurpose>
 104     </refnamediv>
 105     <refsynopsisdiv>
 106      <cmdsynopsis>
 107       <command>yaz-proxy</command>
 108       <arg choice="opt">-a <replaceable>fname</replaceable></arg>
 109       <arg choice="opt">-c <replaceable>num</replaceable></arg>
 110       <arg choice="opt">-v <replaceable>level</replaceable></arg>
 111       <arg choice="opt">-t <replaceable>target</replaceable></arg>
 112       <arg choice="opt">-u <replaceable>auth</replaceable></arg>
 113       <arg choice="opt">-o <replaceable>level</replaceable></arg>
 114       <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
 115      </cmdsynopsis>
 116     </refsynopsisdiv>
 117
 118     <refsect1><title>DESCRIPTION</title>
 119      <para>
 120       The proxy is a daemon on its own and runs standalone (no
 121       inetd support). The host:port specifies host address and
 122       listening port respectively. Use <literal>@</literal>
 123       for ANY address.
 124      </para>
 125     </refsect1>
 126     <refsect1><title>OPTIONS</title>
 127      <variablelist>
 128       <varlistentry><term>-a <replaceable>fname</replaceable></term>
 129        <listitem><para>
 130          APDU log.
 131         </para></listitem>
 132       </varlistentry>
 133       <varlistentry><term>-c <replaceable>num</replaceable></term>
 134        <listitem><para>
 135          Specifies maximum number of connections to be cached.
 136         </para></listitem>
 137       </varlistentry>
 138       <varlistentry><term>-v <replaceable>level</replaceable></term>
 139        <listitem><para>
 140          Debug level (like YAZ).
 141         </para></listitem>
 142       </varlistentry>
 143       <varlistentry><term>-t <replaceable>target</replaceable></term>
 144        <listitem><para>
 145          Default target.
 146         </para></listitem>
 147       </varlistentry>
 148       <varlistentry><term>-t <replaceable>target</replaceable></term>
 149        <listitem><para>
 150          Authentication info sent to the backend target.
 151          Useful if you happen to have an internal target that does
 152          require authentication or if the client software does not allow
 153          you to set it.
 154         </para></listitem>
 155       </varlistentry>
 156       <varlistentry><term>-o <replaceable>level</replaceable></term>
 157        <listitem><para>
 158          Sets level for optimization. Use zero to disable; non-zero
 159          to enable. Handling for this is not fully implemented;
 160          we will probably use a bitmask to enable/disable specific
 161          features.
 162         </para></listitem>
 163       </varlistentry>
 164      </variablelist>
 165     </refsect1>
 166     <refsect1>
 167      <title>EXAMPLES</title>
 168      <para>
 169       The following starts the proxy so that it listens on port
 170       9000. The default backend target is LOC.
 171       <screen>
 172        $ yaz-proxy -t z3950.loc.gov:7090 @:9000
 173       </screen>
 174       The LOC target is sometimes very slow. You can connect to
 175       it using yaz-client as follows:
 176       <screen>
 177 $ yaz-client localhost:9000/voyager
 178 Connecting...Ok.
 179 Sent initrequest.
 180 Connection accepted by target.
 181 ID     : 34
 182 Name   : Voyager LMS - Z39.50 Server
 183 Version: 1.13
 184 Options: search present
 185 Elapsed: 7.131197
 186 Z> f computer
 187 Sent searchRequest.
 188 Received SearchResponse.
 189 Search was a success.
 190 Number of hits: 10000
 191 records returned: 0
 192 Elapsed: 6.695174
 193 Z> f computer
 194 Sent searchRequest.
 195 Received SearchResponse.
 196 Search was a success.
 197 Number of hits: 10000
 198 records returned: 0
 199 Elapsed: 0.001417
 200        </screen>
 201       In this test, the second search was more than 4000 times faster
 202       than the first.
 203      </para>
 204      <para>
 205       The YAZ client allows you to set the backend target in
 206       the Initialize Request using option -p. To connect to
 207       Index Data's target you could use:
 208       <screen>
 209        yaz-client -p indexdata.dk localhost:9000/gils
 210       </screen>
 211      </para>
 212     </refsect1>
 213    </refentry>
 214   </section>
 215  </chapter>
 216  <!-- Keep this comment at the end of the file
 217  Local variables:
 218  mode: sgml
 219  sgml-omittag:t
 220  sgml-shorttag:t
 221  sgml-minimize-attributes:nil
 222  sgml-always-quote-attributes:t
 223  sgml-indent-step:1
 224  sgml-indent-data:t
 225  sgml-parent-document: "yaz++.xml"
 226  sgml-local-catalogs: nil
 227  sgml-namecase-general:t
 228  End:
 229  -->