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">-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 proxy that accepts connections
  31   from Z39.50/SRW/SRU clients and contacts a Z39.50 backend.
  32   The listening port must be specified on the command-line.
  33   <command>inetd</command> operation is not supported.
  34   The <replaceable>host</replaceable>:<replaceable>port</replaceable>
  35   argument specifies host address to listen to, and the port to
  36   listen on.  Use the host <literal>@</literal>
  37   to listen for connections coming from any address.
  38  </para>
  39  <para>
  40   <command>yazproxy</command> can be configured using command-line
  41   options or a configuration file.
  42   Configuration file options override values specified
  43   on the command-line.
  44  </para>
  45  <para>
  46   <command>yazproxy</command> rereads its configuration file and
  47   reopens log files when it receives the hangup signal, SIGHUP.
  48  </para>
  49 </refsect1>
  50
  51 <refsect1><title>OPTIONS</title>
  52  <variablelist>
  53   <varlistentry><term>-a <replaceable>filename</replaceable></term>
  54    <listitem><para>
  55      Specifies the name of a file to which to write a log of the
  56      APDUs (protocol packets) that pass through the proxy.  The
  57      special filename <literal>-</literal> may be used to indicate
  58      standard output.
  59     </para></listitem>
  60   </varlistentry>
  61   <varlistentry><term>-l <replaceable>filename</replaceable></term>
  62    <listitem><para>
  63      Specifies the name of a file to which to write a log of the
  64      YAZ proxy activity. This uses the logging facility as provided
  65      by the YAZ toolkit. If this options is omitted, the output
  66      directed to stderr.
  67     </para></listitem>
  68   </varlistentry>
  69   <varlistentry><term>-m <replaceable>num</replaceable></term>
  70    <listitem><para>
  71      Specifies the maximum number of connections to be cached
  72      [default 50].
  73     </para></listitem>
  74   </varlistentry>
  75   <varlistentry><term>-v <replaceable>level</replaceable></term>
  76    <listitem><para>
  77      Sets the logging level. <replaceable>level</replaceable> is
  78      a comma-separated list of members of the set
  79      {<literal>fatal</literal>,<literal>debug</literal>,<literal>warn</literal>,<literal>log</literal>,<literal>malloc</literal>,<literal>all</literal>,<literal>none</literal>}.
  80     </para></listitem>
  81   </varlistentry>
  82   <varlistentry><term>-t <replaceable>target</replaceable></term>
  83    <listitem><para>
  84      Specifies the default backend target to use when a client
  85      connects that does not explicitly specify a target in its
  86      <literal>initRequest</literal>.
  87     </para></listitem>
  88   </varlistentry>
  89   <varlistentry><term>-U <replaceable>auth</replaceable></term>
  90    <listitem><para>
  91      Specifies authentication info to be sent to the backend target.
  92      This is useful if you happen to have an internal target that
  93      requires authentication, or if the client software does not allow
  94      you to set it.
  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>-i <replaceable>seconds</replaceable></term>
 106    <listitem><para>
 107      Specifies in seconds the idle time for communication between
 108      client and proxy. If a connection is inactive for this long
 109      it will be closed. Default: 600 seconds (10 minutes).
 110     </para></listitem>
 111   </varlistentry>
 112   <varlistentry><term>-T <replaceable>seconds</replaceable></term>
 113    <listitem><para>
 114      Specifies in seconds the idle time for communication between
 115      proxy and backend target.
 116      If a connection is inactive for this long
 117      it will be closed. Default: 600 seconds (10 minutes).
 118     </para></listitem>
 119   </varlistentry>
 120   <varlistentry><term>-p <replaceable>pidfile</replaceable></term>
 121    <listitem><para>
 122      When specified, yazproxy will create <replaceable>pidfile</replaceable>
 123      with the process ID of the proxy. The pidfile will be generated
 124      before the process changes identity (see option <literal>-u</literal>).
 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>-c <replaceable>config</replaceable></term>
 136    <listitem><para>
 137      Specifies config filename. Configuration is in XML
 138      and is only supported if the YAZ proxy is compiled with
 139      libxml2.
 140     </para></listitem>
 141   </varlistentry>
 142  </variablelist>
 143 </refsect1>
 144 <refsect1>
 145  <title>EXAMPLES</title>
 146  <para>
 147   The following command starts the proxy, listening on port
 148   9000, with its default backend target set to Index Data's
 149   test server:
 150  </para>
 151  <screen>
 152   $ yazproxy -t indexdata.dk:210 @:9000
 153  </screen>
 154  <para>
 155   You can connect to the proxy via yaz-client as follows:
 156  </para>
 157  <screen>
 158   $ ./yaz-client  localhost:9000/gils
 159   Connecting...OK.
 160   Sent initrequest.
 161   Connection accepted by v3 target.
 162   ID     : 81
 163   Name   : Zebra Information Server/GFS/YAZ (YAZ Proxy)
 164   Version: Zebra 1.3.15/1.23/2.0.19
 165   Options: search present delSet scan sort extendedServices namedResultSets
 166   Elapsed: 0.152108
 167   Z> f computer
 168   Sent searchRequest.
 169   Received SearchResponse.
 170   Search was a success.
 171   Number of hits: 3, setno 1
 172   SearchResult-1: computer(3)
 173   records returned: 0
 174   Elapsed: 0.172533
 175  </screen>
 176  <para>
 177   The YAZ command-line client,
 178   <command>yaz-client</command>,
 179   allows you to set the proxy address by specifying option -p. In
 180   that case, the actual backend target is specified as part of the
 181   Initialize Request.
 182  </para>
 183  <para>Suppose the proxy running on localhost, port 9000.
 184   To connect to British Library's server at
 185   <literal>blpcz.bl.uk:21021</literal> use:
 186   <screen>
 187    yaz-client -p localhost:9000 blpcz.bl.uk:21021/BLPC-ALL
 188   </screen>
 189  </para>
 190 </refsect1>
 191  <!-- Keep this comment at the end of the file
 192  Local variables:
 193  mode: sgml
 194  sgml-omittag:t
 195  sgml-shorttag:t
 196  sgml-minimize-attributes:nil
 197  sgml-always-quote-attributes:t
 198  sgml-indent-step:1
 199  sgml-indent-data:t
 200  sgml-parent-document: "reference.xml"
 201  sgml-local-catalogs: nil
 202  sgml-namecase-general:t
 203  End:
 204  -->