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 single 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 priviledged
  16     user.
  17    </para>
  18   </section>
  19   <section id="proxy-target">
  20    <title>Specifying 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   </section>
  61   <section id="proxy-keepalive">
  62    <title>Keep-alive Facility</title>
  63    <para>
  64     The keep-alive is a facility where the proxy keeps the connection to the
  65     backend server - even if the client closes the connection to the proxy.
  66    </para>
  67    <para>
  68     If a new or another client connects to the proxy again and requests the
  69     same backend it will be reassigned to this backend. In this case, the
  70     proxy sends an initialize response directly to the client and an
  71     initialize handshake with the backend is omitted.
  72    </para>
  73    <para>
  74     When a client reconnects, query and record caching works better, if the
  75     proxy assigns it to the same backend as before. And the result set
  76     (if any) is re-used. To achieve this, Index Data defined a session
  77     cookie which identifies the backend session.
  78    </para>
  79    <para>
  80     The cookie is defined by the client and is sent as part of the
  81     Initialize Request and passed in an
  82     <link linkend="otherinfo-encoding"><literal>otherInfo</literal></link>
  83     element with OID <literal>1.2.840.10003.10.1000.81.2</literal>.
  84    </para>
  85    <para>
  86     Clients that do not send a cookie as part of the initialize request
  87     may still better performance, since the init handshake is saved.
  88    </para>
  89    <para>
  90     Refer to <xref linkend="proxy-config-keepalive"/> on how to setup
  91     configuration parameters for keepalive.
  92     </para>
  93   </section>
  94
  95   <section id="proxy-config-file">
  96    <title>Proxy Configuration File</title>
  97    <para>
  98     The Proxy may read a configuration file using option
  99     <literal>-c</literal> followed by the filename of a config file.
 100    </para>
 101    <para>
 102     The config file is XML based. The YAZ proxy must be compiled
 103     with <ulink url="http://www.xmlsoft.org/">libxml2</ulink> and
 104     <ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> support in
 105     order for the config file facility to be enabled.
 106    </para>
 107    <tip>
 108     <para>To check for a config file to be well-formed, the yazproxy may
 109      be invoked without specifying a listening port, i.e.
 110      <screen>
 111       yazproxy -c myconfig.xml
 112      </screen>
 113      If this does not produce errors, the file is well-formed.
 114     </para>
 115    </tip>
 116    <section id="proxy-config-header">
 117     <title>Proxy Configuration Header</title>
 118     <para>
 119      The proxy config file must have a root element called
 120      <literal>proxy</literal>. All information except an optional XML
 121      header must be stored within the <literal>proxy</literal> element.
 122     </para>
 123     <screen>
 124      &lt;?xml version="1.0"?>
 125       &lt;proxy>
 126        &lt;!-- content here .. -->
 127       &lt;/proxy>
 128     </screen>
 129    </section>
 130    <section id="proxy-config-target">
 131     <title>target</title>
 132     <para>
 133      The element <literal>target</literal> which may be repeated zero
 134      or more times with parent element <literal>proxy</literal> contains
 135      information about each backend target.
 136      The <literal>target</literal> element have two attributes:
 137      <literal>name</literal> which holds the logical name of the backend
 138      target (required) and <literal>default</literal> (optional) which
 139      (when given) specifies that the backend target is the default target -
 140      equivalent to command line option <literal>-t</literal>.
 141     </para>
 142     <para>
 143      <screen>
 144      &lt;?xml version="1.0"?>
 145      &lt;proxy>
 146       &lt;target name="server1" default="1">
 147        &lt;!-- description of server1 .. -->
 148       &lt;/target>
 149       &lt;target name="server2">
 150        &lt;!-- description of server2 .. -->
 151       &lt;/target>
 152      &lt;/proxy>
 153      </screen>
 154     </para>
 155    </section>
 156    <section id="proxy-config-url">
 157     <title>url</title>
 158     <para>
 159      The <literal>url</literal> which may be repeated one or more times
 160      should be the child of the <literal>target</literal> element.
 161      The CDATA of <literal>url</literal> is the Z-URL of the backend.
 162     </para>
 163     <para>
 164      Multiple <literal>url</literal> element may be used. In that case, then
 165      a client initiates a session, the proxy chooses the URL with the lowest
 166      number of active sessions, thereby distributing the load. It is
 167      assumed that each URL represents the same database (data).
 168     </para>
 169    </section>
 170
 171    <section id="proxy-config-target-timeout">
 172     <title>target-timeout</title>
 173     <para>
 174      The element <literal>target-timeout</literal> is the child of element
 175      <literal>target</literal> and specifies the amount in seconds before
 176      a target session is shut down.
 177     </para>
 178     <para>
 179      This can also be specified on the command line by using option
 180      <literal>-T</literal>. Refer to OPTIONS.
 181     </para>
 182    </section>
 183
 184    <section id="proxy-config-client-timeout">
 185     <title>client-timeout</title>
 186     <para>
 187      The element <literal>client-timeout</literal> is the child of element
 188      <literal>target</literal> and specifies the amount in seconds before
 189      a client session is shut down.
 190      </para>
 191     <para>
 192      This can also be specified on the command line by using option
 193      <literal>-i</literal>. Refer to OPTIONS.
 194     </para>
 195    </section>
 196
 197    <section id="proxy-config-keepalive">
 198     <title>keepalive</title>
 199     <para>The <literal>keepalive</literal> element holds information about
 200      the keepalive Z39.50 sessions. Keepalive sessions are proxy-to-backend
 201      sessions that is no longer associated with a client session.
 202     </para>
 203     <para>The <literal>keepalive</literal> element which is the child of
 204      the <literal>target</literal>holds two elements:
 205      <literal>bandwidth</literal> and <literal>pdu</literal>.
 206      The <literal>bandwidth</literal> is the maximum total bytes
 207      transferred to/from the target. If a target session exceeds this
 208      limit, it is shut down (and no longer kept alive).
 209      The <literal>pdu</literal> is the maximum number of requests sent
 210      to the target. If a target session exceeds this limit, it is
 211      shut down. The idea of these two limits is that avoid very long
 212      sessions that use resources in a backend (that leaks!).
 213     </para>
 214     <para>
 215      The following sets maximum number of bytes transferred in a
 216      target session to 1 MB and maxinum of requests to 400.
 217      <screen>
 218       &lt;keepalive>
 219        &lt;bandwidth>1048576&lt;/bandwidth>
 220        &lt;retrieve>400&lt;/retrieve>
 221       &lt;/keepalive>
 222      </screen>
 223     </para>
 224    </section>
 225    <section id="proxy-config-limit">
 226     <title>limit</title>
 227     <para>
 228      The <literal>limit</literal> section specifies bandwidth/pdu requests
 229      limits for an active session.
 230      The proxy records bandwidth/pdu requests during the last 60 seconds
 231      (1 minute). The <literal>limit</literal> may include the
 232      elements <literal>bandwidth</literal>, <literal>pdu</literal>,
 233      and <literal>retrieve</literal>. The <literal>bandwidth</literal>
 234      measures the number of bytes transferred within the last minute.
 235      The <literal>pdu</literal> is the number of requests in the last
 236      minute. The <literal>retrieve</literal> holds the maximum records to
 237      be retrieved in one Present Request.
 238     </para>
 239     <para>
 240      If a bandwidth/pdu limit is reached the proxy will postpone the
 241      requests to the target and wait one or more seconds. The idea of the
 242      limit is to ensure that clients that downloads hundreds or thousands of
 243      records do not hurt other users.
 244     </para>
 245     <para>
 246      The following sets maximum number of bytes transferred per minute to
 247      500Kbytes and maximum number of requests to 40.
 248      <screen>
 249       &lt;limit>
 250        &lt;bandwidth>524288&lt;/bandwidth>
 251        &lt;retrieve>40&lt;/retrieve>
 252       &lt;/limit>
 253      </screen>
 254     </para>
 255     <note>
 256      <para>
 257       Typically the limits for keepalive are much higher than
 258       those for session minute average.
 259      </para>
 260     </note>
 261    </section>
 262
 263    <section id="proxy-config-attribute">
 264     <title>attribute</title>
 265     <para>
 266      The <literal>attribute</literal> element specifies accept or reject
 267      or a particular attribute type, value pair.
 268      Well-behaving targets will reject unsupported attributes on their
 269      own. This feature is useful for targets that do not gracefully
 270      handle unsupported attributes.
 271     </para>
 272     <para>
 273      Attribute elements may be repeated. The proxy inspects the attribute
 274      specifications in the order as specified in the configuration file.
 275      When a given attribute specification matches a given attribute list
 276      in a query, the proxy takes appropriate action (reject, accept).
 277     </para>
 278     <para>
 279      If no attribute specifications matches the attribute list in a query,
 280      it is accepted.
 281     </para>
 282     <para>
 283      The <literal>attribute</literal> element has two required attributes:
 284      <literal>type</literal> which is the Attribute Type-1 type, and
 285      <literal>value</literal> which is the Attribute Type-1 value.
 286      The special value/type <literal>*</literal> matches any attribute
 287      type/value. A value may also be specified as a list with each
 288      value separated by comma, a value may also be specified as a
 289      list: low value - dash - high value.
 290     </para>
 291     <para>
 292      If attribute <literal>error</literal> is given, that holds a
 293      Bib-1 diagnostic which is sent to the client if the particular
 294      type, value is part of a query.
 295     </para>
 296     <para>
 297      If attribute <literal>error</literal> is not given, the attribute
 298      type, value is accepted and passed to the backend target.
 299     </para>
 300     <para>
 301      A target that supports use attributes 1,4, 1000 through 1003 and
 302      no other use attributes, could use the following rules:
 303      <screen>
 304       &lt;attribute type="1" value="1,4,1000-1003">
 305       &lt;attribute type="1" value="*" error="114"/>
 306      </screen>
 307     </para>
 308    </section>
 309
 310    <!-- TODO -->
 311    <!--
 312
 313     <syntax type="xml" marcxml="1" stylesheet="MARC21slim2MODS.xsl"
 314       identifier="http://www.loc.gov/mods"
 315       >
 316       <title>MODS v2</title>
 317       <name>mods2</name>
 318     </syntax>
 319
 320
 321 -->
 322    <section id="proxy-config-syntax">
 323     <title>syntax</title>
 324     <para>
 325      The <literal>syntax</literal> element specifies accept or reject
 326      or a particular record syntax request from the client.
 327     </para>
 328     <para>
 329      The <literal>syntax</literal> has one required attribute:
 330      <literal>type</literal> which is the Preferred Record Syntax.
 331     </para>
 332     <para>
 333      If attribute <literal>error</literal> is given, that holds a
 334      Bib-1 diagnostic which is sent to the client if the particular
 335      record syntax is part of a present - or search request.
 336     </para>
 337     <para>
 338      If attribute <literal>error</literal> is not given, the record syntax
 339      is accepted and passed to the backend target.
 340     </para>
 341     <para>
 342      If attribute <literal>marcxml</literal> is given, the proxy will
 343      perform MARC21 to MARCXML conversion. In this case the
 344      <literal>type</literal> should be XML. The proxy will use
 345      preferred record syntax USMARC/MARC21 against the backend target.
 346     </para>
 347     <para>To accept USMARC and offer MARCXML XML records but reject
 348      all other requests the following configuration could be used:
 349      <screen>
 350       &lt;proxy>
 351        &lt;target name="mytarget">
 352        &lt;syntax type="usmarc"/>
 353         &lt;syntax type="xml" marcxml="1"/>
 354         &lt;syntax type="*" error="238"/>
 355        &lt;/target>
 356       &lt;/proxy>
 357      </screen>
 358     </para>
 359    </section>
 360
 361    <section id="proxy-config-explain">
 362     <title>explain</title>
 363     <para>
 364      The <literal>explain</literal> element includes Explain information
 365      for SRW/SRU about the server in the target section. This
 366      information must have a <literal>serverInfo</literal> element
 367      with a database that this target must be available as (URL path).
 368      For example,
 369      <screen><![CDATA[
 370       <explain xmlns="http://explain.z3950.org/dtd/2.0/">
 371         <serverInfo>
 372           <host>myhost.org</host>
 373           <port>8000</port>
 374           <database>mydatabase</database>
 375         </serverInfo>
 376         <!-- remaining Explain stuff -->
 377       </explain>
 378       ]]>
 379      </screen>
 380      In the above case, the SRW/SRU service is available as
 381      <literal>http://myhost.org:8000/mydatabase</literal>.
 382     </para>
 383
 384    </section>
 385
 386    <section id="proxy-config-cql2rpn">
 387     <title>cql2rpn</title>
 388     <para>
 389      The CDATA of <literal>cql2rpn</literal> refers to CQL to a RPN conversion
 390      file - for the server in the target section. This element
 391      is required for SRW/SRU searches to operate against a Z39.50
 392      server that doesn't support CQL. Most Z39.50 servers only support
 393      Type-1/RPN so this is usually required.
 394      See YAZ documentation for more information about the
 395      <ulink url="http://indexdata.dk/yaz/doc/tools.tkl#tools.cql.pqf">CQL
 396       to PQF</ulink> conversion. See also the
 397      <filename>pqf.properties</filename> in the <filename>etc</filename>
 398      (or <replaceable>prefix/share/yazproxy</replaceable>)
 399      directory of the YAZ proxy.
 400     </para>
 401    </section>
 402
 403    <section id="proxy-config-preinit">
 404     <title>preinit</title>
 405     <para>
 406      The element <literal>preinit</literal> is the child of element
 407      <literal>target</literal> and specifies the number of spare
 408      connection to a target. By default no spare connection are
 409      created by the proxy. If the proxy uses a target exclusive or
 410      a lot, the preinit session will ensure that target sessions
 411      have been made before the client makes a connection and will therefore
 412      reduce the connect-init handshake dramatically. Never set this to
 413      more than 5.
 414     </para>
 415    </section>
 416
 417    <section id="proxy-config-max-clients">
 418     <title>max-clients</title>
 419     <para>
 420      The element <literal>max-clients</literal> is the child of element
 421      <literal>proxy</literal> and specifies the total number of
 422      allowed connections to targets (all targets). If this limit
 423      is reached the proxy will close the least recently used connection.
 424     </para>
 425     <para>
 426      Note, that many Unix systems impose a system on the number of
 427      open files allowed in a single process, typically in the
 428      range 256 (Solaris) to 1024 (Linux).
 429      The proxy uses 2 sockets per session + a few files
 430      for logging. As a rule of thumb, ensure that 2*max-clients + 5
 431      can be opened by the proxy process.
 432     </para>
 433     <tip>
 434      <para>
 435       Using the <ulink url="http://www.gnu.org/software/bash/bash.html">
 436        bash</ulink> shell, you can set the limit with
 437       <literal>ulimit -n</literal><replaceable>no</replaceable>.
 438        Use <literal>ulimit -a</literal> to display limits.
 439      </para>
 440      </tip>
 441    </section>
 442
 443    <section id="proxy-config-log">
 444     <title>log</title>
 445     <para>
 446      The element <literal>log</literal> is the child of element
 447      <literal>proxy</literal> and specifies what to be logged by the
 448      proxy.
 449      </para>
 450     <para>
 451      Specify the log file with command-line option <literal>-l</literal>.
 452     </para>
 453     <para>
 454      The text of the <literal>log</literal> element is a sequence of
 455      options separated by white space. See the table below:
 456      <table frame="top"><title>Logging options</title>
 457       <tgroup cols="2">
 458        <colspec colwidth="1*"/>
 459        <colspec colwidth="2*"/><thead>
 460         <row>
 461          <entry>Option</entry>
 462          <entry>Description</entry>
 463         </row>
 464        </thead>
 465        <tbody>
 466         <row>
 467          <entry><literal>client-apdu</literal></entry>
 468          <entry>
 469           Log APDUs as reported by YAZ for the
 470           communication between the client and the proxy.
 471           This facility is equivalent to the APDU logging that
 472           happens when using option <literal>-a</literal>, however
 473           this tells the proxy to log in the same file as given
 474           by <literal>-l</literal>.
 475          </entry>
 476         </row>
 477         <row>
 478          <entry><literal>server-apdu</literal></entry>
 479          <entry>
 480           Log APDUs as reported by YAZ for the
 481           communication between the proxy and the server (backend).
 482          </entry>
 483         </row>
 484         <row>
 485          <entry><literal>clients-requests</literal></entry>
 486          <entry>
 487           Log a brief description about requests transferred between
 488           the client and the proxy. The name of the request and the size
 489           of the APDU is logged.
 490          </entry>
 491         </row>
 492         <row>
 493          <entry><literal>server-requests</literal></entry>
 494          <entry>
 495           Log a brief description about requests transferred between
 496           the proxy and the server (backend). The name of the request
 497           and the size of the APDU is logged.
 498          </entry>
 499         </row>
 500        </tbody>
 501       </tgroup>
 502      </table>
 503     </para>
 504     <para>
 505      To log communication in details between the proxy and the backend, th
 506      following configuration could be used:
 507      <screen><![CDATA[
 508       <target name="mytarget">
 509        <log>server-apdu server-requests</log>
 510       </target>
 511       ]]>
 512      </screen>
 513     </para>
 514    </section>
 515   </section>
 516
 517   <section id="query-cache">
 518    <title>Query Caching</title>
 519    <para>
 520     Simple stateless clients often send identical Z39.50 searches
 521     in a relatively short period of time (e.g. in order to produce a
 522     results-list page, the next page,
 523     a single full-record, etc). And for many targets, it's
 524     much more expensive to produce a new result set than to
 525     reuse an existing one.
 526    </para>
 527    <para>
 528     The proxy tries to solve that by remembering the last query for each
 529     backend target, so that if an identical query is received next, it
 530     is turned into Present Requests rather than new Search Requests.
 531    </para>
 532    <note>
 533     <para>
 534      In a future we release will will probably allows for
 535      an arbitrary-sized cache for targets supporting named result sets.
 536     </para>
 537    </note>
 538    <para>
 539     You can enable/disable query caching using option -o.
 540    </para>
 541   </section>
 542
 543   <section id="record-cache">
 544    <title>Record Caching</title>
 545    <para>
 546     As an option, the proxy may also cache result set records for the
 547     last search.
 548     The proxy takes into account the Record Syntax and CompSpec.
 549     The CompSpec includes simple element set names as well.
 550     By default the cache is 200000 bytes per session.
 551    </para>
 552   </section>
 553
 554   <section id="query-validation">
 555    <title>Query Validation</title>
 556    <para>
 557     The Proxy may also be configured to trap particular attributes in
 558     Type-1 queries and send Bib-1 diagnostics back to the client without
 559     even consulting the backend target. This facility may be useful if
 560     a target does not properly issue diagnostics when unsupported attributes
 561     are send to it.
 562    </para>
 563   </section>
 564
 565    <section id="record-validation">
 566    <title>Record Syntax Validation</title>
 567    <para>
 568     The proxy may be configured to accept, reject or convert records.
 569     When accepted, the target passes search/present requests to the
 570     backend target under the assumption that the target can honor the
 571     request (In fact it may not do that). When a record is rejected because
 572     the record syntax is "unsupported" the proxy returns a diagnostic to the
 573     client. Finally, the proxy may convert records.
 574    </para>
 575    <para>
 576     The proxy can convert from MARC to MARCXML and thereby offer an
 577     XML version of any MARC record as long as it is ISO2709 encoded.
 578     If the proxy is compiled with libXSLT support it can also
 579     perform XSLT on XML.
 580    </para>
 581   </section>
 582
 583   <section id="other-optimizations">
 584    <title>Other Optimizations</title>
 585    <para>
 586     We've had some plans to support global caching of result set records,
 587     but this has not yet been implemented.
 588    </para>
 589   </section>
 590
 591   <section id="proxy-usage">
 592    <title>Proxy Usage (man page)</title>
 593    <refentry id="yazproxy-man">
 594     &yaz-proxy-ref;
 595    </refentry>
 596   </section>
 597
 598   <section id="otherinfo-encoding">
 599    <title>OtherInformation Encoding</title>
 600    <para>
 601     The proxy uses the OtherInformation definition to carry
 602     information about the target address and cookie.
 603    </para>
 604    <screen>
 605   OtherInformation   ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{
 606     category           [1]   IMPLICIT InfoCategory OPTIONAL,
 607     information        CHOICE{
 608       characterInfo            [2]  IMPLICIT InternationalString,
 609       binaryInfo               [3]  IMPLICIT OCTET STRING,
 610       externallyDefinedInfo    [4]  IMPLICIT EXTERNAL,
 611       oid                      [5]  IMPLICIT OBJECT IDENTIFIER}}
 612 --
 613   InfoCategory ::= SEQUENCE{
 614       categoryTypeId   [1]   IMPLICIT OBJECT IDENTIFIER OPTIONAL,
 615       categoryValue    [2]   IMPLICIT INTEGER}
 616   </screen>
 617    <para>
 618     The <literal>categoryTypeId</literal> is either
 619     OID 1.2.840.10003.10.1000.81.1, 1.2.840.10003.10.1000.81.2
 620     for proxy target and proxy cookie respectively. The
 621     integer element <literal>category</literal> is set to 0.
 622     The value proxy and cookie is stored in element
 623     <literal>characterInfo</literal> of the <literal>information</literal>
 624      choice.
 625    </para>
 626    </section>
 627  </chapter>
 628
 629  <!-- Keep this comment at the end of the file
 630  Local variables:
 631  mode: sgml
 632  sgml-omittag:t
 633  sgml-shorttag:t
 634  sgml-minimize-attributes:nil
 635  sgml-always-quote-attributes:t
 636  sgml-indent-step:1
 637  sgml-indent-data:t
 638  sgml-parent-document: "yazproxy.xml"
 639  sgml-local-catalogs: nil
 640  sgml-namecase-general:t
 641  End:
 642  -->
 643