********* DRAFT **********
RWhois - Referral Whois Client Program V-1.0BETA2


rwhois [-v -d -q -m -s -- -+] [-h host[:port]] [-a host[:port]] 
[-c config file] [-f command][-t authority][-e userid][-p authstring]

Summary

This document reflects the features of the client developed as
the prototype for the RWhois protocol. Some of the features are
implementation preferences of the author and do not represent the
required elements of the protocol.  Please refer to the RWhois
protocol RFC  (RFC 1714) for more detailed information.  This
client will interact with Whois, RWhois and RWhois root servers.
It also has the limited ability to interact with
Whois++ servers.

The RWhois server/client protocol allows for delegation of
information linked in a hierarchical fashion.   A RWhois root
server is a server at the top of the search heirarchy.  The
client will query a server identified in the command line or
configuration file instruction, otherwise it will query the
default server. There are several scenarios for client/server
interaction.

RWhois servers are located at multiple sites around the Internet.
Each server is administered by the local site administrator.
Servers typically contain information relevant to the
organization hosting the server.  Server data may be changed by
the local administrator or remote RWhois client user.


If the user directs the client to contact an RWhois server that
is not a root RWhois server and the information requested does
not exist at that server, the client will be directed to refer to
another RWhois server closer to the RWhois root server. If the
server queried is an RWhois root server and the information
requested does not exist at that server and the query can not be
reduced, the server will send a data not found error to the
client, ending the session.  If the root server can reduce the
query, the client will be referred to a server that has
information about the query.  Whois and Whois++  servers are leaf
servers.  Leaf servers can answer a query, but can not refer the
client back to the RWhois heirarchy.  If the server to which the
client was referred is a leaf server and the answer is not
contained in that server, a query not found message in the leaf
server format will be received.


There are two ways to modify the behavior of the RWhois client.
One is by adding command line options at execution time. This
method will modify the client behavior for the current execution
alone. The second method is to use a configuration file, of which
there are three means.



Command line options :

Command line options affect the action of the client for the
current execution only. They may be entered at any position on
the command line. Each command will be executed in the order they
are presented with the exception of the verbose level commands
which are processed first regardless of where they are in the
command line.  If there are conflicting commands, the last one
processed will prevail.

-a <server name>

   ADD TO THE CURRENT SERVER LIST. This option adds the specified
   server to the end of the current server list. (NOTE: Great for
   searches where the user knows that the information may be at
   another server.)
   [same as configuration instruction "server add <name>"]

   [rwhois -a rwhois.ripe.net:4321 test.ripe.net]
   [rwhios -h slam.internic.net:43 -a dmeister.thomtech.com:4321
   williamson]

-c <configuration file>

  LOAD SPECIFIED CONFIGURATION FILE.  This option will load the
  specified configuration file.  Note:  The position of  -c  on
  the command line is important. Any command line option or
  configuration file loaded prior to the -c command line option
  will be overridden by the instructions contained in the
  configuration file.

  [rwhois -c slam56.rc internic.net]
  [rwhois -c biglimit.rc -c slam43.rc smith]

-d

   VERBOSE LEVEL SHOUT. User will receive messages about
   connection attempts, connection progress, warning and fatal
   error messages, and general statistics.
   [same as configuration instruction "verbose shout"]

   [rwhois -d -h slam.internic.net sw226]

-e <query string>

  EDIT THE OBJECT INSTANCE ASSOCIATED WITH THE QUERY STRING.
  This option will cause the client to process a registration
  add/modify operation with the default server or the server
  indicated in the -h option. The client will query the server
  with the query string using the dump output format modifier.
  The server response will be collected in a temporary file and
  passed to the editor.  A copy of the original data is
  maintained to compare with the editor results to ensure that
  changes were made before sending the new information to the
  server.  If changes were made the registration directive will
  be sent with the new information.

  [rwhois -d -h slam.internic.net:5656 -e sw226 -u
  scottw@thomtech.com -p No_My_AUthstring]


