X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fproxy.xml;h=d64d6cfe9ad23e136e43bfee7cf9f2b6742bad00;hb=faba80dab06ced169a5e16e24e2c3f43c867892f;hp=d0250cd467112b5797e35dccd394e118acc0ba62;hpb=2ad40f2e15a4d6927833231b8dc6874b747fed2e;p=yazpp-moved-to-github.git
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
+
+
+
+
+
+