archie/release/base/manpages/archie_clients.n

.\" Copyright (c) 1996 Bunyip Information Systems Inc.
.\" All rights reserved.  
.\"	
.\" Archie 3.5
.\" April 1996
.\"	
.\"	@(#)archie_clients.n
.\"
.TH ARCHIE_CLIENTS N "August 1996"
.SH NAME
.B telnet-client, email-client
\- Archie client interfaces
.SH SYNOPSIS
.B telnet-client
[
.BI -d \ <debug\ level>
] [
.B -e
] [
.B -i
] [
.B -l
] [
.BI -L \ <logfile>
] [
.BI -o \ <output\ file>
] [
.B -s
]
.sp
.B email-client
[
.BI -i \ <input\ file>
] [
.BI -M \ <dir>
] [
.BI -h \ <dir>
] [
.B -l
] [
.BI -L \ <logfile>
] [
.BI -T \ <telnet\ client>
] [
.BI -t \ <tmp\ dir>
] [
.BI -u
] [
.BI -v
]
.SH DESCRIPTION
.LP
This manual page describes the Archie telnet and email interface clients for
Archie system administrators. The instructions for general use can be found in
.BR archie (n).
In Archie versions 3.X all clients use the Prospero server to process incoming
requests. This lowers the demand that each telnet session and email message
places on the host and allows more users to access the system at one time.

Currently the email and telnet clients only support access to the
\fBanonftp\fP database. It is likely that in future releases they will be
modified to allow access to other databasess.

