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