doc/reference.xml

   1  <chapter id="proxy-reference">
   2   <title>Proxy Reference</title>
   3   <section id="proxy-operation">
   4    <title>Operating Environment</title>
   5    <para>
   6     The YAZ proxy is a console program. After startup it spawns
   7     a child process (except on Windows or if option -X is given).
   8     The child process is the core of the proxy and it handles all
   9     communication with clients and servers. The parent process
  10     will restart the child process if it dies unexpectedly and report
  11     the reason. For options for YAZ proxy,
  12     see <xref linkend="proxy-usage"/>.
  13    </para>
  14    <para>
  15     As an option, the proxy may change user identity to a less privileged
  16     user.
  17    </para>
  18   </section>
  19   <section id="proxy-target">
  20    <title>Choosing the Backend Server</title>
  21    <para>
  22     When the proxy receives a Z39.50 Initialize Request from a Z39.50
  23     client, it determines the backend server by the following rules:
  24     <orderedlist>
  25      <listitem>
  26       <para>If the <literal>InitializeRequest</literal> PDU from the
  27        client includes an
  28        <link linkend="otherinfo-encoding"><literal>otherInfo</literal></link>
  29        element with OID
  30        <literal>1.2.840.10003.10.1000.81.1</literal>, then the
  31        contents of that element specify the server to be used, in the
  32        usual YAZ address format (typically
  33        <literal>tcp:<parameter>hostname</parameter>:<parameter>port</parameter></literal>)
  34        as described in
  35        <ulink url="http://www.indexdata.dk/yaz/doc/comstack.addresses.tkl"
  36         >the Addresses section of the YAZ manual</ulink>.
  37       </para>
  38      </listitem>
  39
  40      <listitem>
  41       <para>Otherwise, the Proxy uses the default server, if one was
  42        specified in the proxy configuration file. See
  43        <xref linkend="proxy-config-target"/>.
  44       </para>
  45      </listitem>
  46
  47      <listitem>
  48       <para>Otherwise, the Proxy uses the default server, if one was
  49        specified on the command-line with the <literal>-t</literal>
  50        option.
  51       </para>
  52      </listitem>
  53      <listitem>
  54       <para>Otherwise, the proxy closes the connection with
  55        the client.
  56       </para>
  57      </listitem>
  58     </orderedlist>
  59    </para>
  60    <para>
  61     If the proxy receives an SRW/SRU request, the following rules are used.
  62     <orderedlist>
  63      <listitem>
  64       <para>If default target has Explain information with a
  65        <literal>database</literal> that matches the path of the
  66         HTTP request of SRW/SRU that backend server is used for
  67        SRW/SRU operation.
  68        </para>
  69      </listitem>
  70      <listitem>
  71       <para>
  72        Otherwise the service will return HTTP 404 (Not found).
  73       </para>
  74      </listitem>
  75     </orderedlist>
  76    </para>
  77    <note>
  78     <para>
  79      We know it is stupid to only check for explain in default target.
  80      It means that it is only possible to offer one SRW/SRU server.
  81      We expect to improve that in the next version of the YAZ proxy.
  82     </para>
  83    </note>
  84   </section>
  85   <section id="proxy-keepalive">
  86    <title>Keep-alive Facility</title>
  87    <para>
  88     The keep-alive is a facility where the proxy keeps the connection to the
  89     backend server - even if the client closes the connection to the proxy.
  90    </para>
  91    <para>
  92     If a new or another client connects to the proxy again and requests the
  93     same backend it will be reassigned to this backend. In this case, the
  94     proxy sends an initialize response directly to the client and an
  95     initialize handshake with the backend is omitted.
  96    </para>
  97    <para>
  98     When a client reconnects, query and record caching works better, if the
  99     proxy assigns it to the same backend as before. And the result set
 100     (if any) is re-used. To achieve this, Index Data defined a session
 101     cookie which identifies the backend session.
 102    </para>
 103    <para>
 104     The cookie is defined by the client and is sent as part of the
 105     Initialize Request and passed in an
 106     <link linkend="otherinfo-encoding"><literal>otherInfo</literal></link>
 107     element with OID <literal>1.2.840.10003.10.1000.81.2</literal>.
 108    </para>
 109    <para>
 110     Clients that do not send a cookie as part of the initialize request
 111     may still better performance, since the init handshake is saved.
 112    </para>
 113    <para>
 114     Refer to <xref linkend="proxy-config-keepalive"/> on how to setup
 115     configuration parameters for keepalive.
 116     </para>
 117   </section>
 118
 119
 120   <section id="query-cache">
 121    <title>Query Caching</title>
 122    <para>
 123     Simple stateless clients often send identical Z39.50 searches
 124     in a relatively short period of time (e.g. in order to produce a
 125     results-list page, the next page,
 126     a single full-record, etc). And for many targets, it's
 127     much more expensive to produce a new result set than to
 128     reuse an existing one.
 129    </para>
 130    <para>
 131     The proxy tries to solve that by remembering the last query for each
 132     backend target, so that if an identical query is received next, it
 133     is turned into Present Requests rather than new Search Requests.
 134    </para>
 135    <note>
 136     <para>
 137      In a future we release will will probably allows for
 138      an arbitrary-sized cache for targets supporting named result sets.
 139     </para>
 140    </note>
 141    <para>
 142     You can enable/disable query caching using option -o.
 143    </para>
 144   </section>
 145
 146   <section id="record-cache">
 147    <title>Record Caching</title>
 148    <para>
 149     As an option, the proxy may also cache result set records for the
 150     last search.
 151     The proxy takes into account the Record Syntax and CompSpec.
 152     The CompSpec includes simple element set names as well.
 153     By default the cache is 200000 bytes per session.
 154    </para>
 155   </section>
 156
 157   <section id="query-validation">
 158    <title>Query Validation</title>
 159    <para>
 160     The Proxy may also be configured to trap particular attributes in
 161     Type-1 queries and send Bib-1 diagnostics back to the client without
 162     even consulting the backend target. This facility may be useful if
 163     a target does not properly issue diagnostics when unsupported attributes
 164     are send to it.
 165    </para>
 166   </section>
 167
 168    <section id="record-validation">
 169    <title>Record Syntax Validation</title>
 170    <para>
 171     The proxy may be configured to accept, reject or convert records.
 172     When accepted, the target passes search/present requests to the
 173     backend target under the assumption that the target can honor the
 174     request (In fact it may not do that). When a record is rejected because
 175     the record syntax is "unsupported" the proxy returns a diagnostic to the
 176     client. Finally, the proxy may convert records.
 177    </para>
 178    <para>
 179     The proxy can convert from MARC to MARCXML and thereby offer an
 180     XML version of any MARC record as long as it is ISO2709 encoded.
 181     If the proxy is compiled with libXSLT support it can also
 182     perform XSLT on XML.
 183    </para>
 184   </section>
 185
 186   <section id="other-optimizations">
 187    <title>Other Optimizations</title>
 188    <para>
 189     We've had some plans to support global caching of result set records,
 190     but this has not yet been implemented.
 191    </para>
 192   </section>
 193
 194   <section id="proxy-config-file">
 195    <title>Proxy Configuration File</title>
 196    <para>
 197     The Proxy may read a configuration file using option
 198     <literal>-c</literal> followed by the filename of a config file.
 199    </para>
 200    <para>
 201     The config file is XML based. The YAZ proxy must be compiled
 202     with <ulink url="http://www.xmlsoft.org/">libxml2</ulink> and
 203     <ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> support in
 204     order for the config file facility to be enabled.
 205    </para>
 206    <para>
 207     See <xref linkend="yazproxy-schema"/> for an XML schema
 208     for the configuration.
 209    </para>
 210    <tip>
 211     <para>To check for a config file to be well-formed, the yazproxy may
 212      be invoked without specifying a listening port, i.e.
 213      <screen>
 214       yazproxy -c myconfig.xml
 215      </screen>
 216      If this does not produce errors, the file is well-formed.
 217     </para>
 218    </tip>
 219    <section id="proxy-config-header">
 220     <title>Proxy Configuration Header</title>
 221     <para>
 222      The proxy config file must have a root element called
 223      <literal>proxy</literal> and scoped within namespace
 224      <literal> xmlns="http://indexdata.dk/yazproxy/schema/0.8/</literal>.
 225      All information except an optional XML header must be stored
 226      within the <literal>proxy</literal> element.
 227     </para>
 228     <screen>
 229      &lt;?xml version="1.0"?>
 230      &lt;proxy xmlns="http://indexdata.dk/yazproxy/schema/0.8/">
 231       &lt;!-- content here .. -->
 232      &lt;/proxy>
 233     </screen>
 234    </section>
 235    <section id="proxy-config-target">
 236     <title>target</title>
 237     <para>
 238      The element <literal>target</literal> which may be repeated zero
 239      or more times with parent element <literal>proxy</literal> contains
 240      information about each backend target.
 241      The <literal>target</literal> element have two attributes:
 242      <literal>name</literal> which holds the logical name of the backend
 243      target (required) and <literal>default</literal> (optional) which
 244      (when given) specifies that the backend target is the default target -
 245      equivalent to command line option <literal>-t</literal>.
 246     </para>
 247     <para>
 248      <screen>
 249      &lt;?xml version="1.0"?>
 250      &lt;proxy xmlns="http://indexdata.dk/yazproxy/schema/0.9/">
 251       &lt;target name="server1" default="1">
 252        &lt;!-- description of server1 .. -->
 253       &lt;/target>
 254       &lt;target name="server2">
 255        &lt;!-- description of server2 .. -->
 256       &lt;/target>
 257      &lt;/proxy>
 258      </screen>
 259     </para>
 260    </section>
 261    <section id="proxy-config-url">
 262     <title>url</title>
 263     <para>
 264      The <literal>url</literal> which may be repeated one or more times
 265      should be the child of the <literal>target</literal> element.
 266      The CDATA of <literal>url</literal> is the Z-URL of the backend.
 267     </para>
 268     <para>
 269      Multiple <literal>url</literal> element may be used. In that case, then
 270      a client initiates a session, the proxy chooses the URL with the lowest
 271      number of active sessions, thereby distributing the load. It is
 272      assumed that each URL represents the same database (data).
 273     </para>
 274    </section>
 275
 276    <section id="proxy-config-target-timeout">
 277     <title>target-timeout</title>
 278     <para>
 279      The element <literal>target-timeout</literal> is the child of element
 280      <literal>target</literal> and specifies the amount in seconds before
 281      a target session is shut down.
 282     </para>
 283     <para>
 284      This can also be specified on the command line by using option
 285      <literal>-T</literal>. Refer to OPTIONS in <xref linkend="proxy-usage"/>.
 286     </para>
 287    </section>
 288
 289    <section id="proxy-config-client-timeout">
 290     <title>client-timeout</title>
 291     <para>
 292      The element <literal>client-timeout</literal> is the child of element
 293      <literal>target</literal> and specifies the amount in seconds before
 294      a client session is shut down.
 295      </para>
 296     <para>
 297      This can also be specified on the command line by using option
 298      <literal>-i</literal>.  Refer to OPTIONS in <xref linkend="proxy-usage"/>.
 299     </para>
 300    </section>
 301
 302    <section id="proxy-config-keepalive">
 303     <title>keepalive</title>
 304     <para>The <literal>keepalive</literal> element holds information about
 305      the keepalive Z39.50 sessions. Keepalive sessions are proxy-to-backend
 306      sessions that is no longer associated with a client session.
 307     </para>
 308     <para>The <literal>keepalive</literal> element which is the child of
 309      the <literal>target</literal>holds two elements:
 310      <literal>bandwidth</literal> and <literal>pdu</literal>.
 311      The <literal>bandwidth</literal> is the maximum total bytes
 312      transferred to/from the target. If a target session exceeds this
 313      limit, it is shut down (and no longer kept alive).
 314      The <literal>pdu</literal> is the maximum number of requests sent
 315      to the target. If a target session exceeds this limit, it is
 316      shut down. The idea of these two limits is that avoid very long
 317      sessions that use resources in a backend (that leaks!).
 318     </para>
 319     <para>
 320      The following sets maximum number of bytes transferred in a
 321      target session to 1 MB and maximum of requests to 400.
 322      <screen>
 323       &lt;keepalive>
 324        &lt;bandwidth>1048576&lt;/bandwidth>
 325        &lt;pdu>400&lt;/pdu>
 326       &lt;/keepalive>
 327      </screen>
 328     </para>
 329    </section>
 330    <section id="proxy-config-limit">
 331     <title>limit</title>
 332     <para>
 333      The <literal>limit</literal> section specifies bandwidth/pdu requests
 334      limits for an active session.
 335      The proxy records bandwidth/pdu requests during the last 60 seconds
 336      (1 minute). The <literal>limit</literal> may include the
 337      elements <literal>bandwidth</literal>, <literal>pdu</literal>,
 338      <literal>retrieve</literal> and <literal>search</literal>.
 339      The <literal>bandwidth</literal>
 340      measures the number of bytes transferred within the last minute.
 341      The <literal>pdu</literal> is the number of requests in the last
 342      minute. The <literal>retrieve</literal> holds the maximum records to
 343      which may be retrieved in one Present Request.
 344      The <literal>search</literal> is the maximum number of searches
 345      within the last minute.
 346     </para>
 347     <para>
 348      If a bandwidth/pdu/search limit is reached the proxy will postpone the
 349      requests to the target and wait one or more seconds. The idea of the
 350      limit is to ensure that clients that downloads hundreds or thousands of
 351      records do not hurt other users.
 352     </para>
 353     <para>
 354      The following sets maximum number of bytes transferred per minute to
 355      500Kbytes, maximum number of records retrievals to 40
 356      and maximum number of searches to 20.
 357      <screen>
 358       &lt;limit>
 359        &lt;bandwidth>524288&lt;/bandwidth>
 360        &lt;retrieve>40&lt;/retrieve>
 361        &lt;search>20&lt;/search>
 362       &lt;/limit>
 363      </screen>
 364     </para>
 365     <note>
 366      <para>
 367       Typically the values in the keepalive section are mugh higher
 368       than their equivalent limit counterparts (bandwidth, pdu).
 369      </para>
 370     </note>
 371    </section>
 372
 373    <section id="proxy-config-attribute">
 374     <title>attribute</title>
 375     <para>
 376      The <literal>attribute</literal> element specifies accept or reject
 377      or a particular attribute type, value pair.
 378      Well-behaving targets will reject unsupported attributes on their
 379      own. This feature is useful for targets that do not gracefully
 380      handle unsupported attributes.
 381     </para>
 382     <para>
 383      Attribute elements may be repeated. The proxy inspects the attribute
 384      specifications in the order as specified in the configuration file.
 385      When a given attribute specification matches a given attribute list
 386      in a query, the proxy takes appropriate action (reject, accept).
 387     </para>
 388     <para>
 389      If no attribute specifications matches the attribute list in a query,
 390      it is accepted.
 391     </para>
 392     <para>
 393      The <literal>attribute</literal> element has two required attributes:
 394      <literal>type</literal> which is the Attribute Type-1 type, and
 395      <literal>value</literal> which is the Attribute Type-1 value.
 396      The special value/type <literal>*</literal> matches any attribute
 397      type/value. A value may also be specified as a list with each
 398      value separated by comma, a value may also be specified as a
 399      list: low value - dash - high value.
 400     </para>
 401     <para>
 402      If attribute <literal>error</literal> is given, that holds a
 403      Bib-1 diagnostic which is sent to the client if the particular
 404      type, value is part of a query.
 405     </para>
 406     <para>
 407      If attribute <literal>error</literal> is not given, the attribute
 408      type, value is accepted and passed to the backend target.
 409     </para>
 410     <para>
 411      A target that supports use attributes 1,4, 1000 through 1003 and
 412      no other use attributes, could use the following rules:
 413      <screen>
 414       &lt;attribute type="1" value="1,4,1000-1003"/>
 415       &lt;attribute type="1" value="*" error="114"/>
 416      </screen>
 417     </para>
 418    </section>
 419    <section id="proxy-config-syntax">
 420     <title>syntax</title>
 421     <para>
 422      The <literal>syntax</literal> element specifies accept or reject
 423      or a particular record syntax request from the client.
 424     </para>
 425     <para>
 426      The <literal>syntax</literal> has one required attribute:
 427      <literal>type</literal> which is the Preferred Record Syntax.
 428     </para>
 429     <para>
 430      If attribute <literal>error</literal> is given, that holds a
 431      Bib-1 diagnostic which is sent to the client if the particular
 432      record syntax is part of a present - or search request.
 433     </para>
 434     <para>
 435      If attribute <literal>error</literal> is not given, the record syntax
 436      is accepted and passed to the backend target.
 437     </para>
 438     <para>
 439      If attribute <literal>marcxml</literal> is given, the proxy will
 440      perform MARC21 to MARCXML conversion. In this case the
 441      <literal>type</literal> should be XML. The proxy will use
 442      preferred record syntax USMARC/MARC21 or <literal>backendtype</literal>
 443      (if given) against the backend target.
 444      For the special case where <literal>backendtype</literal> is
 445      <literal>opac</literal> the proxy will convert the OPAC
 446      record to OPACXML.
 447     </para>
 448     <para>
 449      If attribute <literal>backendtype</literal> is given, that holds the
 450      record syntax to be transmitted to backend.
 451     </para>
 452     <para>
 453      If attribute <literal>stylesheet</literal> is given, the proxy
 454      will convert XML record from server via XSLT. It is important
 455      that the content from server is XML. If used in conjunction with
 456      attribute <literal>marcxml</literal>, the MARC to MARCXML/OPACXML
 457      conversion takes place before the XSLT conversion takes place.
 458     </para>
 459     <para>
 460      If attribute <literal>identifier</literal> is given that is the
 461      SRW/SRU record schema identifier for the resulting output record (after
 462      MARCXML and/or XSLT conversion).
 463     </para>
 464     <para>
 465      If sub element <literal>title</literal> is given (as child element
 466      of <literal>syntax</literal>, then that is the official SRW/SRU
 467      name of the resulting record schema.
 468     </para>
 469     <para>
 470      If sub element <literal>name</literal> is given that is an alias
 471      for the record schema identifier. Multiple <literal>name</literal>s
 472      may be specified.
 473     </para>
 474     <example>
 475      <title>MARCXML conversion</title>
 476      <para>To accept USMARC and offer MARCXML XML plus Dublin Core (via
 477       XSLT conversion) but the following configuration could be used:
 478       <screen>
 479        &lt;proxy>
 480        &lt;target name="mytarget">
 481        ..
 482        &lt;syntax type="usmarc"/>
 483        &lt;syntax type="xml" marcxml="1"
 484          identifier="info:srw/schema/1/marcxml-v1.1"
 485          &lt;title>MARCXML&lt;title>
 486          &lt;name>marcxml&lt;name>
 487        &lt;/syntax>
 488        &lt;syntax type="xml" marcxml="1" stylesheet="MARC21slim2SRWDC.xsl"
 489          identifier="info:srw/schema/1/dc-v1.1">
 490          &lt;title>Dublin Core&lt;title>
 491          &lt;name>dc&lt;name>
 492        &lt;/syntax>
 493        &lt;syntax type="*" error="238"/>
 494        ..
 495        &lt;/target>
 496        &lt;/proxy>
 497       </screen>
 498     </para>
 499     </example>
 500
 501    </section>
 502
 503    <section id="proxy-config-explain">
 504     <title>explain</title>
 505     <para>
 506      The <literal>explain</literal> element includes Explain information
 507      for SRW/SRU about the server in the target section. This
 508      information must have a <literal>serverInfo</literal> element
 509      with a database that this target must be available as (URL path).
 510      For example,
 511      <screen><![CDATA[
 512       <explain xmlns="http://explain.z3950.org/dtd/2.0/">
 513         <serverInfo>
 514           <host>myhost.org</host>
 515           <port>8000</port>
 516           <database>mydatabase</database>
 517         </serverInfo>
 518         <!-- remaining Explain stuff -->
 519       </explain>
 520       ]]>
 521      </screen>
 522      In the above case, the SRW/SRU service is available as
 523      <literal>http://myhost.org:8000/mydatabase</literal>.
 524     </para>
 525
 526    </section>
 527
 528    <section id="proxy-config-cql2rpn">
 529     <title>cql2rpn</title>
 530     <para>
 531      The content of the <literal>cql2rpn</literal> element specifies
 532      the path from the working directory to a CQL-to-RPN conversion
 533      file for the server in the target section. This element
 534      is required for SRW/SRU searches to operate against Z39.50
 535      servers that don't support CQL. Most Z39.50 servers only support
 536      Type-1/RPN so this is usually required.
 537     </para>
 538     <para>
 539      See YAZ documentation for more information about the
 540      <ulink url="http://indexdata.dk/yaz/doc/tools.tkl#tools.cql.pqf">CQL
 541       to PQF</ulink> conversion. See also the
 542      <filename>pqf.properties</filename> in the <filename>etc</filename>
 543      (or <replaceable>prefix/share/yazproxy</replaceable>)
 544      directory of the YAZ proxy distribution.
 545     </para>
 546    </section>
 547
 548    <section id="proxy-config-preinit">
 549     <title>preinit</title>
 550     <para>
 551      The element <literal>preinit</literal> is the child of element
 552      <literal>target</literal> and specifies the number of spare
 553      connection to a target. By default no spare connection are
 554      created by the proxy. If the proxy uses a target exclusive or
 555      a lot, the preinit session will ensure that target sessions
 556      have been made before the client makes a connection and will therefore
 557      reduce the connect-init handshake dramatically. Never set this to
 558      more than 5.
 559     </para>
 560    </section>
 561
 562    <section id="proxy-config-target-authentication">
 563     <title>target-authentication</title>
 564     <para>
 565      The element <literal>target-authentication</literal> specifies
 566      fixed authentication information to be sent to the backend target.
 567     </para>
 568     <para>
 569      This element takes a an attribute <literal>type</literal> which is
 570      the authenticatin type to be used..
 571     </para>
 572     <variablelist>
 573      <varlistentry><term><literal>none</literal></term>
 574       <listitem>
 575        <para>
 576         No authentication. There is no CDATA associated with this.
 577        </para>
 578       </listitem>
 579      </varlistentry>
 580
 581      <varlistentry><term><literal>anonymous</literal></term>
 582       <listitem>
 583        <para>
 584         Anonymous authentication. There is no CDATA associated with this.
 585        </para>
 586       </listitem>
 587      </varlistentry>
 588
 589      <varlistentry><term><literal>open</literal></term>
 590       <listitem>
 591        <para>
 592         Open authentication. The CDATA consists of the
 593         open authentication string.
 594        </para>
 595       </listitem>
 596      </varlistentry>
 597
 598      <varlistentry><term><literal>idPass</literal></term>
 599       <listitem>
 600        <para>
 601         IdPass authentication. The CDATA consists of
 602         three terms: user, group and password.
 603        </para>
 604       </listitem>
 605      </varlistentry>
 606     </variablelist>
 607    </section>
 608
 609    <section id="proxy-config-target-charset">
 610     <title>target-charset</title>
 611     <para>
 612      The element <literal>target-charset</literal> specifies the
 613      native character set that the target uses for queries.
 614     </para>
 615     <para>
 616      If this is specified the proxy will act as a Z39.50 server
 617      supporting character set negotiation. And in SRW/SRU mode
 618      it will convert from UTF-8 (UNICODE) to this native character
 619      set (if possible).
 620     </para>
 621    </section>
 622
 623    <section id="proxy-config-max-clients">
 624     <title>max-clients</title>
 625     <para>
 626      The element <literal>max-clients</literal> is the child of element
 627      <literal>proxy</literal> and specifies the total number of
 628      allowed connections to targets (all targets). If this limit
 629      is reached the proxy will close the least recently used connection.
 630     </para>
 631     <para>
 632      Note, that many Unix systems impose a system on the number of
 633      open files allowed in a single process, typically in the
 634      range 256 (Solaris) to 1024 (Linux).
 635      The proxy uses 2 sockets per session + a few files
 636      for logging. As a rule of thumb, ensure that 2*max-clients + 5
 637      can be opened by the proxy process.
 638     </para>
 639     <tip>
 640      <para>
 641       Using the <ulink url="http://www.gnu.org/software/bash/bash.html">
 642        bash</ulink> shell, you can set the limit with
 643       <literal>ulimit -n</literal><replaceable>no</replaceable>.
 644        Use <literal>ulimit -a</literal> to display limits.
 645      </para>
 646      </tip>
 647    </section>
 648
 649    <section id="proxy-config-log">
 650     <title>log</title>
 651     <para>
 652      The element <literal>log</literal> is the child of element
 653      <literal>proxy</literal> and specifies what to be logged by the
 654      proxy.
 655      </para>
 656     <para>
 657      Specify the log file with command-line option <literal>-l</literal>.
 658     </para>
 659     <para>
 660      The text of the <literal>log</literal> element is a sequence of
 661      options separated by white space. See the table below:
 662      <table frame="top"><title>Logging options</title>
 663       <tgroup cols="2">
 664        <colspec colwidth="1*"/>
 665        <colspec colwidth="2*"/><thead>
 666         <row>
 667          <entry>Option</entry>
 668          <entry>Description</entry>
 669         </row>
 670        </thead>
 671        <tbody>
 672         <row>
 673          <entry><literal>client-apdu</literal></entry>
 674          <entry>
 675           Log APDUs as reported by YAZ for the
 676           communication between the client and the proxy.
 677           This facility is equivalent to the APDU logging that
 678           happens when using option <literal>-a</literal>, however
 679           this tells the proxy to log in the same file as given
 680           by <literal>-l</literal>.
 681          </entry>
 682         </row>
 683         <row>
 684          <entry><literal>server-apdu</literal></entry>
 685          <entry>
 686           Log APDUs as reported by YAZ for the
 687           communication between the proxy and the server (backend).
 688          </entry>
 689         </row>
 690         <row>
 691          <entry><literal>clients-requests</literal></entry>
 692          <entry>
 693           Log a brief description about requests transferred between
 694           the client and the proxy. The name of the request and the size
 695           of the APDU is logged.
 696          </entry>
 697         </row>
 698         <row>
 699          <entry><literal>server-requests</literal></entry>
 700          <entry>
 701           Log a brief description about requests transferred between
 702           the proxy and the server (backend). The name of the request
 703           and the size of the APDU is logged.
 704          </entry>
 705         </row>
 706         <row>
 707          <entry><literal>client-ip</literal></entry>
 708          <entry>
 709           Log the client IP for each log entry. By default, the client IP
 710           is only logged when a new session starts.
 711          </entry>
 712         </row>
 713        </tbody>
 714       </tgroup>
 715      </table>
 716     </para>
 717     <para>
 718      To log communication in details between the proxy and the backend, th
 719      following configuration could be used:
 720      <screen><![CDATA[
 721       <target name="mytarget">
 722        <log>server-apdu server-requests</log>
 723       </target>
 724       ]]>
 725      </screen>
 726     </para>
 727    </section>
 728
 729    <section id="proxy-max-connect">
 730     <title>max-connect</title>
 731     <para>
 732      The element <literal>max-connect</literal> is a child of element
 733      <literal>proxy</literal> and specifies the maximum number
 734      of connections to be initiated within the last minute.
 735     </para>
 736     <para>
 737      If the maximum number is reached the proxy will terminate the
 738      just initiated session (connection terminated).
 739     </para>
 740    </section>
 741
 742    <section id="proxy-limit-connect">
 743     <title>limit-connect</title>
 744     <para>
 745      The element <literal>max-connect</literal> is a child of element
 746      <literal>proxy</literal> and specifies the limit of number
 747      of connections to be initiated within the last minute.
 748     </para>
 749     <para>
 750      If the maximum number is reached the proxy delay the first operatation
 751      in the session (Thus delaying the connection).
 752     </para>
 753    </section>
 754
 755    <section id="proxy-docpath">
 756     <title>docpath</title>
 757     <para>
 758      The element <literal>docpath</literal> is a child of element
 759      <literal>proxy</literal> and specifies an allowed HTTP path
 760      for local file access. Using <literal>docpath</literal> the
 761      proxy may return static file content.
 762     </para>
 763     <para>
 764      The value of docpath both serves as a HTTP path prefix
 765      <emphasis>and</emphasis> as a local file prefix.
 766      If a value of <literal>etc</literal> is used only URLs with the
 767      prefix <literal>/etc/</literal> results in a local file access to the
 768      directory <literal>etc</literal> within the working directory
 769      of yazproxy.
 770     </para>
 771     <note>
 772     <para>
 773       Care has been taken to ensure that hostile URLs are rejected - including
 774       strings such as <literal>..</literal> and <literal>/</literal> (absolute
 775       file system access).
 776      </para>
 777     </note>
 778    </section>
 779
 780   </section>
 781   <section id="proxy-usage">
 782    <title>Proxy Manual Pages</title>
 783    <refentry id="yazproxy-man">
 784     &yaz-proxy-ref;
 785    </refentry>
 786   </section>
 787
 788   <section id="otherinfo-encoding">
 789    <title>OtherInformation Encoding</title>
 790    <para>
 791     The proxy uses the OtherInformation definition to carry
 792     information about the target address and cookie.
 793    </para>
 794    <screen>
 795   OtherInformation   ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{
 796     category           [1]   IMPLICIT InfoCategory OPTIONAL,
 797     information        CHOICE{
 798       characterInfo            [2]  IMPLICIT InternationalString,
 799       binaryInfo               [3]  IMPLICIT OCTET STRING,
 800       externallyDefinedInfo    [4]  IMPLICIT EXTERNAL,
 801       oid                      [5]  IMPLICIT OBJECT IDENTIFIER}}
 802 --
 803   InfoCategory ::= SEQUENCE{
 804       categoryTypeId   [1]   IMPLICIT OBJECT IDENTIFIER OPTIONAL,
 805       categoryValue    [2]   IMPLICIT INTEGER}
 806   </screen>
 807    <para>
 808     The <literal>categoryTypeId</literal> is either
 809     OID 1.2.840.10003.10.1000.81.1, 1.2.840.10003.10.1000.81.2
 810     for proxy target and proxy cookie respectively. The
 811     integer element <literal>category</literal> is set to 0.
 812     The value proxy and cookie is stored in element
 813     <literal>characterInfo</literal> of the <literal>information</literal>
 814      choice.
 815    </para>
 816   </section>
 817   <section id="yazproxy-schema">
 818    <title>YAZ Proxy Configuration Schema</title>
 819    <para>
 820     Here an XML Schema for the YAZ proxy configuration file.
 821     The schema, <filename>yazproxy.xsd</filename> is located in sub
 822     directory <filename>etc</filename> of the distribution.
 823    </para>
 824    <screen><![CDATA[
 825 <?xml version="1.0"?>
 826 <!-- XML Schema for YAZ proxy config file.
 827     $Id: reference.xml,v 1.17 2006-04-06 12:04:19 adam Exp $
 828 -->
 829 <xs:schema
 830   xmlns:xs="http://www.w3.org/2001/XMLSchema"
 831   xmlns:exp="http://explain.z3950.org/dtd/2.0/"
 832   xmlns="http://indexdata.dk/yazproxy/schema/0.9/"
 833   targetNamespace="http://indexdata.dk/yazproxy/schema/0.9/"
 834   >
 835  <xs:import namespace="http://explain.z3950.org/dtd/2.0/"
 836       schemaLocation="zeerex-2.0.xsd"/>
 837  <xs:element name="proxy">
 838   <xs:complexType>
 839    <xs:sequence>
 840     <xs:element ref="target" minOccurs="0" maxOccurs="unbounded"/>
 841     <xs:element ref="max-clients" minOccurs="0"/>
 842     <xs:element ref="log" minOccurs="0"/>
 843     <xs:element ref="module" minOccurs="0"/>
 844    </xs:sequence>
 845   </xs:complexType>
 846  </xs:element>
 847
 848  <xs:element name="target">
 849   <xs:complexType>
 850    <xs:sequence>
 851      <xs:element ref="url" minOccurs="0" maxOccurs="unbounded"/>
 852      <xs:element ref="target-timeout" minOccurs="0"/>
 853      <xs:element ref="client-timeout" minOccurs="0"/>
 854      <xs:element ref="keepalive" minOccurs="0"/>
 855      <xs:element ref="limit" minOccurs="0"/>
 856      <xs:element ref="attribute" minOccurs="0" maxOccurs="unbounded"/>
 857      <xs:element ref="syntax" minOccurs="0" maxOccurs="unbounded"/>
 858      <xs:element ref="preinit" minOccurs="0"/>
 859      <xs:element ref="exp:explain" minOccurs="0"/>
 860      <xs:element ref="cql2rpn" minOccurs="0"/>
 861      <xs:element ref="target-authentication" minOccurs="0"/>
 862      <xs:element ref="client-authentication" minOccurs="0"/>
 863      <xs:element ref="negotiation-charset" minOccurs="0"/>
 864      <xs:element ref="negotiation-lang" minOccurs="0"/>
 865    </xs:sequence>
 866    <xs:attribute name="default" type="xs:string" use="optional"/>
 867    <xs:attribute name="name" type="xs:string"/>
 868    <xs:attribute name="database" type="xs:string"/>
 869   </xs:complexType>
 870  </xs:element>
 871
 872  <xs:element name="url" type="xs:string"/>
 873  <xs:element name="target-timeout" type="xs:integer"/>
 874  <xs:element name="client-timeout" type="xs:integer"/>
 875  <xs:element name="bandwidth" type="xs:integer"/>
 876  <xs:element name="pdu" type="xs:integer"/>
 877  <xs:element name="retrieve" type="xs:integer"/>
 878  <xs:element name="preinit" type="xs:integer"/>
 879  <xs:element name="cql2rpn" type="xs:string"/>
 880  <xs:element name="target-authentication">
 881    <xs:complexType>
 882     <xs:simpleContent>
 883       <xs:extension base="xs:string">
 884         <xs:attribute name="type" type="xs:string"/>
 885       </xs:extension>
 886     </xs:simpleContent>
 887    </xs:complexType>
 888  </xs:element>
 889
 890  <xs:element name="client-authentication">
 891    <xs:complexType>
 892     <xs:simpleContent>
 893       <xs:extension base="xs:string">
 894         <xs:attribute name="module" type="xs:string"/>
 895         <xs:attribute name="args" type="xs:string"/>
 896       </xs:extension>
 897     </xs:simpleContent>
 898    </xs:complexType>
 899  </xs:element>
 900
 901  <xs:element name="negotiation-charset" type="xs:string"/>
 902  <xs:element name="negotiation-lang" type="xs:string"/>
 903
 904  <xs:element name="keepalive">
 905   <xs:complexType>
 906    <xs:sequence>
 907     <xs:element ref="bandwidth" minOccurs="0"/>
 908     <xs:element ref="pdu" minOccurs="0"/>
 909    </xs:sequence>
 910   </xs:complexType>
 911  </xs:element>
 912  <xs:element name="limit">
 913   <xs:complexType>
 914    <xs:sequence>
 915     <xs:element ref="bandwidth" minOccurs="0"/>
 916     <xs:element ref="pdu" minOccurs="0"/>
 917     <xs:element ref="retrieve" minOccurs="0"/>
 918    </xs:sequence>
 919   </xs:complexType>
 920  </xs:element>
 921
 922  <xs:element name="attribute">
 923   <xs:complexType>
 924    <xs:attribute name="type" type="xs:string"/>
 925    <xs:attribute name="value" type="xs:string"/>
 926    <xs:attribute name="error" type="xs:integer"/>
 927   </xs:complexType>
 928  </xs:element>
 929
 930  <xs:element name="syntax">
 931   <xs:complexType>
 932    <xs:sequence>
 933     <xs:element ref="title" minOccurs="0"/>
 934     <xs:element ref="name" minOccurs="0" maxOccurs="unbounded"/>
 935    </xs:sequence>
 936    <xs:attribute name="error" type="xs:string" />
 937    <xs:attribute name="type" type="xs:string" />
 938    <xs:attribute name="marcxml" type="xs:string" />
 939    <xs:attribute name="identifier" type="xs:string" />
 940    <xs:attribute name="stylesheet" type="xs:string" />
 941    <xs:attribute name="backendtype" type="xs:string" />
 942    <xs:attribute name="backendcharset" type="xs:string" />
 943    <xs:attribute name="usemarconstage1" type="xs:string" />
 944    <xs:attribute name="usemarconstage2" type="xs:string" />
 945   </xs:complexType>
 946  </xs:element>
 947
 948  <xs:element name="title" type="xs:string"/>
 949  <xs:element name="name" type="xs:string"/>
 950
 951  <xs:element name="max-clients" type="xs:integer"/>
 952  <xs:element name="log" type="xs:string"/>
 953  <xs:element name="module" type="xs:string"/>
 954
 955 </xs:schema>
 956 ]]>
 957    </screen>
 958   </section>
 959  </chapter>
 960
 961  <!-- Keep this comment at the end of the file
 962  Local variables:
 963  mode: sgml
 964  sgml-omittag:t
 965  sgml-shorttag:t
 966  sgml-minimize-attributes:nil
 967  sgml-always-quote-attributes:t
 968  sgml-indent-step:1
 969  sgml-indent-data:t
 970  sgml-parent-document: "yazproxy.xml"
 971  sgml-local-catalogs: nil
 972  sgml-namecase-general:t
 973  End:
 974  -->
 975