-f<directive>

  FORCE RWHOIS DIRECTIVE.   This option will direct the client
  to send a RWhois directive to the server.  If the directive
  contains more than one word it must be enclosed in quotes. The
  allowable server directives are:

            define [macro name]
          directive [directive]
          limit <value>
          load
          object [object]
          schema [object]
          soa [authority area]
          status
          xfer [object]
          
  [rwhois -h slam.internic.net -f status]
  [rwhios -h dmeister.thomtech.com:4321 -f schema user]

-h <server name>

   OVERRIDE THE CURRENT SERVER LIST. This option will replace the
   current server list with the server identifier following the -
   h option. The server's host name is required. The port may
   optionally be specified if the value differs from the default.
   The port number for the server is appended to the host named
   with the ":port". (example: -h slam.internic.net:4321  where
   host = slam.internic.net and port = 5656 ) If no port is
   specified, the default port will be used. The default port for
   this client is 4321, but can be overridden in a configuration
   file.   ( NOTE: The 4321 is the official IANA assigned port
   number for the RWhois application.)
   [same as configuration instruction "server change <name>"]

   [rwhios -h dmeister.thomtech.com:5656 williamson]

-k <query string>

  DELETE/KILL THE OBJECT INSTANCE ASSOICATED WITH THE QUERY
  STRING.  This option will cause the client to process a
  registration delete operation with the default server or the
  server indicated in the -h option. The client will query the
  server with the query string using the dump output format
  modifier.  The server response will be collected in a
  temporary file and passed to the editor for display to the
  user. If the user indicates that the object is the correct
  object to delete the client will instruct the server to delete
  the object .

  [rwhios -h dmeister.thomtech.com:5656 -u scottw@thomtech.com -
  p Not_It -k sw226]

-m

   ALLOW MULTIPLE SERVER QUERIES. The client will continue to
   query the servers identified in the server-list regardless of
   whether a referral or answer is received.  [same as
   configuration instruction "shots multi"]

   [rwhois -a rwhois.ripe.net -m smith]

-p <authentication string>

  IDENTIFIES THE AUTHENTICATION STRING.  For certain queries or
  registration actions, the server will require client
  authentication.   With the -p option, the user is able to
  satisfy the requirement.  Following the -p option, the user
  types a string of characters which the client will apply
  during its authentication process with the server.  The use of
  the string by the client depends on the type of authentication
  process being used (i.e. PGP, SKEY, plain key password.)   If
  the authentication string contains spaces, quotes must
  surround the string.  If any of the characters are considered
  special characters by the operating shell they must be
  escaped.

  [rwhois -h slam.internic.net:43 -u sw226 -p Big string Okkkk
  pubkey markk@internic.net]

-q

   VERBOSE LEVEL QUIET. User will not receive progress or error
   messages. This is recommended when doing compares between two
   Whois servers.
   [same as configuration instruction "verbose quiet"]

   [rwhois -q scottw@thomtech.com]
-s

   RESTRICT QUERY TO A SINGLE SERVER. This option initiates a
   single server mode in that once a server name is resolved and
   a good connection is made, the client will query the server
   then quit.  As a result, the client will not accept referral
   or see-also responses from that server.  Note:  This forces
   the client to behave like the whois client.
   [same as configuration instruction "shots single"]

   [rwhois -s williamson]

-t

  REQUIRE SOA CHECK.  This option instructs the client to check
  the server for SOA information about the query.  The user will
  be informed whether or not the information returned is
  authoritative based on the presence of the SOA record in the
  server.

  [rwhois -d -t dmeister.internic.net]

-u     <user id>

  IDENTIFIES THE USERS RWHOIS IDENTITY. This option is only
  necessary if authentication is required and the user
  instruction  has not been issued in a configuration file, or
  if  the user wishes to change the active user id.  The user id
  is often the email address of the sender.  This value will be
  used as part of the authentication process to identify the
  user for interactions with the server .

  [rwhios -h slam.internic.net:4343 -u sw226 p Not-The word -e
  sw226]

-v

   VERBOSE LEVEL TALK. User will be informed of connection
   attempts, fatal errors, and general progress of the client.
   [same as configuration instruction "verbose talk"]

