Software Engineering, August 1996.
[RFC2052] Gulbrandsen, A., P. Vixie, "A DNS RR for specifying the
location of services (DNS SRV)", RFC2052, Troll Technologies, Vixie
Enterprises, October 1996.
[X.500] "The Directory: Overview of Concepts, Models and Service",
CCITT Recommendation X.500, 1988.
Authors' Addresses
Scott Williamson (scottw@rwhois.net)
Mark Kosters (markk@internic.net)
David Blacka (davidb@rwhois.net)
Jasdip Singh (jasdips@rwhois.net)
Koert Zeilstra (kzeil@rwhois.net)
Postal Address:
505 Huntmar Park Drive
Herndon, VA 22070-5100
Telephone: 703-742-0400
Appendix A: Glossary Of Terms
ABNF: Augmented Backus-Naur Form. Refined version of BNF, defined in
[RFC822]. See BNF.
Attribute: A named field and the smallest typed unit in a database
schema. See Database Schema.
Authority Area: An autonomous part of an RWhois tree. It is
associated and named after a particular piece of a hierarchy and is
able to state authoritatively whether or not an instance of
hierarchical data is present within the RWhois tree. See RWhois Tree.
Banner: A line sent by a server indicating which protocol versions it
supports and which directives are implemented. This line is issued by
the server after a connection is opened and as a response to the "-
rwhois" directive. See Directive and Response.
Base Class: A class from which all defined classes in a database
schema inherit attributes. See Attribute, Class, and Database Schema.
BNF: Backus-Naur Form. Language to precisely define the syntax of
protocols and computer languages.
Class: A collection of attributes. See Attribute.
Complete Replication: The process of replicating all of the data for
an authority area. See Replication.
Database Schema: A collection of all the classes forming an RWhois
database. See Class.
Directive: A command that a client sends to a server to set a control
parameter for the session, get the meta-information (class
definitions and SOA information) about an authority area, or get the
data in an authority area. See Class and SOA.
Guardian Class: A standard class that contains security information.
An object is guarded by containing a pointer to a guardian object.
See Class and Object.
Incremental Replication: The process of replicating the data that has
changed since the last replication for an authority area. See
Replication.
Info: The miscellaneous information that a server sends to a client.
Lexically Hierarchical Label: A text string whose position in a
hierarchy is encoded in the string itself.
Link Referral: A pointer to another server that is further down an
RWhois tree. It is used to route a query down the tree. See Referral
and RWhois Tree.
Master Server: A server where the data is registered for an authority
area. It answers authoritatively to queries in the authority area.
It is also called a primary server. See Authority Area.
Namespace: A particular naming system defined by a set of rules
describing the format of a name. Alternately, all of the names
satisfying the rules.
Object: An instance of a class. It is data with a type of <class>.
See Class.
PGP: Pretty Good Privacy. An authentication and encryption scheme.
Primary Server: See Master Server.
Punt Referral: A pointer to another server that is further up an
RWhois tree. It is used to route a query up the tree. See Referral
and RWhois Tree.
Query: A command that a client sends to a server to access the data
in an authority area.
Query Routing: Redirecting a query to another server for resolution.
See Query.
Referral: A pointer to another server that is presumed to be closer
to the desired data. It is used to route a query. See Query Routing.
Referral Class: A standard class that contains referral information
for an authority area. See Class and Referral.
Replication: A server duplicating data from another server on a per-
authority area basis. See Authority Area.
Response: The information that a server returns to a client for a
directive. See Directive.
Result: The information that a server returns to a client for a
query. It can be either the accessed data or referrals to other
servers. See Query and Referral.
RWhois Tree: A data information tree of RWhois servers where the data
is arranged hierarchically in the authority areas. See Authority
Area.
Schema: See Class.
Secondary Server: See Slave Server.
Slave Server: A server where the data is replicated from the master
server for an authority area. It also answers authoritatively to
queries in the authority area. It is also called a secondary server.
See Master Server.
SOA: Start Of Authority. Administrative variables, defined at the
master server, to control replication for an authority area. See
Master Server and Replication.
Appendix B: RWhois ABNF
This specification uses the Augmented Backus-Naur Form (ABNF)
notation, as defined in Section 2 of [RFC822].
General Definitions
Lexical Tokens
alpha = "a".."z" / "A".."Z"
digit = "0".."9"
hex-digit = digit / "a".."f" / "A".. "F"
id-char = alpha / digit / "_" / "-"
any-char = <ASCII 1..255,
except LF (linefeed) and CR (carriage return)>
dns-char = alpha / digit / "-"
email-char = <see [RFC822]>
space = " "
tab = <ASCII TAB (tab)>
lf = <ASCII LF (linefeed)>
cr = <ASCII CR (carriage return)>
crlf = cr lf
Grammar
year = 4digit
month = 2digit
day = 2digit
hour = 2digit
minute = 2digit
second = 2digit
milli-second = 3digit
host-name = dns-char *(dns-char / ".")
email = 1*email-char "@" host-name
authority-area = (dns-char / ".") *(dns-char / "." / "/")
object-id = 1*id-char "." authority-area
host-port = (host-name / ip-address) ":" 1*5digit
ip-address = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
class-name = 1*id-char
attribute-name = 1*id-char
attribute-value = 1*any-char
time-stamp = year month day hour minute second milli-second
on-off = "on" / "off"
Note that the time-stamp must be in the Greenwich Mean Time (GMT)
time zone.
response = ok-response crlf / error-response crlf / info-response
ok-response = "%ok"
error-response = "%error" space error-code space error-text
error-code = 3digit
error-text = 1*any-char
info-response = "%info" space "on" crlf *(*any-char crlf) "%info"
space "off" crlf
rwhois-banner = "%rwhois" space version-list space host-name
[space implementation] crlf
version-list = version *("," version)
version = version-number [":" capability-id]
/ "V-1.5" ":" capability-id
version-number = "V-" 1*digit "." 1*digit
capability-id = response-id ":" extra-id
response-id = 6hex-digit
extra-id = 2hex-digit
implementation = 1*any-char
rwhois-protocol = client-sends / server-returns
client-sends = *(directives / rwhois-query)
server-returns = *(responses / rwhois-query-result)
directives = rwhois-dir / class-dir / directive-dir / display-dir /
holdconnect-dir / limit-dir / notify-dir / quit-dir /
register-dir / schema-dir / security-dir / soa-dir /
status-dir / xfer-dir / x-dir
responses = rwhois-response / class-response/ directive-response/
display-response/ holdconnect-response/ limit-response/
notify-response/ quit-response/ register-response/
schema-response / security-response/ soa-response/
status-response/ xfer-response/ x-response
Required Directives
rwhois
rwhois-dir = "-rwhois" space version-number [space implementation]
crlf
rwhois-response = "%rwhois" space version space host-name
[space implementation] crlf
Optional Directives
class
class-dir = "-class" space authority-area *(space class-name) crlf
class-response = *class-record response
class-record = *class-line "%class" crlf
class-line = "%class" space class-name ":" "description" ":"
1*any-char crlf
/ "%class" space class-name ":" "version" ":" time-stamp crlf
/ "%class" space class-name ":" meta-field ":" meta-value crlf
meta-field = 1*id-char
meta-value = 1*any-char
directive
directive-dir = "-directive" *(space directive-name)crlf
directive-name = 1*id-char
directive-response = *directive-record response
directive-record = "%directive" space "directive" ":"
directive-name crlf *directive-line "%directive" crlf
directive-line = "%directive" space "description" ":" 1*any-char crlf
/ "%directive" space attribute-name ":" attribute-value crlf
display
display-dir = "-display" crlf
/ "-display" space display-name crlf
display-name = 1*id-char
display-response = *display-record response
display-record = "%display" space "name" ":" display-name crlf
*display-line "%display" crlf
display-line = "%display" space attribute-name ":" attribute-value
crlf
holdconnect
holdconnect-dir = "-holdconnect" space on-off crlf
holdconnect-response = response
limit
limit-dir = "-limit" space 1*digit crlf
limit-response = response
notify
notify-dir = "-notify" space "badref" space referral-query crlf
/ "-notify" space "recurref" space referral-query crlf
/ "-notify" space "update" space host-port ":" authority-area
crlf
/ "-notify" space "inssec" space host-port ":" authority-area
crlf
/ "-notify" space "delsec" space host-port ":" authority-area
crlf
referral-query = referral-url space [class-name space] query
notify-response = response
See the query section for the definitions of referral-url and query.
quit
quit-dir = "-quit" crlf
quit-response = response
register
register-dir = register-on space "add" space maintainer-id crlf
register-add register-off
/ register-on space "mod" space maintainer-id crlf
register-mod register-off
/ register-on space "del" space maintainer-id crlf
register-del register-off
register-on = "-register" space "on"
register-off = "-register" space "off" crlf
register-add = 1*(register-line crlf)
register-mod = 1*(register-line crlf) "_NEW_" crlf
1*(register-line crlf)
register-del = 1*(register-line crlf)
maintainer-id = email
register-line = attribute-name ":" attribute-value
register-on-response = response
register-off-response = "%register" space "ID" ":" object-id crlf
response
/ "%register" space "Updated" ":" time-stamp crlf response
/ response
schema
schema-dir = "-schema" space authority-area *(space class-name) crlf
schema-response = *schema-record response
schema-record = *schema-line "%schema" crlf
schema-line = "%schema" space class-name ":" attribute-name ":"
attribute-value crlf
security
security-dir = "-security" space "on" space direction space
security-method [space security-data] crlf security-payload
["-security" space "off" crlf]
direction = "request" / "response"
security-method = "password" / "pgp" / 1*id-char
security-data = password-data / pgp-data / 1*any-char
password-data = 1*any-char
pgp-data = "signed" / "encrypt" [space key-id] / "signed-encrypt"
[space key-id]
security-payload = *(*any-char crlf)
security-response = response
soa
soa-dir = "-soa" *(space authority-area) crlf
soa-response = *soa-record response
soa-record = *soa-line "%soa" crlf
soa-line = "%soa" space "authority" ":" authority-area crlf
/ "%soa" space "ttl" ":" 1*digit crlf
/ "%soa" space "serial" ":" time-stamp crlf
/ "%soa" space "refresh" ":" 1*digit crlf
/ "%soa" space "increment" ":" 1*digit crlf
/ "%soa" space "retry" ":" 1*digit crlf
/ "%soa" space "tech-contact" ":" email crlf
/ "%soa" space "admin-contact" ":" email crlf
/ "%soa" space "hostmaster" ":" email crlf
/ "%soa" space "primary" ":" host-port crlf
/ "%soa" space attribute-name ":" attribute-value crlf
status
status-dir = "-status" crlf
status-response = *status-line response
status-line = "%status" space "limit" ":" 1*digit crlf
/ "%status" space "holdconnect" ":" on-off crlf
/ "%status" space "forward" ":" on-off crlf
/ "%status" space "authority" ":" 1*digit crlf
/ "%status" space "display" ":" 1*any-char crlf
/ "%status" space "contact" ":" email crlf
/ "%status" space attribute-name ":" attribute-value crlf
xfer
xfer-dir = "-xfer" space authority-area *attribute-def
[space serial-number] crlf
attribute-def = [space "class=" class-name]
*(space "attribute=" attribute-name)
serial-number = time-stamp
xfer-response = *xfer-record response
xfer-record = *xfer-line "%xfer" crlf
xfer-line = "%xfer" space class-name ":" attribute-name ":"
attribute-value crlf
X
x-dir = "-X-" x-directive [space *[x-arguments]] crlf
x-directive = 1*id-char
x-arguments = *any-char
x-response = *(*any-char crlf) response
Query
rwhois-query = [class-name space] query crlf
query = query-string / attribute-query / query bin-boolean query
query-char = <any-char, except """, space, tab>
quoted-query-char = query-char / space / tab / "
query-string = 1*query-char ["*"] / """ 1*quoted-query-char ["*"] """
attribute-query = attribute-name "=" query-string
bin-boolean = "and" / "or"
rwhois-query-result = *(query-record / referral-record) response
query-record = 1*query-line crlf
query-line = class-name ":" attribute-name [";" type-char] ":"
attribute-value crlf
type-char = "T" / "I" / "S"
referral-record = 1*(referral-line crlf)
referral-line = "%referral" space referral-url
referral-url = "rwhois" ":" "//" host-port "/" "auth-area="
authority-area
Appendix C: Error Codes
When a server fails to run a command (directive or query), it returns
an error response. The ABNF for an error response is as follows.
error-response = "%error" space error-code space error-text
error-code = 3digit
error-text = 1*any-char
An error text may be modified, but its meaning must remain the same.
The server may append additional information to it, for example
"%error 333 Not master for authority area: foobar.com".
The following table describes the possible digits in the first,
second, and third positions of an error code.
XXX Description
1XX Information only, no action required
2XX Information, action required
3XX Specific command error, retry that command or try another one
4XX Serious for current command, may correct with another command
5XX Fatal, must disconnect
X0X System wide, no specific command
X1X System wide, no specific command
X2X Registration error
X3X Specific command
X4X Specific command
X5X Specific command
X6X Extended message (version specific)
XXX Sequential order
The following table gives an ordered list of RWhois error codes.
These codes may be extended with implementation- specific codes. An
implementation- specific code must have a "6" in the second position.
Code Text
120 Registration deferred
130 Object not authoritative
230 No objects found
300 Not compatible with version
320 Invalid attribute
321 Invalid attribute syntax
322 Required attribute missing
323 Object reference not found
324 Primary key not unique
325 Failed to update outdated object
330 Exceeded maximum objects limit
331 Invalid limit
332 Nothing to transfer
333 Not master for authority area
336 Object not found
338 Invalid directive syntax
340 Invalid authority area
341 Invalid class
342 Invalid host/port
350 Invalid query syntax
351 Query too complex
352 Invalid security method
353 Authentication failed
354 Encryption failed
400 Directive not available
401 Not authorized for directive
402 Unidentified error
420 Registration not authorized
436 Invalid display format
500 Memory allocation problem
501 Service not available
502 Unrecoverable error
503 Idle time exceeded
The following error codes, defined in [RFC1714], have been made
obsolete: 100, 200, 231, 334, 335, 337, 421, 431, 432, 433, 434,
460, 461, and 530.
Appendix D: Capability ID
The capability ID encodes which directives are implemented in the
server. To create a capability ID, perform a logical OR on all the
hexadecimal numbers corresponding to the implemented directives. The
resulting number is used in the banner, which is sent by the server
after opening a connection and as a response to the "-rwhois"
directive. The eight most significant bits of the capability ID are
reserved for future use:
class 000001h
directive 000002h
display 000004h
forward 000008h
holdconnect 000010h
limit 000020h
notify 000040h
quit 000080h
register 000100h
schema 000200h
security 000400h
soa 000800h
status 001000h
xfer 002000h
X 004000h
Appendix E: Schema Definitions
Attribute Definition Model
Name Type Description
Attribute N This is the name of the attribute.
Description S This is a free-form description of the attribute.
Type T This is a parameter that broadly indicates the use
of the attribute to the protocol. There are three
standard types: TEXT, ID, and SEE-ALSO. The default
is TEXT, which indicates that the value is a text
string. ID indicates that the attribute contains
the ID of another RWhois object. This type of
attribute is used for database normalization. SEE-
ALSO indicates that the attribute contains a pointer
(a Uniform Resource Identifier (URI)) to some other
kind of external data; for example, a World Wide Web
page or FTP site.
Format S This is an interpretable string that describes the
acceptance format of the value. The server (and
optionally the client) should match the value to the
format string to determine if the value is
acceptable. The format of this property is a
keyword indicating the syntax of the format string,
followed by a colon, followed by the format string
itself. Currently, the only keyword recognized is
"re" for POSIX.2 extended regular expressions.
Indexed B This is a true or false flag that indicates that
this attribute should be indexed (and therefore able
to be searched).
Required B This is a true or false flag that indicates that
this attribute must have a value.
Multi-Line B This is a true or false flag that indicates that
this attribute may have multiple instances in an
object; all the instances are to be considered as
multiple lines of the same attribute instance.
Repeatable B This is a true or false flag that indicates that
there may be multiple instances of this attribute in
a class and each instance is to be interpreted as a
separate instance (in contrast to Multi-Line). This
flag is mutually exclusive with Multi-Line: if
Multi-Line is true, then Repeatable must be false
and vice versa.
Primary B This is a true or false flag that indicates that
this attribute is a primary key. If more than one
attribute in a class is marked as primary, then
these attributes together form a single primary key.
The primary key is intended to be used to force
uniqueness among class instances. Therefore, there
can be only one instance of a primary key in a
database. The Primary flag implies that the
attribute is also required.
Hierarchical B This is a true or false flag that indicates that
this attribute is lexically hierarchical.
Private B This is a true or false flag that indicates whether
or not this attribute is private (that is, publicly
not viewable). It defaults to false. If it is true,
then only the clients that satisfy the
authentication/encryption requirements of a guardian
are able to view the attribute-value pair.
Type is defined as follows:
Type ABNF Definition
B "ON" / "OFF"
N 1*id-char
S 1*any-char
T "ID" / "SEE-ALSO" / "TEXT"
Base Class
Name Type Required RepeatableDescription
Class-Name TEXT Y N This attribute is the name of the
class to which the object
belongs.
Auth-Area TEXT Y N This attribute is the name of the
authority area to which the
object belongs.
ID TEXT Y N This attribute is the universal
identifier of the object.
Updated TEXT Y N This attribute is a time/date
stamp that indicates the time of
last modification of the object.
Guardian ID N Y This attribute is a link to a
guardian object. Its value is the
ID of a guardian object.
Private TEXT N N This attribute is a true or false
flag that indicates whether or
not an object is private (that
is, publicly not viewable). It
defaults to false. If it is
true, then only the clients
that satisfy the
authentication/encryption
requirements of one of the
object's guardians are able to
view the object. If the object
is publicly viewable, then the
Private attribute property of
each of its attributes still
applies.
TTL TEXT N N This attribute is the
"time-to-live" of a given object.
It is included only if an object
has a different time-to-live than
the default given in the Start of
Authority information. Its value
is specified in seconds.
Appendix F: Changes RWhois V1.0 - V1.5
General
* Multiple authority areas per server.
* Data replication.
* Revised schema model.
* Revised query routing rules.
* Revised error codes.
* Removed unnecessary spaces in responses and results.
Directives
* Class: New. Returns meta-information for a class.
* Display: Can return supported display formats.
* Load: Obsolete.
* Notify: Syntax change.
* Private: Obsolete.
* Register: Syntax change.
* Schema: Syntax change.
* Security: Obsoletes Private.
* Xfer: Syntax change.
Query
* Display option removed.
* Output format: Only the dump format is standard; optional type
character added.
* Attribute-restricted query.
* Revised referral syntax.