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