2 <!-- $Id: proxy.xml,v 1.4 2002-10-22 14:04:17 mike 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 id="proxy-target">
22 <title>Specifying the backend target</title>
24 When a Z39.50 client session is accepted by the proxy, the proxy
25 determines the backend target by the following rules:
28 <para> If the Initialize Request PDU from the client
29 includes Other-Information, with OID,
30 <literal>1.2.840.10003.10.1000.81.1</literal>, that
35 <para> Otherwise, the Proxy uses the default target if given.
36 (option <literal>-t</literal>).
40 <para> Otherwise, the proxy closes the connection with
47 <section id="proxy-keepalive">
48 <title>Keep-alive facility for Stateless clients</title>
50 Stateless clients may generate a cookie for a Z39.50
51 session which is sent to the proxy as part of PDUs.
52 In this case, the proxy will keep the Z39.50 session alive
53 to the backend target even the connection from the client
54 to the proxy is closed. When the client contacts the
55 proxy again it will re-issue the cookie and reuse the
56 Z39.50 connection with the backend target. Note that there is not
57 guarantee that the Z39.50 is kept forever to the backend
58 target, since the proxy will shut it down after certain
59 idle time. So in effect, the connection from the client's
60 point of view should be considered stateless.
63 As for the target specification, the Other-Information
64 area is used to hold the cookie with OID
65 <literal>1.2.840.10003.10.1000.81.2</literal>.
69 <section id="proxy-cache">
70 <title>Query Caching</title>
72 Simple stateless clients often sends identical Z39.50 searches
73 in a relatively short period of time (full-list, next-page,
74 single full-record, etc). And for many targets, it's
75 much more expensive to produce a new result set than
76 reuse and existing one.
79 The proxy tries to solve that by storing the last query for each
80 backend target. So when an identical query is received that
81 is turned into Present Requests rather than new Search Requests.
84 This optimization should work for any Z39.50 client and/or
85 target. The target does not have to support named result sets.
90 <section id="proxy-optimizations">
91 <title>Other optimizations</title>
93 We've had some plans to support caching of result set records,
94 but this had not yet been implemented.
98 <section id="proxy-usage">
99 <title>Proxy usage</title>
102 <refentry id="yaz-proxy">
104 <refentrytitle>yaz-proxy</refentrytitle>
105 <manvolnum>8</manvolnum>
108 <refname>yaz-proxy</refname>
109 <refpurpose>Z39.50 proxy</refpurpose>
113 <command>yaz-proxy</command>
114 <arg choice="opt">-a <replaceable>fname</replaceable></arg>
115 <arg choice="opt">-c <replaceable>num</replaceable></arg>
116 <arg choice="opt">-v <replaceable>level</replaceable></arg>
117 <arg choice="opt">-t <replaceable>target</replaceable></arg>
118 <arg choice="opt">-u <replaceable>auth</replaceable></arg>
119 <arg choice="opt">-o <replaceable>level</replaceable></arg>
120 <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
124 <refsect1><title>DESCRIPTION</title>
126 The proxy is a daemon on its own and runs stand-alone (no
127 inetd support). The host:port specifies host address and
128 listening port respectively. Use <literal>@</literal>
132 <refsect1><title>OPTIONS</title>
134 <varlistentry><term>-a <replaceable>fname</replaceable></term>
139 <varlistentry><term>-c <replaceable>num</replaceable></term>
141 Specifies maximum number of connections to be cached.
144 <varlistentry><term>-v <replaceable>level</replaceable></term>
146 Debug level (like YAZ).
149 <varlistentry><term>-t <replaceable>target</replaceable></term>
154 <varlistentry><term>-t <replaceable>target</replaceable></term>
156 Authentication info sent to the backend target.
157 Useful if you happen to have an internal target that does
158 require authentication or if the client software does not allow
162 <varlistentry><term>-o <replaceable>level</replaceable></term>
164 Sets level for optimization. Use zero to disable; non-zero
165 to enable. Handling for this is not fully implemented;
166 we will probably use a bit mask to enable/disable specific
173 <title>EXAMPLES</title>
175 The following starts the proxy so that it listens on port
176 9000. The default backend target is LOC.
178 $ yaz-proxy -t z3950.loc.gov:7090 @:9000
180 The LOC target is sometimes very slow. You can connect to
181 it using yaz-client as follows:
183 $ yaz-client localhost:9000/voyager
186 Connection accepted by target.
188 Name : Voyager LMS - Z39.50 Server
190 Options: search present
194 Received SearchResponse.
195 Search was a success.
196 Number of hits: 10000
201 Received SearchResponse.
202 Search was a success.
203 Number of hits: 10000
207 In this test, the second search was more than 4000 times faster
211 The YAZ client allows you to set the backend target in
212 the Initialize Request using option -p. To connect to
213 Index Data's target you could use:
215 yaz-client -p indexdata.dk localhost:9000/gils
222 <!-- Keep this comment at the end of the file
227 sgml-minimize-attributes:nil
228 sgml-always-quote-attributes:t
231 sgml-parent-document: "yaz++.xml"
232 sgml-local-catalogs: nil
233 sgml-namecase-general:t