doc/yaz-proxy-ref.xml

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