From c2f14867d5abde02ffe548fb0e269aa37756915f Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Mon, 21 Oct 2002 13:37:31 +0000 Subject: [PATCH] Actual documentation for proxy --- doc/proxy.xml | 220 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 214 insertions(+), 6 deletions(-) diff --git a/doc/proxy.xml b/doc/proxy.xml index d0250cd..d64d6cf 100644 --- a/doc/proxy.xml +++ b/doc/proxy.xml @@ -1,10 +1,218 @@ - + YAZ Proxy - - About YAZ Proxy. - - + + The YAZ proxy is a transparent Z39.50 to Z39.50 gateway. + It is useful for debugging Z39.50 software, redirect + Z39.50 packages through firewalls, etc. + + + Furthermore, the proxy offers facilities that often + boost performance for "connection-less" Z39.50 clients such + as web gateways. + + + Unlike most other "server" software the proxy runs single-threaded, + single-process. Every I/O operation + is non-blocking so it is light-weight and very fast. + It does not store "state" information on the hard drive + except the log files you want. + +
Specifying the backend target + + When a Z39.50 client session is accepted by the proxy, the proxy + determines the backend target by the following rules: + + + If the Initialize Request PDU from the client + includes OtherInformation, with OID, + 1.2.840.10003.10.1000.81.1, that + specifies the target. + + + + Otherwise, the Proxy uses the default target if given. + (option -t). + + + + Otherwise, the proxy closes the connection with + the client. + + + + +
+
Keep-alive facility for Stateless clients + + Stateless clients may generate a cookie for a Z39.50 + session which is sent to the proxy as part of PDUs. + In this case, the proxy will keep the Z39.50 session alive + to the backend target even the connection from the client + to the proxy is closed. When the client contacts the + proxy again it will re-issue the cookie and reuse the + Z39.50 connection with the backend target. Note that there is not + guarantee that the Z39.50 is kept forever to the backend + target, since the proxy will shut it down after certain + idle time. So in effect, the connection from the client's + point of view should be considered stateless. + + + As for the target specification, the OtherInformation + area is used to hold the cookie with OID + 1.2.840.10003.10.1000.81.2. + +
+ +
Query Caching + + Simple stateless clients often sends identical Z39.50 searches + in a relatively short period of time (full-list, next-page, + single full-record, etc). And for many targets, it's + much more expensive to produce a new result set than + reuse and existing one. + + + The proxy tries to solve that by storing the last query for each + backend target. So when an identical query is received that + is turned into Present Requests rather than new Search Requests. + + + This optimization should work for any Z39.50 client and/or + target. The target does not have to support named result sets. + + +
+ +
Other optimizations + + We've had some plans to support caching of result set records, + but this had not yet been implemented. + +
+
Proxy usage + + + + + yaz-proxy + 8 + + + yaz-proxy + Z39.50 proxy + + + + yaz-proxy + -a fname + -c num + -v level + -t target + -u auth + -o level + host:port + + + + DESCRIPTION + + The proxy is a daemon on its own and runs standalone (no + inetd support). The host:port specifies host address and + listening port respectively. Use @ + for ANY address. + + + OPTIONS + + -a fname + + APDU log. + + + -c num + + Specifies maximum number of connections to be cached. + + + -v level + + Debug level (like YAZ). + + + -t target + + Default target. + + + -t target + + Authentication info sent to the backend target. + Useful if you happen to have an internal target that does + require authentication or if the client software does not allow + you to set it. + + + -o level + + Sets level for optimization. Use zero to disable; non-zero + to enable. Handling for this is not fully implemented; + we will probably use a bitmask to enable/disable specific + features. + + + + + + EXAMPLES + + The following starts the proxy so that it listens on port + 9000. The default backend target is LOC. + + $ yaz-proxy -t z3950.loc.gov:7090 @:9000 + + The LOC target is sometimes very slow. You can connect to + it using yaz-client as follows: + +$ yaz-client localhost:9000/voyager +Connecting...Ok. +Sent initrequest. +Connection accepted by target. +ID : 34 +Name : Voyager LMS - Z39.50 Server +Version: 1.13 +Options: search present +Elapsed: 7.131197 +Z> f computer +Sent searchRequest. +Received SearchResponse. +Search was a success. +Number of hits: 10000 +records returned: 0 +Elapsed: 6.695174 +Z> f computer +Sent searchRequest. +Received SearchResponse. +Search was a success. +Number of hits: 10000 +records returned: 0 +Elapsed: 0.001417 + + In this test, the second search was more than 4000 times faster + than the first. + + + The YAZ client allows you to set the backend target in + the Initialize Request using option -p. To connect to + Index Data's target you could use: + + yaz-client -p indexdata.dk localhost:9000/gils + + + + +
+