Configuring your Isite Service

General Configuration Details

For the remainder of the tutorial there will be several directories in which software, configuration files, metadata, and indices will be placed. The following is intended to lay the ground rules for the terminology used in the rest of the tutorial. You may name these directories anything you like on your system, but they will be consistently named as follows so you can keep them straight:

• metadata -- this is a directory that contains the triplet of metadata files in HTML, SGML, and text format with the .html, .sgml, and .text suffixes, respectively. These are the files created by mp or your favorite compliant metadata editor.
• index -- this is a directory into which searchable, binary index files are written from the Iindex command you'll soon learn about. There is nothing to look at here, except that when an index is created all the index files in this directory will have the same file prefix name, which is the name of your index or "database".
• Isite/bin -- this is the directory that contains the executable programs and configuration files for Isite and, if you want, even additional metadata tools such as cns and mp. The Windows distribution does not include a bin directory but stores these files at the Isite level.

All three of these directories will be referenced in the remainder of the tutorial and may be placed as top-level directories, or subdirectories anywhere on your system. You need to keep track of where they are and what they are called, and make the appropriate substitutions when you work with them using the software.

Installing the Isite Software

In the Isite package as delivered for the Clearinghouse is composed of a directory with two subdirectories in it (bin and doc). The Isite/bin directory holds the executables needed to index, test, and serve your geospatial metadata.

The filename you downloaded should reflect the version number and the platform on which you will install this software. The installation file is provided as a compressed tar (tape archive) (or ZIP for Windows) file containing the directory structure to be installed. For Windows, simply extract the contents of the zip archive to a new directory, e.g. C:\Isite and continue on the next section, Checking the Initialization Files.

1. Identify a target directory into which the Isite software can be installed. It should contain at least 10 megabytes of space for the software, documentation, and configuration files.
2. Move the compressed tarfile to the installation directory. The Windows version of Isite comes as a .zip file. Use a program such as WinZip to uncompress this file. Name the destination directory to your liking and continue to the "Checking the Initialization Files" step below. In Unix/Linux, uncompressing the tarfile will automatically create a subdirectory for you:

   % cp /tmp/Isite_2.00.06-sun.tar.Z /usr/local

3. Uncompress the tarfile:

   % cd /usr/local
   % uncompress /tmp/Isite_2.00.06-sun.tar.Z

4. Extract the software directories from the archive:

   % tar xvf Isite_2.00.06-sun.tar
   a Isite/doc
   a Isite/doc/Isite.doc
   a Isite/doc/Isite.html
   a Isite/doc/Isite.txt
   a Isite/doc/README
   ...

   The contents will be reported to the screen as they are extracted. You may remove the tarfile at your discretion (rm Isite*.tar).

5. Change directory to the Isite directory and list the contents, then change directory to the bin directory where the configuration files are stored.

   % cd Isite
   % ls
   COPYRIGHT README bin doc
   % cd bin
   % ls
   Iindex geo.fgdcmap zserver.ini
   Isearch gils.fgdcmap izclient
   Iutil sapi.ini zping
   bib1.fgdcmap zclient
   fgdc.fields zserver

   Your directory contents should have at least these files, but more files are bound to be included with a given distribution.

Checking the Initialization files

There are two files in Isite/bin that the zserver process needs for configuration: the sapi.ini file and the zserver.ini file. These files are usually kept local to (in the same directory as) the zserver executable.

The sapi.ini passes the search to the correct search engine from the server and defines where the metadata index is.

The zserver.ini file includes the options for running the Z39.50 server process as standalone or to be activated when the computer restarts (inetd), the port number, the location of the sapi.ini file, the access log file to be created, and a list of the local databases it knows of.

At this time you need to edit the sapi.ini and zserver.ini files in the Isite's bin directory.

Editing the sapi.ini file

The sapi.ini file in the Isite's bin directory contains essential information for the server to connect to a specific search engine. In this reference implementation we are using the Isearch utility built by the Iindex command, although one can couple other search engines to the server.

At the top of the sapi.ini file are a list of the indexed collections active at this site, by keyword to reference the block, shown in square brackets [ ] below.

The following elements should be understood by the administrator in setting up the server:

• [Default] - a block in the initialization file that declares which Isite indices (databases) are active, by name. Each of these mentioned databases is listed in the DBList in the zserver.ini file.

• [your_index_name] - the beginning of the fgdcmeta configuration. Replace the word 'fgdcmeta' with the shortname (no spaces) you chose above.

• Type=ISEARCH - declares that the Isearch engine is to be used.

• Location=/some/pathname - declares the pathname to the "index" directory containing the metadata index files. In this example, the index files start with the name fgdcmeta.

• FieldMaps=/usr/local/Isite/bib1.fgdcmap,\
  /usr/local/Isite/gils.fgdcmap,\
  /usr/local/Isite/geo.fgdcmap - declares the location of the field mapping files. This should include the full path to your Isite/bin directory. There are three mapp9ing files that must be referenced here that allow your server to be seen as an FGDC server, a bibliographic server, and a GILS server. All three files are included in the binary distribution directory of your Isite software. The three files can be referenced as a single line of text separated by commas only (no spaces) or as in the above example, separated by a line-continuation character as a backslash (UNIX only).

Editing the zserver.ini file

The zserver.ini file contains configuration information for the server process. A given server process runs as a background process on your host computer, "listening" to a designated port, then spins off a child process to handle each incoming request. This is the same behavior as a Web server process, except that Z39.50 is not the http protocol and uses a different port. A server process can handle connections to multiple locally-indexed document collections, although for most purposes you will only reference one collection for FGDC service.

Elements that are sometimes modified in zserver.ini:

• Debug_Level=0 - for debugging purposes on new platforms this can be set to 5 for verbose feedback to the logfile, or 0 for minimal server log feedback. This setting does not change performance or user presentation. Default should be 0.

• ServerType=STANDALONE - This flags the server process whether it will be started as a daemon when the computer is booted or whether it will be interactively started and stopped. In general, this should be set to STANDALONE. If you are interested in having this process run at a "low numbered port" ( port# < 1024 ) then this may need to be set as INETD since the inetd process controls these port numbers, and only root can start and stop the process. Ports greater than 1024 can be used, and the ServerType needs to be then set to STANDALONE.

• Port=210 - This is the identity of the TCP/IP port that you will use for external service. The default and suggested port is 210, reserved in the /etc/services file for Z39.50. Port numbers less than 1024 must be initiated by the root process. At your discretion, an alternative port number may be used. The conventional setting for Z39.50 in the wider internet community is on port 210.

• SAPI=/your_install_dir_for_Isite/bin/sapi.ini - this is the full pathname to the Search API (sapi.ini) configuration file.

• AccessLog=/some_directory/zserver_access.log - this is the full pathname to the location where the access log is written. The access log contains all connection and query information, the content and depth of which are determined by the Debug_Level setting above. As with a Web access log, this file may get large and should be periodically reviewed and removed.

• DBList=your_index_name - where your_index_name is the rootname of the index files and provides a key to the [your_index_name] block of information below. This is the index name, also the rootname of the index files you will create in the "index" directory. It can be anything you want it to be, but must be consistently named at your site. We suggest you use a friendly mnemonic for your site, e.g. OregonLib and use that consistently wherever your_index_name is mentioned in these tutorials.

Back to Imagemap