RFC 1714
Network Working Group S. Williamson
Request for Comments: 1714 M. Kosters
Category: Informational Network Solutions Inc.
InterNIC
November 1994
Referral Whois Protocol (RWhois)
Status of this Memo
This memo provides information for the Internet community. This memo
does not specify an Internet standard of any kind. Distribution of
this memo is unlimited.
Abstract
This memo describes version 1.0 of the client/server interaction of
RWhois. RWhois provides a distributed system for the display of
hierarchical information. This system is hierarchical by design,
allowing for the reduction of a query, and the referral of the user
closer to the maintainer of the information.
Table of Contents
1. Introduction................................... 3
2. RWhois Client Model............................ 5
2.1 Directives: Client to Server Interaction ... 6
2.2 Required Directives ......................... 6
2.2.1 .................................. 6
2.2.2 RWhois................................... 7
2.3 Optional Directives ......................... 7
2.3.1 load..................................... 7
2.3.2 limit.................................... 7
2.3.3 schema................................... 8
2.3.4 xfer..................................... 8
2.3.5 quit..................................... 9
2.3.6 status................................... 9
2.3.7 cache.................................... 9
2.3.8 holdconnect..............................10
2.3.9 forward..................................10
2.3.10 soa.....................................11
2.3.11 notify..................................11
2.3.12 register................................13
2.3.13 object..................................14
2.3.14 define..................................15
2.3.15 private.................................15
2.3.16 X-......................................16
Williamson & Kosters [Page 1]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
2.3.17 directive...............................17
2.3.18 display.................................17
2.3.19 language................................18
2.4 RWhois Client Model .........................18
3. RWhois Server Model............................20
3.1 Output Display and Restriction Keywords .....20
3.2 Responses: Server to Client Interaction ....21
3.3 Required Responses ..........................22
3.3.1 RWhois...................................22
3.3.2 referral.................................22
3.3.3 ok.......................................24
3.3.4 error....................................24
3.4 Optional Responses ..........................25
3.4.1 see-also.................................25
3.4.2 load.....................................26
3.4.3 soa......................................26
3.4.4 status...................................28
3.4.5 xfer.....................................29
3.4.6 schema...................................30
3.4.7 define...................................32
3.4.8 object...................................32
3.4.9 directive................................33
3.4.10 info....................................34
3.4.11 display.................................34
3.4.12 X-......................................35
3.4.13 language................................35
3.5 Query Reduction .............................36
3.6 Determining Authority .......................36
3.7 Secondary Server Interaction ................37
3.8 Registration Process ........................38
3.9 Out-of-Service ..............................38
4. Interaction: Client Directives and Acceptable
Server Responses...............................39
4.1 General ......................................39
4.2 On Connection ................................39
4.3 ......................................39
4.4 -RWhois ......................................40
4.5 -load ........................................40
4.6 -limit< value > ..........................40
4.7 -schema[object] ..........................40
4.8 -xfer[object] ............................40
4.9 -quit ........................................40
4.10 -cache ..........................40
4.11 -status .....................................40
4.12 -forward ....................................40
4.13 -soa ........................................40
4.14 -notify .....................................41
4.15 -register ...................................41
Williamson & Kosters [Page 2]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
4.16 -holdconnect ................................41
4.17 -object .....................................41
4.18 -define .....................................41
4.19 -X- .........................................41
4.20 -display ....................................41
4.21 -language ...................................41
5. Error Codes....................................42
5.1 Error Code List .............................42
6. Attribute Format...............................43
6.1 Format Specification Macros .................44
7. Quick Query (RWhois using UDP).................45
8. References.....................................46
9. Security Considerations....................... 46
10. Authors' Addresses.............................46
1. Introduction
Early in ARPANET development, the SRI-NIC established a centralized
whois database that provided host and network information about the
systems connected to the network and the E-mail addresses of the
users on those systems. The ARPANET experiment has evolved into a
global network with countless people and hundreds of thousands of end
systems. Given the sheer size and effort needed to maintain a
centralized database, an alternate, decentralized approach to store
and display this information is desired.
The Internet portions of the DDN NIC have been transitioned to what
is now known as InterNIC Registration Services (RS). The charter for
InterNIC RS has been reduced to maintain information only for IP
networks, top-level domains, Autonomous System Numbers, and the
points of contact for each of these particular entities. In
addition, the InterNIC, in its role as an Internet Registry (IR), has
delegated IP block assignment authority to Regional Registries such
as the RIPE NCC for Europe and the APNIC for the Asian Pacific
region, while retaining authority for North America and all non-
delegated regions. This has led to a fragmentation of whois service
to the Internet user.
Several different solutions have been proposed and developed by the
various regional IR's. Two solutions have been worked on
extensively: the Shared Whois Project (SWIP) and X.500.
The SWIP project has a common exchange format that can be parsed by
the various IR's for input and output. Thus, one can synchronize
their databases with information obtained from the other IR's. This
project is showing promise and is now operational. However, this
approach still requires a centralized database for store and display.
Williamson & Kosters [Page 3]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
The InterNIC has also been involved in the use of X.500 for display
of registration information. Among other things, this included
defining schemas and Directory information tree structures for the
purpose of distributing information amongst the various IR X.500
Directory Service Agents (DSA). Unfortunately, X.500's complexity,
resource utilization, and lack of Internet support has made a search
for an alternative solution necessary.
The information that the various IR's maintain is inherently
hierarchical in nature. (Examples: hammer.nic.ddn.mil is under the
nic.ddn.mil domain which is under the ddn.mil domain which is under
the .mil domain. 198.41.0.21 is part of network 198.41.0.0/24 which
is part of the block 198.41.0.0/16 which is part of the block
198.0.0.0/8) The InterNIC may not have the information, but will at
least be able to reduce the query and point or refer the users closer
to their goal. This has led to the development of a referral whois,
and the corresponding RWhois protocol.
The underlying premise for this project has been to retain the basic
functionality of the whois server and client, making all of the
extensions optional. The server must respond to the original whois
client, currently included with many operating systems. The RWhois
client must also interact with RFC 954 [RFC-954] whois servers.
RWhois has been designed as an extensible protocol to ensure that
many uses can be accommodated. Public extensions to the protocol
should be documented as RFCs. Private extensions can be used with
agreement left up to the client and server.
If extensions are not implemented at the server in question, an
appropriate error message must be sent. The use of extended error
message is outlined in Section 5 - Error Codes.
Throughout this document the following notations will be used to
describe the RWhois server/client interaction:
space
[arg] optional argument
required argument
() conditional required argument
([arg]) conditional optional argument
{format} format of item
\ continued on next line
The words should and must are significant in this document. If
should is used, the implementor has the option to follow the advice
of this document. If must is used then it is a required part of the
protocol. Implementations without this functionality may not
Williamson & Kosters [Page 4]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
interact correctly with other RWhois servers.
The format descriptions throughout this document use macro
definitions described in Section 6.1. Refer to that section for
clarification.
The RWhois protocol specified in this document can be extended to
accommodate such applications as NetHelp and ZoneGen (DNS zone
generator).
2. RWhois Client Model
The RWhois design requires compatibility with the current Whois and
Whois++ servers. Therefore, the RWhois client must wait or have
knowledge of server type to determine if the server contacted is an
RWhois server. The user should have control over the time the client
waits, since this will vary based on network congestion and capacity.
If after the wait the server does not respond with the %RWhois
response, the client must not send any RWhois extended directives.
In this case, the client should only send the query. We realize that
the server identification feature may mean that the identity of an
RWhois server may be missed. However, it will allow the RWhois
system to utilize the current Whois and Whois++ infrastructure.
Referrals from RWhois can be directed toward a Whois or Whois++
server. These non-RWhois servers must be placed as a leaf on the
hierarchical tree. These servers represent a mesh structure from the
RWhois perspective. This restriction should not discourage the use
of these servers in building the RWhois structure.
The RWhois server must remain connected until a query is received.
If the client wishes to make multiple queries it must send the
-holdconnect directive. In this mode, once the client has sent the
last query and received either an answer or the error code indicating
that no records were found, it must issue the -quit directive. If
the client only wishes to issue directives, then upon completion the
-quit directive must be sent. If it is not sent, the server will
wait until it receives non-directive input from the client.
Considering the requirement for compatibility with the original
whois, the RWhois client in default mode must operate exactly like
the current Whois client. However, in the enhanced mode, the RWhois
client can do much more based on information received from the RWhois
server.
Williamson & Kosters [Page 5]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
2.1 Directives: Client to Server Interaction
The RWhois client sends directives to the RWhois server. These
directives are prefaced with the `-' character always at the start of
a new line. However, for compatibility with older Whois clients, the
query is not prefaced with the `-' character. Only after the client
is certain that the server is an RWhois server should these
directives be sent. Compatibility with RFC 954 [RFC-954] whois
servers is required. All directives must be terminated by .
2.2 Required Directives
The following are required RWhois client directives.
2.2.1
The query is generally the final directive sent to the server. It is
the only directive that does not start with a `-'. The query is the
question that the client wants the server to answer. The qualifiers
that may proceed the query are addressed in Section 3.1 - Output
Display and Restriction Keywords.
Format for use:
[display format][query restriction]
[Display format]{%s} This optional pre-query directive allows
the requester to select the format of
the returned data. Details of the
allowable values can be found in Section
3.1.
[Query restriction]{%s} This optional pre-query directive allows
the requester to limit the area in which
the servers search for a specific
object.
Example of use:
dump domain netsol.com
Williamson & Kosters [Page 6]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
2.2.2 RWhois
The -RWhois directive identifies the client as an RWhois client
allowing the server to operate using the RWhois protocol exclusively.
Format for use:
-RWhoisV-[imp identifier]
{%2d.%2d} This required argument identifies
the specification version that the
client is built to conform with.
Clients that are built in
accordance with this document are
V-1.0. This argument will be used
by the server to determine if
features introduced in subsequent
releases of the protocol document
may be used.
[Imp identifier]{%s} This optional argument identifies client
implementation information. It is
recommended that the implementor maintain a
version number separate from the
specification version.
Example of use:
-RWhois V-1.0 [InterNIC B.0.9.7]
2.3 Optional Directives
The following are OPTIONAL RWhois server directives.
2.3.1 load
The -load directive allows the client to make a quick decision about
presenting the query to the current server. If the client determines
that another server can better serve the query, then control may be
transferred to the server with the lower load and better connection.
This directive has no arguments.
2.3.2 limit
The -limit directive will allow the client to request the server
allocate enough space to collect more responses than would currently
be collected by the server.
Williamson & Kosters [Page 7]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
Format for use:
-limit{%d} This required argument is the new limit requested by
the client. If the limit exceeds the limit set by
the server administrator, the client must receive an
error message. It is recommended that if the client
receives an error for exceeding the servers upper
limit, it should cut the request in half and resend
the request until an acceptable level has been
negotiated.
Example of use:
-limit 2000
2.3.3 schema
One of the shortcomings of X.500 was the requirement to know the
schema of an object before making a query. RWhois allows the client
to request the schema for an object without knowledge of the object
by using the -schema directive.
Format for use:
-schema[object]
[object]{%s} This optional argument identifies the objects for
which the schema is being requested. If this
argument is not sent, the schemas for all objects
contained in the server will be sent.
Example of use:
-schema domain
2.3.4 xfer
The -xfer directive is used to transfer all data from a server. This
method of transfer has no limit on the number of records that can be
transferred to the client application. This directive is primarily
used to transfer data contained in an authority area for caching at a
secondary server.
Format for use:
-xfer[object][authority area][SOA]
Williamson & Kosters [Page 8]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
[Object]{All|%s} This required argument identifies the
object to transfer. If the keyword all
is sent, all objects contained in the
server will be transferred. Otherwise,
only the object specified will be sent.
[Authority area]{%s} This optional argument contains the
authority area of the object to send
further limiting the data transfer.
[SOA]{%d} This optional argument notifies the server
to send everything that has been updated
since this SOA number.
Example of use:
-xfer domain netsol.com
-xfer domain netsol.com 19940818141259
2.3.5 quit
The -quit directive will inform the server that the client is
finished. The server and client should close the connection. This
directive has no arguments.
2.3.6 status
The -status directive is used to poll the server for its status.
There are seven required responses to this directive. Additional
attributes may be sent in the response. The client should ignore all
unknown attributes. This directive has no arguments.
2.3.7 cache
The RWhois server can hold data that it has no authority over. If
the server sends this data to a requester, it is considered a non-
authoritative response. The holding of this data is called caching.
The physical data for these objects is not contained on the system
hosting the server. The -cache directive allows the client to
instruct the server whether or not to send cached data. The RWhois
client should start with the cache turned off. The server must start
with the cache turned on in order to function like the RFC 954 [RFC-
954] whois server. Because of the server's default, the client
should send the -cache off directive during initial session setup if
cached data should not be sent. Details on expiration of cache data
can be found in section 3.4.3, %soa response.
Williamson & Kosters [Page 9]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
Format for use:
-cache{on|off}
on: Turns caching on.
off: Turns caching off.
Example of use:
-cache on
2.3.8 holdconnect
The RWhois server must close the connection after the response to a
query has been received. The query is the final exchange between the
client and server. However, this characteristic can be modified with
the -holdconnect directive. If this directive is issued to the
RWhois sever, it will remain connected until the -quit directive is
received. Once the -quit directive is received, both the server and
the client must close their connection.
Format for use:
-holdconnect{on|off}
On: Turns holdconnect on.
Off: Turns holdconnect off.
Example of use:
-holdconnect on
2.3.9 forward
During normal sever operation the server will send %referral or
see-also responses to the client, expecting the client to redirect
the query to the server identified in the response. If the client is
located behind a firewall or is poorly connected, having a server
make the query may improve query performance or allow a query to be
satisfied. The -forward directive will instruct the server to
operate as a forwarding server. Whether or not this directive should
be allowed should be a configuration parameter of the server.
Williamson & Kosters [Page 10]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
Format for use:
-forward{on|off}
On: Turns forwarding on.
Off: Turns forwarding off.
Example of use:
-forward on
2.3.10 soa
The identification of authority area is an important part of the
RWhois design. The -soa directive is used to question the server's
authority for a specific area. A positive response will include the
administrative parameters for the authority area as detailed in
section 3.4.3. If the server does not contain an SOA for the
authority area requested, it must send an error message to the
client.
Format for use:
-soa[authority area]
[Authority area]{%s} This optional argument identifies the
authority area being requested. If this
argument is not sent, information about
all authority areas contained in the
server must be sent.
Example of use:
-soa netsol.com
2.3.11 notify
The -notify directive is used to notify a server of a bad or
recursive referral or a change in a primary server's data.
Format for use:
-notify{badref|recurref|update|inssec|delsec}
Williamson & Kosters [Page 11]
RFC 1714 Referral Whois Protocol (RWhois) November 1994
badref When a client receives a %referral response that does
not work, it must report the bad referral to the server
that issued the referral. The referral is bad only if
the referred server does not contain the SOA record for
the authority area in question. It is not considered a
bad referral if the server does not have an answer to
the query, but responds positively to the -soa area
directive. This merely means that there is not an
answer to the query. When a -badref is sent to the
referring server; it should log the bad referral so the
administrator of that server can remove the reference
if it is no longer correct. This action should only be
taken after receiving a negative response to the query
and the SOA request.
recurref When a client receives a referral that results in a
recursive action, the referring server must be
informed. The -recurref directive must be sent
identifying the recursive loop. This directive should
only be sent to the server one level back, even if
multiple server were involved in the referral.
update An RWhois primary server must be aware of its
secondary servers. If the data in the primary server
changes, the primary server may choose to notify the
secondary servers. This allows the secondary servers
to quickly reflect changes in the primary server's data.
inssec This action will inform the authority server that the
server indicated in the argument will be a secondary
for its authority area. The server receiving this
directive must determine if the secondary is
acceptable. If it is, the server should be added to
the update list so that it will be informed if data in
the authority area changes.
delsec This action will inform the server that the server
indicated in the subsequent arguments will no longer be
a secondary. The server receiving this action must
determine if the server is a secondary and if so,
remove it from the update list.
{action=badref|recurref <:>
action=inssec|delsec|update
<: