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    -- All config directives --
   9    -- SRW/SRU ..
  10    -- Example config
  11    -- Mention XSLT conversion
  12   </para>
  13   <para>
  14    The YAZ Proxy is useful for debugging SRW/SRU/Z39.50 software, logging
  15    APDUs, redirecting Z39.50 packages through firewalls, etc.
  16    Furthermore, it offers facilities that often
  17    boost performance for connectionless Z39.50 clients such
  18    as web gateways.
  19   </para>
  20   <para>
  21    Unlike most other server software, the proxy runs single-threaded,
  22    single-process. Every I/O operation
  23    is non-blocking so it is very lightweight and extremely fast.
  24    It does not store any state information on the hard drive,
  25    except any log files you ask for.
  26   </para>
  27
  28   <example id="example-apdu-logging">
  29    <title>Using the Proxy to Log APDUs</title>
  30    <para>
  31     Suppose you use a commercial Z39.50 client for which you do not
  32     have source code, and it's not behaving how you think it should
  33     when running against some specific server that you have no control
  34     over.  One way to diagnose the problem is to find out what packets
  35     (APDUs) are being sent and received, but not all client
  36     applications have facilities to do APDU logging.
  37    </para>
  38    <para>
  39     No problem.  Run the proxy on a friendly machine, get it to log
  40     APDUs, and point the errant client at the proxy instead of
  41     directly at the server that's causing it problems.
  42    </para>
  43    <para>
  44     Suppose the server is running on <literal>foo.bar.com</literal>,
  45     port 18398.  Run the proxy on the machine of your choice, say
  46     <literal>your.company.com</literal> like this:
  47    </para>
  48    <screen>
  49     yazproxy -a - -t tcp:foo.bar.com:18398 tcp:@:9000
  50    </screen>
  51    <para>
  52     (The <literal>-a -</literal> option requests APDU logging on
  53     standard output, <literal>-t tcp:foo.bar.com:18398</literal>
  54     specifies where the backend target is, and
  55     <literal>tcp:@:9000</literal> tells the proxy to listen on port
  56     9000 and accept connections from any machine.)
  57    </para>
  58    <para>
  59     Now change your client application's configuration so that instead
  60     of connecting to <literal>foo.bar.com</literal> port 18398, it
  61     connects to <literal>your.company.com</literal> port 9000, and
  62     start it up.  It will work exactly as usual, but all the packets
  63     will be sent via the proxy, which will generate a log like this:
  64    </para>
  65    <screen><![CDATA[
  66     decode choice
  67     initRequest {
  68         referenceId OCTETSTRING(len=4) 69 6E 69 74
  69         protocolVersion BITSTRING(len=1)
  70         options BITSTRING(len=2)
  71         preferredMessageSize 1048576
  72         maximumRecordSize 1048576
  73         implementationId 'Mike Taylor (id=169)'
  74         implementationName 'Net::Z3950.pm (Perl)'
  75         implementationVersion '0.31'
  76     }
  77     encode choice
  78     initResponse {
  79         referenceId OCTETSTRING(len=4) 69 6E 69 74
  80         protocolVersion BITSTRING(len=1)
  81         options BITSTRING(len=2)
  82         preferredMessageSize 1048576
  83         maximumRecordSize 1048576
  84         result TRUE
  85         implementationId '81'
  86         implementationName 'GFS/YAZ / Zebra Information Server'
  87         implementationVersion 'YAZ 1.9.1 / Zebra 1.3.3'
  88     }
  89     decode choice
  90     searchRequest {
  91         referenceId OCTETSTRING(len=1) 30
  92         smallSetUpperBound 0
  93         largeSetLowerBound 1
  94         mediumSetPresentNumber 0
  95         replaceIndicator TRUE
  96         resultSetName 'default'
  97         databaseNames {
  98             'gils'
  99         }
 100         {
 101             smallSetElementSetNames choice
 102             generic 'F'
 103         }
 104         {
 105             mediumSetElementSetNames choice
 106             generic 'B'
 107         }
 108         preferredRecordSyntax OID: 1 2 840 10003 5 10
 109         {
 110             query choice
 111             type_1 {
 112                 attributeSetId OID: 1 2 840 10003 3 1
 113                 RPNStructure choice
 114                 {
 115                     simple choice
 116                     attributesPlusTerm {
 117                         attributes {
 118                         }
 119                         term choice
 120                         general OCTETSTRING(len=7) 6D 69 6E 65 72 61 6C
 121                     }
 122                 }
 123             }
 124         }
 125     }
 126 ]]>
 127    </screen>
 128   </example>
 129
 130   <example id="example-firewall">
 131    <title>Exposing a Z39.50 server behind a firewall</title>
 132    <para>
 133     ..
 134    </para>
 135   </example>
 136
 137   <example id="example-srw-service">
 138    <title>Offering SRW/SRU/Z39.50 service</title>
 139    <para>
 140     ..
 141    </para>
 142   </example>
 143
 144  </chapter>
 145
 146  <!-- Keep this comment at the end of the file
 147  Local variables:
 148  mode: sgml
 149  sgml-omittag:t
 150  sgml-shorttag:t
 151  sgml-minimize-attributes:nil
 152  sgml-always-quote-attributes:t
 153  sgml-indent-step:1
 154  sgml-indent-data:t
 155  sgml-parent-document: "yazproxy.xml"
 156  sgml-local-catalogs: nil
 157  sgml-namecase-general:t
 158  End:
 159  -->
 160