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.
- 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.
-
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
-
Uncompress the tarfile:
% cd /usr/local
% uncompress /tmp/Isite_2.00.06-sun.tar.Z -
Extract the software directories from the archive:
% tar xvf Isite_2.00.06-sun.tar
The contents will be reported to the screen as they are extracted. You may remove the tarfile at your discretion (rm Isite*.tar).
a Isite/doc
a Isite/doc/Isite.doc
a Isite/doc/Isite.html
a Isite/doc/Isite.txt
a Isite/doc/README
... -
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
Your directory contents should have at least these files, but more files are bound to be included with a given distribution.
% 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
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.