From a03eabd5ecf775dc8ba57186fc906b4b698772ed Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Tue, 22 Oct 2002 23:12:49 +0000 Subject: [PATCH] Finished, I think. Ready to release. --- doc/proxy.xml | 333 ++++++++++++++++++++++++++++++++++++++---------------- doc/yaz++.xml.in | 13 ++- 2 files changed, 246 insertions(+), 100 deletions(-) diff --git a/doc/proxy.xml b/doc/proxy.xml index efb9a1b..cf76fe6 100644 --- a/doc/proxy.xml +++ b/doc/proxy.xml @@ -1,38 +1,149 @@ - - YAZ Proxy + The 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 fire walls, etc. + The YAZ proxy is a transparent Z39.50-to-Z39.50 gateway. That is, + it is a Z39.50 server which has as its back-end a Z39.50 client + that forwards requests on to another server (known as the + backend target.) - Furthermore, the proxy offers facilities that often boost - performance for stateless Z39.50 clients such as web gateways. + The YAZ Proxy is useful for debugging Z39.50 software, logging + APDUs, redirecting Z39.50 packages through firewalls, etc. + Furthermore, it offers facilities that often + boost performance for connectionless Z39.50 clients such + as web gateways. - Unlike most other "server" software the proxy runs single-threaded, + 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. + is non-blocking so it is very lightweight and extremely fast. + It does not store any state information on the hard drive, + except any log files you ask for. + +
+ Example: Using the Proxy to Log APDUs + + Suppose you use a commercial Z39.50 client for which you do not + have source code, and it's not behaving how you think it should + when running against some specific server that you have no control + over. One way to diagnose the problem is to find out what packets + (APDUs) are being sent and received, but not all client + applications have facilities to do APDU logging. + + + No problem. Run the proxy on a friendly machine, get it to log + APDUs, and point the errant client at the proxy instead of + directly at the server that's causing it problems. + + + Suppose the server is running on foo.bar.com, + port 18398. Run the proxy on the machine of your choice, say + your.company.com like this: + + + yaz-proxy -a - -t tcp:foo.bar.com:18398 tcp:@:9000 + + + (The -a - option requests APDU logging on + standard output, -t tcp:foo.bar.com:18398 + specifies where the backend target is, and + tcp:@:9000 tells the proxy to listen on port + 9000 and accept connections from any machine.) + + + Now change your client application's configuration so that instead + of connecting to foo.bar.com port 18398, it + connects to your.company.com port 9000, and + start it up. It will work exactly as usual, but all the packets + will be sent via the proxy, which will generate a log like this: + + + decode choice + initRequest { + referenceId OCTETSTRING(len=4) 69 6E 69 74 + protocolVersion BITSTRING(len=1) + options BITSTRING(len=2) + preferredMessageSize 1048576 + maximumRecordSize 1048576 + implementationId 'Mike Taylor (id=169)' + implementationName 'Net::Z3950.pm (Perl)' + implementationVersion '0.31' + } + encode choice + initResponse { + referenceId OCTETSTRING(len=4) 69 6E 69 74 + protocolVersion BITSTRING(len=1) + options BITSTRING(len=2) + preferredMessageSize 1048576 + maximumRecordSize 1048576 + result TRUE + implementationId '81' + implementationName 'GFS/YAZ / Zebra Information Server' + implementationVersion 'YAZ 1.9.1 / Zebra 1.3.3' + } + decode choice + searchRequest { + referenceId OCTETSTRING(len=1) 30 + smallSetUpperBound 0 + largeSetLowerBound 1 + mediumSetPresentNumber 0 + replaceIndicator TRUE + resultSetName 'default' + databaseNames { + 'gils' + } + { + smallSetElementSetNames choice + generic 'F' + } + { + mediumSetElementSetNames choice + generic 'B' + } + preferredRecordSyntax OID: 1 2 840 10003 5 10 + { + query choice + type_1 { + attributeSetId OID: 1 2 840 10003 3 1 + RPNStructure choice + { + simple choice + attributesPlusTerm { + attributes { + } + term choice + general OCTETSTRING(len=7) 6D 69 6E 65 72 61 6C + } + } + } + } + } + +
+
- Specifying the backend target + Specifying the Backend Target - When a Z39.50 client session is accepted by the proxy, the proxy + When the proxy accepts a Z39.50 client session, it determines the backend target by the following rules: - If the Initialize Request PDU from the client - includes Other-Information, with OID - 1.2.840.10003.10.1000.81.1, that - specifies the target. + If the InitializeRequest PDU from the + client includes an otherInfo element with OID + 1.2.840.10003.10.1000.81.1, then the + contents of that element specify the target to be used, in the + usual YAZ address format (typically + tcp:hostname:port) + as described in + the Addresses section of the YAZ manual. - Otherwise, the Proxy uses the default target if given. - (option -t). + Otherwise, the Proxy uses the default target, if one was + specified on the command-line with the -t + option. @@ -44,58 +155,68 @@
- Keep-alive facility for Stateless clients + Keep-alive Facility for Stateless Clients - Stateless clients may generate a cookie for a Z39.50 + Stateless clients such as web gateways 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 + In this case, the proxy will keep alive its Z39.50 session + to the backend target even when 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. + proxy again, and re-issues the same cookie, the proxy reuses the + Z39.50 connection with the backend target. - As for the target specification, the Other-Information - area is used to hold the cookie with OID - 1.2.840.10003.10.1000.81.2. + There is no + guarantee that the Z39.50 connection to the backend + target is kept forever: 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, and the keep-alive + facility should be treated only as a performance booster. + + + Cookies may be passed in an otherInfo element + 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. + Simple stateless clients often send identical Z39.50 searches + in a relatively short period of time (e.g. in order to produce a + results-list page, the next page, + a single full-record, etc). And for many targets, it's + much more expensive to produce a new result set than to + reuse an 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 + The proxy tries to solve that by remembering the last query for each + backend target, so that if an identical query is received next, it 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 + Other Optimizations We've had some plans to support caching of result set records, - but this had not yet been implemented. + but this has not yet been implemented.
- Proxy usage + Proxy Usage @@ -105,12 +226,12 @@ yaz-proxy - Z39.50 proxy + The YAZ toolkit's transparent Z39.50 proxy yaz-proxy - -a fname + -a filename -c num -v level -t target @@ -122,39 +243,49 @@ DESCRIPTION - The proxy is a daemon on its own and runs stand-alone (no - inetd support). The host:port specifies host address and - listening port respectively. Use @ - for ANY address. + The proxy runs stand-alone (not from + inetd). The + host:port + argument specifies host address to listen to, and the port to + listen on. Use the host @ + to listen for connections coming from any address. OPTIONS - -a fname + -a filename - APDU log. + Specifies the name of a file to which to write a log of the + APDUs (protocol packets) that pass through the proxy. The + special filename - may be used to indicate + standard output. -c num - Specifies maximum number of connections to be cached. + Specifies the maximum number of connections to be cached + [default 50]. -v level - Debug level (like YAZ). + Sets the logging level. level is + a comma-separated list of members of the set + {fatal,debug,warn,log,malloc,all,none}. -t target - Default target. + Specifies the default backend target to use when a client + connects that does not explicitly specify a target in its + initRequest. - -t target + -u auth - 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 + Specifies authentication info to be sent to the backend target. + This is useful if you happen to have an internal target that + requires authentication, or if the client software does not allow you to set it. @@ -171,50 +302,58 @@ EXAMPLES - The following starts the proxy so that it listens on port - 9000. The default backend target is the LOC target. - - $ yaz-proxy -t z3950.loc.gov:7090 @:9000 - - This target is sometimes very slow. You can connect to + The following command starts the proxy, listening on port + 9000, with its default backend target set to the Library of + Congress bibliographic server: + + + $ 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 - + + + $ 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. + than the first, because the proxy cached the result of the first + search and noticed that the second was the same. - The YAZ client allows you to set the backend target in - the Initialize Request using option -p. To connect to - Index Data's target through a proxy on localhost, port 9000, - you could use: - - yaz-client -p indexdata.dk localhost:9000/gils - + The YAZ command-line client, + yaz-client, + allows you to set the backend target in + the initRequest using the + -p option. For example, to connect to + Index Data's target you could use: + + yaz-client -p indexdata.dk localhost:9000/gils +
diff --git a/doc/yaz++.xml.in b/doc/yaz++.xml.in index f135386..4b087c6 100644 --- a/doc/yaz++.xml.in +++ b/doc/yaz++.xml.in @@ -6,7 +6,7 @@ ]> - + YAZ++ @@ -17,8 +17,15 @@ Index Data Mike Taylor - - Short introduction. + + + YAZ++ is a set of libraries and header files that make it easier + to use the popular C-language + YAZ toolkit + from C++, together with some utilities written using these + libraries. It includes an implementation of the C++ binding for + ZOOM (ZOOM-C++) and a powerful, + general-purpose Z39.50 proxy. -- 1.7.10.4