-x <extended directive>

  SEND AN EXTENDED DIRECTIVE TO A SERVER.  Extended directives
  are capabilities added to an Rwhois server that are beyond the
  capability specified in the Rwhois protocol (i.e. date)
  Following the option, the user types the directive.  If the
  server does not support the extended directive, the user will
  be informed by an error message. If the extended directive
  contains more than one word it must be enclosed in quotes.

  [rwhios -h slam.internic.net -x date]
  [rwhios -h dmeister.thomtech.com:4321 -u sw226 -p Not_My
  password -x dns genzone labs.thomtech.com]

--

  SHOW FINAL CONFIGURATION AND EXIT.  This option directs the
  client to load in proper order all configuration files and
  command line options.  The client will then display the final
  configuration and exit before connecting to the RWhois server.
  This enables a user on a multiuser system to check the default
  configuration  set by the system administrator.

  [rwhois --]

Configuration file:

A configuration file is a text file consisting of RWhois
instructions used to modify the behavior of the Rwhois client.
Of the three ways to address a configuration file, the first two
are automatically attempted by the client.  In the event that the
files are not present at the location specified, no action will
be taken, and unless the user is in the verbose mode talk, the
user will not be informed whether the configuration files are
present or readable.  The third  method is user initiated.  In
the event that the configuration file specified on the command
line is not found, the user will receive an error message and the
client will exit. The order of loading is as follows:

     1 - /usr/local/etc/rwhois.rc

     This configuration file will be loaded  by all clients on
     the system  and is to be maintained by the system
     administrator. The instructions in this file will effect the
     initialization of  all RWhois clients executed on the system
     and therefore should be used for universal purposes like
     directing users to the closest RWhois servers. ( i.e.
     clients in Europe or Asia may wish to point to an RWhois
     server that supports their area before querying
     rwhios.internic.net )

     2 - $HOME/.rwhois.rc

     This configuration file will be loaded by the client from
     the users home directory. It is maintained by each user [in
     their home directory] and represents the users default
     preferences, like user id and query limits.  The user may
     also override the configuration defined by the system
     administrator [explained above]  by including specific
     instructions, i.e. to change the default configuration
     directory to somewhere within the users home directory the
     user would type:  set confdir  home/scottw/.rcfiles.

     3 - Command line -c <config file>

     This configuration file will affect the client initiating
     the instruction and is to be maintained by the user.  This
     file enables the user to override the selection of the
     system administrator and user's defaults for the current
     execution of the client only.  The command line
     configuration file preferences must be added to the command
     line each time that behavior is desired.
     

The following are configuration instructions:

CACHE [ON/OFF]
CONFDIR
EDITOR
FORWARD
MIME
SERVER [ADD/CHANGE]
SET [LIMIT/LOAD/PORT/WAIT]
SHOTS [ MULTI/SINGLE ]
URL
USER
VERBOSE [QUIET/WHISPER/TALK/SHOUT]


CACHE [ON/OFF]

     RWhois servers may cache information collected from previous
     requests or collected during pullup operations.  If set to
     ON the client will direct to the server to send cached
     information in response to the query.  If set to OFF the
     client will direct the server not to send cached
     information.

CONFDIR  [confdir /home/user/rwhois/configs]

     Sets the default configuration directory.  This will set the
     path prefix for the -c command line option. This allows the
     user to use the command line " -c ripe" instead of the more
     extensive " -c /home/user/rwhois/configs/ripe.rc "  This
     option only makes sense if included in a ".rc" file at start-
     up.

EDITOR [editor/usr/ucb/vi]

     Sets the default external editor to use during the
     registration. This will set the program to use when the
     object has been received during the ( -e or -k option ).
     This program will be executed with the temp file name passed
     as an argument. Once this program is exited the registration
     object will be sent. Be sure that the filename is not
     changed by the editor.

FORWARD [forward]

     This instruction will request that the server act as a proxy
     server.  If a referral is found the server will follow the
     referral and return the results.  The server queried will
     use a local RWhois client to forward the client's query.
     Some servers may not allow this directive. The user with a
     verbose level above WHISPER will be informed. This allows
     operation of the RWhois client from behind a firewall. If
     allowed by the server, this could improve the performance of
     a client with poor connection to the network.

