
	THIS IS ALPHA CODE - PLEASE DON'T CIRCULATE WIDELY YET!

	--   WHOIS++ query server   ---

This program is a jazzed up WHOIS, supporting the WHOIS++ protocol
extensions to serve information from IAFA-style records of attribute/value
pairs. In effect, it is a generalized template-oriented info browser.

This program is intended to be launched by inetd when someone connects to
your machine's "whois" port. It reads a single line on stdin, parses it and
sends the resulting query to a separate search engine for resolution. The
result of the query is returned on stdout. Full details of the valid
commands, query engine to search engine protocol and so forth are (or will
be) available in a companion document, or see the "HELP" files.

In operation, the query server parses the single line of input looking for a
valid command. If it recognizes a system command, it will execute this
command and exit. If it recognizes a search command (which consists of one
or more search terms) it builds up a query by filling in the global struct
"query" with the appropriate user-specified terms. Once it has done this, it
spawns the search engine (specified in the SEARCH_ENGINE path, see the file
"install.h") and passes the query to the engine. The search engine performs
the actual search and returns the result, which is returned to the caller.

Note, eventually this should probably be multi-threaded, so that inetd
doesn't have to block waiting for a response but whistles and bells come
later (this is needed because otherwise a system can only answer one query
at a time. This _could_ be a problem at a large site).

This program is ALPHA CODE! It isn't even indented properly. Please report
all bugs to "peterd@bunyip.com", but be nice. I don't criticize _your_ 
indenting style! :-)


Author:			Peter Deutsch (peterd@bunyip.com)
			Bunyip Information Systems Inc.

Copyright:	(c) 1992, Bunyip Information Systems Inc.
		All rights reserved.
		May be freely redistributed provided this notice
		is retained and no fee charged.
		This software is supplied with NO WARRANTY,
		EXPRESSED OR IMPLIED.



System Files
-------------

defines.h	- contains global defines for the system. This file is
		  included in all program files. This file shouldn't normally
		  have to change.
		  
declares.h	- contains the global declares (eg. input line buffer, 
		  associated ptrs, token variables, query header, etc)
		  this is included _only_ in the files main.c and the
		  engine.c. Note that the various parsing routines pass info
		  in several global variables, all of which are declared in
		  this file.

externs.h	- the companion to declares.h for inclusion in every 
		  other module in the system. It lets the compiler know
		  what the various variables are without actually allocating
		  any space.

main.c		- contains the code to fetch user input, open pipes, etc.
		  Calls "parse_query()" to sort things out before sending to
		  search engine.

parser.c	- contains parse_query() and associated routines. This is
		  a simple loop, calling "parse_term()" to parse each term
		  of a command.

term.c		- contains parse_term() and associated routines. This is a
		  simple Finite State Machine designed around the format of
		  the structure of a valid command. Calls "get_token()" to
		  actually fetch another token from the input line.

get_token.c	- contains the "get_token()" routine, which is
		  a Finite State Machine to provide a simple lexical
		  analyser. This should probably all be lex'ed and yacc'ed.
		  <Sigh> one day..

engine.c	- a skeleton for a search engine that is invoked by the
		  query engine. it receives a single query on stdin, and
		  rebuilds the equivalent to the query structure found in the
		  query engine after successfully parsing the input line.
		  It should as a minimum search a hierarchy of directories
		  for records and returns the results on stdout. It should
		  ideally be replaced with a much more efficient search
		  engine based upon WAIS, etc. This is under development.


Installation Instructions:
--------------------------

1) Configure install.h
-----------------------

To begin installation, first set up the file "install.h", selecting
appropriate values for the various declares. These are all explained in the
file, but the main points are to select yourself a whoisd directory (which
must contain subdirectories for each template type to be supported and the
various system help messages) and specify the path to the search engine,
which is spawned by the query engine.


2) Make the query and search engines
--------------------------------------

