Section 3.3.13).
ABNF
limit-dir = "-limit" space 1*digit crlf
limit-response = response
Errors
331 Invalid limit
338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive
Examples
C -limit 100
S %ok
3.3.7 notify
Description
The "-notify" directive performs several functions.
* If the server returns a referral that results in an error, the
client can report the bad referral to the server using the
"badref" option.
* When the client follows referrals and goes through the same
referral twice, that referral is a recursive referral and causes
a referral loop. The client can report the recursive referral to
the server using the "recurref" option.
* When the data in an authority area changes, a master server can
use the "update" option to notify its slave servers to update
the data.
* The "inssec" option allows an RWhois server to register itself
as a slave server for an authority area with a master server.
The master server may reject the request on the basis of its
registration policy.
* The "delsec" option allows a slave server to cancel its
registration with the master server.
ABNF
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 Section 3.4 for the definitions of referral-url and query.
Errors
338 Invalid directive syntax
340 Invalid authority area
342 Invalid host/port
400 Directive not available
401 Not authorized for directive
Examples
# The client reports a bad referral to rwhois.foobar.com to the
# server.
C -notify badref rwhois://rwhois.foobar.com:4321/auth-area=foobar.com
domain foobar.com
S %ok
# The client reports a recursive referral to rwhois.foobar.com to the
# server.
C -notify recurref rwhois://rwhois.foobar.com:4321/auth-area=
foobar.com contact Last-Name="Beeblebrox"
S %ok
# The master server for the foobar.com authority area notifies its
# slave servers to update the data.
C -notify update master.foobar.com:4321:foobar.com
S %ok
# The server rwhois2.foobar.com registers as a slave server for the
# foobar.com authority area.
C -notify inssec rwhois2.foobar.com:4321:foobar.com
S %ok
# The server rwhois2.foobar.com cancels its registration as a slave
# server for the foobar.com authority area.
C -notify delsec rwhois2.foobar.com:4321:foobar.com
S %ok
3.3.8 quit
Description
The "-quit" directive can be used by the client to close the
connection. Before the server closes the connection, it must respond
with "%ok".
ABNF
quit-dir = "-quit" crlf
quit-response = response
Errors
No errors.
Examples
C -quit
S %ok
3.3.9 register
Description
The "-register" directive can be used by the client to add, modify,
or delete objects in the server's database. The client must wait to
send the registration data until the "%ok" response is received from
the server. This directive has the following options.
* The "add" option indicates that the object being sent should be
added to the server's database.
* The "mod" option indicates that the object being sent is a
modification of an object that already resides on the server's
database. During a modify operation, the "_NEW_" tag is used to
delineate the end of the original (unmodified) object and the
beginning of the replacement object. That is, the identifying
characteristics of the original object are sent first, then the
"_NEW_" separator is sent, and then the entire replacement
object is sent.
The "del" option indicates that the object being sent should be
deleted from the server's database.
After a register operation (add, modify, or delete an object) in an
authority area, the server should update the "Serial-Number" variable
in the SOA information for the authority area. This is useful for
data replication because a slave server checks the "Serial-Number"
variable to detect a data change at the master server (see Section
3.6.2).
ABNF
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
* The server must return the register-on-response for the
"-register on" directive and the register-off-response for the
"-register off" directive.
* The maintainer-id identifies, for maintenance purposes, the
sender of registration information. The server should not use it
to authenticate the sender.
* For the "add" option, the client must send all the required
attributes for the object, including the Class-Name and Auth-
Area attributes. However, the client must not send the ID and
Updated attributes. These attributes are assigned by the server
and returned in the response.
* For the "mod" option, the client must send the identifying
information for the object to be modified, followed by the
"_NEW_" separator and the entire replacement object. The
identifying information must contain the ID and Updated
attributes; it may contain other attributes, but the server may
not check them. The ID, Auth-Area, and Class-Name attributes
must match in both the original object data and the replacement
object. The original object data is sent before the replacement
object to enable the server to lock the record in the database.
* For the "del" option, the client must send the identifying
information for the object to be deleted. The identifying
information must contain the ID and Updated attributes; it may
contain other attributes, but the server may not check them.
Errors
120 Registration deferred
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
336 Object not found
338 Invalid directive syntax
340 Invalid authority area
341 Invalid class
400 Directive not available
401 Not authorized for directive
Examples
# Add an object.
C -register on add joe@netsol.com
S %ok
C Class-Name:contact
C Auth-Area:a.com
C First-Name:Scott
C Last-Name:Williamson
C Name:Williamson, Scott
C Email:scottw@a.com
C -register off
S %register ID:23456789.a.com
S %register Updated:19961205224403000
S %ok
# Modify an object.
C -register on mod joe@netsol.com
S %ok
C ID:23456789.a.com
C Updated:19961205124403000
C _NEW_
C Class-Name:contact
C Auth-Area:a.com
C ID:23456789.a.com
C First-Name:Scott
C Last-Name:Williamson
C Name:Williamson, Scott
C Email:sw@a.com
C -register off
S %ok
# Delete an object.
C -register on del joe@netsol.com
S %ok
C ID:23456789.a.com
C Updated:19961205224403000
C -register off
S %ok
3.3.10 schema
Description
The "-schema" directive can be used by the client to get the
attribute definitions of one or more classes in an authority area. If
the client specifies class names, the server must return the
attribute definitions of the specified classes. Otherwise, the server
must return the attribute definitions of all the classes in the
authority area. Every schema record must end with an empty "%schema"
line.
ABNF
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
Errors
338 Invalid directive syntax
340 Invalid authority area
341 Invalid class
400 Directive not available
401 Not authorized for directive
Examples
C -schema map
S %schema map:attribute:Class-Name
S %schema map:description:Type of the object
S %schema map:type:TEXT
S %schema map:format:re:[a-zA-Z0-9-]+
S %schema map:indexed:OFF
S %schema map:required:ON
S %schema map:multi-line:OFF
S %schema map:repeatable:OFF
S %schema map:primary:OFF
S %schema map:hierarchical:OFF
S %schema map:private:OFF
S %schema
S %schema map:attribute:ID
S %schema map:description:Globally unique object identifier
S %schema map:type:TEXT
S %schema map:format:re:[0-9]+.[a-zA-Z0-9.-]+
S %schema map:indexed:ON
S %schema map:required:ON
S %schema map:multi-line:OFF
S %schema map:repeatable:OFF
S %schema map:primary:ON
S %schema map:hierarchical:OFF
S %schema map:private:OFF
S %schema
# This is an abbreviated example, more attributes usually follow.
S %ok
3.3.11 security
Description
The "-security" directive enables either a client request or a server
response to be authenticated and/or encrypted. Currently, RWhois uses
two standard security methods: password and PGP. Password provides
authentication only, and PGP provides both authentication and
encryption. This directive can be used to securely access or update
any information (meta or data) in an authority area that is protected
by one or more guardian objects.
ABNF
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
* The "password" security-method is available in the "request"
direction only. For password, the security-data is a cleartext
password.
* The "pgp" security-method is available in both the "request" and
"response" directions. For PGP, the security-data indicates how
to treat the security-payload: signed, encrypted, or signed and
encrypted. To encrypt the security-payload in the "response"
direction, the security-data must include the public key ID with
which to encrypt it.
Errors
338 Invalid directive syntax
352 Invalid security method
353 Authentication failed
354 Encryption failed
400 Directive not available
401 Not authorized for directive
Examples
# Authenticate a request using password.
C -security on request password hello!1
S %ok
# Authenticate a PGP signed request.
C -security on request pgp signed
S %ok
C -register on mod joe@netsol.com
S %ok
C -----BEGIN PGP MESSAGE-----
C Version: 2.6.2
C
C owHrZJjKzMpgdP9D9crUhdpBYnwHGRnPbmVhmHlV7Hef9je/n7vyzhmE6589/+Dg
C jPpVm59tNz92vPSmrFB/4ankBRz+xgY+7z9OUYjefGahbWSNwzzxbw6TpWZGerU+
C uOUg/Cygs33JBdHqjwEc+wyfZPp+N5p2bu+ywoaOu8eLPyn+m2Mt/T9p1UaG68vP
C Zd2d9EPw+Ywpio7dco6yh3b/v7zmQxJHcWpyaVFmSSUDEHi6WBkZm5iamVtY6iXq
C JefnKnCFFqQklqSmWBlaWpoZGhmYGhqZmBgYGxgYKHA55yQWF+v6JeamWiXn55Uk
C JpcocDmWlmToOhalJlpB9cf7uYbHE6kWi/VumUXFJRB9wcn5JUBdPokwgfDMnJzM
C xNzi/DwFLjQBHQWoatfcxMwcq+JyB6h5AA==
C =a0sQ
C -----END PGP MESSAGE-----
C -register off
S %ok
# Encrypt a response using PGP. 52160EC1 is the public key ID with
# which the response is encrypted.
C -security on response pgp encrypt 52160EC1
S %ok
C -xfer com class=domain attribute=Domain-Name
attribute=Organization-Name
S -----BEGIN PGP MESSAGE-----
S Version: 2.6.2
S
S hIwDqWWhK1IWDsEBBACOXssTzD2CbB7Vjj2cNURScpJc2as2TbUDOQiwkT+8qFgG
S ZyRfktpwNNTawRIcGOk1Kcs84z8a3vvTA/oje9vZexHtzfJwBHFdiIZxPuCEpvgv
S 2ppK7WqlmHGcQKVBJJHYw7Fq83CUkeGJB9P1M3CQiXeW8h8MwAuhxSgbgt23PKYA
S AABuhknJrXeh9Owm81+MvyzgLOyM7sjDYmttU9sj/yuOYmAhS9V+34MT/Mwn4wO8
S 2BCsJqBHXbwOuYKs02p0se4jyKFtZR8MDPWNm9QyAP+oNMTjsufy6ZRa9PegUC6t
S HDhXymkiP03mKMMVK1//7X0=
S =vZ2x
S -----END PGP MESSAGE-----
S %ok
3.3.12 soa
Description
The "-soa" directive can be used by the client to retrieve the SOA
information for one or more authority areas. When no authority area
name is given, the server must return the SOA information for all the
authority areas. Every SOA record must end with an empty "%soa" line.
ABNF
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
The server must return the following SOA information for an authority
area.
attribute-name attribute-value Comments
authority authority-area This is the name of the authority area.
ttl 1*digit This is the default time to live for
the data in the authority area.
serial time-stamp This is the serial number of the data
in the authority area; it changes
when the data changes.
refresh 1*digit This is the time interval before a
slave server checks for complete
replication.
increment 1*digit This is the time interval before a
slave server checks for incremental
replication.
retry 1*digit This is the time interval before a
slave server tries again to connect
to a master server that appears to be
out-of-service.
tech-contact email This is the contact for the operation
of the master server.
admin-contact email This is the contact for the data
integrity at the master server.
hostmaster email This is the contact for sending update
requests at the master server.
primary host-port This is the host name (or IP address)
and port number of the master server.
Errors
338 Invalid directive syntax
340 Invalid authority area
400 Directive not available
401 Not authorized for directive
Examples
C -soa org
S %soa authority:org
S %soa ttl:86400
S %soa serial:19961119111535000
S %soa refresh:3600
S %soa increment:1800
S %soa retry:180
S %soa tech-contact:tech@internic.net
S %soa admin-contact:admin@internic.net
S %soa hostmaster:hostmaster@internic.net
S %soa primary:rs.internic.net:4321
S %soa
S %ok
3.3.13 status
Description
The "-status" directive can be used by the client to get various
status flags from the server. The response must include the number of
objects in all the authority areas, the current display format, the
server contact information, and the status flags for the state-
oriented directives: "-limit", "-holdconnect", and "-forward".
ABNF
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 "objects" ":" 1*digit crlf
/ "%status" space "display" ":" 1*any-char crlf
/ "%status" space "contact" ":" email crlf
/ "%status" space attribute-name ":" attribute-value crlf
Errors
338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive
Examples
C -status
S %status limit:20
S %status holdconnect:OFF
S %status forward:OFF
S %status objects:12345
S %status display:dump
S %status contact:joe@rwhois.net
S %ok
3.3.14 xfer
Description
The "-xfer" directive can be used by the client (generally, a slave
server) to transfer the data in an authority area. The client can
control the amount of data transferred using one of the following
options.
* serial-number: The client can transfer all the objects that have
been added, modified or deleted since a certain time, specifying
the serial-number that indicates that time. This option is used
for incremental replication.
* class: The client can limit the data transfer to one or more
classes, using the "class=<class-name>" option. The server must
return data for only the specified classes. If no class name is
specified, the server must return data for all the classes.
* attribute: The client can limit the data transfer to one or more
attributes of a class, using the "attribute=<attribute-name>"
option in combination with the "class=<class-name>" option. The
server must return data for only the specified attributes of the
class. The client can specify multiple "class=" and "attribute="
pairs.
ABNF
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
Errors
332 Nothing to transfer
333 Not master for authority area
338 Invalid directive syntax
340 Invalid authority area
341 Invalid class
342 Invalid attribute
400 Directive not available
401 Not authorized for directive
Examples
C -xfer com class=domain attribute=Domain-Name
attribute=Organization-Name
S %xfer domain:Domain-Name:acme.com
S %xfer domain:Organization-Name:Acme Inc.
S %xfer
S %xfer domain:Domain-Name:vogon.com
S %xfer domain:Organization-Name:Vogon Heavy Industries
S %xfer
S %ok
3.3.15 X
Description
The "-X" directive is used to specify an additional, non-standard
directive. It can be implemented by executing an external program, by
internal functions, or by other means. It may interact with the
client or simply produce output like one of the standard directives.
ABNF
x-dir = "-X-" x-directive [space x-arguments] crlf *x-line
x-directive = 1*id-char
x-arguments = *any-char
x-response = *(*any-char crlf) response
x-line = *any-char crlf
Errors
338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive
Examples
The following example uses an implementation that executes an
external program, the UNIX "date" command. The server runs the "date"
command and returns its output to the client.
C -X-date
S Mon Jan 6 13:21:20 EST 1997
S %ok
3.4 Query
Description
The query allows the client to retrieve objects from the server's
database. The server must support the following types of queries.
* Unrestricted query: It is a single word or a quoted string. The
server must return all the matching objects where one or more
attributes match the query, regardless of the class.
* Class-restricted query: It is a class name specified in front
of the unrestricted query. The server must return all the
matching objects where one or more attributes of the specified
class match the query.
* Attribute-restricted query: It is of the
"<attribute-name>=<search-string>" form. The server must return
all the matching objects where the specified attribute matches
the query.
The server may implement the following types of queries.
* Boolean operator query: It consists of simpler queries combined
using the "and" and "or" operators.
* Wild card query: It consists of an asterisk ("*") in the front
and/or at the end of the search string. The server may support
partial matching using the asterisk.
In response to the query, the server will return the objects that
match the query. If the server does not support complex queries,
with, for example, wild cards or boolean operators, the server may
return the "351 Query too complex" error. When the number of objects
found exceeds the limit (set by the "-limit" directive), the server
should return the objects, followed by the "330 Exceeded maximum
objects limit" error.
The default object output format is the dump format that uses the
"<class-name>:<attribute-name>;<type character>:<attribute-value>"
form. The type character is optional and identifies the type of the
attribute value. The type character is a shorthand for the Type field
of the attribute definition (see Section 2.3.1). The type characters
are defined as follows.
Type Attribute
character Type
T TEXT
I ID
S SEE-ALSO
When no type character is given, the client should assume the "T"
type character. The server must provide the type character when the
attribute type is ID or SEE-ALSO. The purpose of the type character
is to aid the client in displaying the data. For example, when an
attribute value is an ID, the client may indicate to the end-user
that it is possible to retrieve the object indicated by the ID.
The server may return one or more referrals in the "%referral
rwhois://<host-name>:<port-number>/auth-area=<authority area>" form.
The client can distinguish multiple referrals by comparing their
authority areas; if all the referrals refer to the same authority
area, the client should follow only one of them. Otherwise, the
client should follow all of them. To follow a referral, the client
must connect to the specified host name and port number, and issue
the same query.
ABNF
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
Errors
130 Object not authoritative
230 No objects found
330 Exceeded maximum objects limit
340 Invalid authority area
341 Invalid class
342 Invalid attribute
350 Invalid query syntax
351 Query too complex
Examples
This example illustrates a query, where no objects are found.
C vogon
S %error 230 No objects found
This example illustrates a query, where two different objects are
returned.
C ibm
S domain:ID:IBMLIFEPRO-DOM.com
S domain:Auth-Area:com
S domain:Domain-Name:IBMLIFEPRO.COM
S domain:Org-Name:IBM
S domain:Server;I:NS12345-HST.NET
S domain:Server;I:NS12345-HST.NET
S domain:Admin-Contact;I:TW1234.COM
S domain:Tech-Contact;I:BN123.NET
S domain:Updated:19961120123455000
S domain:Updated-By:autoreg@internic.net
S domain:Class-Name:domain
S
S network:ID:NET-IBMNET-3.0.0.0/0
S network:Auth-Area:0.0.0.0/0
S network:Network-Name:IBMNET-3
S network:IP-Network:123.45.67.0/24
S network:Org-Name:IBM
S network:Street-Address:1234 Maneck Avenue
S network:City:Black Plains
S network:State:NY
S network:Postal-Code:12345
S network:Country-Code:US
S network:Tech-Contact;I:MG305.COM
S network:Updated:19931120123455000
S network:Updated-By:joeblo@nic.ddn.mil
S network:Class-Name:network
S
S %ok
This example illustrates a query with a class restrictor, where the
number of objects found exceeds the limit set by the "-limit"
directive.
C -limit 1
S %ok
C domain ibm
S domain:ID:IBMLIFEPRO-DOM.com
S domain:Auth-Area:com
S domain:Domain-Name:IBMLIFEPRO.COM
S domain:Org-Name:IBM
S domain:Server;I:NS12345-HST.NET
S domain:Server;I:NS12345-HST.NET
S domain:Admin-Contact;I:TW1234.COM
S domain:Tech-Contact;I:BN123.NET
S domain:Updated:19961120123455000
S domain:Updated-By:erice@internic.net
S domain:Class-Name:domain
S
S %error 330 Exceeded maximum objects limit
This is an example of attribute matching.
C domain Domain-Name=konabo.com
S domain:ID:12345678.com
S domain:Auth-Area:com
S domain:Domain-Name:konabo.com
S domain:Org-Name:ACME
S domain:Server;I:12345670.com
S domain:Server;I:12345671.com
S domain:Admin-Contact;I:12345660.com
S domain:Tech-Contact;I:12345665.com
S domain:Updated:19961120123455000
S domain:Updated-By:joeblo@internic.net
S domain:Class-Name:domain
S
S %ok
This example illustrates a link referral.
C domain a.b.rwhois.net
# The server returns a link referral to a server serving the
# b.rwhois.net authority area.
S %referral rwhois://master.b.rwhois.net:4321/auth-area=b.rwhois.net
S %ok
This example illustrates a punt referral.
C domain internic.net
# The server returns a punt referral to a server serving the root
# authority area.
S %referral rwhois://rs.internic.net:4321/auth-area=.
S %ok
This example illustrates multiple referrals that refer to the same
authority area. The client should follow only one of them.
C domain a.b.rwhois.net
# The server returns link referrals to two RWhois servers serving the
# b.rwhois.net authority area.
S %referral rwhois://master.b.rwhois.net:4321/auth-area=b.rwhois.net
S %referral rwhois://slave.b.rwhois.net:4321/auth-area=b.rwhois.net
S %ok
This example illustrates multiple referrals that refer to different
authority areas. The client should follow all of them.
C contact Last-Name="Beeblebrox"
# The server returns a link referral to a server serving the
# b.rwhois.net authority area.
S %referral rwhois://master.b.rwhois.net:4321/auth-area=b.rwhois.net
# The server also returns a punt referral to a server serving the
# net authority area since the query matched an entry in the
# non-hierarchical index received from it.
S %referral rwhois://rs.internic.net:4321/auth-area=net
S %ok
This is an example of a boolean operator and wildcard matching.
C ibm and jubliana*
S host:ID:JUBLIANA-HST.root
S host:Auth-Area:.
S host:Host-Name:JUBLIANA.TRL.IBM.CO.JP
S host:IP-Address:123.156.220.68
S host:Org-Name:IBM
S host:Street-Address:1234 Maneck Avenue
S host:City:Black Plains
S host:State:NY
S host:Postal-Code:12345
S host:Country-Code:US
S host:Updated:19961120123455000
S host:Updated-By:joeblo@nic.ddn.mil
S host:Class-Name:host
S
S %ok
3.5 Connection Model
An RWhois client can connect to an RWhois server using one of the
following transport protocols.
3.5.1 Transmission Control Protocol (TCP)
TCP provides a reliable stream transport service between a client and
a server. In RWhois, TCP is the default transport protocol because,
during a particular session, a client can send more than one query
and a server can reliably return a large amount of data for each of
those queries. By default, a TCP RWhois server should run on the
standard, Internet Assigned Number Authority (IANA)-assigned port
4321. However, if port 4321 is not available, it may run on an
available port in the non-reserved range (1024 - 65535).
3.5.2 User Datagram Protocol (UDP)
UDP provides an unreliable connectionless transport service between a
client and a server. In RWhois, UDP may be used as the transport
protocol if a client wants to quickly send only one query, without
incurring the overhead of establishing a TCP connection with a
server. By default, a UDP RWhois server should run on the standard,
IANA-assigned port 4321. However, if port 4321 is not available, it
may run on an available port in the non-reserved range (1024 -
65535). A separate document will describe the use of UDP as the
transport protocol in RWhois.
3.6 Data Replication
This section discusses when and how a slave server should replicate
data. Further, it describes the server registration and location
mechanisms.
3.6.1 When to Replicate Data
The time when a slave server may replicate data for an authority area
is determined by the SOA variables for that authority area. The
possible times are the following.
* When the "Refresh-Interval" expires, a slave server may
completely replicate data.
* When the "Increment-Interval" expires, a slave server may
incrementally replicate data.
* A slave server fails to connect to its master server to
replicate data. When the "Retry-Interval" expires, it tries
again to replicate data.
* When the data in an authority area is changed and its "Serial-
Number" updated, a master server may notify its slave servers to
immediately update the data. To notify about the data change,
the master server should send the "-notify update <host-
name>:<port-number>:<authority-area>" directive to its slave
servers.
3.6.2 How to Replicate Data
To replicate data, a slave server sends a series of directives to its
master server and checks each response before sending the next
directive. The following sections describe the protocols for
complete and incremental replication.
Complete Replication
The protocol between a master server and a slave server to completely
replicate data for an authority area is as follows.
1. The slave server should connect to the master server. If there
is a connection error, the slave server should log an error and
exit.
2. The slave server should send the "-soa <authority-area>"
directive to the master server and parse the SOA variables from
the response. Let the "Serial-Number" variable in this response
be called the "old-serial-number".
3. The slave server should send the "-class <authority-area>"
directive to the master server and parse the versions of all the
classes from the response.
4. The slave server should send the "-schema <authority-area>"
directive to the master server and parse the definitions of all
the classes from the response.
5. The slave server should send the "-xfer <authority-area>"
directive to the master server and parse the data objects from
the response. The master server should return all the data
objects, excluding the deleted ones, in the authority area. The
slave server should index these data objects.
6. When the "Refresh-Interval" expires, the slave server should
to the master server. If there is a connection error, the slave
server should try again after the "Retry-Interval".
7. The slave server should send the "-soa <authority-area>"
directive to the master server and parse the SOA variables from
the response. Let the "Serial-Number" variable in this response
be called the "new-serial-number". If the "new-serial-number" is
not greater than the "old-serial-number", go back to step 6.
Otherwise, it indicates a data change at the master server.
8. The slave server should send the "-class <authority-area>"
directive to the master server and parse the versions of all the
classes from the response. If the version of any of the classes
has changed, the slave server should send the "-schema
<authority-area>" directive to the master server and parse the
definitions of all the classes from the response.
9. The slave server should send the "-xfer <authority-area>"
directive the master server and parse the data objects from the
response. The master server should return all the data objects,
excluding the deleted ones, in the authority area. The slave
server should index these data objects and seamlessly replace
the old index with the new one. Further, it should assign the
"new-serial-number" to the "old-serial-number".
10. Go back to step 6.
Note that the "-class", "-schema", and "-xfer" directives change when
a slave server replicates data for only a subset of the schema for an
authority area.
In the following example, a slave server completely replicates data
for all the classes in an authority area. The notation in the example
uses a prefix to indicate from where the information is coming. An
"M" indicates that the master server sends the data to the slave
server. An "S" indicates that the slave server sends the data to the
master server. The line is a comment when "#" is used. The space
after the prefix is not part of the data. The example authority area
is "rwhois.net".
# The slave server connects to the master server.
M %rwhois V-1.5:00ffff:00 master.rwhois.net
S -soa rwhois.net
M ...
M %soa serial:19970103102258000
M %soa refresh:3600
M ...
S -class rwhois.net
# The master server returns the versions of all the classes in the
# rwhois.net authority area.
S -schema rwhois.net
# The master server returns the definitions of all the classes in the
# rwhois.net authority area.
S -xfer rwhois.net
# The master server returns all the data objects, excluding the
# deleted ones, in the rwhois.net authority area. The slave server
# indexes these data objects.
# The refresh interval of 3600 seconds expires.
S -soa rwhois.net
M ...
M %soa serial:19970103103258000
M %soa refresh:3600
M ...
# The new serial number 19970103103258000 is greater than the old
# serial number 19970103102258000. It indicates a data change at the
# master server.
S -class rwhois.net
# The master server returns the versions of all the classes in the
# rwhois.net authority area. If the version of any of the classes has
# changed, the slave server logs an error and closes the connection.
S -xfer rwhois.net
# The master server returns all the data objects, excluding the
# deleted ones, in the rwhois.net authority area. The slave server
# indexes these data objects and seamlessly replaces the old index.
# The refresh interval of 3600 seconds expires.
S ...
Incremental Replication
The protocol between a master server and a slave server to
incrementally replicate data for an authority area is as follows.
1. The slave server should connect to the master server. If there
is a connection error, the slave server should log an error and
exit.
2. The slave server should send the "-soa <authority-area>"
directive to the master server and parse the SOA variables from
the response. Let the "Serial-Number" variable in this response
be called the "old-serial-number".
3. The slave server should send the "-class <authority-area>"
directive to the master server and parse the versions of all the
classes from the response.
4. The slave server should send the "-schema <authority-area>"
directive to the master server and parse the definitions of all
the classes from the response.
5. The slave server should send the "-xfer <authority-area>"
directive to the master server and parse the data objects from
the response. The master server should return all the data
objects, excluding the deleted ones, in the authority area. The
slave server should index these data objects.
6. When the "Increment-Interval" expires, the slave server should
connect to the master server. If there is a connection error,
the slave server should try again after the "Retry-Interval".
7. The slave server should send the "-soa <authority-area>"
directive to the master server and parse the SOA variables from
the response. Let the "Serial-Number" variable in this response
be called the "new-serial-number". If the "new-serial-number" is
not greater than the "old-serial-number", go back to step 6.
Otherwise, it indicates a data change at the master server.
8. The slave server should send the "-class <authority-area>"
directive to the master server and parse the versions of all the
classes from the response. If the version of any of the classes
has changed, the slave server should send the "-schema
<authority-area>" directive to the master server and parse the
definitions of all the classes from the response. The slave
server should then send the "-xfer <authority-area>" directive
to the master server and parse the data objects from the
response. The master server should return all the data objects,
excluding the deleted ones, in the authority area. The slave
server should index these data objects and seamlessly replace
the old index with the new one. Further, it should assign the
"new-serial-number" to the "old-serial-number". If the version
of any of the classes has changed, go back to step 6.
9. The slave server should send the "-xfer <authority-area>
<old-serial-number>" directive to the master server and parse
the data objects from the response. The master server should
return all the data objects in the authority area that have been
inserted, updated, or deleted since the "old-serial-number". The
slave server should index all the data again after purging stale
data objects and seamlessly replace the old index with the new
one. Further, it should assign the "new-serial-number" to the
"old-serial-number".
10. Go back to step 6.
Note that the "-class", "-schema", and "-xfer" directives change when
a slave server replicates data for only a subset of the schema for an
authority area.
In the following example, a slave server incrementally replicates
data for all the classes in an authority area. The notation in the
example uses a prefix to indicate from where the information is
coming. An "M" indicates that the master server sends the data to the
slave server. An "S" indicates the slave server sends the data to the
master server. The line is a comment when "#" is used. The space
after the prefix is not part of the data. The example authority area
is "rwhois.net".
# The slave server connects to the master server.
M %rwhois V-1.5:00ffff:00 master.rwhois.net
S -soa rwhois.net
M ...
M %soa serial:19970103102258000
M %soa increment:1800
M ...
S -class rwhois.net
# The master server returns the versions of all the classes in the
# rwhois.net authority area.
S -schema rwhois.net
# The master server returns the definitions of all the classes in the
# rwhois.net authority area.
S -xfer rwhois.net
# The master server returns all the data objects, excluding the
# deleted ones, in the rwhois.net authority area. The slave server
# indexes these data objects.
# The increment interval of 1800 seconds expires.
S -soa rwhois.net
M ...
M %soa serial:19970103103258000
M %soa increment:1800
M ...
# The new serial number 19970103103258000 is greater than the old
# serial number 19970103102258000. It indicates a data change at
# the master server.
S -class rwhois.net
# The master server returns the versions of all the classes in the
# rwhois.net authority area. If the version of any of the classes has
# changed, the slave server logs an error and closes the connection.
S -xfer rwhois.net 19970103102258000
# The master server returns all the data objects in the rwhois.net
# authority area that have been inserted, updated, or deleted since
# 19970103102258000. The slave server indexes all the data again
# after purging stale data objects and seamlessly replaces the old
# index. The increment interval of 1800 seconds expires.
S ...
3.6.3 Server Registration
This section discusses how an RWhois server can register itself or
cancel its registration as a slave server for an authority area with
a master server.
The initial list of slave servers for an authority area should be
manually configured at the master server. To register itself as a
slave server, the server should send the "-notify inssec <host-
name>:<port-number>:<authority-area>" directive to the master server.
The master server may reject the request on the basis of its
registration policy. To cancel its registration as a slave server,
the server should send the "-notify delsec <host-name>:<port-
number>:<authority-area>" directive to the master server. Note that
the "host-name" and "port-number" in the above directives correspond
to the requesting server.
3.6.4 Server Location
To resolve a query in a particular authority area, an RWhois client
may need to first locate the master and slave servers for that
authority area. The different server location mechanisms are as
follows.
Referrals
An RWhois client should know about at least one RWhois server. It
should send the "referral <authority-area>" query to that server. The
query may be routed up or down the RWhois tree before getting
resolved. If the query does get resolved, the result should be a
referral object for that authority area. The client should parse the
"Referral" attributes from the result to obtain a list of servers
serving that authority area.
The client should then send the "-soa <authority-area>" directive to
one of the above servers and parse the "Primary-Server" variable from
the response. The value of this variable is the master server. Then,
the remaining servers in the list are the slave servers.
SRV RRs
The Server Resource Record (SRV RR), defined for DNS, can be used to
locate the master and slave servers for an authority area. An SRV RR
specifies the location of a network service in an organization's DNS.
It is defined in [RFC2052] as follows.
Service.Proto.Name TTL Class SRV Priority Weight Port Target
Since an authority area identifier is generally a domain name or an
IP address, the RWhois SRV RRs can be added to the DNS file for that
domain or IP address. For example, the RWhois SRV RRs for the
"rwhois.net" authority area could be:
rwhois.tcp.rwhois.net. 86400 IN SRV 10 0 4321 master.rwhois.net.
SRV 20 0 4322 slave.rwhois.net.
where the "master.rwhois.net" server has a higher priority than the
"slave.rwhois.net" server. The client must try to connect to the
server with a higher (lower-numbered) priority.
4. Security Considerations
RWhois provides security using the guardian class (see Section
2.3.6). Any information (meta or data) in an authority area can be
guarded by containing pointers to one or more guardian objects; that
is, it can be securely updated and accessed. Currently, there are two
standard security methods: password and PGP (see Section 3.3.11).
Password provides authentication only, and PGP provides both
authentication and encryption. PGP is the recommended security
method in RWhois.
The following sections discuss how to securely update and access the
data in an authority area.
4.1 Data Update
This involves the ability to securely add, modify, or delete some
information (meta or data) in an authority area. An authority area,
on the whole, can be guarded by linking guardians to its SOA and
schema information. Only these guardians should be allowed to add
objects to the authority area and modify its SOA and schema
information. In addition, they can also modify or delete existing
objects in the authority area. However, the function of modifying or
deleting existing objects can be delegated to other guardians by
linking them to objects on a per-object basis.
4.2 Access Control
There are two access control issues; the first is the ability to
securely transfer data between the slave and master servers. To
transfer data for an authority area, a slave server can authenticate
itself by satisfying one of the guardians linked to the SOA
information of the authority area at the master server. In addition,
the master server may encrypt the transferred data.
The second issue is the ability to make public only a subset of the
data in an authority area. If all the objects of a particular class
need to be private, the Private attribute of the class should be set
to true. If only some attributes of all the objects of a particular
class need to be private, the Private attribute property of each of
those attributes should be set to true. The guardians of such objects
must be able to view them completely.
5. Acknowledgments
The authors would like to acknowledge the following individuals.
Stan Borinski
C. Ming Lu
Leslie Meador
Michael Mealling
Greg Pierce
Amar Rao
6. References
[CIP] Allen, J., "The Common Indexing Protocol (CIP)", Bunyip
Information Systems, November 1996, Work in Progress.
[Guardian] Singh, J., M. Kosters, "The InterNIC Guardian Object",
ftp://rs.internic.net/policy/internic/internic-gen-1.txt, Network
Solutions, February 1996.
[RFC821] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
821, ISI, August 1982.
[RFC822] Crocker, D, "Standards for the Format of ARPA Internet Text
Messages", STD 11, RFC822, University of Delaware, August 1982.
[RFC954] Harrenstien, K., Stahl, M., Feinler, E., "NICNAME/WHOIS",
RFC954, SRI, October 1985.
[RFC1034] Mockapetris, P. V., "Domain names - concepts and
facilities", STD 13, RFC1034, November 1987.
[RFC1714] Williamson, S., Kosters, M., "Referral Whois Protocol",
RFC1714, Network Solutions, November 1994.
[RFC1738] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform
Resource Locators (URL)", RFC1738, CERN, Xerox Corporation,
University of Minnesota, December 1994.
[RFC1991] Atkins, D., W. Stallings, P. Zimmermann, "PGP Message
Exchange Formats", RFC1991