MIME [mime /usr/local/bin/metamail]

     Sets the default external mime reader. This will set the
     program to be executed when a mime document is received
     during a query.

SERVER [ADD/CHANGE]

     add [server add whois.ripe.net:43]

      Add a server to the current server list (same as the -a
      command line option).

     change [server change nic.ddn.mil:43]

      Renew server list with this server at the start (same as
      the -h command line option).

SET  [LIMIT/LOAD/PORT/WAIT]

     LIMIT [set limit 2000]

      This instruction will direct the client to request an
      increase or decrease in the number of responses returned by
      the server.  If the limit requested exceeds that allowed by
      the server an error message will be returned.  The limit
      request will be cut in half then re-requested until a good
      limit level can be achieved. The user with a verbose level,
      above whisper, will be informed of the agreed limit. If a
      limit request is not sent, the server's default will be
      used. Requesting a large limit may affect the performance
      of the server. As a general rule, use of the server default
      will deliver better performance results.

     LOAD [set load 2]

      This instruction sets the acceptable level of load on a
      server host before trying another server with a lower
      level.  This operation occurs as follows:

      If the load exceeds the specified level, try another
      server.  If no other servers are available or none have a
      load level lower than the limit, return to the first
      server and go ahead with the query.

     PORT [set port 5656]

      This instruction will change the client's default port for
      connection to servers with no port assignment specified.

     WAIT [set wait 10]

      This instruction will set the time (in seconds) to wait for
      the %RWHois server response. This can be used to reduce the
      wait during an operations with non-RWhois servers or
      increase the wait to detect an RWhois server on a slow
      connection. If this is set too high, the user will have to
      wait an extended period of time for a response from a non-
      RWhois server. If it is set too low,  the client will not
      be able to detect the RWhois server and be reduced to
      traditional whois interactions.

SHOTS [MULTI/SINGLE]

     multi [shots multi]

      Go through entire server list even if an answer is
      received. (same as -m command line option)

     single [shots single]

      Once a connection is made to a server, don't contact any
      others.  The client will try others on the list if the
      server's name can not be resolved or there are problems
      with the connection. (same as the -s command line option)

URL [url /usr/local/bin/mosaic]

     Sets the default external url follower. This will set the
     program to be executed when a url is received during a
     query.  This would be a program like mosaic that can query a
     server identified by the url.

USER [user scottw@thomtech.com]

     This instruction will set the default user id to be used
     during authentication process for things such as
     registration ( -e  or -k option ).

VERBOSE

     talk [verbose talk]

      User will be informed of connection attempt, fatal errors,
      and general progress of the client (same as the -v command
      line option)

     quiet [verbose quiet]

      No progress or error messages displayed (same as the -q
      command line option)

     whisper [verbose whisper]

      User will be informed of connection attempt and fatal
      errors. (same as the default operation)

     shout [verbose shout]

      User will receive message about connection attempt,
      connection progress, warning and fatal error messages, and
      general statistics. (same as the -d  command line option)


Default client settings:

verbose = whisper
servers = rs.internic.net:4321  rs.internic.net:43
shots   = modified single ( Only the first server resolved and
      connected to will be queried. However, unlike the -s option
      or "shot single" directives referral and see-also will be
      acted upon.
confdir = current location ( . )
wait    = 5 seconds
port    = 4321
limit   = not requested, set to 0
load    = not checked, set to 0
user, mime, url, editor  =  not pre-set



Sample client configuration file:

# Contact ripe server then InterNIC RS
server change rwhois.ripe.net:43:rwhios
server add rwhois.internicn.et:4321:rwhois
# up the response limit to 2000
set limit 2000
# give me some good feedback
verbose talk
# continue down the server list even if answer recieved
shots multi
# allow 45 seconds for an inital RWhios server response
set wait 45
# set the user id to scottw@internic.net
user scottw@internic.net
# user the vi editor for object registation
editor /bin/vi
# user netscape if a url with addtional information is recived
url /usr/local/bin/netscape
# use metamail to interpet an additional information message
mime /usr/local/bin/metamail

