doc/using.xml

   1  <chapter id="using">
   2   <title>Using YAZ proxy</title>
   3   <para>
   4    As mentioned in the introduction the YAZ proxy has many uses.
   5    This chapter includes a few examples.
   6   </para>
   7   <para>
   8    The YAZ Proxy is useful for debugging SRW/SRU/Z39.50 software, logging
   9    APDUs, redirecting Z39.50 packages through firewalls, etc.
  10    Furthermore, it offers facilities that often
  11    boost performance for connection-less Z39.50 clients such
  12    as web gateways.
  13   </para>
  14   <para>
  15    Unlike most other server software, the proxy runs single-threaded,
  16    single-process. Every I/O operation
  17    is non-blocking so it is very lightweight and extremely fast.
  18    It does not store any state information on the hard drive,
  19    except any log files you ask for.
  20   </para>
  21
  22   <example id="example-apdu-logging">
  23    <title>Using the Proxy to Log APDUs</title>
  24    <para>
  25     Suppose you use a commercial Z39.50 client for which you do not
  26     have source code, and it's not behaving how you think it should
  27     when running against some specific server that you have no control
  28     over.  One way to diagnose the problem is to find out what packets
  29     (APDUs) are being sent and received, but not all client
  30     applications have facilities to do APDU logging.
  31    </para>
  32    <para>
  33     No problem.  Run the proxy on a friendly machine, get it to log
  34     APDUs, and point the errant client at the proxy instead of
  35     directly at the server that's causing it problems.
  36    </para>
  37    <para>
  38     Suppose the server is running on <literal>foo.bar.com</literal>,
  39     port 18398.  Run the proxy on the machine of your choice, say
  40     <literal>your.company.com</literal> like this:
  41    </para>
  42    <screen>
  43     yazproxy -a - -t tcp:foo.bar.com:18398 tcp:@:9000
  44    </screen>
  45    <para>
  46     (The <literal>-a -</literal> option requests APDU logging on
  47     standard output, <literal>-t tcp:foo.bar.com:18398</literal>
  48     specifies where the backend target is, and
  49     <literal>tcp:@:9000</literal> tells the proxy to listen on port
  50     9000 and accept connections from any machine.)
  51    </para>
  52    <para>
  53     Now change your client application's configuration so that instead
  54     of connecting to <literal>foo.bar.com</literal> port 18398, it
  55     connects to <literal>your.company.com</literal> port 9000, and
  56     start it up.  It will work exactly as usual, but all the packets
  57     will be sent via the proxy, which will generate a log like this:
  58    </para>
  59    <screen><![CDATA[
  60     decode choice
  61     initRequest {
  62         referenceId OCTETSTRING(len=4) 69 6E 69 74
  63         protocolVersion BITSTRING(len=1)
  64         options BITSTRING(len=2)
  65         preferredMessageSize 1048576
  66         maximumRecordSize 1048576
  67         implementationId 'Mike Taylor (id=169)'
  68         implementationName 'Net::Z3950.pm (Perl)'
  69         implementationVersion '0.31'
  70     }
  71     encode choice
  72     initResponse {
  73         referenceId OCTETSTRING(len=4) 69 6E 69 74
  74         protocolVersion BITSTRING(len=1)
  75         options BITSTRING(len=2)
  76         preferredMessageSize 1048576
  77         maximumRecordSize 1048576
  78         result TRUE
  79         implementationId '81'
  80         implementationName 'GFS/YAZ / Zebra Information Server'
  81         implementationVersion 'YAZ 1.9.1 / Zebra 1.3.3'
  82     }
  83     decode choice
  84     searchRequest {
  85         referenceId OCTETSTRING(len=1) 30
  86         smallSetUpperBound 0
  87         largeSetLowerBound 1
  88         mediumSetPresentNumber 0
  89         replaceIndicator TRUE
  90         resultSetName 'default'
  91         databaseNames {
  92             'gils'
  93         }
  94         {
  95             smallSetElementSetNames choice
  96             generic 'F'
  97         }
  98         {
  99             mediumSetElementSetNames choice
 100             generic 'B'
 101         }
 102         preferredRecordSyntax OID: 1 2 840 10003 5 10
 103         {
 104             query choice
 105             type_1 {
 106                 attributeSetId OID: 1 2 840 10003 3 1
 107                 RPNStructure choice
 108                 {
 109                     simple choice
 110                     attributesPlusTerm {
 111                         attributes {
 112                         }
 113                         term choice
 114                         general OCTETSTRING(len=7) 6D 69 6E 65 72 61 6C
 115                     }
 116                 }
 117             }
 118         }
 119     }
 120 ]]>
 121    </screen>
 122   </example>
 123
 124   <example id="first-config">
 125    <title>Using a configuration file</title>
 126    <para>
 127     In <xref linkend="example-apdu-logging"/> the default backend server
 128     was specified by a command line option. The same proxy behavior can
 129     be achieved by creating a configuration with the following contents:
 130     <screen><![CDATA[
 131      <?xml version="1.0"?>
 132      <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.9/">
 133        <target name="foo" default="1">
 134          <url>foo.bar.com:18398</url>
 135          <log>client-apdu</log>
 136        </target>
 137        <target name="*">
 138        </target>
 139      </proxy>
 140 ]]>
 141     </screen>
 142    </para>
 143    <para>
 144     The proxy is started with
 145     <screen><![CDATA[
 146      yazproxy -c config.xml @:9000
 147 ]]>
 148     </screen>
 149    </para>
 150    <para>
 151     The last target section is used for all servers except foo.
 152     Had the the last section been omitted, then
 153     <emphasis>only</emphasis> foo could be reached via the proxy.
 154    </para>
 155   </example>
 156
 157   <example id="example-srw-service">
 158    <title>Offering SRW/SRU/Z39.50 service</title>
 159    <para>
 160     In order to offer SRW/SRU service we must be specify sufficient
 161     information to allow the proxy to convert from SRW/SRU to Z39.50.
 162     This involves translating CQL queries
 163     to Type-1 (also called RPN/PQF), since most
 164     Z39.50 servers do not support CQL. The conversion
 165     is specified by the <literal>cql2rpn</literal> element.
 166    </para>
 167    <para>
 168     We must also ensure that the
 169     server can return at least one kind of XML record (Dublin-Core
 170     recommended).
 171    </para>
 172    <para>
 173     An explain record for the SRW/SRU service must also be created.
 174    </para>
 175    <para>
 176     The following is a relatively simple configuration file for
 177     such a service. This service lives on <literal>indexdata.dk</literal>,
 178     port 9000. The database is <literal>gils</literal>. The
 179     backend server is also <literal>indexdata.dk</literal> (port 210) as
 180     given by <literal>url</literal>.
 181    </para>
 182    <para>
 183     The server may return USMARC/MARC21 (Z39.50/SRW/SRU) and
 184     MARCXML (SRW/SRU only) as specified by the
 185     <link linkend="proxy-config-syntax">syntax</link> elements.
 186    </para>
 187     <screen><![CDATA[
 188 <?xml version="1.0"?>
 189 <!-- $Id: using.xml,v 1.6 2005-03-14 13:16:03 adam Exp $ -->
 190 <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.9/">
 191   <target name="bagel">
 192     <url>indexdata.dk</url>
 193     <target-timeout>240</target-timeout>
 194     <client-timeout>180</client-timeout>
 195     <attribute type="1" value="1-11,13-1016"/>
 196     <attribute type="1" value="*" error="114"/>
 197     <syntax type="usmarc"/>
 198     <syntax type="none"/>
 199     <syntax type="xml" marcxml="1"
 200       identifier="info:srw/schema/1/marcxml-v1.1" >
 201       <name>marcxml</name>
 202     </syntax>
 203     <syntax type="*" error="238"/>
 204     <preinit>0</preinit>
 205     <explain xmlns="http://explain.z3950.org/dtd/2.0/">
 206        <serverInfo>
 207        <host>indexdata.dk</host>
 208        <port>9000</port>
 209        <database>gils</database>
 210        </serverInfo>
 211     </explain>
 212     <cql2rpn>pqf.properties</cql2rpn>
 213   </target>
 214 </proxy>
 215 ]]>
 216     </screen>
 217    <para>
 218     The conversion from CQL to RPN is specified by a file whose name,
 219     relative to the working directory, is given in the
 220     <link linkend="proxy-config-cql2rpn">cql2rpn</link> element.
 221     A complete Bath/DC conversion file,
 222     <filename>pqf.properties</filename> is provided as part of the
 223     yazproxy distribution in the <filename>etc</filename>
 224     subdirectory.
 225    </para>
 226    <para>
 227     Explain information is embedded in the configuration file.
 228     Note that in this example,only a few mandatory
 229     explain elements are specified. A well-behaving server should describe
 230     index sets, indexes, record schemas as well.
 231    </para>
 232   </example>
 233  </chapter>
 234
 235  <!-- Keep this comment at the end of the file
 236  Local variables:
 237  mode: sgml
 238  sgml-omittag:t
 239  sgml-shorttag:t
 240  sgml-minimize-attributes:nil
 241  sgml-always-quote-attributes:t
 242  sgml-indent-step:1
 243  sgml-indent-data:t
 244  sgml-parent-document: "yazproxy.xml"
 245  sgml-local-catalogs: nil
 246  sgml-namecase-general:t
 247  End:
 248  -->
 249