doc/proxy.xml

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