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