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