doc/server.xml

   1 <chapter id="server">
   2  <!-- $Id: server.xml,v 1.3 2002-04-10 14:47:49 heikki Exp $ -->
   3  <title>The Z39.50 Server</title>
   4
   5  <sect1 id="zebrasrv">
   6   <title>Running the Z39.50 Server (zebrasrv)</title>
   7
   8   <para>
   9    FIXME - We need to be consistent here, zebraidx had the options at the
  10            end, and lots of explaining text before them. Same for zebrasvr! -H
  11    FIXME - At least we need a small intro, what is zebrasvr, and how it
  12            can be run (inetd, nt service, stand-alone program, daemon...) -H
  13   </para>
  14
  15   <para>
  16    <emphasis remap="bf">Syntax</emphasis>
  17
  18    <screen>
  19     zebrasrv &lsqb;options&rsqb; &lsqb;listener-address ...&rsqb;
  20    </screen>
  21
  22   </para>
  23
  24   <para>
  25    <emphasis remap="bf">Options</emphasis>
  26    <variablelist>
  27
  28     <varlistentry>
  29      <term>-a <replaceable>APDU file</replaceable></term>
  30      <listitem>
  31       <para>
  32        Specify a file for dumping PDUs (for diagnostic purposes).
  33        The special name "-" sends output to <literal>stderr</literal>.
  34       </para>
  35      </listitem>
  36     </varlistentry>
  37     <varlistentry>
  38      <term>-c <replaceable>config-file</replaceable></term>
  39      <listitem>
  40       <para>
  41        Read configuration information from
  42        <replaceable>config-file</replaceable>.
  43        The default configuration is <literal>./zebra.cfg</literal>.
  44       </para>
  45      </listitem>
  46     </varlistentry>
  47     <varlistentry>
  48      <term>-S</term>
  49      <listitem>
  50       <para>
  51        Don't fork on connection requests. This can be useful for
  52        symbolic-level debugging. The server can only accept a single
  53        connection in this mode.
  54       </para>
  55      </listitem>
  56     </varlistentry>
  57     <varlistentry>
  58      <term>-z</term>
  59      <listitem>
  60       <para>
  61        Use the Z39.50 protocol. Currently the only protocol supported.
  62        The option is retained for historical reasons, and for future
  63        extensions.
  64       </para>
  65      </listitem>
  66     </varlistentry>
  67     <varlistentry>
  68      <term>-l <replaceable>logfile</replaceable></term>
  69      <listitem>
  70       <para>
  71        Specify an output file for the diagnostic messages.
  72        The default is to write this information to <literal>stderr</literal>.
  73       </para>
  74      </listitem>
  75     </varlistentry>
  76     <varlistentry>
  77      <term>-v <replaceable>log-level</replaceable></term>
  78      <listitem>
  79       <para>
  80        The log level. Use a comma-separated list of members of the set
  81        &lcub;fatal,debug,warn,log,all,none&rcub;.
  82       </para>
  83      </listitem>
  84     </varlistentry>
  85     <varlistentry>
  86      <term>-u <replaceable>username</replaceable></term>
  87      <listitem>
  88       <para>
  89        Set user ID. Sets the real UID of the server process to that of the
  90        given <replaceable>username</replaceable>.
  91        It's useful if you aren't comfortable with having the
  92        server run as root, but you need to start it as such to bind a
  93        privileged port.
  94       </para>
  95      </listitem>
  96     </varlistentry>
  97     <varlistentry>
  98      <term>-w <replaceable>working-directory</replaceable></term>
  99      <listitem>
 100       <para>
 101        Change working directory.
 102       </para>
 103      </listitem>
 104     </varlistentry>
 105     <varlistentry>
 106      <term>-i</term>
 107      <listitem>
 108       <para>
 109        Run under the Internet superserver, <literal>inetd</literal>.
 110        Make sure you use the logfile option <literal>-l</literal> in
 111        conjunction with this mode and specify the <literal>-l</literal>
 112        option before any other options.
 113       </para>
 114      </listitem>
 115     </varlistentry>
 116     <varlistentry>
 117      <term>-t <replaceable>timeout</replaceable></term>
 118      <listitem>
 119       <para>
 120        Set the idle session timeout (default 60 minutes).
 121       </para>
 122      </listitem>
 123     </varlistentry>
 124     <varlistentry>
 125      <term>-k <replaceable>kilobytes</replaceable></term>
 126      <listitem>
 127       <para>
 128        Set the (approximate) maximum size of
 129        present response messages. Default is 1024 KB (1 MB).
 130       </para>
 131      </listitem>
 132     </varlistentry>
 133    </variablelist>
 134   </para>
 135
 136   <para>
 137    A <replaceable>listener-address</replaceable> consists of an optional
 138    transport mode followed by a colon (:) followed by a listener address.
 139    The transport mode is either <literal>ssl</literal> or
 140    <literal>tcp</literal> (default).
 141   </para>
 142
 143   <para>
 144    For TCP, an address has the form
 145   </para>
 146
 147   <para>
 148
 149    <screen>
 150     hostname | IP-number &lsqb;: portnumber&rsqb;
 151    </screen>
 152
 153   </para>
 154
 155   <para>
 156    The port number defaults to 210 (standard Z39.50 port) for
 157    privileged users (root), and 9999 for normal users.
 158   </para>
 159
 160   <para>
 161    Examples
 162   </para>
 163
 164   <para>
 165
 166    <screen>
 167     tcp:dranet.dra.com
 168
 169     ssl:secure.lib.com:3000
 170    </screen>
 171
 172   </para>
 173
 174   <para>
 175    In both cases, the special hostname "@" is mapped to
 176    the address INADDR_ANY, which causes the server to listen on any local
 177    interface. To start the server listening on the registered port for
 178    Z39.50, and to drop root privileges once the ports are bound, execute
 179    the server like this (from a root shell):
 180   </para>
 181
 182   <para>
 183
 184    <screen>
 185     zebrasrv -u daemon @
 186    </screen>
 187
 188   </para>
 189
 190   <para>
 191    You can replace <literal>daemon</literal> with another user, eg.
 192    your own account, or a dedicated IR server account.
 193   </para>
 194
 195   <para>
 196    The default behavior for <literal>zebrasrv</literal> is to establish
 197    a single TCP/IP listener, for the Z39.50 protocol, on port 9999.
 198   </para>
 199
 200  </sect1>
 201
 202  <sect1 id="protocol-support">
 203   <title>Z39.50 Protocol Support and Behavior</title>
 204
 205   <sect2>
 206    <title>Initialization</title>
 207
 208    <para>
 209     During initialization, the server will negotiate to version 3 of the
 210     Z39.50 protocol, and the option bits for Search, Present, Scan,
 211     NamedResultSets, and concurrentOperations will be set, if requested by
 212     the client. The maximum PDU size is negotiated down to a maximum of
 213     1 MB by default.
 214    </para>
 215
 216   </sect2>
 217
 218   <sect2 id="search">
 219    <title>Search</title>
 220
 221    <para>
 222     FIXME - Need to explain the string tag stuff before people get bogged
 223             down with all these attribute numbers. Perhaps in its own
 224             chapter? -H
 225    </para>
 226
 227    <para>
 228     The supported query type are 1 and 101. All operators are currently
 229     supported with the restriction that only proximity units of type "word"
 230     are supported for the proximity operator.
 231     Queries can be arbitrarily complex.
 232     Named result sets are supported, and result sets can be used as operands
 233     without limitations.
 234     Searches may span multiple databases.
 235    </para>
 236
 237    <para>
 238     The server has full support for piggy-backed present requests (see
 239     also the following section).
 240    </para>
 241
 242    <para>
 243     <emphasis>Use</emphasis> attributes are interpreted according to the
 244     attribute sets which have been loaded in the
 245     <literal>zebra.cfg</literal> file, and are matched against specific
 246     fields as specified in the <literal>.abs</literal> file which
 247     describes the profile of the records which have been loaded.
 248     If no Use attribute is provided, a default of Bib-1 Any is assumed.
 249    </para>
 250
 251    <para>
 252     If a <emphasis>Structure</emphasis> attribute of
 253     <emphasis>Phrase</emphasis> is used in conjunction with a
 254     <emphasis>Completeness</emphasis> attribute of
 255     <emphasis>Complete (Sub)field</emphasis>, the term is matched
 256     against the contents of the phrase (long word) register, if one
 257     exists for the given <emphasis>Use</emphasis> attribute.
 258     A phrase register is created for those fields in the
 259     <literal>.abs</literal> file that contains a
 260     <literal>p</literal>-specifier.
 261    </para>
 262
 263    <para>
 264     If <emphasis>Structure</emphasis>=<emphasis>Phrase</emphasis> is
 265     used in conjunction with <emphasis>Incomplete Field</emphasis> - the
 266     default value for <emphasis>Completeness</emphasis>, the
 267     search is directed against the normal word registers, but if the term
 268     contains multiple words, the term will only match if all of the words
 269     are found immediately adjacent, and in the given order.
 270     The word search is performed on those fields that are indexed as
 271     type <literal>w</literal> in the <literal>.abs</literal> file.
 272    </para>
 273
 274    <para>
 275     If the <emphasis>Structure</emphasis> attribute is
 276     <emphasis>Word List</emphasis>,
 277     <emphasis>Free-form Text</emphasis>, or
 278     <emphasis>Document Text</emphasis>, the term is treated as a
 279     natural-language, relevance-ranked query.
 280     This search type uses the word register, i.e. those fields
 281     that are indexed as type <literal>w</literal> in the
 282     <literal>.abs</literal> file.
 283    </para>
 284
 285    <para>
 286     If the <emphasis>Structure</emphasis> attribute is
 287     <emphasis>Numeric String</emphasis> the term is treated as an integer.
 288     The search is performed on those fields that are indexed
 289     as type <literal>n</literal> in the <literal>.abs</literal> file.
 290    </para>
 291
 292    <para>
 293     If the <emphasis>Structure</emphasis> attribute is
 294     <emphasis>URx</emphasis> the term is treated as a URX (URL) entity.
 295     The search is performed on those fields that are indexed as type
 296     <literal>u</literal> in the <literal>.abs</literal> file.
 297    </para>
 298
 299    <para>
 300     If the <emphasis>Structure</emphasis> attribute is
 301     <emphasis>Local Number</emphasis> the term is treated as
 302     native Zebra Record Identifier.
 303    </para>
 304
 305    <para>
 306     If the <emphasis>Relation</emphasis> attribute is
 307     <emphasis>Equals</emphasis> (default), the term is matched
 308     in a normal fashion (modulo truncation and processing of
 309     individual words, if required).
 310     If <emphasis>Relation</emphasis> is <emphasis>Less Than</emphasis>,
 311     <emphasis>Less Than or Equal</emphasis>,
 312     <emphasis>Greater than</emphasis>, or <emphasis>Greater than or
 313      Equal</emphasis>, the term is assumed to be numerical, and a
 314     standard regular expression is constructed to match the given
 315     expression.
 316     If <emphasis>Relation</emphasis> is <emphasis>Relevance</emphasis>,
 317     the standard natural-language query processor is invoked.
 318    </para>
 319
 320    <para>
 321     For the <emphasis>Truncation</emphasis> attribute,
 322     <emphasis>No Truncation</emphasis> is the default.
 323     <emphasis>Left Truncation</emphasis> is not supported.
 324     <emphasis>Process &num;</emphasis> is supported, as is
 325     <emphasis>Regxp-1</emphasis>.
 326     <emphasis>Regxp-2</emphasis> enables the fault-tolerant (fuzzy)
 327     search. As a default, a single error (deletion, insertion,
 328     replacement) is accepted when terms are matched against the register
 329     contents.
 330    </para>
 331
 332    <sect3>
 333     <title>Regular expressions</title>
 334
 335     <para>
 336      Each term in a query is interpreted as a regular expression if
 337      the truncation value is either <emphasis>Regxp-1</emphasis> (102)
 338      or <emphasis>Regxp-2</emphasis> (103).
 339      Both query types follow the same syntax with the operands:
 340      <variablelist>
 341
 342       <varlistentry>
 343        <term>x</term>
 344        <listitem>
 345         <para>
 346          Matches the character <emphasis>x</emphasis>.
 347         </para>
 348        </listitem>
 349       </varlistentry>
 350       <varlistentry>
 351        <term>.</term>
 352        <listitem>
 353         <para>
 354          Matches any character.
 355         </para>
 356        </listitem>
 357       </varlistentry>
 358       <varlistentry>
 359        <term><literal>[</literal>..<literal>]</literal></term>
 360        <listitem>
 361         <para>
 362          Matches the set of characters specified;
 363          such as <literal>[abc]</literal> or <literal>[a-c]</literal>.
 364         </para>
 365        </listitem>
 366       </varlistentry>
 367      </variablelist>
 368      and the operators:
 369      <variablelist>
 370
 371       <varlistentry>
 372        <term>x*</term>
 373        <listitem>
 374         <para>
 375          Matches <emphasis>x</emphasis> zero or more times. Priority: high.
 376         </para>
 377        </listitem>
 378       </varlistentry>
 379       <varlistentry>
 380        <term>x+</term>
 381        <listitem>
 382         <para>
 383          Matches <emphasis>x</emphasis> one or more times. Priority: high.
 384         </para>
 385        </listitem>
 386       </varlistentry>
 387       <varlistentry>
 388        <term>x?</term>
 389        <listitem>
 390         <para>
 391          Matches <emphasis>x</emphasis> once or twice. Priority: high.
 392          FIXME Is this right? Std regexp has '?' meaning zero or one -H
 393         </para>
 394        </listitem>
 395       </varlistentry>
 396       <varlistentry>
 397        <term>xy</term>
 398        <listitem>
 399         <para>
 400          Matches <emphasis>x</emphasis>, then <emphasis>y</emphasis>.
 401          Priority: medium.
 402         </para>
 403        </listitem>
 404       </varlistentry>
 405       <varlistentry>
 406        <term>x&verbar;y</term>
 407        <listitem>
 408         <para>
 409          Matches either <emphasis>x</emphasis> or <emphasis>y</emphasis>.
 410          Priority: low.
 411         </para>
 412        </listitem>
 413       </varlistentry>
 414      </variablelist>
 415      The order of evaluation may be changed by using parentheses.
 416     </para>
 417
 418     <para>
 419      If the first character of the <emphasis>Regxp-2</emphasis> query
 420      is a plus character (<literal>+</literal>) it marks the
 421      beginning of a section with non-standard specifiers.
 422      The next plus character marks the end of the section.
 423      Currently Zebra only supports one specifier, the error tolerance,
 424      which consists one digit.
 425     </para>
 426
 427     <para>
 428      Since the plus operator is normally a suffix operator the addition to
 429      the query syntax doesn't violate the syntax for standard regular
 430      expressions.
 431     </para>
 432
 433    </sect3>
 434
 435    <sect3>
 436     <title>Query examples</title>
 437
 438     <para>
 439      Phrase search for <emphasis>information retrieval</emphasis> in
 440      the title-register:
 441      <screen>
 442       @attr 1=4 "information retrieval"
 443      </screen>
 444     </para>
 445
 446     <para>
 447      Ranked search for the same thing:
 448      <screen>
 449       @attr 1=4 @attr 2=102 "Information retrieval"
 450      </screen>
 451     </para>
 452
 453     <para>
 454      Phrase search with a regular expression:
 455      <screen>
 456       @attr 1=4 @attr 5=102 "informat.* retrieval"
 457      </screen>
 458     </para>
 459
 460     <para>
 461      Ranked search with a regular expression:
 462      <screen>
 463       @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval"
 464      </screen>
 465     </para>
 466
 467     <para>
 468      In the GILS schema (<literal>gils.abs</literal>), the
 469      west-bounding-coordinate is indexed as type <literal>n</literal>,
 470      and is therefore searched by specifying
 471      <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
 472      To match all those records with west-bounding-coordinate greater
 473      than -114 we use the following query:
 474      <screen>
 475       @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
 476      </screen>
 477     </para>
 478    </sect3>
 479   </sect2>
 480
 481   <sect2>
 482    <title>Present</title>
 483    <para>
 484     The present facility is supported in a standard fashion. The requested
 485     record syntax is matched against the ones supported by the profile of
 486     each record retrieved. If no record syntax is given, SUTRS is the
 487     default. The requested element set name, again, is matched against any
 488     provided by the relevant record profiles.
 489    </para>
 490   </sect2>
 491   <sect2>
 492    <title>Scan</title>
 493    <para>
 494     The attribute combinations provided with the termListAndStartPoint are
 495     processed in the same way as operands in a query (see above).
 496     Currently, only the term and the globalOccurrences are returned with
 497     the termInfo structure.
 498    </para>
 499   </sect2>
 500   <sect2>
 501    <title>Sort</title>
 502
 503    <para>
 504     Z39.50 specifies three different types of sort criteria.
 505     Of these Zebra supports the attribute specification type in which
 506     case the use attribute specifies the "Sort register".
 507     Sort registers are created for those fields that are of type "sort" in
 508     the default.idx file.
 509     The corresponding character mapping file in default.idx specifies the
 510     ordinal of each character used in the actual sort.
 511    </para>
 512
 513    <para>
 514     Z39.50 allows the client to specify sorting on one or more input
 515     result sets and one output result set.
 516     Zebra supports sorting on one result set only which may or may not
 517     be the same as the output result set.
 518    </para>
 519   </sect2>
 520   <sect2>
 521    <title>Close</title>
 522    <para>
 523     If a Close PDU is received, the server will respond with a Close PDU
 524     with reason=FINISHED, no matter which protocol version was negotiated
 525     during initialization. If the protocol version is 3 or more, the
 526     server will generate a Close PDU under certain circumstances,
 527     including a session timeout (60 minutes by default), and certain kinds of
 528     protocol errors. Once a Close PDU has been sent, the protocol
 529     association is considered broken, and the transport connection will be
 530     closed immediately upon receipt of further data, or following a short
 531     timeout.
 532    </para>
 533   </sect2>
 534  </sect1>
 535 </chapter>
 536  <!-- Keep this comment at the end of the file
 537  Local variables:
 538  mode: sgml
 539  sgml-omittag:t
 540  sgml-shorttag:t
 541  sgml-minimize-attributes:nil
 542  sgml-always-quote-attributes:t
 543  sgml-indent-step:1
 544  sgml-indent-data:t
 545  sgml-parent-document: "zebra.xml"
 546  sgml-local-catalogs: nil
 547  sgml-namecase-general:t
 548  End:
 549  -->