.SH "EMAIL CLIENT"
The email client interface is a wrapper around the telnet client, which
performs all of the query processing. The email client determines the return
address from the header of the incoming mail as well as extracting the
`Subject:' line, which, in the Archie system, is treated as part of the
message body. This information is passed to the telnet client, which arranges
for the queries to be performed and the resulting message returned to the
user.
.SS "Email Client Options"
The following options are accepted by the email client.
.TP
.B \-l
\fIDo not\fP write any user output to the default email log file
.B ~archie/logs/email.log.
Note that this is the \fIreverse\fP of most other programs in the Archie
system.  Errors will be written to
.I stderr
if this option is used.
.TP
.BI \-M \ <dir>
The master Archie database directory path. If not specified, the program
looks in the directory
.BR ~archie/db ,
then
.BR ./db .
.TP
.BI \-h \ <dir>	
The Archie host database directory path. If not specified, the program first
tries
.BR ~archie/db/host_db ,
then
.BR ./host_db .
.TP
.BI \-L \ <logfile>	
The name of the file to be used for logging information, rather than the
default,
.BR ~archie/logs/email.log .
Note that debugging information is also written to the log file. This option is
passed to the telnet client.
.TP
.BI -i \ <input\ file>
Read the incoming mail from
.I <input\ file>
rather than the default,
.IR stdin .
This option is provided so that the incoming mail may be queued in a temporary
directory, then processed periodically.
.TP
.BI -T \ <telnet\ client>
Use the
.I absolute path
specified by
.I <telnet\ client>
as the program to execute to process the incoming mail. If omitted, the
program invokes the program
.BR ~archie/bin/telnet-client .
.TP
.BI -t \ <tmp\ dir>
Use the directory
.I <tmp\ dir>
for temporary files. This must be the absolute path of the directory. By
default, the directory
.B ~archie/db/tmp
is used.
.TP
.BI -u
Log the incoming mail to the current log file. The log entry contains the
default return address and a timestamp. Note that the log will not reflect
return addresses modified in the message body by the \fBpath\fP command or
\fBmailto\fP variable. A entry is written to the log file on completion of the
request.
.TP
.BI -v
Verbose mode. The email client will log each phase of the request processing,
as well as echoing each line of the input message as it is written to the
telnet client process. This mode should only be used when trying to determine
problems, as the verbosity will cause the log file to become very large, very
quickly.
.PP
Once the appropriate information has been extracted from the incoming mail,
the email client invokes the telnet client to service the request, then exits
when the telnet client has completed.  Note that the email client performs
only minor processing and that all queries are ultimately submitted to the
Prospero server, thus it uses very few system resources.

.SS Variables
Variables in the telnet client have a number of attributes affecting their
use.  These are:
.TP
.B name
This is the unique character string by which the user refers to a variable.
.TP
.B type
Boolean, numeric and string.  A boolean variable is either set or unset,
corresponding to true and false.  Except in certain cases, both numeric and
string variables may also be unset, in which case they lose their current
value.
.TP
.B    status
Set or unset.
.TP
.B value
As above, boolean variables have no value, merely a status.  When set, numeric
and string variables will have \fIsome\fP value, when unset they lose their
current value.  Some numeric or string variables have default values when the
telnet client is invoked.

Some variables may not be set by the user, and may be set only in the telnet
client initialization file.
.TP
.B visibility
Some variables may be set only through the initialization file.  Such
variables are typically used for internal state information or for local
configuration, and may neither set nor displayed by the user.
.TP
.B range
Due to their special meaning, some numeric and string variables are restricted
to a limited range of values.  (Currently, these ranges are fixed in the
software.)  An example is the \fBsearch\fP variable, which, due to fixed
search types, \fImust\fP take one of a preselected range of values.

If the value of a string variable is to contain leading or trailing spaces
then it must be quoted.  Text may be quoted by surrounding it with a pair of
double quotes (`"'), or by preceding individual characters with a
backslash (`\e').  (A double quote, or a backslash may itself be quoted by
preceding it by a backslash.)  The resulting value is that of the string with
the quotes stripped off.  For example
.\" WARNING: the indented lines contain _real_ tabs.  Keep 'em.
.sp
	set prompt "zork-archie> "
.sp
would cause the value of \fBprompt\fP to retain the trailing space.
.sp
	set prompt "a "prompt\\ >
.sp
embeds two spaces in the prompt, while
.sp
	set prompt slash-quote\\\\\\"
.sp
will put a slash and a double quote at the end of the prompt.

.SH "TELNET CLIENT"
This client has four modes which determine how it behaves for certain
operations. Some variables may only be set, and are only visible when the
telnet client is running in a particular mode. Similarly, some commands may
only be executed in certain modes. The current modes are \fIsystem batch\fP,
for initialization files set up by the administrator, \fIuser batch\fP, for
initialization files set up by an ordinary user, \fIinteractive\fP, for the
normal command line mode and \fIemail\fP, when the telnet client is run from
the email client.  These are explained below.

.SS "Telnet Client Options"
.TP
.B \-l
Write any user output to the default log file
.B ~archie/logs/archie.log.
If desired, this can be overridden with the 
.B -L
option. Errors will, by default, be written to
.IR stderr .
.TP
.BI \-L " <logfile>"
The name of the file to be used for logging information.  Note that debugging
information is also written to the log file.
.TP
.B -e
Set the telnet client to run in email mode. See
.SM "Email Mode"
below.
.TP
.B -i
Set the program to run in interactive mode. See
.SM "Interactive Mode"
below.
.TP
.BI -o " <output file>"
This option is no longer supported and is allowed for backward compatibility
only.
.TP
.B -s
Run in system batch mode. See
.SM "System Batch Mode"
below.
.PP
The telnet client need not reside on the same machine as the Prospero server,
or the rest of the Archie system. For example, a university may decide to
install the telnet client on several machines around the campus.

Users have the option of executing the telnet client on these hosts to have
their queries performed. This technique allows the Archie server machine to be
free of any Archie sessions itself, although it is still responsible for
processing the queries in the normal fashion.  In this way the telnet client
is effectively the same as other client programs like
.BR xarchie ,
or the Archie command line client. If this technique is used then the
\fBserver\fP variable must be set to the name of the Archie server host.

.SS "System Batch Mode"
Unless the
.B \-i
option is supplied, the telnet client always starts in this mode. The purpose
is to allow system specific commands to be executed, and variables to be set,
which cannot then be changed once in interactive or email mode. The client
first reads the default configuration file
.BR ~archie/.archierc .
If the client is invoked as any user other than the
pre-defined
.I archie
user, it will then switch to
.I user batch
mode and attempt to read the file
.BI ~ <user> /.archierc
for further configuration information (where
.I <user>
is the name of the user executing the program).

The following variables may only be set in the system configuration file.
Variables which are interactive in nature (such as
.B term
and
.BR status )
should
.I not
be set in the configuration file.
.TP
.B niceness
A number passed to the
.BR nice (3)
function before the client enters the command loop. This has the effect of
reducing the priority of the telnet client process. This may be useful when
the host system is under a high load or has other, more time\-critical,
processes running.
.TP
.B email_help_file
The name of the help file, returned to the sender, when the incoming mail
message contains the command
.BR help ,
or an empty message is received.  By default this is
.BR ~archie/etc/email.help .
.TP
.B help_dir
The name of the directory containing the help tree. It has a default value of
.BI ~archie/help/ <language>\fR,\fP
where
.I <language>
is the value of the
.B language
variable. This value is modified when the
.B language
variable is modified.  The internal system default is
.BR ~archie/help/english .
See
.SM "The Help System"
below.
.TP
.B mail_from
This is the `From' address put in mail sent to the user.  The default is
`archie\(emerrors'.
.TP
.B mail_host
The machine to which to connect in order to send mail. This machine contains
the programs to actually compress, encode, split, etc. the mail.  The default
is `localhost'.
.TP
.B mail_service
The service, as listed in in
.BR /etc/services ,
to which to connect, in order to reach the actual mail sending program. A
numeric value is interpreted as a port number.  The default is
`archiemail'.
.TP
.B man_ascii_file
The path to the plain ASCII version of the Archie manual page, which is
accessed through the
.B manpage
command.  It has a default value of
.BR ~archie/etc/manpage.ascii .
.TP
.B man_roff_file
As above, but the troff (nroff) version.  The default value is
.BR ~archie/etc/manpage.roff .
.TP
.B pager_help_opts
Options to be passed to the pager, when invoked within the help system. The
default is
.BR \-c .
See the
.BR less (1)
manual page for further information.
.TP
.B pager_opts
Similar to the previous variable, but it applies when the pager is used
outside of the help system.  The default is
.BR \-c .
.TP
.B prompt
The prompt displayed in the main command loop.  The default is `archie> '.
.TP
.B servers_file
Relative path to the file containing the list of current Archie servers.  The
contents of the file are printed when the
.B servers
command is invoked. The default is
.BR ~archie/etc/serverlist .
.PP
The following commands may only be used in system batch mode.
.TP
.BI disable
Disables the use of the command name supplied as an argument. For example, the
line
.sp
.\" WARNING: the indented line contains _real_ tabs.  Keep 'em
	\fCdisable mail\fP
.sp
if placed in the system configuration file, will disable the use of the
.B mail
command by users.

.SS "User Batch mode"
Currently all variables available in interactive mode are also available in
user batch mode.

.SS "Email Mode"
None of the interactive commands (such as
.BR status )
or variables (such as
.BR pager )
are available in email mode.

.SS "Interactive mode"
The variables documented in
.BR archie (n)
may all be set by the user. In addition, Archie administrators should be aware
of the following variables.
.TP
.B language
This variable allows the user to specify the language in which help, etc. is
presented. Currently the default value is `english'. The directory
.BI help/ <language>
must exist for this variable to be changed to
.IR <language> .
To add a new language to the help facility, the directory
.BI ~archie/help/ <language>
must be created.  Then, a translated version of an existing help hierarchy
must be placed under that directory.

.SS "The Help System"
The Archie help system is hierarchical, in that there is an initial set of
topics, some of which may have further subtopics.  Within the help system the
user is presented with a different prompt and has a limited set of commands
for moving around the hierarchy. Different languages may be supported in the
help system by creating an alternate hierarchy for each language.

For example, to set up a hierarchy for French, you would create the directory
.BR ~archie/help/francais ,
under which you would create a separate directory for each topic for which you
wanted to provide help.  In each such directory, a file called
.B =
must contain the actual text to be displayed. For example, the
.BR ~archie/help/english
directory contains the directory
.BR set .
If the user types `help set' the text in the file
.B ~archie/help/english/set/=
is displayed.

Subcommands (or subtopics) are supported by creating subdirectories of the
main topic directories similarly to that described above. For example, the
text for the subtopic `search', under the topic `set', would be in
the file
.BR ~archie/help/english/set/search/= .

Please note that while the help system can support multiple languages, the
list of commands, as well as error messages are currently returned in English.
Future versions of the client will also allow these to be converted in an
administrator-defined fashion, thereby allowing the client to operate
completely in the language of choice.

Full details of the operation of the Archie clients can be found in the user
manual page in
.BR ~archie/etc/manpage.roff .

.SH "SEE ALSO"
.BR archie (n).
.SH AUTHOR
Bunyip Information Systems.
.br
Montr\o"\'e"al, Qu\o"\'e"bec, Canada
.sp
Archie is a registered trademark of Bunyip Information Systems Inc., Canada,
1990.