doc/yaz-proxy-ref.xml

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