X-Git-Url: http://git.indexdata.com/?p=yazpp-moved-to-github.git;a=blobdiff_plain;f=doc%2Fproxy.xml;h=9d04a650f4a208b1a509da61f4c6732cc21a356c;hp=d64d6cfe9ad23e136e43bfee7cf9f2b6742bad00;hb=5554ddf9c4d9670aaaa8f8b9ce6def1dadff3c96;hpb=c2f14867d5abde02ffe548fb0e269aa37756915f diff --git a/doc/proxy.xml b/doc/proxy.xml index d64d6cf..9d04a65 100644 --- a/doc/proxy.xml +++ b/doc/proxy.xml @@ -1,38 +1,151 @@ - - 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 firewalls, 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 "connection-less" Z39.50 clients such + 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. -
Specifying the backend target + +
+ 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. + - When a Z39.50 client session is accepted by the proxy, the proxy + 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 + + 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 OtherInformation, 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. @@ -43,175 +156,129 @@
-
Keep-alive facility for Stateless clients +
+ Keep-alive Facility + + The keep-alive is a facility where the proxy keeps the connection to the + backend - even if the client closes the connection to the proxy. + + + If a new or another client connects to the proxy again and requests the + same backend it will be reassigned to this backend. In this case, the + proxy sends an initialize response directly to the client and an + initialize handshake with the backend is omitted. + + + When a client reconnects, query and record caching works better, if the + proxy assigns it to the same backend as before. And the result set + (if any) is re-used. To achive this, Index Data defined a session + cookie which identifies the backend session. + - 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. + The cookie is defined by the client and is sent as part of the + Initialize Request and passed in an + otherInfo + element with OID 1.2.840.10003.10.1000.81.2. - As for the target specification, the OtherInformation - area is used to hold the cookie with OID - 1.2.840.10003.10.1000.81.2. + Clients that do not send a cookie as part of the initialize request + may still better performance, since the init handshake is saved.
-
Query Caching +
+ 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. + + + In a future we release will will probably allows for + an arbitrary-sized cache for targets supporting named result sets. + + - This optimization should work for any Z39.50 client and/or - target. The target does not have to support named result sets. + You can enable/disable query caching using option -o. +
+ +
+ Record Caching + + As an option, the proxy may also cache result set records for the + last search. + The proxy takes into account the Record Syntax and CompSpec. + The CompSpec includes simple element set names as well. +
-
Other optimizations - - We've had some plans to support caching of result set records, - but this had not yet been implemented. +
+ Query Validation + + +
+ +
+ Record Syntax Validation + + +
+ +
+ Other Optimizations + + We've had some plans to support global caching of result set records, + but this has not yet been implemented.
-
Proxy usage + +
+ 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 - - - + &yaz-proxy-ref;
+
OtherInformation Encoding + + The proxy uses the OtherInformation definition to carry + information about the target address and cookie. + + + OtherInformation ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{ + category [1] IMPLICIT InfoCategory OPTIONAL, + information CHOICE{ + characterInfo [2] IMPLICIT InternationalString, + binaryInfo [3] IMPLICIT OCTET STRING, + externallyDefinedInfo [4] IMPLICIT EXTERNAL, + oid [5] IMPLICIT OBJECT IDENTIFIER}} +-- + InfoCategory ::= SEQUENCE{ + categoryTypeId [1] IMPLICIT OBJECT IDENTIFIER OPTIONAL, + categoryValue [2] IMPLICIT INTEGER} + + + The categoryTypeId is either + OID 1.2.840.10003.10.1000.81.1, 1.2.840.10003.10.1000.81.2 + for proxy target and proxy cookie respectively. The + integer element category is set to 0. + The value proxy and cookie is stored in element + characterInfo of the information + choice. + +