2 <title>Using YAZ proxy</title>
4 As mentioned in the introduction the YAZ proxy has many uses.
5 This chapter includes a few examples.
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
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.
22 <example id="example-apdu-logging">
23 <title>Using the Proxy to Log APDUs</title>
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.
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.
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:
43 yazproxy -a - -t tcp:foo.bar.com:18398 tcp:@:9000
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.)
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:
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'
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
80 implementationName 'GFS/YAZ / Zebra Information Server'
81 implementationVersion 'YAZ 1.9.1 / Zebra 1.3.3'
85 referenceId OCTETSTRING(len=1) 30
88 mediumSetPresentNumber 0
90 resultSetName 'default'
95 smallSetElementSetNames choice
99 mediumSetElementSetNames choice
102 preferredRecordSyntax OID: 1 2 840 10003 5 10
106 attributeSetId OID: 1 2 840 10003 3 1
114 general OCTETSTRING(len=7) 6D 69 6E 65 72 61 6C
124 <example id="first-config">
125 <title>Using a configuration file</title>
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:
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>
144 The proxy is started with
146 yazproxy -c config.xml @:9000
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.
157 <example id="example-srw-service">
158 <title>Offering SRW/SRU/Z39.50 service</title>
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.
168 We must also ensure that the
169 server can return at least one kind of XML record (Dublin-Core
173 An explain record for the SRW/SRU service must also be created.
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>.
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.
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" >
203 <syntax type="*" error="238"/>
205 <explain xmlns="http://explain.z3950.org/dtd/2.0/">
207 <host>indexdata.dk</host>
209 <database>gils</database>
212 <cql2rpn>pqf.properties</cql2rpn>
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>
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.
235 <!-- Keep this comment at the end of the file
240 sgml-minimize-attributes:nil
241 sgml-always-quote-attributes:t
244 sgml-parent-document: "yazproxy.xml"
245 sgml-local-catalogs: nil
246 sgml-namecase-general:t