1 <!doctype linuxdoc system>
4 $Id: egate.sgml,v 1.4 1995/07/06 12:34:50 adam Exp $
8 <title>Email/Z39.50 gateway guide
9 <author>Europagate, 1995
10 <date>$Revision: 1.4 $
12 This document describes a Email server that provides access to the
21 This document describes how to compile, install and setup the
22 Email server (ES) software. It does not address the internal design of
25 <sect>Before you begin
28 An ANSI C compiler is required in order to compile the ES software.
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.
34 The Zdist package can be found in:
36 <url url="ftp://ftp.cnidr.org/pub/NIDR.tools/zdist/zdist102b1-1.tar.Z" >
38 The Zdist package doesn't support result-set references. Also, it has a few
39 bugs. Therefore we've included a patch <tt/<zdist.patch/ which fixes
41 Run patch in the directory above <tt/zdist102b1-1/:
48 <url url="ftp://ftp.algonet.se/pub/index/yaz/">.
50 The ES also use GNU's regex package to parse regular expressions.
51 The ES has been tested with regex-0.12. Some systems, such as Linux,
52 comes with the regex package preinstalled.
57 Unpack <tt>egate.tar.gz</tt> and edit the top level <tt/Makefile/. Specify
58 where the GNU regex package is located and specify whether you use
59 YAZ or zdist. One some systems, you may have to set the <tt/NETLIB/ as
62 You may wish to set <tt/CC/ and <tt/CFLAGS/ in your shell, since these
63 will affect the compilation — these are not set in the <tt/Makefile/.
70 If the compilation was successful, you should install the software.
71 Edit the <tt/Makefile/ and set the LIBDIR to the installation
72 directory. Since, the ES is executed by the mail system, and not by a
73 user, this directory shouldn't be globally executable.
75 When satisfied, type <tt/make install/.
77 Three executables are installed in LIBDIR:
79 <tag/eti/ The email transport interface. This program receives
80 incoming mail, identifies the user, and delivers the mail request
81 to the monitor or kernel (depending on configuration).
82 <tag/monitor/ The monitor
83 is optional component. The main objective
84 of the monitor is to limit the number of simultanous running kernel
86 <tag/kernel/ The kernel process is the core of the ES. It parses
87 the user's requests and interfaces the Z39.50 protocols.
90 The <tt/sendmail/ or a similar program delivers the mail to the
91 <tt/eti/ program. The <tt/sendmail/ program usually runs as user
92 <tt/mail/ or some other special user name. We strongly suggest that
93 you create a special user and group for the ES software. In this case
94 you should use <tt/chmod/ to and set the 'set user ID on execution'
95 bits on the executable files and give that user read/write/execute
96 permissions in LIBDIR.
98 The mail system needs to know about the ES. Pick some name that serves
99 as the ES user and edit <tt/aliases/ used by your mail system (usually
100 <tt>usr/lib/aliases</tt>). Now add the following line:
102 <tt>es:"|/usr/local/lib/es/eti </tt><em>options</em><tt>"</tt>
104 In this example the mail user name was <tt/es/ and the LIBDIR was
105 <tt>/usr/local/lib/es</tt>.
107 The ES system can operate with or without the monitor. When using
108 the monitor the number of simultanous running kernels can be
109 controlled. If the <tt>eti</tt> program is started with
110 two dashes (<tt>--</tt>) it will operate without the monitor and
111 the options specified after the two dashes are transferred to the
114 <sect1>With the monitor
117 The monitor must be running at all times in this mode. You should
118 start the monitor in one of your boot scripts (rc). For example this
119 might be put in a boot script:
122 (cd /usr/local/lib/es; ./monitor -d -l mon.log -- -d -l kernel.log &)
125 Here the monitor is started with the options <tt>-d -l mon.log</tt>
126 and the options after the two dashes are transferred to the
127 kernel. In this mode, the eti should contact the monitor (and not
128 the kernel), so the following might be put in the aliases file:
131 es:"|/usr/local/lib/es/eti -c /usr/local/lib/es"
134 The eti sets current directory to the path specified by option <tt>-c</tt>.
136 <sect1>Without the monitor
139 In this mode you should never start the monitor.
140 The eti will contact the kernel directly. The following line could
141 be put in your aliases file:
144 es:"|/usr/local/lib/es/eti -c /usr/local/lib/es -- -d -l kernel.log"
150 The eti program accepts the following options:
152 <tag><tt>-l </tt>log</tag> The log file. If absent stderr is used.
153 <tag><tt>-d</tt></tag> Turns on debugging.
154 <tag><tt>-c </tt>dir</tag> Sets current directory to dir.
155 <tag><tt>-H</tt></tag> Help message.
156 <tag><tt>--</tt></tag> Indicates that the eti program should contact the
157 kernel (and not the monitor. All options after this one are transferred
164 The monitor program accepts the following command line options:
166 <tag><tt>-l </tt>log</tag> The log file. If absent stderr is used.
167 <tag><tt>-d</tt></tag> Turns on debugging.
168 <tag><tt>-H</tt></tag> Help message.
169 <tag><tt>--</tt></tag> Precedes options that are transferred to the kernel
172 The monitor normally reads the resource <tt>default.res</tt> in
173 current directory. You can change this behaviour by specifying an
174 alternate file on the command line.
179 List of options observed by the kernel:
181 <tag><tt>-d</tt></tag> Turns on debugging.
182 <tag><tt>-t </tt>target</tag> Opens connection to target (for testing only).
183 <tag><tt>-g </tt>lang</tag> Set language name.
184 <tag><tt>-o </tt>res</tag> Overriding resource file name. These
185 resources override both <tt>default.res</tt> and all user resources.
186 <tag><tt>-h </tt>host</tag> Override host name (for testing only).
187 <tag><tt>-p </tt>port</tag> Override port no (for testing only).
188 <tag><tt>-l </tt>log</tag> Specify log file.
189 <tag><tt>-H</tt></tag> Help message.
192 The kernel normally reads the resource <tt>default.res</tt> in
193 current directory. You can change this behaviour by specifying an
194 alternate file on the command line.
196 <sect>Managing the system
198 <sect1>Summary of files
201 To maintain the ES you need to know the files it uses. These are:
203 <tag>*.res</tag> Resource files with several settings that control
204 how the system operates, such as definition of targets, messages, etc.
205 <tag>*.bib</tag> Bib-1 attribute mapping files. These files describe
206 the mapping between CCL and the RPN query.
207 <tag>user.db</tag> Database of users. Only the eti process accesses
209 <tag>user.*.r</tag> Resource file for a user — accessed by the kernel
210 — only created when the user uses the <tt>def</tt> command.
211 <tag>user.*.p</tag> Persistency file for a user — accessed by
216 The ES system is mostly managed by resource files. The following
217 are example resource files that comes with the ES:
219 <tag><tt>default.res</tt></tag> General resource with reasonable defaults.
220 This file is read by the monitor and the kernel.
221 <tag><tt>loc.res</tt></tag> Resource file for Library of Congress test
223 <tag><tt>drewdb.res</tt></tag> Resource file for Data Research's test
225 <tag><tt>lang.uk.res</tt></tag> Resource file for english conversation.
226 <tag><tt>lang.dk.res</tt></tag> Resource file for danish conversation.
232 Most general resources should be set in the file <tt>default.res</tt>.
233 Some of the resources may be changed (overridden) by the user, while
234 others may be overridden by individual target defintions.
235 The complete scenario is depicted below:
241 |<---------| "target.res" |
245 |<---------| user.x.res |
249 |<---------| "lang.res" |
253 |<---------| "override" |
258 The following describes the general resources:
260 <tag>gw.reply.mta</tag> Name of MTA program — default
261 <tt>/usr/lib/sendmail</tt>.
262 <tag>gw.reply.tmp.prefix</tag> Prefix of temporary files used by the ES.
263 <tag>gw.reply.tmp.dir</tag> Name of directory with temporary files.
264 <tag>gw.marc.log</tag> If this resource is specified, retrieved MARC
265 records will be appended to this file.
266 <tag>gw.timeout</tag> Idle time before the kernel exits. When the
267 kernel exits, the Z39.50 persistency layer will reconnect when
269 <tag>gw.resultset</tag> If this setting is 1, the Z39.50 client will
270 use named result sets. If 0, the Z39.50 system will always use
271 <tt/Default/ as result-set name.
272 <tag>gw.persist</tag> If this setting 1, the persistency is enabled;
274 <tag>gw.max.process</tag> This settings is the maximum number of
275 simultaneous kernel processes — only used by the monitor.
276 <tag>gw.ignore.which</tag> Some targets doesn't indicate whether
277 a record is a diagnostic messaage or a database record. If this
278 setting is 1, the ES will always try to interpret the record as a
279 database record in ISO2709 format. If 0, the ES will use the
281 <tag>gw.default.show</tag> Default number of records to retrieve and display
282 when using the show command. This setting may be changed by the user
283 with the <tt>def defaultshow</tt> command.
284 <tag>gw.max.show</tag> This setting specifies the maximum number of
285 records the user may retrieve in one show command — default 100.
286 <tag>gw.autoshow</tag> Number of records to retrieve in a find
287 command — default 0. This setting may be changed by the user by
288 the <tt>def autoshow</tt> command.
289 <tag>gw.display.format</tag> Default display format. This setting may
290 be changed by the user by the <tt>def f</tt> command.
291 <tag>gw.language</tag> Current language. This setting may be
292 changed by the user with the <tt>def lang</tt> command. When the
293 langauge is set to something, say x, then the resource gw.lang.x
294 should hold a name of a resource file read by the kernel.
295 <tag>gw.lang.<em/x/</tag> Specifies name of resource file for
297 <tag>gw.target.<em/name/ </tag> Name of resource file of target
299 <tag>gw.portno</tag> Z39.50 target port number — default 210.
300 <tag>gw.hostname</tag> Z39.50 target host name.
301 <tag>gw.bibset</tag> Name of file with Bib-1 attribute mapping.
302 <tag>gw.databases</tag> Available databases on target.
303 <tag>gw.description</tag> Description of a target. This message
304 is returned to the user when the connection is established with the
306 <tag>gw.account</tag> Z39.50 Authentication string — default
313 There are several resource settings that deal with language
314 dependencies. These fall into the following categories that
315 depend on the resource name prefixes:
317 <tag>gw.msg</tag> Miscellaneous messages.
318 <tag>gw.err</tag> Error messages.
319 <tag>gw.bib1.diag.<em/no/</tag> Diagnostic error message indicated by
321 <tag>gw.help</tag> Help/description of various commands.
322 <tag>ccl.command</tag> CCL command names.
323 <tag>ccl.token</tag> CCL tokens names.
326 Refer to the sample files, <tt>default.res</tt>, <tt>lang.uk.res</tt>
327 and <tt>lang.dk.res</tt> for all available settings.
329 <sect1>Target definitions
332 To add a target definition called <em/mytarget/ you need to make a resource
333 entry in <tt>default.res</tt> called <tt>gw.target.</tt><em>mytarget</em>.
334 The value of this resource is the name of a resource file — for
335 example <em>mytarget</em><tt>.res</tt>. The resource file should at least
336 define the resources: <tt/gw.hostname/, <tt/gw.databases/ and
337 <tt/gw.description/. You might also consider specifying
338 <tt/gw.account/, <tt/gw.bibset/, <tt/gw.resultset/ and <tt/gw.portno/
339 in the target resource file. The user only needs to use the command
340 <tt>target </tt><em>mytarget</em> to use the target. Also, since we
341 already specified database names, the user doesn't need to use the
344 <sect1>CCL to RPN mapping
347 The mapping between CCL-queries and RPN are stored in files —
348 normally with the suffix <tt>.bib</tt>. We will refer these
349 files as bibset-files. You might consult the file <tt/default.bib/
350 to see an example of such file.
352 The mapping is necessary because targets usually only support a little
353 subset of the Bib-1 attribute set and because the CCL qualifiers
354 (field names) are not standardized. A bibset-file is specified
355 by the <tt/gw.bibset/ resource.
357 Column zero of a bib-file line either hold a hash character (<tt/#/)
358 indicating a comment in which case the rest of the line is
359 ignored; or a CCL qualifier.
361 The name of the CCL qualifier is up to you. However, the special
362 qualifier name <tt/term/ applies to the case where no qualifier
363 is specified in CCL. The CCL qualifier is
364 followed by one or more mapping specifications. A mapping
365 specification takes the form:
367 <em/type/<tt/=/<em/value/<tt/,/<em/value/...
369 The type is simply one of the six Bib-1 attribute query types:
371 <tag/u/ Use attribute. Value is an integer.
372 <tag/t/ Truncation attribute. Value is an integer; or the
373 value is a combination of:
375 <tag/l/ This character indicates that the CCL parser should allow
376 left truncation (2) if indicated by a <tt/?/ on the left side
378 <tag/r/ This character indicates that the CCL parser should allow
379 right truncation (1) if indicated by a <tt/?/ on the right side
381 <tag/b/ This character indicates that the CCL parser should allow
382 both left and right (3) truncation indicated by a <tt/?/ on both
383 left and right side of a term.
384 <tag/n/ This character indicates that the CCL parser should announce
385 no truncation (100) if no truncation was indicated.
387 <tag/p/ Position attribute. Valus is an integer.
388 <tag/s/ Structure attribute. Value is an integer; or the
389 value is <tt/pw/ in which case the CCL parser announces word (2) or
390 phrase (1) depending on the number of adjacent terms.
391 <tag/r/ Relation attribute. Value is an integer; or the value is
392 <tt/o/ in which case, the CCL parser will select <em/less than/,
393 <em/less than or equal/, ... <em/greater than/ — depending on
394 the relation specified in CCL.
395 <tag/p/ Position attribute. Value is an integer.
398 Consider these bibset-lines:
404 The first line describes the mapping in when no qualifiers are
409 In this case the right truncation is enabled and the structure is
412 The second line is used in this search:
416 where the use attribute is <em/author/ and the structure is <em/word/.
418 The third line is used in:
422 where the use attribute is <em/date/ and the relation is <em/greater than/.
427 Copyright © 1995, the EUROPAGATE consortium (see below).
429 The EUROPAGATE consortium members are:
432 <item>University College Dublin
433 <item>Danmarks Teknologiske Videnscenter
434 <item>An Chomhairle Leabharlanna
435 <item>Consejo Superior de Investigaciones Cientificas
438 Permission to use, copy, modify, distribute, and sell this software and
439 its documentation, in whole or in part, for any purpose, is hereby granted,
442 1. This copyright and permission notice appear in all copies of the
443 software and its documentation. Notices of copyright or attribution
444 which appear at the beginning of any file must remain unchanged.
446 2. The names of EUROPAGATE or the project partners may not be used to
447 endorse or promote products derived from this software without specific
448 prior written permission.
450 3. Users of this software (implementors and gateway operators) agree to
451 inform the EUROPAGATE consortium of their use of the software. This
452 information will be used to evaluate the EUROPAGATE project and the
453 software, and to plan further developments. The consortium may use
454 the information in later publications.
456 4. Users of this software agree to make their best efforts, when
457 documenting their use of the software, to acknowledge the EUROPAGATE
458 consortium, and the role played by the software in their work.
460 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
461 EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
462 WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
463 IN NO EVENT SHALL THE EUROPAGATE CONSORTIUM OR ITS MEMBERS BE LIABLE
464 FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF
465 ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA
466 OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND
467 ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
468 USE OR PERFORMANCE OF THIS SOFTWARE.