Once you have finished setting up "install.h", type "make" and it should
compile the query engine. This will be named "whoisd" by default. There's no
brain surgery here, so there should be no problems. If so, please let me
know. Note that this has only been tested on a NeXT, but you should have no
problems on a Sun or any other Berkeley box, since I do nothing really
clever.

Once you have the query engine built, you can start to work on the search
engine. A prototype search engine is included in the file "engine.c", but if
your name is Jim Fullton, presumably you will need to add the actual search
capability. :-) It turns out that the protocol spoken between the query
engine and the search engine is almost irrelevant in understanding any of
this. The important point is that once the two stop talking, you should have
a valid "query_type" structure filled in, with the various search terms in
associated "term_type" structures. Your search engine code can either be
included in "engine.c", or (maybe nicer in the long run) it can fork off the
real search engine, reserving engine.c for preparing the received query and
formatting the reply.

See "declares.h" for details of the associated structures and "defines.h"
forthe associated declares.


3) Install executables and HELP files
--------------------------------------

Assuming you have both a query engine and a search engine built, you can put
things in their new homes. Move the executables to where they will live.
The query daemon should be copied somewhere visible. We use "/usr/local/bin"
for such things, your mileage may vary. You may want to create a dummy
"whois" user, and chown the software to him, although I haven't been doing
that myself. Of coure, inetd runs as root.

You will need as a minimum, an "IAFA-HELP" subdirectory with the HELP and
HELPHELP files in them, for now.  The IAFA-HELP directory from the release
should be copied into the "whoisd" home directory you specified in
"install.h". You will also need (for now) a copy of a blank template for
each template type supported to be placed into a directory with the same
name as the template. These are picked up and served for the "list" and
"template" commands. I plan to clean this up later.

Eventually, there will be a "make install" option. Bear with me.


4) Test the query engine
--------------------------

You can test things by running the query program by hand. It reads one line
from stdin on startup, parses it and then (if valid) processes the associated
command.

There's still a _lot_ of debugging messages throughout the code, and if you
want to see these, look at the routine "logit()", in file "main.c". There is
an "if" statement to find the messages from each routine, and if it finds
one it bypasses printing the associated message.  Comment out the "if"
statement for any routine you want to trace, then recompile. The system will
then tell you what it's up to with messages to stdout.

This works in "engine.c" as well, although if there are problems and the
server dies, you might not see them. Eventually, I want to add real logging
capability (that is, writing to a log file) but that comes later.


5) Notify inetd
 --------------- 

Once you have got the query daemon running to your satisfaction and
installed where it will live, you must tell inetd about it. To do this, you
should add a line similar to the following to the file "/etc/inetd.conf":

whois   stream  tcp     nowait  nobody  /u/peterd/bin/whoisd    whoisd

Don't forget to check that you don't already have a "whois" program in the
file and don't forget to set the right path.....


Once you've written out this file, don't forget to send the inet daemon a
SIGHUP signal with kill to get it to reread the "/etc/inetd.conf" file, thus:

		# ps aux | grep inetd

<find pid for inetd>

		# kill -SIGHUP <pid_of_inetd>


Of course, this must be done as root.


6) Final test with telnet...
------------------------------

You can now test things out by telnetting to the whois port, thus:

	telnet yourmachine.wherever whois

You should get the intro message and command prompt. Try "help" to get
started.

That should be it, unless I've forgotten something. If so, please let me
know and I'll fold it back into the next release. A lot of this can and will
be automated later.

Also, please don't do lots of hacking on this code without letting me know.
It's far from perfect, but I'd like to keep changes limited for now. Once
we turn it loose I expect much better implementations to start popping up,
but for now I don't want to have to give advice on versions that have been
too heavily changed without me knowing how.


That's it for now. Assume that if you are reading this you don't have the
latest version, since this program is still under active development, in
between a gazillion other things. Please send comments, bug reports,
suggestions, etc to me at the address below.


Maintained by:	Peter Deutsch
Email address:  peterd@bunyip.com
Last Update:	August 7, 1992.


