From a0954355a5d3cc8685283d2102dec4b6d4284eab Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Mon, 13 Oct 2003 20:31:12 +0000 Subject: [PATCH] More about proxy config.xml --- doc/proxy.xml | 294 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 266 insertions(+), 28 deletions(-) diff --git a/doc/proxy.xml b/doc/proxy.xml index 4ba22ec..2e26476 100644 --- a/doc/proxy.xml +++ b/doc/proxy.xml @@ -121,7 +121,7 @@ } - +
Specifying the Backend Target @@ -145,7 +145,8 @@ Otherwise, the Proxy uses the default target, if one was specified on the command-line with the -t - option. + option. A default target can also be specified in the + XML Config file. @@ -159,33 +160,33 @@
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. + 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. + 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. + 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. - The cookie is defined by the client and is sent as part of the - Initialize Request and passed in an + 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. + element 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. + 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 @@ -219,18 +220,35 @@ last search. The proxy takes into account the Record Syntax and CompSpec. The CompSpec includes simple element set names as well. + By default the cache is 200000 bytes per session.
- +
Query Validation + The Proxy may also be configured to trap particular attributes in + Type-1 queries and send Bib-1 diagnostics back to the client without + even consulting the backend target. This facility may be useful if + a target does not properly issue diagnostics when unsupported attributes + are send to it.
Record Syntax Validation + The proxy may be configured to accept, reject or convert records. + When accepted, the target passes search/present requests to the + backend target under the assumption that the target can honor the + request (In fact it may not do that). When a record is rejected because + the record syntax is "unsupported" the proxy returns a diagnostic to the + client. Finally, the proxy may convert records. + + + In the current version the only supported conversion is + MARC21/USMARC in MARC-8 charset to MARCXML in UTF-8. Future version of + the proxy may do other record/charset conversions.
@@ -242,6 +260,226 @@
+
+ Proxy Configuration File + + The Proxy as an option may read a configuration file using option + -c followed by the filename of a config file. + + + The config file is in XML format. The YAZ proxy must be compiled + with libxml2 support in + order for the config file facility to be enabled. + + + To check for a config file to be well-formed, the yaz-proxy may + be invoked without specifying a listening port, i.e. + + yaz-proxy -c myconfig.xml + + If this does not produce errors, the file is well-formed. + + +
+ Proxy Configuration Header + + The proxy config file must have a root element called + proxy. All information except an optional XML + header must be stored within the proxy element. + + + <?xml version="1.0"?> + <!-- $Id --> + <proxy> + <!-- content here .. --> + </proxy> + +
+
+ Configuration: target + + The element target which may be repeated zero + or more times with parent elemtn proxy contains + information about each backend target. + The target element have two attributes: + name which holds the logical name of the backend + target (required) and default (optional) which + (when given) specifies that the backend target is the default target - + equivalent to command line option -t. + + + + <?xml version="1.0"?> + <!-- $Id --> + <proxy> + <target name="server1" default="1"> + <!-- description of server1 .. --> + </target> + <target name="server2"> + <!-- description of server2 .. --> + </target> + </proxy> + + +
+
+ Configuration:url + + The url which may be repeated one or more times + should be the child of the target element. + The CDATA of url is the Z-URL of the backend. + + + Multiple url element may be used. In that case, then + a client initiates a session, the proxy chooses the URL with the lowest + number of active sessions, thereby distributing the load. It is + assumed that each URL represents the same database (data). + +
+
+ Configuration: keepalive + The keepalive element holds information about + the keepalive Z39.50 sessions. Keepalive sessions are proxy-to-backend + sessions that is no longer associated with a client session. + + The keepalive element which is the child of + the targetholds two elements: + bandwidth and pdu. + The bandwidth is the maximum total bytes + transferred to/from the target. If a target session exceeds this + amount it is shut down (and no longer kept alive). + The pdu is the maximum number of requests sent + to the target. If a target session exceeds this amount it is + shut down. The idea of these two limits is that avoid very long + sessions that eat resources in a backend (that leaks!). + +
+
+ Configuration:limit + + The limit section specifies bandwidth/pdu requests + limits for an active session. + The proxy records bandwidth/pdu requests during the last 60 seconds + (1 minute). The limit may include the + elements bandwidth, pdu, + and retrieve. The bandwidth + measures the number of bytes transferred within the last minute. + The pdu is the number of requests in the last + minute. The retrieve holds the maximum records to + be retrived in one Present Request. + + + If a bandwidth/pdu limit is reached the proxy will postpone the + requests to the target and wait one or more seconds. The idea of the + limit is to ensure that clients that downloads hundreds or thousands of + records do not hurt other users. + +
+ +
+ Configuration: attribute + + The attribute element specifies accept or reject + or a particular attribute type, value pair. + + + The attribute has two required attributes: + type which is the Attribute Type-1 type, and + value which is the Attribute Type-1 value. + + + If attribute error is given, that holds a + Bib-1 diagnostic which is sent to the client if the particular + type, value is part of a query. + + + If attribute error is not given, the attribute + type, value is accepted and passed to the backend target. + +
+ +
+ Configuration: syntax + + The syntax element specifies accept or reject + or a particular record syntax request from the client. + + + The syntax has one equired attribute: + type which is the Preferred Record Syntax. + + + If attribute error is given, that holds a + Bib-1 diagnostic which is sent to the client if the particular + record syntax is part of a present - or search request. + + + If attribute error is not given, the record syntax + is accepted and passed to the backend target. + + + If attribute marcxml is given, the proxy will + perform MARC21 to MARCXML conversion. In this case the + type should be XML. The proxy will use + preferred record syntax USMARC/MARC21 against the backend target. + + To accept USMARC and offer MARCXML XML recors but reject + all other requests the following configuaration could be used: + + <proxy> + <target name="mytarget"> + <syntax type="usmarc"/> + <syntax type="xml" marcxml="1"/> + <syntax type="*" error="238"/> + </target> + </proxy> + + +
+ +
+ Configuration: target-timeout + + The element target-timeout is the child of element + target and specifies the amount in seconds before + a target session is shut down. + +
+ +
+ Configuration: client-timeout + + The element client-timeout is the child of element + target and specifies the amount in seconds before + a client session is shut down. + +
+ +
+ Configuration: preinit + + The element preinit is the child of element + target and specifies the number of spare + connection to a target. By default no spare connection are + created by the proxy. If the proxy uses a target exclusive or + a lot, the preinit session will ensure that target sessions + have been made before the client makes a connection and will therefore + reduce the connect-init handshake dramatically. Never set this to + more than 5. + +
+ +
+ Configuration: max-clients + + The element max-clients is the child of element + proxy and specifies the total number of + allowed connections to targets (all targets). If this limit + is reached the proxy will close the least recently used connection. + +
+ +
Proxy Usage @@ -269,15 +507,15 @@ 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. - -
+ 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. + +