X-Git-Url: http://git.indexdata.com/?p=yazproxy-moved-to-github.git;a=blobdiff_plain;f=doc%2Freference.xml;h=caebaf157e24a07a968eba7ad86cd3e0c6c7e5da;hp=fef3d7120f66909b4b14afa6114ff95f5cb20c0e;hb=c2102bf5035278bef1600520805f3dc0a44f9a91;hpb=a6a57677933b3cc8be9477c44ffa1c00ec6a76ca
diff --git a/doc/reference.xml b/doc/reference.xml
index fef3d71..caebaf1 100644
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -32,7 +32,7 @@
usual YAZ address format (typically
tcp:hostname:port)
as described in
- the Addresses section of the YAZ manual.
@@ -58,14 +58,13 @@
- If the proxy receives an SRW/SRU request, the following rules are used.
+ If the proxy receives an SRU request, the following rules are used.
If default target has Explain information with a
database that matches the path of the
- HTTP request of SRW/SRU that backend server is used for
- SRW/SRU operation.
-
+ HTTP request of SRU that backend server is used for SRU operation.
+
@@ -74,13 +73,6 @@
-
-
- We know it is stupid to only check for explain in default target.
- It means that it is only possible to offer one SRW/SRU server.
- We expect to improve that in the next version of the YAZ proxy.
-
- Keep-alive Facility
@@ -199,8 +191,8 @@
The config file is XML based. The YAZ proxy must be compiled
- with libxml2 and
- libXSLT support in
+ with libxml2 and
+ libXSLT support in
order for the config file facility to be enabled.
@@ -221,13 +213,13 @@
The proxy config file must have a root element called
proxy and scoped within namespace
- xmlns="http://indexdata.dk/yazproxy/schema/0.8/.
+ xmlns="http://indexdata.dk/yazproxy/schema/0.9/".
All information except an optional XML header must be stored
within the proxy element.
<?xml version="1.0"?>
- <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
+ <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.9/">
<!-- content here .. -->
</proxy>
@@ -245,16 +237,17 @@
equivalent to command line option -t.
-
- <?xml version="1.0"?>
- <proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
- <target name="server1" default="1">
- <!-- description of server1 .. -->
- </target>
- <target name="server2">
- <!-- description of server2 .. -->
- </target>
- </proxy>
+
+
+
+
+
+
+
+
+
+ ]]>
@@ -299,6 +292,16 @@
+
+ max-sockets
+
+ The element max-sockets is the child of element
+ target and specifies the maximum number of sockets
+ to use for the target for all sessions using it. In other words: maximum
+ number of Z39.50 session to the target.
+
+
+
keepaliveThe keepalive element holds information about
@@ -322,7 +325,7 @@
<keepalive>
<bandwidth>1048576</bandwidth>
- <retrieve>400</retrieve>
+ <pdu>400</pdu>
</keepalive>
@@ -335,32 +338,37 @@
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
+ retrieve and search.
+ 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 retrieved in one Present Request.
+ which may be retrieved in one Present Request.
+ The search is the maximum number of searches
+ within the last minute.
- If a bandwidth/pdu limit is reached the proxy will postpone the
+ If a bandwidth/pdu/search 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.
The following sets maximum number of bytes transferred per minute to
- 500Kbytes and maximum number of requests to 40.
+ 500Kbytes, maximum number of records retrievals to 40
+ and maximum number of searches to 20.
<limit>
<bandwidth>524288</bandwidth>
<retrieve>40</retrieve>
+ <search>20</search>
</limit>
- Typically the limits for keepalive are much higher than
- those for session minute average.
+ Typically the values in the keepalive section are mugh higher
+ than their equivalent limit counterparts (bandwidth, pdu).
@@ -415,7 +423,8 @@
syntax
The syntax element specifies accept or reject
- or a particular record syntax request from the client.
+ or a particular record syntax request from the client. It also
+ allows record conversion of XML records via XSLT.
The syntax has one required attribute:
@@ -434,23 +443,49 @@
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.
+ preferred record syntax USMARC/MARC21 or backendtype
+ (if given) against the backend target.
+ For the special case where backendtype is
+ opac the proxy will convert the OPAC
+ record to OPACXML.
+
+
+ When marcxml is used, yazproxy assumes
+ that records retrieved from the backend are encoded in the
+ MARC-8 character set.
+ This is correct for most MARC21 based systems, but not for
+ other MARC variants or UTF-8 based MARC21 systems.
+ The backendcharset attribute specifies
+ the character set of the MARC records to be converted.
+
+
+ If attribute backendtype is given, that holds the
+ record syntax to be transmitted to backend.
+
+
+ If attribute backendelementset is given, that holds
+ elementset to be transmitted to backend. If
+ backendelementset is omitted, the element
+ set from client is used, except if marcxml is used.
+ If no backendelementset is given and
+ marcxml is used, the elementset is omitted in
+ request to backend.
If attribute stylesheet is given, the proxy
will convert XML record from server via XSLT. It is important
that the content from server is XML. If used in conjunction with
- attribute marcxml the MARC to MARCXML conversion
- takes place before the XSLT conversion takes place.
+ attribute marcxml, the MARC to MARCXML/OPACXML
+ conversion takes place before the XSLT conversion takes place.
If attribute identifier is given that is the
- SRW/SRU record schema identifier for the resulting output record (after
+ SRU record schema identifier for the resulting output record (after
MARCXML and/or XSLT conversion).
If sub element title is given (as child element
- of syntax, then that is the official SRW/SRU
+ of syntax, then that is the official SRU
name of the resulting record schema.
@@ -491,7 +526,7 @@
explain
The explain element includes Explain information
- for SRW/SRU about the server in the target section. This
+ for SRU about the server in the target section. This
information must have a serverInfo element
with a database that this target must be available as (URL path).
For example,
@@ -506,7 +541,7 @@
]]>
- In the above case, the SRW/SRU service is available as
+ In the above case, the SRU service is available as
http://myhost.org:8000/mydatabase.
@@ -515,17 +550,20 @@
cql2rpn
- The CDATA of cql2rpn refers to CQL to a RPN conversion
- file - for the server in the target section. This element
- is required for SRW/SRU searches to operate against a Z39.50
- server that doesn't support CQL. Most Z39.50 servers only support
+ The content of the cql2rpn element specifies
+ the path from the working directory to a CQL-to-RPN conversion
+ file for the server in the target section. This element
+ is required for SRU searches to operate against Z39.50
+ servers that don't support CQL. Most Z39.50 servers only support
Type-1/RPN so this is usually required.
+
+
See YAZ documentation for more information about the
- CQL
- to PQF conversion. See also the
+ CQL to PQF conversion.
+ See also the
pqf.properties in the etc
(or prefix/share/yazproxy)
- directory of the YAZ proxy.
+ directory of the YAZ proxy distribution.
@@ -543,6 +581,67 @@
+
+ target-authentication
+
+ The element target-authentication specifies
+ fixed authentication information to be sent to the backend target.
+
+
+ This element takes a an attribute type which is
+ the authenticatin type to be used..
+
+
+ none
+
+
+ No authentication. There is no CDATA associated with this.
+
+
+
+
+ anonymous
+
+
+ Anonymous authentication. There is no CDATA associated with this.
+
+
+
+
+ open
+
+
+ Open authentication. The CDATA consists of the
+ open authentication string.
+
+
+
+
+ idPass
+
+
+ IdPass authentication. The CDATA consists of
+ three terms: user, group and password.
+
+
+
+
+
+
+
+ target-charset
+
+ The element target-charset specifies the
+ native character set that the target uses for queries.
+
+
+ If this is specified the proxy will act as a Z39.50 server
+ supporting character set negotiation. And in SRU mode
+ it will convert from UTF-8 (UNICODE) to this native character
+ set (if possible).
+
+
+
max-clients
@@ -561,8 +660,8 @@
- Using the
- bash shell, you can set the limit with
+ Using the bash shell, you can set
+ the limit with
ulimit -nno.
Use ulimit -a to display limits.
@@ -626,6 +725,13 @@
and the size of the APDU is logged.
+
+ client-ip
+
+ Log the client IP for each log entry. By default, the client IP
+ is only logged when a new session starts.
+
+
@@ -641,9 +747,77 @@
+
+
+ max-connect
+
+ The element max-connect is a child of element
+ proxy and specifies the maximum number
+ of connections to be initiated within the last minute (or
+ value of period-connect.
+
+
+ If the maximum number is reached the proxy will terminate the
+ just initiated session (connection terminated).
+
+
+
+
+ limit-connect
+
+ The element max-connect is a child of element
+ proxy and specifies the limit of number
+ of connections to be initiated within the last minute (or
+ value of period-connect.
+
+
+ If the maximum number is reached the proxy delays the first operation
+ in the session by one second.
+
+
+
+
+ period-connect
+
+ The element period-connect is a child of element
+ proxy and specifies period - in the number of seconds
+ that limit-connect and
+ max-connect
+ should measure connections.
+
+
+ If period-connect is omitted, 60 seconds is used.
+
+
+
+
+ docpath
+
+ The element docpath is a child of element
+ proxy and specifies an allowed HTTP path
+ for local file access. Using docpath the
+ proxy may return static file content.
+
+
+ The value of docpath both serves as a HTTP path prefix
+ and as a local file prefix.
+ If a value of etc is used only URLs with the
+ prefix /etc/ results in a local file access to the
+ directory etc within the working directory
+ of yazproxy.
+
+
+
+ Care has been taken to ensure that hostile URLs are rejected - including
+ strings such as .. and / (absolute
+ file system access).
+
+
+
+
- Proxy Usage (man page)
+ Proxy Manual Pages
&yaz-proxy-ref;
@@ -672,7 +846,7 @@
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.
+ categoryValue is set to 1.
The value proxy and cookie is stored in element
characterInfo of the information
choice.
@@ -688,13 +862,12 @@
@@ -704,6 +877,7 @@
+
@@ -714,6 +888,7 @@
+
@@ -721,20 +896,49 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -773,6 +977,11 @@
+
+
+
+
+
@@ -781,6 +990,7 @@
+
]]>