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