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