2 <!-- $Id: proxy.xml,v 1.3 2002-10-22 08:23:57 adam Exp $ -->
3 <title>YAZ Proxy</title>
5 The YAZ proxy is a transparent Z39.50 to Z39.50 gateway.
6 It is useful for debugging Z39.50 software, redirect
7 Z39.50 packages through fire walls, etc.
10 Furthermore, the proxy 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 light-weight and very fast.
18 It does not store "state" information on the hard drive
19 except the log files you want.
21 <section><title>Specifying the backend target</title>
23 When a Z39.50 client session is accepted by the proxy, the proxy
24 determines the backend target by the following rules:
27 <para> If the Initialize Request PDU from the client
28 includes Other-Information, with OID,
29 <literal>1.2.840.10003.10.1000.81.1</literal>, that
34 <para> Otherwise, the Proxy uses the default target if given.
35 (option <literal>-t</literal>).
39 <para> Otherwise, the proxy closes the connection with
46 <section><title>Keep-alive facility for Stateless clients</title>
48 Stateless clients may generate a cookie for a Z39.50
49 session which is sent to the proxy as part of PDUs.
50 In this case, the proxy will keep the Z39.50 session alive
51 to the backend target even the connection from the client
52 to the proxy is closed. When the client contacts the
53 proxy again it will re-issue the cookie and reuse the
54 Z39.50 connection with the backend target. Note that there is not
55 guarantee that the Z39.50 is kept forever to the backend
56 target, since the proxy will shut it down after certain
57 idle time. So in effect, the connection from the client's
58 point of view should be considered stateless.
61 As for the target specification, the Other-Information
62 area is used to hold the cookie with OID
63 <literal>1.2.840.10003.10.1000.81.2</literal>.
67 <section><title>Query Caching</title>
69 Simple stateless clients often sends identical Z39.50 searches
70 in a relatively short period of time (full-list, next-page,
71 single full-record, etc). And for many targets, it's
72 much more expensive to produce a new result set than
73 reuse and existing one.
76 The proxy tries to solve that by storing the last query for each
77 backend target. So when an identical query is received that
78 is turned into Present Requests rather than new Search Requests.
81 This optimization should work for any Z39.50 client and/or
82 target. The target does not have to support named result sets.
87 <section><title>Other optimizations</title>
89 We've had some plans to support caching of result set records,
90 but this had not yet been implemented.
93 <section><title>Proxy usage</title>
96 <refentry id="yaz-proxy">
98 <refentrytitle>yaz-proxy</refentrytitle>
99 <manvolnum>8</manvolnum>
102 <refname>yaz-proxy</refname>
103 <refpurpose>Z39.50 proxy</refpurpose>
107 <command>yaz-proxy</command>
108 <arg choice="opt">-a <replaceable>fname</replaceable></arg>
109 <arg choice="opt">-c <replaceable>num</replaceable></arg>
110 <arg choice="opt">-v <replaceable>level</replaceable></arg>
111 <arg choice="opt">-t <replaceable>target</replaceable></arg>
112 <arg choice="opt">-u <replaceable>auth</replaceable></arg>
113 <arg choice="opt">-o <replaceable>level</replaceable></arg>
114 <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
118 <refsect1><title>DESCRIPTION</title>
120 The proxy is a daemon on its own and runs stand-alone (no
121 inetd support). The host:port specifies host address and
122 listening port respectively. Use <literal>@</literal>
126 <refsect1><title>OPTIONS</title>
128 <varlistentry><term>-a <replaceable>fname</replaceable></term>
133 <varlistentry><term>-c <replaceable>num</replaceable></term>
135 Specifies maximum number of connections to be cached.
138 <varlistentry><term>-v <replaceable>level</replaceable></term>
140 Debug level (like YAZ).
143 <varlistentry><term>-t <replaceable>target</replaceable></term>
148 <varlistentry><term>-t <replaceable>target</replaceable></term>
150 Authentication info sent to the backend target.
151 Useful if you happen to have an internal target that does
152 require authentication or if the client software does not allow
156 <varlistentry><term>-o <replaceable>level</replaceable></term>
158 Sets level for optimization. Use zero to disable; non-zero
159 to enable. Handling for this is not fully implemented;
160 we will probably use a bit mask to enable/disable specific
167 <title>EXAMPLES</title>
169 The following starts the proxy so that it listens on port
170 9000. The default backend target is LOC.
172 $ yaz-proxy -t z3950.loc.gov:7090 @:9000
174 The LOC target is sometimes very slow. You can connect to
175 it using yaz-client as follows:
177 $ yaz-client localhost:9000/voyager
180 Connection accepted by target.
182 Name : Voyager LMS - Z39.50 Server
184 Options: search present
188 Received SearchResponse.
189 Search was a success.
190 Number of hits: 10000
195 Received SearchResponse.
196 Search was a success.
197 Number of hits: 10000
201 In this test, the second search was more than 4000 times faster
205 The YAZ client allows you to set the backend target in
206 the Initialize Request using option -p. To connect to
207 Index Data's target you could use:
209 yaz-client -p indexdata.dk localhost:9000/gils
216 <!-- Keep this comment at the end of the file
221 sgml-minimize-attributes:nil
222 sgml-always-quote-attributes:t
225 sgml-parent-document: "yaz++.xml"
226 sgml-local-catalogs: nil
227 sgml-namecase-general:t