doc/yaz-proxy-ref.xml

   1 <refmeta>
   2  <refentrytitle>yaz-proxy</refentrytitle>
   3  <manvolnum>8</manvolnum>
   4 </refmeta>
   5 <refnamediv>
   6  <refname>yaz-proxy</refname>
   7  <refpurpose>The YAZ toolkit's transparent Z39.50 proxy</refpurpose>
   8 </refnamediv>
   9 <refsynopsisdiv>
  10  <cmdsynopsis>
  11   <command>yaz-proxy</command>
  12   <arg choice="opt">-a <replaceable>filename</replaceable></arg>
  13   <arg choice="opt">-c <replaceable>num</replaceable></arg>
  14   <arg choice="opt">-v <replaceable>level</replaceable></arg>
  15   <arg choice="opt">-t <replaceable>target</replaceable></arg>
  16   <arg choice="opt">-u <replaceable>auth</replaceable></arg>
  17   <arg choice="opt">-o <replaceable>level</replaceable></arg>
  18   <arg choice="opt">-i <replaceable>seconds</replaceable></arg>
  19   <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
  20  </cmdsynopsis>
  21 </refsynopsisdiv>
  22
  23 <refsect1><title>DESCRIPTION</title>
  24  <para>
  25   The proxy runs stand-alone (not from
  26   <literal>inetd</literal>). The
  27   <replaceable>host</replaceable>:<replaceable>port</replaceable>
  28   argument specifies host address to listen to, and the port to
  29   listen on.  Use the host <literal>@</literal>
  30   to listen for connections coming from any address.
  31  </para>
  32 </refsect1>
  33 <refsect1><title>OPTIONS</title>
  34  <variablelist>
  35   <varlistentry><term>-a <replaceable>filename</replaceable></term>
  36    <listitem><para>
  37      Specifies the name of a file to which to write a log of the
  38      APDUs (protocol packets) that pass through the proxy.  The
  39      special filename <literal>-</literal> may be used to indicate
  40      standard output.
  41     </para></listitem>
  42   </varlistentry>
  43   <varlistentry><term>-c <replaceable>num</replaceable></term>
  44    <listitem><para>
  45      Specifies the maximum number of connections to be cached
  46      [default 50].
  47     </para></listitem>
  48   </varlistentry>
  49   <varlistentry><term>-v <replaceable>level</replaceable></term>
  50    <listitem><para>
  51      Sets the logging level.  <replaceable>level</replaceable> is
  52      a comma-separated list of members of the set
  53      {<literal>fatal</literal>,<literal>debug</literal>,<literal>warn</literal>,<literal>log</literal>,<literal>malloc</literal>,<literal>all</literal>,<literal>none</literal>}.
  54     </para></listitem>
  55   </varlistentry>
  56   <varlistentry><term>-t <replaceable>target</replaceable></term>
  57    <listitem><para>
  58      Specifies the default backend target to use when a client
  59      connects that does not explicitly specify a target in its
  60      <literal>initRequest</literal>.
  61     </para></listitem>
  62   </varlistentry>
  63   <varlistentry><term>-u <replaceable>auth</replaceable></term>
  64    <listitem><para>
  65      Specifies authentication info to be sent to the backend target.
  66      This is useful if you happen to have an internal target that
  67      requires authentication, or if the client software does not allow
  68      you to set it.
  69     </para></listitem>
  70   </varlistentry>
  71   <varlistentry><term>-o <replaceable>level</replaceable></term>
  72    <listitem><para>
  73      Sets level for optimization. Use zero to disable; non-zero
  74      to enable. Handling for this is not fully implemented;
  75      we will probably use a bit mask to enable/disable specific
  76      features. By default optimization is enabled (value 1).
  77     </para></listitem>
  78   </varlistentry>
  79   <varlistentry><term>-i <replaceable>seconds</replaceable></term>
  80    <listitem><para>
  81      Specifies in seconds the idle time for communication
  82      for proxy. If a connection is inactive for this long
  83      it willl be closed. Default: 600 seconds (10 minutes).
  84     </para></listitem>
  85   </varlistentry>
  86  </variablelist>
  87 </refsect1>
  88    <refsect1>
  89  <title>EXAMPLES</title>
  90  <para>
  91   The following command starts the proxy, listening on port
  92   9000, with its default backend target set to the Library of
  93   Congress bibliographic server:
  94     </para>
  95  <screen>
  96   $ yaz-proxy -t z3950.loc.gov:7090 @:9000
  97  </screen>
  98  <para>
  99   The LOC target is sometimes very slow.  You can connect to
 100   it using yaz-client as follows:
 101  </para>
 102  <screen>
 103   $ yaz-client localhost:9000/voyager
 104   Connecting...Ok.
 105   Sent initrequest.
 106   Connection accepted by target.
 107   ID     : 34
 108   Name   : Voyager LMS - Z39.50 Server
 109   Version: 1.13
 110   Options: search present
 111   Elapsed: 7.131197
 112   Z> f computer
 113   Sent searchRequest.
 114   Received SearchResponse.
 115   Search was a success.
 116   Number of hits: 10000
 117   records returned: 0
 118   Elapsed: 6.695174
 119   Z> f computer
 120   Sent searchRequest.
 121   Received SearchResponse.
 122   Search was a success.
 123   Number of hits: 10000
 124   records returned: 0
 125   Elapsed: 0.001417
 126  </screen>
 127  <para>
 128   In this test, the second search was more than 4000 times faster
 129   than the first, because the proxy cached the result of the first
 130   search and noticed that the second was the same.
 131  </para>
 132  <para>
 133   The YAZ command-line client,
 134   <literal>yaz-client</literal>,
 135   allows you to set the proxy target as part of the Initialize
 136   Request using option <literal>-p</literal>.
 137   For example, to connect to Index Data's target you could use:
 138  </para>
 139  <screen>
 140   yaz-client -p indexdata.dk localhost:9000/gils
 141  </screen>
 142 </refsect1>
 143  <!-- Keep this comment at the end of the file
 144  Local variables:
 145  mode: sgml
 146  sgml-omittag:t
 147  sgml-shorttag:t
 148  sgml-minimize-attributes:nil
 149  sgml-always-quote-attributes:t
 150  sgml-indent-step:1
 151  sgml-indent-data:t
 152  sgml-parent-document: "proxy.xml"
 153  sgml-local-catalogs: nil
 154  sgml-namecase-general:t
 155  End:
 156  -->