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