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:
</para>
- <screen>
+ <screen><![CDATA[
decode choice
initRequest {
referenceId OCTETSTRING(len=4) 69 6E 69 74
}
}
}
+]]>
</screen>
</section>
<para>
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
+ (if any) is re-used. To achieve this, Index Data defined a session
cookie which identifies the backend session.
</para>
<para>
<literal>-c</literal> followed by the filename of a config file.
</para>
<para>
- The config file is in XML format. The YAZ proxy must be compiled
- with <ulink url="http://www.xmlsoft.org/">libxml2</ulink> support in
+ The config file is in XML format. The YAZ proxy must be compiled
+ with <ulink url="http://www.xmlsoft.org/">libxml2</ulink> and
+ <ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> support in
order for the config file facility to be enabled.
</para>
<tip>
</para>
<screen>
<?xml version="1.0"?>
- <!-- $Id -->
<proxy>
<!-- content here .. -->
</proxy>
<title>Configuration: target</title>
<para>
The element <literal>target</literal> which may be repeated zero
- or more times with parent elemtn <literal>proxy</literal> contains
+ or more times with parent element <literal>proxy</literal> contains
information about each backend target.
The <literal>target</literal> element have two attributes:
<literal>name</literal> which holds the logical name of the backend
<para>
<screen>
<?xml version="1.0"?>
- <!-- $Id -->
<proxy>
<target name="server1" default="1">
<!-- description of server1 .. -->
<literal>bandwidth</literal> and <literal>pdu</literal>.
The <literal>bandwidth</literal> 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).
+ limit, it is shut down (and no longer kept alive).
The <literal>pdu</literal> is the maximum number of requests sent
- to the target. If a target session exceeds this amount it is
+ to the target. If a target session exceeds this limit, it is
shut down. The idea of these two limits is that avoid very long
- sessions that eat resources in a backend (that leaks!).
+ sessions that use resources in a backend (that leaks!).
+ </para>
+ <para>
+ The following sets maximum number of bytes transferred in a
+ target session to 1 MB and maxinum of requests to 400.
+ <screen>
+ <keepalive>
+ <bandwidth>1048576</bandwidth>
+ <retrieve>400</retrieve>
+ </keepalive>
+ </screen>
</para>
</section>
<section id="proxy-config-limit">
- <title>Configuration:limit</title>
+ <title>Configuration: limit</title>
<para>
The <literal>limit</literal> section specifies bandwidth/pdu requests
limits for an active session.
measures the number of bytes transferred within the last minute.
The <literal>pdu</literal> is the number of requests in the last
minute. The <literal>retrieve</literal> holds the maximum records to
- be retrived in one Present Request.
+ be retrieved in one Present Request.
</para>
<para>
If a bandwidth/pdu limit is reached the proxy will postpone the
limit is to ensure that clients that downloads hundreds or thousands of
records do not hurt other users.
</para>
+ <para>
+ The following sets maximum number of bytes transferred per minute to
+ 500Kbytes and maximum number of requests to 40.
+ <screen>
+ <limit>
+ <bandwidth>524288</bandwidth>
+ <retrieve>40</retrieve>
+ </limit>
+ </screen>
+ </para>
+ <note>
+ <para>
+ Typically the limits for keepalive are much higher than
+ those for session minute average.
+ </para>
+ </note>
</section>
<section id="proxy-config-attribute">
<para>
The <literal>attribute</literal> element specifies accept or reject
or a particular attribute type, value pair.
+ Well-behaving targets will reject unsupported attributes on their
+ own. This feature is useful for targets that do not gracefully
+ handle unsupported attributes.
</para>
<para>
- The <literal>attribute</literal> has two required attributes:
+ Attribute elements may be repeated. The proxy inspects the attribute
+ specifications in the order as specified in the configuration file.
+ When a given attribute specification matches a given attribute list
+ in a query, the proxy takes appropriate action (reject, accept).
+ </para>
+ <para>
+ If no attribute specifications matches the attribute list in a query,
+ it is accepted.
+ </para>
+ <para>
+ The <literal>attribute</literal> element has two required attributes:
<literal>type</literal> which is the Attribute Type-1 type, and
<literal>value</literal> which is the Attribute Type-1 value.
+ The special value/type <literal>*</literal> matches any attribute
+ type/value. A value may also be specified as a list with each
+ value separated by comma, a value may also be specified as a
+ list: low value - dash - high value.
</para>
<para>
If attribute <literal>error</literal> is given, that holds a
If attribute <literal>error</literal> is not given, the attribute
type, value is accepted and passed to the backend target.
</para>
+ <para>
+ A target that supports use attributes 1,4, 1000 through 1003 and
+ no other use attributes, could use the following rules:
+ <screen>
+ <attribute type="1" value="1,4,1000-1003">
+ <attribute type="1" value="*" error="114"/>
+ </screen>
+ </para>
</section>
<section id="proxy-config-syntax">
or a particular record syntax request from the client.
</para>
<para>
- The <literal>syntax</literal> has one equired attribute:
+ The <literal>syntax</literal> has one required attribute:
<literal>type</literal> which is the Preferred Record Syntax.
</para>
<para>
<literal>type</literal> should be XML. The proxy will use
preferred record syntax USMARC/MARC21 against the backend target.
</para>
- <para>To accept USMARC and offer MARCXML XML recors but reject
- all other requests the following configuaration could be used:
+ <para>To accept USMARC and offer MARCXML XML records but reject
+ all other requests the following configuration could be used:
<screen>
<proxy>
<target name="mytarget">
- <syntax type="usmarc"/>
- <syntax type="xml" marcxml="1"/>
- <syntax type="*" error="238"/>
+ <syntax type="usmarc"/>
+ <syntax type="xml" marcxml="1"/>
+ <syntax type="*" error="238"/>
</target>
</proxy>
</screen>
<literal>target</literal> and specifies the amount in seconds before
a target session is shut down.
</para>
+ <para>
+ This can also be specified on the command line by using option
+ <literal>-T</literal>. Refer to <xref linkend="proxy-usage"/>.
+ </para>
</section>
<section id="proxy-config-client-timeout">
The element <literal>client-timeout</literal> is the child of element
<literal>target</literal> and specifies the amount in seconds before
a client session is shut down.
+ </para>
+ <para>
+ This can also be specified on the command line by using option
+ <literal>-i</literal>. Refer to <xref linkend="proxy-usage"/>.
</para>
</section>
allowed connections to targets (all targets). If this limit
is reached the proxy will close the least recently used connection.
</para>
+ <para>
+ Note, that many Unix systems impose a system on the number of
+ open files allowed in a single process, typically in the
+ range 256 (Solaris) to 1024 (Linux).
+ The proxy uses 2 sockets per session + a few files
+ for logging. As a rule of thumb, ensure that 2*max-clients + 5
+ can be opened by the proxy process.
+ </para>
+ <tip>
+ <para>
+ Using the <ulink url="http://www.gnu.org/software/bash/bash.html">
+ bash</ulink> shell, you can set the limit with
+ <literal>ulimit -n</literal><replaceable>no</replaceable>.
+ Use <literal>ulimit -a</literal> to display limits.
+ </para>
+ </tip>
</section>
-
+
+ <section id="proxy-config-log">
+ <title>Configuration: log</title>
+ <para>
+ The element <literal>log</literal> is the child of element
+ <literal>proxy</literal> and specifies what to be logged by the
+ proxy.
+ </para>
+ <para>
+ Specify the log file with command-line option <literal>-l</literal>.
+ </para>
+ <para>
+ The text of the <literal>log</literal> element is a sequence of
+ options separated by white space. See the table below:
+ <table frame="top"><title>Logging options</title>
+ <tgroup cols="2">
+ <colspec colwidth="1*" colname="option"/>
+ <colspec colwidth="2*" colname="description"/>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>client-apdu</literal></entry>
+ <entry>
+ Log APDUs as reported by YAZ for the
+ communication between the client and the proxy.
+ This facility is equivalent to the APDU logging that
+ happens when using option <literal>-a</literal>, however
+ this tells the proxy to log in the same file as given
+ by <literal>-l</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>server-apdu</literal></entry>
+ <entry>
+ Log APDUs as reported by YAZ for the
+ communication between the proxy and the server (backend).
+ </entry>
+ </row>
+ <row>
+ <entry><literal>clients-requests</literal></entry>
+ <entry>
+ Log a brief description about requests transferred between
+ the client and the proxy. The name of the request and the size
+ of the APDU is logged.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>server-requests</literal></entry>
+ <entry>
+ Log a brief description about requests transferred between
+ the proxy and the server (backend). The name of the request
+ and the size of the APDU is logged.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ To log communication in details between the proxy and the backend, th
+ following configuration could be used:
+ <screen><![CDATA[
+ <target name="mytarget">
+ <log>server-apdu server-requests</log>
+ </target>
+]]>
+ </screen>
+ </para>
+ </section>
+
</section>
<section id="proxy-usage">
<title>Proxy Usage</title>
sgml-namecase-general:t
End:
-->
-
\ No newline at end of file
+
projects / yazpp-moved-to-github.git / blobdiff