Use AM_LDFLAGS instead of LDFLAGS

[yazpp-moved-to-github.git] / doc / proxy.xml

diff --git a/doc/proxy.xml b/doc/proxy.xml
index 2e26476..5562454 100644 (file)
--- a/doc/proxy.xml
+++ b/doc/proxy.xml
@@ -58,7 +58,7 @@
     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>
     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
     decode choice
     initRequest {
         referenceId OCTETSTRING(len=4) 69 6E 69 74

@@ -119,6 +119,7 @@
             }
         }
     }
             }
         }
     }

+]]>

    </screen>
   </section>
   
    </screen>
   </section>
   

@@ -172,7 +173,7 @@
    <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
    <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>
     cookie which identifies the backend session.
    </para>
    <para>

@@ -267,8 +268,9 @@
     <literal>-c</literal> followed by the filename of a config file.
     </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>
     order for the config file facility to be enabled.
    </para>
    <tip>

@@ -289,7 +291,6 @@
     </para>
     <screen>
      &lt;?xml version="1.0"?>
     </para>
     <screen>
      &lt;?xml version="1.0"?>

-     &lt;!-- $Id -->

      &lt;proxy>
       &lt;!-- content here .. -->
      &lt;/proxy>
      &lt;proxy>
       &lt;!-- content here .. -->
      &lt;/proxy>

@@ -299,7 +300,7 @@
     <title>Configuration: target</title>
     <para>
      The element <literal>target</literal> which may be repeated zero
     <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
      information about each backend target.
      The <literal>target</literal> element have two attributes:
      <literal>name</literal> which holds the logical name of the backend

@@ -310,7 +311,6 @@
     <para>
      <screen>
      &lt;?xml version="1.0"?>
     <para>
      <screen>
      &lt;?xml version="1.0"?>

-     &lt;!-- $Id -->

      &lt;proxy>
       &lt;target name="server1" default="1">
        &lt;!-- description of server1 .. -->
      &lt;proxy>
       &lt;target name="server1" default="1">
        &lt;!-- description of server1 .. -->

@@ -347,15 +347,25 @@
      <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
      <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
      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
      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>
+      &lt;keepalive>
+       &lt;bandwidth>1048576&lt;/bandwidth>
+       &lt;retrieve>400&lt;/retrieve>
+      &lt;/keepalive>
+     </screen>

     </para>
    </section>
    <section id="proxy-config-limit">
     </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.
     <para>
      The <literal>limit</literal> section specifies bandwidth/pdu requests
      limits for an active session.

@@ -366,7 +376,7 @@
      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
      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
     </para>
     <para>
      If a bandwidth/pdu limit is reached the proxy will postpone the

@@ -374,6 +384,22 @@
      limit is to ensure that clients that downloads hundreds or thousands of
      records do not hurt other users.
     </para>
      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>
+      &lt;limit>
+       &lt;bandwidth>524288&lt;/bandwidth>
+       &lt;retrieve>40&lt;/retrieve>
+      &lt;/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">
    </section>
    
    <section id="proxy-config-attribute">

@@ -381,11 +407,28 @@
     <para>
      The <literal>attribute</literal> element specifies accept or reject
      or a particular attribute type, value pair.
     <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>
     </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.
      <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 
     </para>
     <para>
      If attribute <literal>error</literal> is given, that holds a 

@@ -396,6 +439,14 @@
      If attribute <literal>error</literal> is not given, the attribute
      type, value is accepted and passed to the backend target.
     </para>
      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>
+      &lt;attribute type="1" value="1,4,1000-1003">
+      &lt;attribute type="1" value="*" error="114"/>
+     </screen>
+    </para>

    </section>
 
    <section id="proxy-config-syntax">
    </section>
 
    <section id="proxy-config-syntax">

@@ -405,7 +456,7 @@
      or a particular record syntax request from the client.
     </para>
     <para>
      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> which is the Preferred Record Syntax.
     </para>
     <para>

@@ -423,14 +474,14 @@
      <literal>type</literal> should be XML. The proxy will use
      preferred record syntax USMARC/MARC21 against the backend target.
     </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>
       &lt;proxy>
        &lt;target name="mytarget">
      <screen>
       &lt;proxy>
        &lt;target name="mytarget">

-       &lt;syntax type="usmarc"/>
-       &lt;syntax type="xml" marcxml="1"/>
-       &lt;syntax type="*" error="238"/>
+        &lt;syntax type="usmarc"/>
+        &lt;syntax type="xml" marcxml="1"/>
+        &lt;syntax type="*" error="238"/>

        &lt;/target>
       &lt;/proxy>
      </screen>
        &lt;/target>
       &lt;/proxy>
      </screen>

@@ -444,6 +495,10 @@
      <literal>target</literal> and specifies the amount in seconds before
      a target session is shut down.
     </para>
      <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">
    </section>
 
    <section id="proxy-config-client-timeout">

@@ -452,6 +507,10 @@
      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.
      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>
    
     </para>
    </section>
    

@@ -477,8 +536,98 @@
      allowed connections to targets (all targets). If this limit
      is reached the proxy will close the least recently used connection.
     </para>
      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>

-   
+
+   <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>
   </section>
   <section id="proxy-usage">
    <title>Proxy Usage</title>

@@ -531,4 +680,4 @@
  sgml-namecase-general:t
  End:
  -->
  sgml-namecase-general:t
  End:
  -->

- 
\ No newline at end of file
+