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/SRW/SRU 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">-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>yazproxy</command> is a proxy that accepts connections
  30   from Z39.50/SRW/SRU clients and contacts a Z39.50 backend.
  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
  50 <refsect1><title>OPTIONS</title>
  51  <variablelist>
  52   <varlistentry><term>-a <replaceable>filename</replaceable></term>
  53    <listitem><para>
  54      Specifies the name of a file to which to write a log of the
  55      APDUs (protocol packets) that pass through the proxy.  The
  56      special filename <literal>-</literal> may be used to indicate
  57      standard output.
  58     </para></listitem>
  59   </varlistentry>
  60   <varlistentry><term>-l <replaceable>filename</replaceable></term>
  61    <listitem><para>
  62      Specifies the name of a file to which to write a log of the
  63      YAZ proxy activity. This uses the logging facility as provided
  64      by the YAZ toolkit. If this options is omitted, the output
  65      directed to stderr.
  66     </para></listitem>
  67   </varlistentry>
  68   <varlistentry><term>-m <replaceable>num</replaceable></term>
  69    <listitem><para>
  70      Specifies the maximum number of connections to be cached
  71      [default 50].
  72     </para></listitem>
  73   </varlistentry>
  74   <varlistentry><term>-v <replaceable>level</replaceable></term>
  75    <listitem><para>
  76      Sets the logging level. <replaceable>level</replaceable> is
  77      a comma-separated list of members of the set
  78      {<literal>fatal</literal>,<literal>debug</literal>,<literal>warn</literal>,<literal>log</literal>,<literal>malloc</literal>,<literal>all</literal>,<literal>none</literal>}.
  79     </para></listitem>
  80   </varlistentry>
  81   <varlistentry><term>-t <replaceable>target</replaceable></term>
  82    <listitem><para>
  83      Specifies the default backend target to use when a client
  84      connects that does not explicitly specify a target in its
  85      <literal>initRequest</literal>.
  86     </para></listitem>
  87   </varlistentry>
  88   <varlistentry><term>-o <replaceable>level</replaceable></term>
  89    <listitem><para>
  90      Sets level for optimization. Use zero to disable; non-zero
  91      to enable. Handling for this is not fully implemented;
  92      we will probably use a bit mask to enable/disable specific
  93      features. By default optimization is enabled (value 1).
  94     </para></listitem>
  95   </varlistentry>
  96   <varlistentry><term>-i <replaceable>seconds</replaceable></term>
  97    <listitem><para>
  98      Specifies in seconds the idle time for communication between
  99      client and proxy. If a connection is inactive for this long
 100      it will be closed. Default: 600 seconds (10 minutes).
 101     </para></listitem>
 102   </varlistentry>
 103   <varlistentry><term>-T <replaceable>seconds</replaceable></term>
 104    <listitem><para>
 105      Specifies in seconds the idle time for communication between
 106      proxy and backend target.
 107      If a connection is inactive for this long
 108      it will be closed. Default: 600 seconds (10 minutes).
 109     </para></listitem>
 110   </varlistentry>
 111   <varlistentry><term>-p <replaceable>pidfile</replaceable></term>
 112    <listitem><para>
 113      When specified, yazproxy will create <replaceable>pidfile</replaceable>
 114      with the process ID of the proxy. The pidfile will be generated
 115      before the process changes identity (see option <literal>-u</literal>).
 116     </para></listitem>
 117   </varlistentry>
 118   <varlistentry><term>-u <replaceable>userid</replaceable></term>
 119    <listitem><para>
 120      When specified, yazproxy will change identity to the user ID
 121      specified, just after the proxy has started listening to a
 122      possibly privileged port and after the PID file has been created
 123      if specified by option <literal>-u</literal>.
 124     </para></listitem>
 125   </varlistentry>
 126   <varlistentry><term>-c <replaceable>config</replaceable></term>
 127    <listitem><para>
 128      Specifies config filename. Configuration is in XML
 129      and is only supported if the YAZ proxy is compiled with
 130      libxml2.
 131     </para></listitem>
 132   </varlistentry>
 133  </variablelist>
 134 </refsect1>
 135 <refsect1>
 136  <title>EXAMPLES</title>
 137  <para>
 138   The following command starts the proxy, listening on port
 139   9000, with its default backend target set to Index Data's
 140   test server:
 141  </para>
 142  <screen>
 143   $ yazproxy -t indexdata.dk:210 @:9000
 144  </screen>
 145  <para>
 146   You can connect to the proxy via yaz-client as follows:
 147  </para>
 148  <screen>
 149   $ ./yaz-client  localhost:9000/gils
 150   Connecting...OK.
 151   Sent initrequest.
 152   Connection accepted by v3 target.
 153   ID     : 81
 154   Name   : Zebra Information Server/GFS/YAZ (YAZ Proxy)
 155   Version: Zebra 1.3.15/1.23/2.0.19
 156   Options: search present delSet scan sort extendedServices namedResultSets
 157   Elapsed: 0.152108
 158   Z> f computer
 159   Sent searchRequest.
 160   Received SearchResponse.
 161   Search was a success.
 162   Number of hits: 3, setno 1
 163   SearchResult-1: computer(3)
 164   records returned: 0
 165   Elapsed: 0.172533
 166  </screen>
 167  <para>
 168   The YAZ command-line client,
 169   <command>yaz-client</command>,
 170   allows you to set the proxy address by specifying option -p. In
 171   that case, the actual backend target is specified as part of the
 172   Initialize Request.
 173  </para>
 174  <para>Suppose the proxy running on localhost, port 9000.
 175   To connect to British Library's server at
 176   <literal>blpcz.bl.uk:21021</literal> use:
 177   <screen>
 178    yaz-client -p localhost:9000 blpcz.bl.uk:21021/BLPC-ALL
 179   </screen>
 180  </para>
 181 </refsect1>
 182  <!-- Keep this comment at the end of the file
 183  Local variables:
 184  mode: sgml
 185  sgml-omittag:t
 186  sgml-shorttag:t
 187  sgml-minimize-attributes:nil
 188  sgml-always-quote-attributes:t
 189  sgml-indent-step:1
 190  sgml-indent-data:t
 191  sgml-parent-document: "reference.xml"
 192  sgml-local-catalogs: nil
 193  sgml-namecase-general:t
 194  End:
 195  -->