--- /dev/null
+<!doctype linuxdoc system>
+
+<!--
+ $Id: egate.sgml,v 1.1 1995/07/03 12:58:17 adam Exp $
+-->
+
+<article>
+<title>Email/Z39.50 gateway guide
+<author>Europagate, 1995
+<date>$Revision: 1.1 $
+<abstract>
+This document describes a Email server that provides access to the
+Z39.50 protocol.
+</abstract>
+
+<toc>
+
+<sect>Introduction
+
+<p>
+This document describes how to compile, install and setup the
+Email server (ES) software. It does not address the internal design of
+the software.
+
+<sect>Before you begin
+
+<p>
+An ANSI C compiler is required in order to compile the ES software.
+
+The ES can use either CNIDR's zdist package or the YAZ package from
+Index Data to interface the Z39.50 protocol. So you need to obtain
+either of these first.
+
+The Zdist package can be found in:
+
+<url url="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/zdist102b1-1.tar.Z" >
+
+The zdist doesn't support result-set references. Also, it has a few
+bugs — see the file zdist.es.patch for details.
+
+YAZ can be found in:
+
+<url url="ftp://ftp.algonet.se/pub/index/yaz/">.
+
+The ES also use GNU's regex package to parse regular expressions.
+The ES has been tested with regex-0.12. Some systems, such as Linux,
+comes with the regex package preinstalled.
+
+<sect>Compilation
+
+<p>
+Unpack <tt>egate.tar.gz</tt> and edit the top level <tt/Makefile/. Specify
+where the GNU regex package is located and specify whether you use
+YAZ or zdist. One some systems, you may have to set the <tt/NETLIB/ as
+well.
+
+You may wish to set <tt/CC/ and <tt/CFLAGS/ in your shell, since these
+will affect the compilation — these are not set in the <tt/Makefile/.
+
+Now, type <tt/make/.
+
+<sect>Installation
+
+<p>
+If the compilation was successful, you should install the software.
+Edit the <tt/Makefile/ and set the LIBDIR to the installation
+directory. Since, the ES is executed by the mail system, and not by a
+user, this directory shouldn't be globally executable.
+
+When satisfied, type <tt/make install/.
+
+Three executables are installed in LIBDIR:
+<descrip>
+<tag/eti/ The email transport interface. This program receives
+incoming mail, identifies the user, and delivers the mail request
+to the monitor or kernel (depending on configuration).
+<tag/monitor/ The monitor
+ is optional component. The main objective
+of the monitor is to limit the number of simultanous running kernel
+processes.
+<tag/kernel/ The kernel process is the core of the ES. It parses
+the user's requests and interfaces the Z39.50 protocols.
+</descrip>
+
+The <tt/sendmail/ or a similar program delivers the mail to the
+<tt/eti/ program. The <tt/sendmail/ program usually runs as user
+<tt/mail/ or some other special user name. We strongly suggest that
+you create a special user and group for the ES software. In this case
+you should use <tt/chmod/ to and set the 'set user ID on execution'
+bits on the executable files and give that user read/write/execute
+permissions in LIBDIR.
+
+The mail system needs to know about the ES. Pick some name that serves
+as the ES user and edit <tt/aliases/ used by your mail system (usually
+<tt>usr/lib/aliases</tt>). Now add the following line:
+
+<tt>es:"|/usr/local/lib/es/eti </tt><em>options</em><tt>"</tt>
+
+In this example the mail user name was <tt/es/ and the LIBDIR was
+<tt>/usr/local/lib/es</tt>.
+
+The ES system can operate with or without the monitor. When using
+the monitor the number of simultanous running kernels can be
+controlled. If the <tt>eti</tt> program is started with option
+<tt>--</tt> it will operate without the monitor.
+
+<sect1>With the monitor
+
+<p>
+The monitor must be running at all times in this mode. You should
+start the monitor in one of your boot scripts (rc). For example this
+might be put in a boot script:
+
+<tscreen><verb>
+(cd /usr/local/lib/es; ./monitor -d -l mon.log -- -d -l kernel.log &)
+</verb></tscreen>
+
+Here the monitor is started with the options <tt>-d -l mon.log</tt>
+and the options after the two dashes are transferred to the
+kernel. In this mode, the eti should contact the monitor (and not
+the kernel), so the following might be put in the aliases file:
+
+<tscreen><verb>
+es:"|/usr/local/lib/es/eti -c /usr/local/lib/es"
+</verb></tscreen>
+
+The eti sets current directory to the path specified by option <tt>-c</tt>.
+
+<sect1>Without the monitor
+
+<p>
+In this mode you should never start the monitor.
+The eti will contact the kernel directly. The following line could
+be put in your aliases file:
+
+<tscreen><verb>
+es:"|/usr/local/lib/es/eti -c /usr/local/lib/es -- -d -l kernel.log"
+</verb></tscreen>
+
+<sect1>eti
+
+<p>
+The eti program accepts the following options:
+<descrip>
+<tag><tt>-l </tt>log</tag> The log file. If absent stderr is used.
+<tag><tt>-d</tt></tag> Turns on debugging.
+<tag><tt>-c </tt>dir</tag> Sets current directory to dir.
+<tag><tt>--</tt></tag> Indicates that the eti program should contact the
+kernel (and not the monitor. All options are this one are transferred
+to the kernel
+<tag><tt>-H</tt></tag> Help message.
+</descrip>
+
+<sect1>monitor
+
+<p>
+The monitor program accepts the following command line options:
+<descrip>
+<tag><tt>-l </tt>log</tag> The log file. If absent stderr is used.
+<tag><tt>-d</tt></tag> Turns on debugging.
+<tag><tt>-H</tt></tag> Help message.
+<tag><tt>--</tt></tag> Precedes options that are transferred to the kernel
+</descrip>
+
+The monitor normally reads the resource <tt>default.res</tt> in
+current directory. You can change this behaviour by specifying an
+alternate file on the command line.
+
+<sect1>kernel
+
+<p>
+List of options observed by the kernel:
+<descrip>
+<tag><tt>-d</tt></tag> Turns on debugging.
+<tag><tt>-t </tt>target</tag> Opens connection to target (for testing only).
+<tag><tt>-g </tt>lang</tag> Set language name.
+<tag><tt>-o </tt>res</tag> Overriding resource file name. These
+resources override both <tt>default.res</tt> and all user resources.
+<tag><tt>-h </tt>host</tag> Override host name (for testing only).
+<tag><tt>-p </tt>port</tag> Override port no (for testing only).
+<tag><tt>-l </tt>log</tag> Specify log file.
+<tag><tt>-H</tt></tag> Help message.
+</descrip>
+
+The kernel normally reads the resource <tt>default.res</tt> in
+current directory. You can change this behaviour by specifying an
+alternate file on the command line.
+
+<sect>Managing the system
+
+<p>
+
+<sect1>Files
+
+<p>
+To maintain the ES you need to know the files it uses. These are:
+<descrip>
+<tag>*.res</tag> Resource files with several settings that control
+ how the system operates, such as definition of targets, messages, etc.
+<tag>lang.*.res</tag> Resource file for a particular langauge.
+<tag>*.bib</tag> Bib-1 attribute mapping files. These files describe
+ the mapping between CCL and the RPN query.
+<tag>user.db</tag> Database of users. Only the eti process access
+ this file.
+<tag>user.*.r</tag> Resource file for a user — accessed by the kernel
+ — only created when the user uses the <tt>def</tt> command.
+<tag>user.*.p</tag> Persistency file for a user — accessed by
+ the kernel
+ process.
+</descrip>
+
+The ES system is mostly managed by resource files. The following
+resource files are enclosed with the ES:
+<descrip>
+<tag><tt>default.res</tt></tag> General resource with reasonable defaults.
+ This file is read by the monitor and the kernel.
+<tag><tt>loc.res</tt></tag> Resource file for Library of Congress test
+ server.
+<tag><tt>drewdb.res</tt></tag> Resource file for Data Research's test
+ server.
+<tag><tt>lang.uk.res</tt></tag> Resource file for english conversation.
+<tag><tt>lang.dk.res</tt></tag> Resource file for danish conversation.
+</descrip>
+
+<sect1>General resources
+
+<p>
+Most general resources can be found in default.res. Some of the
+resources may be changed (overridden) by the user, while others may be
+overriden by individual target defintions.
+
+<p>
+The following table lists general resources:
+<descrip>
+<tag>gw.reply.mta</tag> Name of MTA program.
+<tag>gw.reply.tmp.prefix</tag> Prefix of temporary files used by the ES.
+<tag>gw.reply.tmp.dir</tag> Name of directory with temporary files.
+<tag>gw.marc.log</tag> If this resource is specified, retrieved MARC
+ records will be appended to this file.
+<tag>gw.timeout</tag> Idle time before the kernel exists. When the
+ kernel exists, the Z39.50 persistency layer will reconnect when
+ necessary.
+<tag>gw.resultset</tag> If this setting is 1, the Z39.50 client will
+ use named result sets. If 0, the Z39.50 will always use Default as
+ result-set name.
+<tag>gw.persist</tag> If this setting 1, the persistency is enabled;
+ disabled otherwise.
+<tag>gw.max.process</tag> This settings is the maximum number of
+ simultaneous kernel processes — only used by the monitor.
+<tag>gw.ignore.which</tag> Some targets doesn't indicate whether
+ a record is a diagnostic messaage or a database record. If this
+ setting is 1, the ES will always try to interpret the record as a
+ database record in ISO2709 format. If 0, the ES will use the
+ record type.
+<tag>gw.default.show</tag> Default number of records to retrieve and display
+ when using the show command. This setting may be changed by the user.
+<tag>gw.max.show</tag> This setting specifies the maximum number of
+ records the user may retrieve in one show command — default 100.
+<tag>gw.autoshow</tag> Number of records to retrieve in a find
+ command — default 0. This setting may be changed by the user.
+<tag>gw.display.format</tag> Default display format. This setting may
+ be changed by the user.
+<tag>gw.language</tag> Current language. This setting may be
+changed by the user.
+</descrip>
+
+</article>
projects / egate.git / commitdiff