doc/egate.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!--
   4   $Id: egate.sgml,v 1.1 1995/07/03 12:58:17 adam Exp $
   5 -->
   6
   7 <article>
   8 <title>Email/Z39.50 gateway guide
   9 <author>Europagate, 1995
  10 <date>$Revision: 1.1 $
  11 <abstract>
  12 This document describes a Email server that provides access to the
  13 Z39.50 protocol.
  14 </abstract>
  15
  16 <toc>
  17
  18 <sect>Introduction
  19
  20 <p>
  21 This document describes how to compile, install and setup the
  22 Email server (ES) software. It does not address the internal design of
  23 the software.
  24
  25 <sect>Before you begin
  26
  27 <p>
  28 An ANSI C compiler is required in order to compile the ES software.
  29
  30 The ES can use either CNIDR's zdist package or the YAZ package from
  31 Index Data to interface the Z39.50 protocol. So you need to obtain
  32 either of these first.
  33
  34 The Zdist package can be found in:
  35
  36 <url url="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/zdist102b1-1.tar.Z" >
  37
  38 The zdist doesn't support result-set references. Also, it has a few
  39 bugs &mdash; see the file zdist.es.patch for details.
  40
  41 YAZ can be found in:
  42
  43 <url url="ftp://ftp.algonet.se/pub/index/yaz/">.
  44
  45 The ES also use GNU's regex package to parse regular expressions.
  46 The ES has been tested with regex-0.12. Some systems, such as Linux,
  47 comes with the regex package preinstalled.
  48
  49 <sect>Compilation
  50
  51 <p>
  52 Unpack <tt>egate.tar.gz</tt> and edit the top level <tt/Makefile/. Specify
  53 where the GNU regex package is located and specify whether you use
  54 YAZ or zdist. One some systems, you may have to set the <tt/NETLIB/ as
  55 well.
  56
  57 You may wish to set <tt/CC/ and <tt/CFLAGS/ in your shell, since these
  58 will affect the compilation &mdash; these are not set in the <tt/Makefile/.
  59
  60 Now, type <tt/make/.
  61
  62 <sect>Installation
  63
  64 <p>
  65 If the compilation was successful, you should install the software.
  66 Edit the <tt/Makefile/ and set the LIBDIR to the installation
  67 directory. Since, the ES is executed by the mail system, and not by a
  68 user, this directory shouldn't be globally executable.
  69
  70 When satisfied, type <tt/make install/.
  71
  72 Three executables are installed in LIBDIR:
  73 <descrip>
  74 <tag/eti/ The email transport interface. This program receives
  75 incoming mail, identifies the user, and delivers the mail request
  76 to the monitor or kernel (depending on configuration).
  77 <tag/monitor/ The monitor
  78  is optional component. The main objective
  79 of the monitor is to limit the number of simultanous running kernel
  80 processes.
  81 <tag/kernel/ The kernel process is the core of the ES. It parses
  82 the user's requests and interfaces the Z39.50 protocols.
  83 </descrip>
  84
  85 The <tt/sendmail/ or a similar program delivers the mail to the
  86 <tt/eti/ program. The <tt/sendmail/ program usually runs as user
  87 <tt/mail/ or some other special user name. We strongly suggest that
  88 you create a special user and group for the ES software. In this case
  89 you should use <tt/chmod/ to and set the 'set user ID on execution'
  90 bits on the executable files and give that user read/write/execute
  91 permissions in LIBDIR.
  92
  93 The mail system needs to know about the ES. Pick some name that serves
  94 as the ES user and edit <tt/aliases/ used by your mail system (usually
  95 <tt>usr/lib/aliases</tt>). Now add the following line:
  96
  97 <tt>es:"|/usr/local/lib/es/eti </tt><em>options</em><tt>"</tt>
  98
  99 In this example the mail user name was <tt/es/ and the LIBDIR was
 100 <tt>/usr/local/lib/es</tt>.
 101
 102 The ES system can operate with or without the monitor. When using
 103 the monitor the number of simultanous running kernels can be
 104 controlled. If the <tt>eti</tt> program is started with option
 105 <tt>--</tt> it will operate without the monitor.
 106
 107 <sect1>With the monitor
 108
 109 <p>
 110 The monitor must be running at all times in this mode. You should
 111 start the monitor in one of your boot scripts (rc). For example this
 112 might be put in a boot script:
 113
 114 <tscreen><verb>
 115 (cd /usr/local/lib/es; ./monitor -d -l mon.log -- -d -l kernel.log &)
 116 </verb></tscreen>
 117
 118 Here the monitor is started with the options <tt>-d -l mon.log</tt>
 119 and the options after the two dashes are transferred to the
 120 kernel. In this mode, the eti should contact the monitor (and not
 121 the kernel), so the following might be put in the aliases file:
 122
 123 <tscreen><verb>
 124 es:"|/usr/local/lib/es/eti -c /usr/local/lib/es"
 125 </verb></tscreen>
 126
 127 The eti sets current directory to the path specified by option <tt>-c</tt>.
 128
 129 <sect1>Without the monitor
 130
 131 <p>
 132 In this mode you should never start the monitor.
 133 The eti will contact the kernel directly. The following line could
 134 be put in your aliases file:
 135
 136 <tscreen><verb>
 137 es:"|/usr/local/lib/es/eti -c /usr/local/lib/es -- -d -l kernel.log"
 138 </verb></tscreen>
 139
 140 <sect1>eti
 141
 142 <p>
 143 The eti program accepts the following options:
 144 <descrip>
 145 <tag><tt>-l </tt>log</tag> The log file. If absent stderr is used.
 146 <tag><tt>-d</tt></tag> Turns on debugging.
 147 <tag><tt>-c </tt>dir</tag> Sets current directory to dir.
 148 <tag><tt>--</tt></tag> Indicates that the eti program should contact the
 149 kernel (and not the monitor. All options are this one are transferred
 150 to the kernel
 151 <tag><tt>-H</tt></tag> Help message.
 152 </descrip>
 153
 154 <sect1>monitor
 155
 156 <p>
 157 The monitor program accepts the following command line options:
 158 <descrip>
 159 <tag><tt>-l </tt>log</tag> The log file. If absent stderr is used.
 160 <tag><tt>-d</tt></tag> Turns on debugging.
 161 <tag><tt>-H</tt></tag> Help message.
 162 <tag><tt>--</tt></tag> Precedes options that are transferred to the kernel
 163 </descrip>
 164
 165 The monitor normally reads the resource <tt>default.res</tt> in
 166 current directory. You can change this behaviour by specifying an
 167 alternate file on the command line.
 168
 169 <sect1>kernel
 170
 171 <p>
 172 List of options observed by the kernel:
 173 <descrip>
 174 <tag><tt>-d</tt></tag> Turns on debugging.
 175 <tag><tt>-t </tt>target</tag> Opens connection to target (for testing only).
 176 <tag><tt>-g </tt>lang</tag> Set language name.
 177 <tag><tt>-o </tt>res</tag> Overriding resource file name. These
 178 resources override both <tt>default.res</tt> and all user resources.
 179 <tag><tt>-h </tt>host</tag> Override host name (for testing only).
 180 <tag><tt>-p </tt>port</tag> Override port no (for testing only).
 181 <tag><tt>-l </tt>log</tag> Specify log file.
 182 <tag><tt>-H</tt></tag> Help message.
 183 </descrip>
 184
 185 The kernel normally reads the resource <tt>default.res</tt> in
 186 current directory. You can change this behaviour by specifying an
 187 alternate file on the command line.
 188
 189 <sect>Managing the system
 190
 191 <p>
 192
 193 <sect1>Files
 194
 195 <p>
 196 To maintain the ES you need to know the files it uses. These are:
 197 <descrip>
 198 <tag>*.res</tag> Resource files with several settings that control
 199  how the system operates, such as definition of targets, messages, etc.
 200 <tag>lang.*.res</tag> Resource file for a particular langauge.
 201 <tag>*.bib</tag> Bib-1 attribute mapping files. These files describe
 202  the mapping between CCL and the RPN query.
 203 <tag>user.db</tag> Database of users. Only the eti process access
 204  this file.
 205 <tag>user.*.r</tag> Resource file for a user &mdash; accessed by the kernel
 206  &mdash; only created when the user uses the <tt>def</tt> command.
 207 <tag>user.*.p</tag> Persistency file for a user &mdash; accessed by
 208  the kernel
 209  process.
 210 </descrip>
 211
 212 The ES system is mostly managed by resource files. The following
 213 resource files are enclosed with the ES:
 214 <descrip>
 215 <tag><tt>default.res</tt></tag> General resource with reasonable defaults.
 216  This file is read by the monitor and the kernel.
 217 <tag><tt>loc.res</tt></tag> Resource file for Library of Congress test
 218  server.
 219 <tag><tt>drewdb.res</tt></tag> Resource file for Data Research's test
 220  server.
 221 <tag><tt>lang.uk.res</tt></tag> Resource file for english conversation.
 222 <tag><tt>lang.dk.res</tt></tag> Resource file for danish conversation.
 223 </descrip>
 224
 225 <sect1>General resources
 226
 227 <p>
 228 Most general resources can be found in default.res. Some of the
 229 resources may be changed (overridden) by the user, while others may be
 230 overriden by individual target defintions.
 231
 232 <p>
 233 The following table lists general resources:
 234 <descrip>
 235 <tag>gw.reply.mta</tag> Name of MTA program.
 236 <tag>gw.reply.tmp.prefix</tag> Prefix of temporary files used by the ES.
 237 <tag>gw.reply.tmp.dir</tag> Name of directory with temporary files.
 238 <tag>gw.marc.log</tag> If this resource is specified, retrieved MARC
 239  records will be appended to this file.
 240 <tag>gw.timeout</tag> Idle time before the kernel exists. When the
 241  kernel exists, the Z39.50 persistency layer will reconnect when
 242  necessary.
 243 <tag>gw.resultset</tag> If this setting is 1, the Z39.50 client will
 244  use named result sets. If 0, the Z39.50 will always use Default as
 245  result-set name.
 246 <tag>gw.persist</tag> If this setting 1, the persistency is enabled;
 247  disabled otherwise.
 248 <tag>gw.max.process</tag> This settings is the maximum number of
 249  simultaneous kernel processes &mdash; only used by the monitor.
 250 <tag>gw.ignore.which</tag> Some targets doesn't indicate whether
 251  a record is a diagnostic messaage or a database record. If this
 252  setting is 1, the ES will always try to interpret the record as a
 253  database record in ISO2709 format. If 0, the ES will use the
 254  record type.
 255 <tag>gw.default.show</tag> Default number of records to retrieve and display
 256  when using the show command. This setting may be changed by the user.
 257 <tag>gw.max.show</tag> This setting specifies the maximum number of
 258  records the user may retrieve in one show command &mdash; default 100.
 259 <tag>gw.autoshow</tag> Number of records to retrieve in a find
 260  command &mdash; default 0. This setting may be changed by the user.
 261 <tag>gw.display.format</tag> Default display format. This setting may
 262  be changed by the user.
 263 <tag>gw.language</tag> Current language. This setting may be
 264 changed by the user.
 265 </descrip>
 266
 267 </article>