<SOA number>{%d}
<cached number>{%d}
<mode>{single|multi}
<type>{%s}
Example of use:
%status limit: 1500
%status load: 1.23
%status cache: off
%status holdconnect: on
%status forward: off
%status Authority:25
%status Cached:200
%status display multi: summary
3.4.5 xfer
The %xfer response will send all instances of an object. This is in
response to the -xfer directive. The transfer may be limited by the
arguments to the directive. If there are no arguments, the server
must send all of the objects in the database. Cached data must not
be transferred using this method unless caching is turned on.
Each object instance is sent with a blank %xfer response between
instances.
Format for use:
%xfer<SP>[<object>:<attribute>:<value>]
These arguments are not required if the current response is an object
instance separator.
<object>{%s} This required argument represents the name of
the object being transferred.
<attribute>{%s} This required argument identifies the attribute
being sent.
<value>{%s} This required argument contains the value of the
attribute. If blank, the attribute value is
blank.
Example of use:
%xfer user:last-name:Kosters
%xfer user:first-name:Mark
%xfer user:organization-phone:703-555-1212
%xfer
%xfer user:last-name:Williamson
%xfer user:first-name:Scott
%xfer user:organization-phone:703-555-1212
%xfer
3.4.6 schema
The %schema response is used to describe the attributes of an object.
This is in response to the -schema directive.
Each attribute is sent with a blank %schema as a separator.
Format for use:
%schema<SP><object>:attribute:<attribute name>
%schema<SP><object>:format:<format string>
%schema<SP><object>:description:<descriptive string>
%schema<SP><object>:indexed:<indexed>
%schema<SP><object>:required:<required>
%schema<SP><object>:multi-line:<multi-line>
%schema<SP><object>:type:<type>
%schema<SP><object>:primary:<primary>
%schema
These arguments are not required if the current response is an
attribute separator.
<attribute name>{%s} This required argument identifies the
name of the attribute being described.
<format string>{%s} This required argument describes the
allowed format for the attribute.
<descriptive string>{%s} This required argument describes the
attribute's use.
<indexed>{on|off} This required argument identifies
attributes that are indexed.
<required>{on|off} This required argument identifies
attributes that are required.
<multi-line>{on|off} This required argument indicates whether
the attribute can span multiple lines.
<type>{text|MIME|see-also|PostScript}
This required argument identifies the
type of the attribute.
<unique-key>{on|off} This required argument indicates whether
the attribute is a unique key.
Example of use:
%schema user:attribute:Object-Type
%schema user:description:Name of the object
%schema
%schema user:attribute:Email
%schema user:format:[%Memail]
%schema user:description:RFC-822 compliant Email address
%schema
%schema user:attribute:Organization-Phone
%schema user:format:[%3d[0-999]-%3d[0-999]-%4d[0-9999]]
%schema user:description:Work phone number
%schema
3.4.7 define
The %define response describes format macros to the client. All
format macros used in the schema format definition string must be
available to the client through the -define directive. Format macros
may be nested. It is the client's responsibility to request all
format strings that are unrecognized from a server. If the format
strings change on a server, the serial number of the schemas that use
the format must change.
Format for use:
%define<SP><macro name>:<[format string]>
[NOTE: The brackets around the format string are required to ensure
that spaces contained in the format string are interpreted correctly
by the client.]
Example of use:
%format server:[%s:%16Bd]
%format email:[%s@%s]
3.4.8 object
All visible objects on an RWhois server must be identified in
response to a -object directive. The %object response either
confirms the existence of an object or returns a complete list of all
objects available to the currently connected user.
A blank %object line serves as an object separator.
Format for use:
%object
%object<SP><object name>:description:<object description>
%object<SP><object name>:restrict:<restriction words>
<object name>{%s} This required argument is the name of
the object.
<object description>{%s} This required argument is a description
of the object identified.
<restriction words>{%s} This required argument is a list of
words used to restrict a search to this
object.
Example of use:
%object user:description:user records for entity POC
%object user:restrict:user
%object user:restrict:person
%object user:restrict:mailbox
3.4.9 directive
The %directive response is used to display directives allowed on the
connected server. The directive name, description and syntax
attributes must be sent for each directive. If information about a
single directive is requested then only information about that
directive must be returned.
A %directive response with no arguments must be sent between
directives.
Format for use:
%directive<SP>directive:<directive>
%directive<SP>description:<description>
%directive<SP>syntax:<format>
%directive
The arguments below are required except when separating directives.
<directive>{%s} This required argument indicates the name of
the directive.
<description>{%s} This required argument describes the
directive.
<format>{%s} This required argument defines the format of
the directive.
Example of use:
%directive directive:schema
%directive description:displays schema attributes
%directive syntax:schema<SP>[%s]
%directive
%directive directive:xfer
%directive description:transfer all object[authority area]
%directive syntax:xfer<SP>[%s]<SP>[%s]
3.4.10 info
The %info response is used to give the user of the client a message.
This response is not initiated by any directive. The information
between the %info on and the %info off should be presented to the
user of the client. An ideal use of this response is to present a
Message of The Day (MOTD) to the user.
Format for use:
%info<SP><mode>
<mode>{on|off}
on: Turns the passthru mode on.
off: Turns the passthru mode off.
Example of use:
%info on
As of 3/24/1994 at 9:00 EST this server will no longer be in
service. If you have this server in your configuration file we
recommend that you change it to rs.internic.net:4343. You will
automatically be redirected there following this message.
%info off
3.4.11 display
The %display response is used to inform the client that the data
following this response is using the indicated method. The method
selected will continue to be active until a %display response is sent
without any arguments. The server must send an error message to
clients that have been identified as non-RWhois clients. This
response allows the use of display methods such as MIME [RFC1521] or
other special character sets such as those used in the Japanese
language.
Format for use:
%display<SP>extended:<extended>
%display<SP>name:<name>
%display<SP>length:<length>
%display<SP>description:<description>
%display<SP>command-line-option:<mode>
<extended> This optional argument identifies if the display
method is extended, i.e., RWhois specific.
Example of use:
%display extended:mime
MIME-Version:1.0
Content-type: image/gif
Content-Transfer-Encoding: base64
...data...
%display
3.4.12 X-
The %X- response represents extended responses. The client must have
prior knowledge of this response.
Format for use:
%X-<response><SP>[arguments]
<response>{%s} This required argument contains the response name.
Example of use:
%X-extstatus numusers:500
%X-extstatus avalslots:200
[NOTE: The above examples are not implemented in the current
RWhois prototype software. They are only examples of the %X-
response to a -X- directive. X6X error codes are used when
problems are encountered in relation to the -X- directives
contained on the server. Details can be found in Section 5.]
3.4.13 language
The %language response is used to inform the client that the data
following this response will be sent in the indicated language. The
language selected will continue to be active until a %language
response is sent without any arguments, at which time the server will
revert back to English, the default. The server must send an error
message to clients that have been identified as non-RWhois clients.
Format for use:
%language:<SP><language>
Example of use:
%language: german
RWhois Deutsche Version: 1.0
%language
3.5 Query Reduction
The critical component of the RWhois server is the ability to reduce
the query to find a server that is closer to the data. The search
algorithm of the server is the following:
1) accept a query
2) find any local matches - display them
3) find any referrals - display them
4) if no local or referral hits, reduce the query and goto step 3
Here is an example of the query ietf.cnri.reston.va.us:
1) query whois for ietf.cnri.reston.va.us
2) search rs.internic.net for information (no hits).
3) search referrals for ietf.cnri.reston.va.us (no hits).
4) search referrals for cnri.reston.va.us (no hits).
5) search referrals for reston.va.us (no hits).
6) search referrals for va.us (no hits).
7) search referrals for us (referral found) - referral to
isi.edu.
[currently on rs.internic.net:4343 for proof of concept].
3.6 Determining Authority
Authority areas are a major part of the RWhois protocol. If an
authoritative response is required, turning the cache off is the
first step. The client can also determine if the server connected
has authority over the name/number space of interest by sending the
-soa <authority area> directive. If the server has authority for the
area requested, it must return important information about the
authority area. The exchange below is a client determining if the
server is an authority for abc.net or no.net.
S wait for connection
C connect to rs.internic.net port 4343
S %RWhois V-1.0 rs.internic.net (Network Solutions, Inc. V-1.0)
C -RWhois V-1.0 (Network Solutions, Inc. V-1.0)
S %ok
C -cache off
S %ok
C -soa abc.net
S %error<SP>333<SP>Not SOA for requested authority area
S %ok
C -soa no.net
S %soa authority: no.net
S %soa ttl: 7500
S %soa serial: 45
S %soa refresh: 3600
S %soa retry: 3600
S %soa tech-contact: markk@no.net
S %soa admin-contact: stanb@no.net
S %soa hostmaster: hostmaster@no.net
S %ok
3.7 Secondary Server Interaction
A server that operates as a secondary will report an authoritative
SOA for the authority area of the data it contains. Below is the
interaction between the primary and secondary server. In reality the
secondary operation would be performed using a client specifically
designed for this purpose.
S wait for connection
C connect to slam.internic.net port 4343
S %RWhois V-1.0 slam.internic.net (Network Solutions Inc. V-1.0)
C -RWhois V-1.0 (Network Solutions Inc. V-1.0)
S %ok
C -soa internic.net
S %soa authority: internic.net
S %soa ttl: 7500
S %soa serial: 45
S %soa refresh: 3600
S %soa retry: 3600
S %soa tech-contact: markk@internic.net
S %soa admin-contact: stanb@internic.net
S %soa hostmaster: hostmaster@rs.internic.net
S %ok
C -xfer domain internic.net
S ... all data for domain object in the internic.net authority
area transferred
S%ok
C -notify inssec netman1.netsol.com:4343:domain:internic.net
S %ok
C -quit
S close connection
C close connection
3.8 Registration Process
The following is the interaction that occurs when a server accepts a
registration from a client.
S wait for connection
C connect to slam.internic.net port 4343
S %RWhois V-1.0 slam.internic.net (Network Solutions Inc. V-1.0)
C -RWhois V-1.0 (Network Solutions Inc. V-1.0)
S %ok
C -soa internic.net
S %soa authority: internic.net
S %soa ttl: 7500
S %soa serial: 45
S %soa refresh: 3600
S %soa retry: 3600
S %soa tech-contact: markk@internic.net
S %soa admin-contact: stanb@internic.net
S %soa hostmaster: hostmaster@rs.internic.net
S %ok
C -private auth password 98uuuts
S %ok
C -register on add scottw@netsol.com 98uuuts
S %ok
C ... send all attributes for object to register
S %error 120 Registration not processed... will process hours:24
C %quit
3.9 Out-of-Service
Servers that are being taken out of service should automatically
refer the client back into the tree. Of course, this is not possible
if the system which hosts the server is out of service. In this
case, the client's robustness must be relied upon to return to the
referrer and notify that server that the referral was bad. If the
system will still be available on the Internet, the following
exchange is recommended:
S wait for connection
C connect to slam.internic.net port 3636
S %RWhois V-1.0 slam.internic.net (Network Solutions Inc. V-1.0)
C -RWhois V-1.0 (Network Solutions Inc. V-1.0)
S %info on
S This server will no longer be in service. You should
S change your configuration file to reflect the new root
S server at rs.internic.net:4343. You will automatically be
S referred to the new root.
S %error 200 Service not available referral to follow
S %referral rs.internic.net:4343
S close connection
C close connection
4. Interaction: Client Directives and Acceptable Server Responses
This section describes the responses to the various client
directives.
4.1 General
The responses below are general responses that can occur as a result
of any directive. Therefore, they will not be repeated under each
directive.
%ok
%error<SP>400<SP>Invalid Server Directive
%error<SP>100<SP>Get Peer Name query failed
%error<SP>500<SP>Memory Allocation Problem
%error<SP>401<SP>Not authorized for directive
%error<SP>402<SP>Unidentified error... continue
%error<SP>502<SP>Unrecoverable error... goodbye
%error<SP>503<SP>Idle time exceeded... goodbye
4.2 On Connection
These responses will only occur following successful connection to
the server's host and start-up of the application:
%RWhois
%error<SP>501<SP>Service not available
%referral
%error<SP>503<SP>Idle time exceeded... goodbye
4.3 <QUERY>
These responses may occur following a query:
<answer>
%referral
%see-also
%error<SP>334<SP>Pre-query directive not implemented
%error<SP>230<SP>No Records Found
%error<SP>130<SP>Not authority for answer... TTL good
%error<SP>231<SP>Not authority for answer... TTL expired
4.4 -RWhois
%error<SP>300<SP>Not compatible with that version number
4.5 -load
%load
%error<SP>335<SP>System's load not available
4.6 -limit<SP>< value >
%limit
%error<SP>330<SP>Exceeded Max Records Limit
%error<SP>331<SP>Invalid Max Records Size
4.7 -schema<SP>[object]
%schema
%error<SP>337<SP>Object's schema not found
4.8 -xfer<SP>[object]
%xfer
%error<SP>332<SP>Nothing to transfer
%error<SP>337<SP>Object's schema not found
4.9 -quit
%ok
4.10 -cache<SP><on/off>
%error<SP>232<SP>Cache disabled
4.11 -status
%status
4.12 -forward
%error<SP>431<SP>Not authorized to forward
%error<SP>433<SP>Bad reference on forward
4.13 -soa
%soa
%error<SP>333<SP>Not SOA for requested authority area
4.14 -notify
%error<SP>434<SP>Referral does not exist on this server
%error<SP>530<SP>Not authorized as secondary
4.15 -register
%error<SP>120<SP>Registration not processed... will process
hours:<hours>
%error<SP>320<SP>Invalid attribute line:<line number>
%error<SP>321<SP>Invalid format line:<line number>
%error<SP>322<SP>Required attribute missing name:<attribute
name>
%error<SP>323<SP>Required related object missing name:<object
name>
%error<SP>324<SP>Primary key not unique
%error<SP>420<SP>Registration not authorized
%error<SP>421<SP>Not authorized to change object:<object
name><SP>key:<key>
4.16 -holdconnect
4.17 -object
%object
%error<SP>336<SP>Object not defined
4.18 -define
%define
%error<SP>435<SP>Macro not defined
4.19 -X-
%X-
%error<SP>460<SP>Extended directive not recognized
%error<SP>461<SP>Extended directive not authorized
4.20 -display
%display
%display<SP>436<SP>Display mode not allowed
4.21 -language
%language<SP>437<SP>Language not supported
5. Error Codes
The error code immediately follows the %error response from the
RWhois server. The definitions of the error codes are below. The
error codes are descriptive so that the client can group the error
messages in order to determine group action that must be taken before
taking error specific action. Error codes should remain consistent
without variable extensions except for messages associated with the
registration process. If a client receives a `6' in the second
position of the error code and the client does not support the
extended code received, the client must act on the first position
code. (Example: If a client received %error 561 and the client did
not support the extended error codes for the server currently
connected, the client would exit based on the `5' in the first
position of the error code.)
X00
1 - information only, no action required
2 - information, action required
3 - Specific command error, retry that command or try
another directive
4 - Serious for current directive, may correct with another
directive
5 - Fatal, must disconnect
0X0
0(1) - System wide, no specific directive
2 - Registration error
3(4,5) - Specific directive
6 - Extended message (version specific)
00X
Sequential order
5.1 Error Code List
Below is an ordered list of RWhois error codes. These codes may be
extended with implementation specific codes. These extended codes
will have a `6' in the second position of the code.
100 Get Peer Name query failed
120 Registration not processed... will process hours:<hours>
130 Not authority for answer... TTL good
200 Service not available... Referral to follow
230 No Records Found
231 Not authority for answer... TTL expired
232 Cache disabled
300 Not compatible with that version number
320 Invalid attribute line:<line number>
321 Invalid format line:<line number>
322 Required attribute missing name:<attribute name>
323 Required related object missing name:<object name>
324 Primary key not unique
330 Exceeded Max Records Limit
331 Invalid Max Records Size
332 Nothing to transfer
333 Not SOA for requested authority area
334 Pre-query directive not implemented
335 System's load not available
336 Object not defined
337 Object's schema not found
400 Invalid Server Directive
401 Not authorized for directive
402 Unidentified error... continue
420 Registration not authorized
421 Not authorized to change object:<object name><SP>key:<key>
431 Not authorized to forward
432 Not authorized to transfer
433 Bad reference on forward
434 Referral does not exist on this server
435 Macro not defined
436 Display mode not allowed
437 Language not supported
460 Extended directive not recognized
461 Extended directive not authorized
500 Memory Allocation Problem
501 Service not available
502 Unrecoverable error... goodbye
503 Idle time exceeded... goodbye
530 Not authorized as secondary
6. Attribute Format
The format for all attributes for objects in the RWhois server must
be specified using a format specifier. This definition will allow
the client software to interpret the received data correctly. The
RWhois format specifier closely follows the `C' language scanf syntax
with macro extensions.
Format specifiers must follow this pattern:
%[alignment][length restriction]<type>[range restriction]
[alignment] '-' = left justified
'.' = right justified
[length restriction] <value> = number of bytes allowed
<value>B = number of bits allowed
<type> This is the only required part of the format specifier.
Below are the allowed format type values. The length
of these values are not specified. These restrictions
will be on the left of the [length restriction].
%c Character
%s String
%d Integer
%x Hex Integer
%o Octal Integer
%f Float
%e Scientific
%M defined macro
[range restriction] The range restriction will limit the allowed
values. This may specify a number,
character, or string range.
Examples: %-3s["ON","OFF"] = Defines a string with 3 characters
left aligned and limited to the
strings ON or OFF.
%16Bd[0-50] = 16 bit integer between 0 and 50
%4.2f[0-2500.50] = Defines a floating point number
limited to 4 digits before and 2
after the decimal with a value
between 0 and 2500.50.
6.1 Format Specification Macros
Format specifications may be presented as macros. Format
specification macros may be defined using the following format.
%M<macro name>=<format string or earlier macro>
The following macros are pre-defined in this RWhois specification:
Month/Day/Year formats:
%MM=[%-2d[0-12]]
%MD=[%-2d[0-31]]
%MY2=[%-2d[0-99]]
%MY4=[%-4d[0-9999]]
%MMs=[%-3s\
["JAN","FEB","MAR","APR","MAY","JUN","JUL","AUG","SEP",\
"OCT","NOV","DEC"]]
Date formats:
%Mdate1=[%MM/%MD/%MY2]
%Mdate2=[%MM/%MD/%MY4]
%Mdate3=[%MD-%MMs-%MY2]
%Mdate4=[%MD-%MMs-%MY4]
%Mdate5=[%MY4%MM%MD]
Hour/Minute/Second formats:
%MTH=[%-2d[0-24]]
%MTM=[%-2d[0-59]]
%MTS=[%-2d[0-59]]
Time formats:
%Mtime1=[%MTH:%MTM:%MTS]
%Mtime2=[%MTH%MTM%MTS]
Miscellaneous formats:
%Mserver=[%s:%16Bd]
%Mipnumber=[%8Bd.%8Bd.%8Bd.%8Bd]
%Memail=[%s@%s]
%Mserial=[%Mdate5%Mtime2]
%Mstype=[RWHOIS/WHOIS/WHOIS++/OTHER]
%Murl=[%s://%s]
Macro definitions may be obtained by sending the -define directive to
the server. For client efficiency, definitions can be remembered.
If the definition of a macro changes, the serial number of all
schemas using that macro must change, allowing the client to
reacquire the schema and format specifier macros.
7. Quick Query (RWhois using UDP)
The overhead incurred by establishing a TCP connection and
interacting with an RWhois server may be unnecessary if the client
only wishes to ask one question. A separate document will describe
the UDP facility for RWhois. Adjustments to the query must be made
to make this a practical option. The only function allowed while
utilizing UDP is a single query.
8. References
[RFC-954] Harrenstien, K., Stahl, M., and E Feinler, "NICNAME/
WHOIS", RFC954, SRI, October 1985.
[RFC-1521] Borenstein, N., and N. Freed, "MIME (Multipurpose
Internet Mail Extensions) Part One: Mechanisms for
Specifying and Describing the Format of Internet
Message Bodies", RFC1521, Bellcore, Innosoft,
September 1993.
9. Security Considerations
Security issues are not discussed in this memo.
10. Authors' Addresses
Scott Williamson
505 Huntmar Park Dr.
Herndon, VA 22070
Phone: (703) 742-4820
EMail: scottw@internic.net
Mark Kosters
505 Huntmar Park Dr.
Herndon, VA 22070
Phone: (703) 742-4795
EMail: markk@internic.net