3 Care and maintenance of a SARA server

This section describes how to install and run the SARA server on a UNIX installation. It does not include information about running the server locally, for example on a standalone MS-DOS machine.

Section 3.1 describes run-time options for the server program. Section 3.2 describes the parameter file used to initialize the server.

3.1 Running the server program

When the server program is executed from the Unix command line the following menu appears:

1. Test mode
2. Run server
3. Add user
4. Remove user
5. List users

On receipt of a number between 1 and 5 from the command line, the server switches to the appropriate mode from the list below:

• Test mode: In test mode, the server accepts client commands from the command line. This is very rarely useful: to debug the server, use the testnet program with a properly running server.
• Run server. Execute the server. The server reads the parameter file, initialises the accelerated streams, resets the log file and waits for connections on port 7000 (or whichever port is specified in the parameter file). Note that it is impossible to start the server while connections from the previous server are still active. Use the Unix command netstat to check that the port is free.
• Add user. Add a new user name and password.
• Remove user. Remove a user name.
• List users. List all users and passwords.

Only one instance of SARA server can run at any time on any port. There is, however, no harm in starting a second server to perform other functions, for example to change user names or passwords.

3.2 Parameter file corpus.prm

The behaviour of the server is determined by the settings for a number of parameters which are read from the file corpus.prm at start-up time. This file contains a series of lines in the form parameter=value where parameter is one of the parameters described below.

The same parameter file is used by the indexing program used to build the SARA index. This is further documented elsewhere.

• ACC

  Specifies the name of a directory in which the server will store files relating to users. The server must have write access. The following files are created by the server:

  • users lists user names and passwords in encrypted form
  • syslog complete log of all transactions. This file may get very large, but is very useful for debugging purposes.
  • admlog list of all users logging on and off.
  Note that the syslog file is re-initialised whenever the server starts. A backup will be kept if the BACK parameter (see below) is non-zero.

• ACL Specifies SGML elements for which an accelerator file (a form of index optimization) is available. These entries must not be changed except when re-indexing the corpus: their order is significant, as well as their content.
• BACK Specifies the number of back-up copies of the syslog to be kept. Normally the system log is re-initialized whenever the server starts; if this parameter has a non-zero value, an existing system log will instead be copied to a file of the name syslog.n, where n is smaller than the value specified for this parameter.
• BIB Specifies the location of the file bibliog.sgm which contains the bibliographic information used by the server.
• BUF Specifies the number of local buffers to be assigned to each client session. The default value is 40.
• ETC

  Specifies a path name for the odds-and-ends directory. The server temporarily saves query data in this directory so must have write access to it. The other files in this directory are never altered and are as follows:

  • *.acc accelerated indexes
  • corpus.dct the dictionary
  • files.ndx only used by the index program
  • files.pdx the list of texts and their location
  • corpus.dsc corpus description file (see 2.39 ).
  • motd.txt message of the day shown to clients when they connect
  • pbib index to the bibliography
  Don't alter any of these files except motd.txt.

• EXC Excludes a text in the corpus directory from the indexing process. Not relevant to operation of the server.
• HDR Specifies the directory in which the file corphdr is located. Not relevant to operation of the server.
• IDX Specifies the location of the index. The simplest way of specifying the value is as a path. The index must be stored in subdirectories whose names consist of three digits. If the index is too large to be held in a single directory, then there may be several successive definitions for the IDX variable as in the following example:

  IDX=/corpus/index0/,100
  IDX=/corpus/index1/,200
  IDX=/corpus/index2/
  ACC=~SARA/admin/
  ETC=/tmp/

  This indicates that directories numbered from 000 to 099 are to be found within directory /corpus/index0, directories numbered 100 to 199 in /corpus/index1 and the rest in /corpus/index2.
• INC May be used to limit the indexing process for debugging purposes. If any INC entry is present, then only files specified by INC entries will be indexed. Not relevant to operation of the server.
• LOG If set to 1 then both syslog and admlog files will be kept. If 0, only admlog is kept. Default is 1.
• PORT Set to the number of the port on which clients connect. The server must have access to this port. The default is 7000.
• SORT Specifies the pathname of the directory to be used by the indexer for scratch space while sorting. Not relevant to operation of the server.
• TAG Set to 0 to use C5 tags and to 1 to use C6. You must, of course, use the setting for the tags actually used in the corpus defined. The default is 0.
• TMP Specifies the pathname of a directory to be used for any other files created by the server (e.g. queries saved on the server by a client).
• TOT Specifies the length of the time-out in seconds. If set to zero, no time-out will operate.
• TXT

  Specifies the root of the directory structure. The corpus comes divided properly into subdirectories and it should not be necessary to move texts around. Each text has a three letter identifier and lives in a directory whose name consists of the first two letters, which is a subdirectory of a directory whose name is the first letter. These one-letter directories should be in the directory specified by the TXT parameter.

  For example, if TXT is set to /corpus/1.0/ then the text GAK would have full pathname /corpus/1.0/G/GA/GAK. Note that all path parameters require a final / separator.