doc/proxy.xml

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