2 <!-- $Id: proxy.xml,v 1.5 2002-10-22 21:21:54 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 boost
11 performance for stateless Z39.50 clients such as web gateways.
14 Unlike most other "server" software the proxy runs single-threaded,
15 single-process. Every I/O operation
16 is non-blocking so it is light-weight and very fast.
17 It does not store state information on the hard drive
18 except the log files you want.
20 <section id="proxy-target">
21 <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 id="proxy-keepalive">
47 <title>Keep-alive facility for Stateless clients</title>
49 Stateless clients may generate a cookie for a Z39.50
50 session which is sent to the proxy as part of PDUs.
51 In this case, the proxy will keep the Z39.50 session alive
52 to the backend target even the connection from the client
53 to the proxy is closed. When the client contacts the
54 proxy again it will re-issue the cookie and reuse the
55 Z39.50 connection with the backend target. Note that there is not
56 guarantee that the Z39.50 is kept forever to the backend
57 target, since the proxy will shut it down after certain
58 idle time. So in effect, the connection from the client's
59 point of view should be considered stateless.
62 As for the target specification, the Other-Information
63 area is used to hold the cookie with OID
64 <literal>1.2.840.10003.10.1000.81.2</literal>.
68 <section id="proxy-cache">
69 <title>Query Caching</title>
71 Simple stateless clients often sends identical Z39.50 searches
72 in a relatively short period of time (full-list, next-page,
73 single full-record, etc). And for many targets, it's
74 much more expensive to produce a new result set than
75 reuse and existing one.
78 The proxy tries to solve that by storing the last query for each
79 backend target. So when an identical query is received that
80 is turned into Present Requests rather than new Search Requests.
83 This optimization should work for any Z39.50 client and/or
84 target. The target does not have to support named result sets.
89 <section id="proxy-optimizations">
90 <title>Other optimizations</title>
92 We've had some plans to support caching of result set records,
93 but this had not yet been implemented.
97 <section id="proxy-usage">
98 <title>Proxy usage</title>
101 <refentry id="yaz-proxy">
103 <refentrytitle>yaz-proxy</refentrytitle>
104 <manvolnum>8</manvolnum>
107 <refname>yaz-proxy</refname>
108 <refpurpose>Z39.50 proxy</refpurpose>
112 <command>yaz-proxy</command>
113 <arg choice="opt">-a <replaceable>fname</replaceable></arg>
114 <arg choice="opt">-c <replaceable>num</replaceable></arg>
115 <arg choice="opt">-v <replaceable>level</replaceable></arg>
116 <arg choice="opt">-t <replaceable>target</replaceable></arg>
117 <arg choice="opt">-u <replaceable>auth</replaceable></arg>
118 <arg choice="opt">-o <replaceable>level</replaceable></arg>
119 <arg choice="req"><replaceable>host</replaceable>:<replaceable>port</replaceable></arg>
123 <refsect1><title>DESCRIPTION</title>
125 The proxy is a daemon on its own and runs stand-alone (no
126 inetd support). The host:port specifies host address and
127 listening port respectively. Use <literal>@</literal>
131 <refsect1><title>OPTIONS</title>
133 <varlistentry><term>-a <replaceable>fname</replaceable></term>
138 <varlistentry><term>-c <replaceable>num</replaceable></term>
140 Specifies maximum number of connections to be cached.
143 <varlistentry><term>-v <replaceable>level</replaceable></term>
145 Debug level (like YAZ).
148 <varlistentry><term>-t <replaceable>target</replaceable></term>
153 <varlistentry><term>-t <replaceable>target</replaceable></term>
155 Authentication info sent to the backend target.
156 Useful if you happen to have an internal target that does
157 require authentication or if the client software does not allow
161 <varlistentry><term>-o <replaceable>level</replaceable></term>
163 Sets level for optimization. Use zero to disable; non-zero
164 to enable. Handling for this is not fully implemented;
165 we will probably use a bit mask to enable/disable specific
172 <title>EXAMPLES</title>
174 The following starts the proxy so that it listens on port
175 9000. The default backend target is the LOC target.
177 $ yaz-proxy -t z3950.loc.gov:7090 @:9000
179 This target is sometimes very slow. You can connect to
180 it using yaz-client as follows:
182 $ yaz-client localhost:9000/voyager
185 Connection accepted by target.
187 Name : Voyager LMS - Z39.50 Server
189 Options: search present
193 Received SearchResponse.
194 Search was a success.
195 Number of hits: 10000
200 Received SearchResponse.
201 Search was a success.
202 Number of hits: 10000
206 In this test, the second search was more than 4000 times faster
210 The YAZ client allows you to set the backend target in
211 the Initialize Request using option -p. To connect to
212 Index Data's target through a proxy on localhost, port 9000,
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