doc/administration.xml

   1 <chapter id="administration">
   2  <!-- $Id: administration.xml,v 1.8 2002-10-11 09:05:09 adam Exp $ -->
   3  <title>Administrating Zebra</title>
   4
   5  <para>
   6   Unlike many simpler retrieval systems, Zebra supports safe, incremental
   7   updates to an existing index.
   8  </para>
   9
  10  <para>
  11   Normally, when Zebra modifies the index it reads a number of records
  12   that you specify.
  13   Depending on your specifications and on the contents of each record
  14   one the following events take place for each record:
  15   <variablelist>
  16
  17    <varlistentry>
  18     <term>Insert</term>
  19     <listitem>
  20      <para>
  21       The record is indexed as if it never occurred before.
  22       Either the Zebra system doesn't know how to identify the record or
  23       Zebra can identify the record but didn't find it to be already indexed.
  24      </para>
  25     </listitem>
  26    </varlistentry>
  27    <varlistentry>
  28     <term>Modify</term>
  29     <listitem>
  30      <para>
  31       The record has already been indexed.
  32       In this case either the contents of the record or the location
  33       (file) of the record indicates that it has been indexed before.
  34      </para>
  35     </listitem>
  36    </varlistentry>
  37    <varlistentry>
  38     <term>Delete</term>
  39     <listitem>
  40      <para>
  41       The record is deleted from the index. As in the
  42       update-case it must be able to identify the record.
  43      </para>
  44     </listitem>
  45    </varlistentry>
  46   </variablelist>
  47  </para>
  48
  49  <para>
  50   Please note that in both the modify- and delete- case the Zebra
  51   indexer must be able to generate a unique key that identifies the record
  52   in question (more on this below).
  53  </para>
  54
  55  <para>
  56   To administrate the Zebra retrieval system, you run the
  57   <literal>zebraidx</literal> program.
  58   This program supports a number of options which are preceded by a dash,
  59   and a few commands (not preceded by dash).
  60 </para>
  61
  62  <para>
  63   Both the Zebra administrative tool and the Z39.50 server share a
  64   set of index files and a global configuration file.
  65   The name of the configuration file defaults to
  66   <literal>zebra.cfg</literal>.
  67   The configuration file includes specifications on how to index
  68   various kinds of records and where the other configuration files
  69   are located. <literal>zebrasrv</literal> and <literal>zebraidx</literal>
  70   <emphasis>must</emphasis> be run in the directory where the
  71   configuration file lives unless you indicate the location of the
  72   configuration file by option <literal>-c</literal>.
  73  </para>
  74
  75  <sect1 id="record-types">
  76   <title>Record Types</title>
  77
  78   <para>
  79    Indexing is a per-record process, in which either insert/modify/delete
  80    will occur. Before a record is indexed search keys are extracted from
  81    whatever might be the layout the original record (sgml,html,text, etc..).
  82    The Zebra system currently supports two fundamental types of records:
  83    structured and simple text.
  84    To specify a particular extraction process, use either the
  85    command line option <literal>-t</literal> or specify a
  86    <literal>recordType</literal> setting in the configuration file.
  87   </para>
  88
  89  </sect1>
  90
  91  <sect1 id="configuration-file">
  92   <title>The Zebra Configuration File</title>
  93
  94   <para>
  95    The Zebra configuration file, read by <literal>zebraidx</literal> and
  96    <literal>zebrasrv</literal> defaults to <literal>zebra.cfg</literal>
  97    unless specified by <literal>-c</literal> option.
  98   </para>
  99
 100   <para>
 101    You can edit the configuration file with a normal text editor.
 102    parameter names and values are separated by colons in the file. Lines
 103    starting with a hash sign (<literal>&num;</literal>) are
 104    treated as comments.
 105   </para>
 106
 107   <para>
 108    If you manage different sets of records that share common
 109    characteristics, you can organize the configuration settings for each
 110    type into "groups".
 111    When <literal>zebraidx</literal> is run and you wish to address a
 112    given group you specify the group name with the <literal>-g</literal>
 113    option.
 114    In this case settings that have the group name as their prefix
 115    will be used by <literal>zebraidx</literal>.
 116    If no <literal>-g</literal> option is specified, the settings
 117    without prefix are used.
 118   </para>
 119
 120   <para>
 121    In the configuration file, the group name is placed before the option
 122    name itself, separated by a dot (.). For instance, to set the record type
 123    for group <literal>public</literal> to <literal>grs.sgml</literal>
 124    (the SGML-like format for structured records) you would write:
 125   </para>
 126
 127   <para>
 128    <screen>
 129     public.recordType: grs.sgml
 130    </screen>
 131   </para>
 132
 133   <para>
 134    To set the default value of the record type to <literal>text</literal>
 135    write:
 136   </para>
 137
 138   <para>
 139    <screen>
 140     recordType: text
 141    </screen>
 142   </para>
 143
 144   <para>
 145    The available configuration settings are summarized below. They will be
 146    explained further in the following sections.
 147   </para>
 148
 149   <!--
 150    FIXME - Didn't Adam make something to have multiple databases in multiple dirs...
 151   -->
 152
 153   <para>
 154    <variablelist>
 155
 156     <varlistentry>
 157      <term>
 158       <emphasis>group</emphasis>
 159       .recordType&lsqb;<emphasis>.name</emphasis>&rsqb;:
 160       <replaceable>type</replaceable>
 161      </term>
 162      <listitem>
 163       <para>
 164        Specifies how records with the file extension
 165        <emphasis>name</emphasis> should be handled by the indexer.
 166        This option may also be specified as a command line option
 167        (<literal>-t</literal>). Note that if you do not specify a
 168        <emphasis>name</emphasis>, the setting applies to all files.
 169        In general, the record type specifier consists of the elements (each
 170        element separated by dot), <emphasis>fundamental-type</emphasis>,
 171        <emphasis>file-read-type</emphasis> and arguments. Currently, two
 172        fundamental types exist, <literal>text</literal> and
 173        <literal>grs</literal>.
 174       </para>
 175      </listitem>
 176     </varlistentry>
 177     <varlistentry>
 178      <term><emphasis>group</emphasis>.recordId:
 179      <replaceable>record-id-spec</replaceable></term>
 180      <listitem>
 181       <para>
 182        Specifies how the records are to be identified when updated. See
 183        <xref linkend="locating-records"/>.
 184       </para>
 185      </listitem>
 186     </varlistentry>
 187     <varlistentry>
 188      <term><emphasis>group</emphasis>.database:
 189      <replaceable>database</replaceable></term>
 190      <listitem>
 191       <para>
 192        Specifies the Z39.50 database name.
 193        <!-- FIXME - now we can have multiple databases in one server. -H -->
 194       </para>
 195      </listitem>
 196     </varlistentry>
 197     <varlistentry>
 198      <term><emphasis>group</emphasis>.storeKeys:
 199      <replaceable>boolean</replaceable></term>
 200      <listitem>
 201       <para>
 202        Specifies whether key information should be saved for a given
 203        group of records. If you plan to update/delete this type of
 204        records later this should be specified as 1; otherwise it
 205        should be 0 (default), to save register space.
 206        See <xref linkend="file-ids"/>.
 207       </para>
 208      </listitem>
 209     </varlistentry>
 210     <varlistentry>
 211      <term><emphasis>group</emphasis>.storeData:
 212       <replaceable>boolean</replaceable></term>
 213      <listitem>
 214       <para>
 215        Specifies whether the records should be stored internally
 216        in the Zebra system files.
 217        If you want to maintain the raw records yourself,
 218        this option should be false (0).
 219        If you want Zebra to take care of the records for you, it
 220        should be true(1).
 221       </para>
 222      </listitem>
 223     </varlistentry>
 224     <varlistentry>
 225      <term>register: <replaceable>register-location</replaceable></term>
 226      <listitem>
 227       <para>
 228        Specifies the location of the various register files that Zebra uses
 229        to represent your databases.
 230        See <xref linkend="register-location"/>.
 231       </para>
 232      </listitem>
 233     </varlistentry>
 234     <varlistentry>
 235      <term>shadow: <replaceable>register-location</replaceable></term>
 236      <listitem>
 237       <para>
 238        Enables the <emphasis>safe update</emphasis> facility of Zebra, and
 239        tells the system where to place the required, temporary files.
 240        See <xref linkend="shadow-registers"/>.
 241       </para>
 242      </listitem>
 243     </varlistentry>
 244     <varlistentry>
 245      <term>lockDir: <replaceable>directory</replaceable></term>
 246      <listitem>
 247       <para>
 248        Directory in which various lock files are stored.
 249       </para>
 250      </listitem>
 251     </varlistentry>
 252     <varlistentry>
 253      <term>keyTmpDir: <replaceable>directory</replaceable></term>
 254      <listitem>
 255       <para>
 256        Directory in which temporary files used during zebraidx' update
 257        phase are stored.
 258       </para>
 259      </listitem>
 260     </varlistentry>
 261     <varlistentry>
 262      <term>setTmpDir: <replaceable>directory</replaceable></term>
 263      <listitem>
 264       <para>
 265        Specifies the directory that the server uses for temporary result sets.
 266        If not specified <literal>/tmp</literal> will be used.
 267       </para>
 268      </listitem>
 269     </varlistentry>
 270     <varlistentry>
 271      <term>profilePath: <literal>path</literal></term>
 272      <listitem>
 273       <para>
 274        Specifies a path of profile specification files.
 275        The path is composed of one or more directories separated by
 276        colon. Similar to PATH for UNIX systems.
 277       </para>
 278      </listitem>
 279     </varlistentry>
 280     <varlistentry>
 281      <term>attset: <replaceable>filename</replaceable></term>
 282      <listitem>
 283       <para>
 284        Specifies the filename(s) of attribute set files for use in
 285        searching. At least the Bib-1 set should be loaded
 286        (<literal>bib1.att</literal>).
 287        The <literal>profilePath</literal> setting is used to look for
 288        the specified files.
 289        See <xref linkend="attset-files"/>
 290       </para>
 291      </listitem>
 292     </varlistentry>
 293     <varlistentry>
 294      <term>memMax: <replaceable>size</replaceable></term>
 295      <listitem>
 296       <para>
 297        Specifies <replaceable>size</replaceable> of internal memory
 298        to use for the zebraidx program.
 299        The amount is given in megabytes - default is 4 (4 MB).
 300       </para>
 301      </listitem>
 302     </varlistentry>
 303
 304     <varlistentry>
 305      <term>root: <replaceable>dir</replaceable></term>
 306      <listitem>
 307       <para>
 308        Specifies a directory base for Zebra. All relative paths
 309        given (in profilePath, register, shadow) are based on this
 310        directory. This setting is useful if if you Zebra server
 311        is running in a different directory from where
 312        <literal>zebra.cfg</literal> is located.
 313       </para>
 314      </listitem>
 315     </varlistentry>
 316
 317    </variablelist>
 318   </para>
 319
 320  </sect1>
 321
 322  <sect1 id="locating-records">
 323   <title>Locating Records</title>
 324
 325   <para>
 326    The default behavior of the Zebra system is to reference the
 327    records from their original location, i.e. where they were found when you
 328    ran <literal>zebraidx</literal>.
 329    That is, when a client wishes to retrieve a record
 330    following a search operation, the files are accessed from the place
 331    where you originally put them - if you remove the files (without
 332    running <literal>zebraidx</literal> again, the client
 333    will receive a diagnostic message.
 334   </para>
 335
 336   <para>
 337    If your input files are not permanent - for example if you retrieve
 338    your records from an outside source, or if they were temporarily
 339    mounted on a CD-ROM drive,
 340    you may want Zebra to make an internal copy of them. To do this,
 341    you specify 1 (true) in the <literal>storeData</literal> setting. When
 342    the Z39.50 server retrieves the records they will be read from the
 343    internal file structures of the system.
 344   </para>
 345
 346  </sect1>
 347
 348  <sect1 id="simple-indexing">
 349   <title>Indexing with no Record IDs (Simple Indexing)</title>
 350
 351   <para>
 352    If you have a set of records that are not expected to change over time
 353    you may can build your database without record IDs.
 354    This indexing method uses less space than the other methods and
 355    is simple to use.
 356   </para>
 357
 358   <para>
 359    To use this method, you simply omit the <literal>recordId</literal> entry
 360    for the group of files that you index. To add a set of records you use
 361    <literal>zebraidx</literal> with the <literal>update</literal> command. The
 362    <literal>update</literal> command will always add all of the records that it
 363    encounters to the index - whether they have already been indexed or
 364    not. If the set of indexed files change, you should delete all of the
 365    index files, and build a new index from scratch.
 366   </para>
 367
 368   <para>
 369    Consider a system in which you have a group of text files called
 370    <literal>simple</literal>.
 371    That group of records should belong to a Z39.50 database called
 372    <literal>textbase</literal>.
 373    The following <literal>zebra.cfg</literal> file will suffice:
 374   </para>
 375   <para>
 376
 377    <screen>
 378     profilePath: /usr/local/yaz
 379     attset: bib1.att
 380     simple.recordType: text
 381     simple.database: textbase
 382    </screen>
 383
 384   </para>
 385
 386   <para>
 387    Since the existing records in an index can not be addressed by their
 388    IDs, it is impossible to delete or modify records when using this method.
 389   </para>
 390
 391  </sect1>
 392
 393  <sect1 id="file-ids">
 394   <title>Indexing with File Record IDs</title>
 395
 396   <para>
 397    If you have a set of files that regularly change over time: Old files
 398    are deleted, new ones are added, or existing files are modified, you
 399    can benefit from using the <emphasis>file ID</emphasis>
 400    indexing methodology.
 401    Examples of this type of database might include an index of WWW
 402    resources, or a USENET news spool area.
 403    Briefly speaking, the file key methodology uses the directory paths
 404    of the individual records as a unique identifier for each record.
 405    To perform indexing of a directory with file keys, again, you specify
 406    the top-level directory after the <literal>update</literal> command.
 407    The command will recursively traverse the directories and compare
 408    each one with whatever have been indexed before in that same directory.
 409    If a file is new (not in the previous version of the directory) it
 410    is inserted into the registers; if a file was already indexed and
 411    it has been modified since the last update, the index is also
 412    modified; if a file has been removed since the last
 413    visit, it is deleted from the index.
 414   </para>
 415
 416   <para>
 417    The resulting system is easy to administrate. To delete a record you
 418    simply have to delete the corresponding file (say, with the
 419    <literal>rm</literal> command). And to add records you create new
 420    files (or directories with files). For your changes to take effect
 421    in the register you must run <literal>zebraidx update</literal> with
 422    the same directory root again. This mode of operation requires more
 423    disk space than simpler indexing methods, but it makes it easier for
 424    you to keep the index in sync with a frequently changing set of data.
 425    If you combine this system with the <emphasis>safe update</emphasis>
 426    facility (see below), you never have to take your server off-line for
 427    maintenance or register updating purposes.
 428   </para>
 429
 430   <para>
 431    To enable indexing with pathname IDs, you must specify
 432    <literal>file</literal> as the value of <literal>recordId</literal>
 433    in the configuration file. In addition, you should set
 434    <literal>storeKeys</literal> to <literal>1</literal>, since the Zebra
 435    indexer must save additional information about the contents of each record
 436    in order to modify the indexes correctly at a later time.
 437   </para>
 438
 439    <!--
 440     FIXME - There must be a simpler way to do this with Adams string tags -H
 441      -->
 442
 443   <para>
 444    For example, to update records of group <literal>esdd</literal>
 445    located below
 446    <literal>/data1/records/</literal> you should type:
 447    <screen>
 448     $ zebraidx -g esdd update /data1/records
 449    </screen>
 450   </para>
 451
 452   <para>
 453    The corresponding configuration file includes:
 454    <screen>
 455     esdd.recordId: file
 456     esdd.recordType: grs.sgml
 457     esdd.storeKeys: 1
 458    </screen>
 459   </para>
 460
 461   <note>
 462    <para>You cannot start out with a group of records with simple
 463     indexing (no record IDs as in the previous section) and then later
 464     enable file record Ids. Zebra must know from the first time that you
 465     index the group that
 466     the files should be indexed with file record IDs.
 467    </para>
 468    </note>
 469
 470   <para>
 471    You cannot explicitly delete records when using this method (using the
 472    <literal>delete</literal> command to <literal>zebraidx</literal>. Instead
 473    you have to delete the files from the file system (or move them to a
 474    different location)
 475    and then run <literal>zebraidx</literal> with the
 476    <literal>update</literal> command.
 477   </para>
 478 </sect1>
 479
 480  <sect1 id="generic-ids">
 481   <title>Indexing with General Record IDs</title>
 482
 483   <para>
 484    When using this method you construct an (almost) arbitrary, internal
 485    record key based on the contents of the record itself and other system
 486    information. If you have a group of records that explicitly associates
 487    an ID with each record, this method is convenient. For example, the
 488    record format may contain a title or a ID-number - unique within the group.
 489    In either case you specify the Z39.50 attribute set and use-attribute
 490    location in which this information is stored, and the system looks at
 491    that field to determine the identity of the record.
 492   </para>
 493
 494   <para>
 495    As before, the record ID is defined by the <literal>recordId</literal>
 496    setting in the configuration file. The value of the record ID specification
 497    consists of one or more tokens separated by whitespace. The resulting
 498    ID is represented in the index by concatenating the tokens and
 499    separating them by ASCII value (1).
 500   </para>
 501
 502   <para>
 503    There are three kinds of tokens:
 504    <variablelist>
 505
 506     <varlistentry>
 507      <term>Internal record info</term>
 508      <listitem>
 509       <para>
 510        The token refers to a key that is
 511        extracted from the record. The syntax of this token is
 512        <literal>(</literal> <emphasis>set</emphasis> <literal>,</literal>
 513        <emphasis>use</emphasis> <literal>)</literal>,
 514        where <emphasis>set</emphasis> is the
 515        attribute set name <emphasis>use</emphasis> is the
 516        name or value of the attribute.
 517       </para>
 518      </listitem>
 519     </varlistentry>
 520     <varlistentry>
 521      <term>System variable</term>
 522      <listitem>
 523       <para>
 524        The system variables are preceded by
 525
 526        <screen>
 527         $
 528        </screen>
 529        and immediately followed by the system variable name, which
 530        may one of
 531        <variablelist>
 532
 533         <varlistentry>
 534          <term>group</term>
 535          <listitem>
 536           <para>
 537            Group name.
 538           </para>
 539          </listitem>
 540         </varlistentry>
 541         <varlistentry>
 542          <term>database</term>
 543          <listitem>
 544           <para>
 545            Current database specified.
 546           </para>
 547          </listitem>
 548         </varlistentry>
 549         <varlistentry>
 550          <term>type</term>
 551          <listitem>
 552           <para>
 553            Record type.
 554           </para>
 555          </listitem>
 556         </varlistentry>
 557        </variablelist>
 558       </para>
 559      </listitem>
 560     </varlistentry>
 561     <varlistentry>
 562      <term>Constant string</term>
 563      <listitem>
 564       <para>
 565        A string used as part of the ID &mdash; surrounded
 566        by single- or double quotes.
 567       </para>
 568      </listitem>
 569     </varlistentry>
 570    </variablelist>
 571   </para>
 572
 573   <para>
 574    For instance, the sample GILS records that come with the Zebra
 575    distribution contain a unique ID in the data tagged Control-Identifier.
 576    The data is mapped to the Bib-1 use attribute Identifier-standard
 577    (code 1007). To use this field as a record id, specify
 578    <literal>(bib1,Identifier-standard)</literal> as the value of the
 579    <literal>recordId</literal> in the configuration file.
 580    If you have other record types that uses the same field for a
 581    different purpose, you might add the record type
 582    (or group or database name) to the record id of the gils
 583    records as well, to prevent matches with other types of records.
 584    In this case the recordId might be set like this:
 585
 586    <screen>
 587     gils.recordId: $type (bib1,Identifier-standard)
 588    </screen>
 589
 590   </para>
 591
 592   <para>
 593    (see <xref linkend="data-model"/>
 594     for details of how the mapping between elements of your records and
 595     searchable attributes is established).
 596   </para>
 597
 598   <para>
 599    As for the file record ID case described in the previous section,
 600    updating your system is simply a matter of running
 601    <literal>zebraidx</literal>
 602    with the <literal>update</literal> command. However, the update with general
 603    keys is considerably slower than with file record IDs, since all files
 604    visited must be (re)read to discover their IDs.
 605   </para>
 606
 607   <para>
 608    As you might expect, when using the general record IDs
 609    method, you can only add or modify existing records with the
 610    <literal>update</literal> command.
 611    If you wish to delete records, you must use the,
 612    <literal>delete</literal> command, with a directory as a parameter.
 613    This will remove all records that match the files below that root
 614    directory.
 615   </para>
 616
 617  </sect1>
 618
 619  <sect1 id="register-location">
 620   <title>Register Location</title>
 621
 622   <para>
 623    Normally, the index files that form dictionaries, inverted
 624    files, record info, etc., are stored in the directory where you run
 625    <literal>zebraidx</literal>. If you wish to store these, possibly large,
 626    files somewhere else, you must add the <literal>register</literal>
 627    entry to the <literal>zebra.cfg</literal> file.
 628    Furthermore, the Zebra system allows its file
 629    structures to span multiple file systems, which is useful for
 630    managing very large databases.
 631   </para>
 632
 633   <para>
 634    The value of the <literal>register</literal> setting is a sequence
 635    of tokens. Each token takes the form:
 636
 637    <screen>
 638     <emphasis>dir</emphasis><literal>:</literal><emphasis>size</emphasis>.
 639    </screen>
 640
 641    The <emphasis>dir</emphasis> specifies a directory in which index files
 642    will be stored and the <emphasis>size</emphasis> specifies the maximum
 643    size of all files in that directory. The Zebra indexer system fills
 644    each directory in the order specified and use the next specified
 645    directories as needed.
 646    The <emphasis>size</emphasis> is an integer followed by a qualifier
 647    code,
 648    <literal>b</literal> for bytes,
 649    <literal>k</literal> for kilobytes.
 650    <literal>M</literal> for megabytes,
 651    <literal>G</literal> for gigabytes.
 652   </para>
 653
 654   <para>
 655    For instance, if you have allocated two disks for your register, and
 656    the first disk is mounted
 657    on <literal>/d1</literal> and has 2GB of free space and the
 658    second, mounted on <literal>/d2</literal> has 3.6 GB, you could
 659    put this entry in your configuration file:
 660
 661    <screen>
 662     register: /d1:2G /d2:3600M
 663    </screen>
 664
 665   </para>
 666
 667   <para>
 668    Note that Zebra does not verify that the amount of space specified is
 669    actually available on the directory (file system) specified - it is
 670    your responsibility to ensure that enough space is available, and that
 671    other applications do not attempt to use the free space. In a large
 672    production system, it is recommended that you allocate one or more
 673    file system exclusively to the Zebra register files.
 674   </para>
 675
 676  </sect1>
 677
 678  <sect1 id="shadow-registers">
 679   <title>Safe Updating - Using Shadow Registers</title>
 680
 681   <sect2>
 682    <title>Description</title>
 683
 684    <para>
 685     The Zebra server supports <emphasis>updating</emphasis> of the index
 686     structures. That is, you can add, modify, or remove records from
 687     databases managed by Zebra without rebuilding the entire index.
 688     Since this process involves modifying structured files with various
 689     references between blocks of data in the files, the update process
 690     is inherently sensitive to system crashes, or to process interruptions:
 691     Anything but a successfully completed update process will leave the
 692     register files in an unknown state, and you will essentially have no
 693     recourse but to re-index everything, or to restore the register files
 694     from a backup medium.
 695     Further, while the update process is active, users cannot be
 696     allowed to access the system, as the contents of the register files
 697     may change unpredictably.
 698    </para>
 699
 700    <para>
 701     You can solve these problems by enabling the shadow register system in
 702     Zebra.
 703     During the updating procedure, <literal>zebraidx</literal> will temporarily
 704     write changes to the involved files in a set of "shadow
 705     files", without modifying the files that are accessed by the
 706     active server processes. If the update procedure is interrupted by a
 707     system crash or a signal, you simply repeat the procedure - the
 708     register files have not been changed or damaged, and the partially
 709     written shadow files are automatically deleted before the new updating
 710     procedure commences.
 711    </para>
 712
 713    <para>
 714     At the end of the updating procedure (or in a separate operation, if
 715     you so desire), the system enters a "commit mode". First,
 716     any active server processes are forced to access those blocks that
 717     have been changed from the shadow files rather than from the main
 718     register files; the unmodified blocks are still accessed at their
 719     normal location (the shadow files are not a complete copy of the
 720     register files - they only contain those parts that have actually been
 721     modified). If the commit process is interrupted at any point during the
 722     commit process, the server processes will continue to access the
 723     shadow files until you can repeat the commit procedure and complete
 724     the writing of data to the main register files. You can perform
 725     multiple update operations to the registers before you commit the
 726     changes to the system files, or you can execute the commit operation
 727     at the end of each update operation. When the commit phase has
 728     completed successfully, any running server processes are instructed to
 729     switch their operations to the new, operational register, and the
 730     temporary shadow files are deleted.
 731    </para>
 732
 733   </sect2>
 734
 735   <sect2>
 736    <title>How to Use Shadow Register Files</title>
 737
 738    <para>
 739     The first step is to allocate space on your system for the shadow
 740     files.
 741     You do this by adding a <literal>shadow</literal> entry to the
 742     <literal>zebra.cfg</literal> file.
 743     The syntax of the <literal>shadow</literal> entry is exactly the
 744     same as for the <literal>register</literal> entry
 745     (see <xref linkend="register-location"/>).
 746      The location of the shadow area should be
 747      <emphasis>different</emphasis> from the location of the main register
 748      area (if you have specified one - remember that if you provide no
 749      <literal>register</literal> setting, the default register area is the
 750      working directory of the server and indexing processes).
 751    </para>
 752
 753    <para>
 754     The following excerpt from a <literal>zebra.cfg</literal> file shows
 755     one example of a setup that configures both the main register
 756     location and the shadow file area.
 757     Note that two directories or partitions have been set aside
 758     for the shadow file area. You can specify any number of directories
 759     for each of the file areas, but remember that there should be no
 760     overlaps between the directories used for the main registers and the
 761     shadow files, respectively.
 762    </para>
 763    <para>
 764
 765     <screen>
 766      register: /d1:500M
 767
 768      shadow: /scratch1:100M /scratch2:200M
 769     </screen>
 770
 771    </para>
 772
 773    <para>
 774     When shadow files are enabled, an extra command is available at the
 775     <literal>zebraidx</literal> command line.
 776     In order to make changes to the system take effect for the
 777     users, you'll have to submit a "commit" command after a
 778     (sequence of) update operation(s).
 779    </para>
 780
 781    <para>
 782
 783     <screen>
 784      $ zebraidx update /d1/records
 785      $ zebraidx commit
 786     </screen>
 787
 788    </para>
 789
 790    <para>
 791     Or you can execute multiple updates before committing the changes:
 792    </para>
 793
 794    <para>
 795
 796     <screen>
 797      $ zebraidx -g books update /d1/records  /d2/more-records
 798      $ zebraidx -g fun update /d3/fun-records
 799      $ zebraidx commit
 800     </screen>
 801
 802    </para>
 803
 804    <para>
 805     If one of the update operations above had been interrupted, the commit
 806     operation on the last line would fail: <literal>zebraidx</literal>
 807     will not let you commit changes that would destroy the running register.
 808     You'll have to rerun all of the update operations since your last
 809     commit operation, before you can commit the new changes.
 810    </para>
 811
 812    <para>
 813     Similarly, if the commit operation fails, <literal>zebraidx</literal>
 814     will not let you start a new update operation before you have
 815     successfully repeated the commit operation.
 816     The server processes will keep accessing the shadow files rather
 817     than the (possibly damaged) blocks of the main register files
 818     until the commit operation has successfully completed.
 819    </para>
 820
 821    <para>
 822     You should be aware that update operations may take slightly longer
 823     when the shadow register system is enabled, since more file access
 824     operations are involved. Further, while the disk space required for
 825     the shadow register data is modest for a small update operation, you
 826     may prefer to disable the system if you are adding a very large number
 827     of records to an already very large database (we use the terms
 828     <emphasis>large</emphasis> and <emphasis>modest</emphasis>
 829     very loosely here, since every application will have a
 830     different perception of size).
 831     To update the system without the use of the the shadow files,
 832     simply run <literal>zebraidx</literal> with the <literal>-n</literal>
 833     option (note that you do not have to execute the
 834     <emphasis>commit</emphasis> command of <literal>zebraidx</literal>
 835     when you temporarily disable the use of the shadow registers in
 836     this fashion.
 837     Note also that, just as when the shadow registers are not enabled,
 838     server processes will be barred from accessing the main register
 839     while the update procedure takes place.
 840    </para>
 841
 842   </sect2>
 843
 844  </sect1>
 845
 846 </chapter>
 847  <!-- Keep this comment at the end of the file
 848  Local variables:
 849  mode: sgml
 850  sgml-omittag:t
 851  sgml-shorttag:t
 852  sgml-minimize-attributes:nil
 853  sgml-always-quote-attributes:t
 854  sgml-indent-step:1
 855  sgml-indent-data:t
 856  sgml-parent-document: "zebra.xml"
 857  sgml-local-catalogs: nil
 858  sgml-namecase-general:t
 859  End:
 860  -->