RFC 1714
Referral Whois Protocol (RWhois)
Referral Whois Protocol (RWhois) 🦋
okay bestie, this is part 1 of 7 💖 so buckle up, we're just getting started!! 🎀
The title block is the RFC's ID card. It was written by S. Williamson and M. Kosters, both from Network Solutions Inc. and InterNIC. It's marked Informational (so it's giving "here's some info," not "this is an Internet standard" 🙈) and it's dated November 1994. The block doesn't list anything it obsoletes or updates. 🌸
Status of This Memo
okay so the vibe here is pretty chill 🧚 this memo is information for the Internet community, and it does not specify an Internet standard of any kind. no cap, it's not a rulebook. and it can be shared freely, because distribution is unlimited 💅
Abstract
this one is about version 1.0 of the client/server conversation in RWhois ✨ the big idea is a distributed system for showing hierarchical info. it's hierarchical by design, so a query can get trimmed down and the user gets referred closer to whoever actually maintains the data. it's giving "ask the right person" energy 👑
Table of Contents
the TOC is the map of the whole doc 🗺️ page numbers point to the original, so keep them in mind:
1. Introduction................................... 3
2. RWhois Client Model............................ 5
2.1 Directives: Client to Server Interaction ... 6
2.2 Required Directives ......................... 6
2.2.1 <query>.................................. 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
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 <QUERY> ......................................39
4.4 -RWhois ......................................40
4.5 -load ........................................40
4.6 -limit<SP>< value > ..........................40
4.7 -schema<SP>[object] ..........................40
4.8 -xfer<SP>[object] ............................40
4.9 -quit ........................................40
4.10 -cache<SP><on/off> ..........................40
4.11 -status .....................................40
4.12 -forward ....................................40
4.13 -soa ........................................40
4.14 -notify .....................................41
4.15 -register ...................................41
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.............................461. Introduction ✨
okay, history lesson, but make it cute 🍓 way back in early ARPANET days, the SRI-NIC ran one centralized whois database. it held info about hosts and networks, plus the E-mail addresses of users on those systems. ARPANET grew into a global network with countless people and hundreds of thousands of end systems 😭 keeping one giant central database going is a LOT of work, so the community wanted a decentralized way to store and display this info. 💜
next, the Internet parts of the DDN NIC moved over to what's now called InterNIC Registration Services (RS). InterNIC RS was scoped down to maintaining info for IP networks, top-level domains, Autonomous System Numbers, and the points of contact for each of those things.
then there's the InterNIC acting as an Internet Registry (IR). it handed off IP block assignment authority to Regional Registries like the RIPE NCC for Europe and the APNIC for the Asian Pacific region, and kept authority for North America and all non-delegated regions. the result? whois service got fragmented for Internet users. main character villain arc, honestly 🥀
different IRs came up with different fixes. two got the most work: the Shared Whois Project (SWIP) and X.500 🦋
SWIP has a common exchange format that the IRs can parse for input and output. so they can sync their databases using info from each other. it's showing promise and it's operational now ✨ the catch is that it still needs a centralized database for storing and displaying stuff.
the InterNIC also played with X.500 for showing registration info. that included defining schemas and Directory information tree structures so info could be spread across the IRs' X.500 Directory Service Agents (DSA). but X.500's complexity, resource utilization, and lack of Internet support made the search for a different solution necessary 💀
here's the key insight, and it's a whole vibe: the info the IRs keep is inherently hierarchical. look at these examples: hammer.nic.ddn.mil lives under nic.ddn.mil, which lives under ddn.mil, which lives under .mil. and 198.41.0.21 is part of network 198.41.0.0/24, which is part of block 198.41.0.0/16, which is part of block 198.0.0.0/8. the InterNIC might not have the exact info, but it can still trim the query down and refer the user closer to their goal 🧚 that's where the referral whois idea and the RWhois protocol came from!!
the big premise: keep the basic whois server and client working, and make all the extensions optional.
here's the plan, bestie 👑 the server MUST respond to the original whois client, the one that's already bundled with lots of operating systems. and the RWhois client MUST also work with [RFC-954] whois servers.
the protocol is built to be extensible so it can handle lots of uses 🌈 public extensions SHOULD be documented as RFCs. private extensions are cool too, and it's up to the client and server to agree on them.
if an extension isn't implemented at the server in question, the server MUST send an appropriate error message. the extended error message stuff is in Section 5 - Error Codes 💅
now the notation. here's how this doc describes the RWhois server/client conversation:
<SP> space
[arg] optional argument
<arg> required argument
(<arg>) conditional required argument
([arg]) conditional optional argument
{format} format of item
\ continued on next lineand yes, the words SHOULD and MUST are super important in this doc!! if SHOULD is used, the implementor gets to choose whether to follow the advice here. if MUST is used, it's a required part of the protocol, and implementations without that functionality may not interact correctly with other RWhois servers 🙈
the format descriptions use the macro definitions from Section 6.1, so check that section if anything's fuzzy ✨
last bit: the RWhois protocol in this doc can be extended for apps like NetHelp and ZoneGen (that's the DNS zone generator) 🎀
more parts coming, bestie!! 🫶
2. RWhois Client Model ✨
okay so RWhois has to stay compatible with the current Whois and Whois++ servers 🫶, which means the RWhois client either has to wait and see or already know what kind of server it's talking to, so it can tell whether that server is an RWhois one 👀. the user should get to decide how long the client waits, since that changes with network congestion and capacity 🐢. if the wait runs out and the server hasn't replied with the %RWhois response, the client must not send any RWhois extended directives 🙅♀️.
in that case the client should only send the query 💌. ngl the server identification thing means an RWhois server might sometimes go unnoticed, but it lets RWhois use the Whois and Whois++ infrastructure that's already out there, which is so iconic 🌈. referrals from RWhois can point to a Whois or Whois++ server. those non-RWhois servers must be placed as a leaf on the hierarchical tree, and from the RWhois point of view they form a mesh structure 🕸️. that restriction shouldn't stop anyone from using them to build an RWhois structure, though 💅.
the RWhois server must stay connected until a query comes in 🔌. if the client wants to make multiple queries, it must send the -holdconnect directive 🔁. in this mode, once the client has sent its last query and gotten either an answer or the error code saying no records were found, it must issue the -quit directive 🏁. if the client only wants to issue directives, then it must send the -quit directive when it's done. if it doesn't, the server will keep waiting until it gets some non-directive input from the client ⏳.
the RWhois client in default mode must operate exactly like the current Whois client, since compatibility with the original whois matters 🫶. in enhanced mode, though, the RWhois client can do so much more based on what the RWhois server sends back 🚀✨.
2.1. Directives: Client to Server Interaction
the RWhois client sends directives to the RWhois server 📮. each directive starts with the - character, always at the start of a new line 🌸. for compatibility with older Whois clients, the query does not get the - character 🧸. the client should only send these directives once it's certain the server is an RWhois server 🔍. compatibility with RFC 954 [RFC-954] whois servers is required 💖. all directives must be terminated by <LF><CR> 🎀.
2.2. Required Directives
the following are required RWhois client directives 📋.
2.2.1. <query>
the query is generally the last directive sent to the server, and it's the only directive that doesn't start with a - 🎯. it's the question the client wants the server to answer. the qualifiers that may precede the query are covered in Section 3.1 - Output Display and Restriction Keywords 🔎.
format for use:
[display format]<SP>[query restriction]<SP><query>[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.com2.2.2. RWhois
the -RWhois directive tells the server that the client is an RWhois client, so the server can use the RWhois protocol exclusively 🦋.
format for use:
-RWhois<SP>V-<spec version #><SP>[imp identifier]<Spec version #>{%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 lets the client make a quick call on whether to send the query to the current server 🏎️. if the client decides another server could handle the query better, 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 lets the client ask the server to allocate enough space to collect more responses than the server currently collects 📦.
format for use:
-limit<SP><value><Value>{%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 20002.3.3. schema
one of the shortcomings of X.500 was that you had to know an object's schema before making a query 😤. RWhois fixes that: the client can ask for the schema of an object without knowing the object, using the -schema directive 🧠.
format for use:
-schema<SP>[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 domain2.3.4. xfer
the -xfer directive transfers all data from a server 🚚. this method has no limit on the number of records that can be transferred to the client application 📚. it's mainly used to transfer data contained in an authority area so a secondary server can cache it 🍓.
format for use:
-xfer<SP>[object]<SP>[authority area]<SP>[SOA][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 199408181412592.3.5. quit
the -quit directive tells 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 polls the server for its status 📊. there are seven required responses to this directive 7️⃣. extra attributes may be sent in the response too, but the client should ignore all unknown attributes 🙈. this directive has no arguments.
2.3.7. cache
the RWhois server can hold data it has no authority over 🗃️. if the server sends this data to a requester, it counts as a non-authoritative response. holding this data is called caching 💭. the physical data for these objects isn't on the system hosting the server. the -cache directive lets the client tell 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 that server default, the client should send the -cache off directive during initial session setup if cached data shouldn't be sent 🙅. details on expiration of cache data can be found in section 3.4.3, %soa response 🕰️.
format for use:
-cache<SP><mode><mode>{on|off}
on: Turns caching on.
off: Turns caching off.example of use:
-cache on2.3.8. holdconnect
the RWhois server must close the connection after the response to a query has been received, since the query is the final exchange between client and server 🤝. but this can be changed with the -holdconnect directive 🔧. if this directive is issued to the RWhois server, it stays connected until the -quit directive is received. once -quit arrives, both the server and the client must close their connection 🔒.
format for use:
-holdconnect<SP><mode><mode>{on|off}
On: Turns holdconnect on.
Off: Turns holdconnect off.example of use:
-holdconnect on2.3.9. forward
during normal server operation, the server sends %referral or see-also responses and expects the client to redirect the query to the server named in the response 🔀. but if the client is behind a firewall or poorly connected, having a server make the query may improve performance or let the query get answered at all 🛡️. the -forward directive tells the server to operate as a forwarding server. whether this directive should be allowed is a configuration parameter of the server 🎚️.
format for use:
-forward<SP><mode><mode>{on|off}
On: Turns forwarding on.
Off: Turns forwarding off.example of use:
-forward on2.3.10. soa
identifying authority areas is a big deal in the RWhois design 👑. the -soa directive is used to ask the server whether it has authority over a specific area 🔍. a positive response includes the administrative parameters for the authority area, as detailed in section 3.4.3 📋. if the server doesn't have an SOA for the requested authority area, it must send an error message to the client 🚨.
format for use:
-soa<SP>[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.com2.3.11 notify ✨
Okay so the -notify directive is how you tell a server about a bad or recursive referral, or about a change to a primary server's data 💌
Format for use:
-notify<SP><action><SP><information>The action can be one of these:
<action>{badref|recurref|update|inssec|delsec}- badref 🙈 When a client gets a
%referralresponse that doesn't work, it must report the bad referral to the server that issued it. The referral is only bad if the referred server does not contain the SOA record for the authority area in question. It's NOT a bad referral if the server has no answer to the query but still responds positively to the-soaarea directive, because that just means there isn't an answer. When a-badrefis sent to the referring server, it should log the bad referral so that server's administrator can remove the reference if it's no longer correct. This action should only be taken after receiving a negative response to both 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
-recurrefdirective must be sent identifying the recursive loop. It should only be sent to the server one level back, even if multiple servers 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 lets the secondaries quickly reflect the changes in the primary server's data.
- inssec ➕ This action informs 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 whether the secondary is acceptable. If it is, the server should be added to the update list so it gets informed whenever data in the authority area changes.
- delsec ➖ This action informs the server that the server indicated in the subsequent arguments will no longer be a secondary. The server receiving this action must determine whether that server is a secondary and, if so, remove it from the update list.
The information part looks like this:
<information>{action=badref|recurref <<server>:<query>>
action=inssec|delsec|update
<<server>:<object>:<authority>>}Here's what each argument means 💅
<server>{%Mserver} This required argument identifies the server
that contained the recursive or bad referral,
or has data that changed.
<query>{%s} This required argument identifies the query
that was sent to the server that gave a
recursive or bad referral.
<object>{%s} This required argument identifies the object
that changed.
<authority>{%s} This required argument identifies the
authority area where the object that changed
currently resides.Example of use:
-notify recurref netman1.netsol.com:4343:scottw@netsol.com
-notify badref nic.ddn.mil:43:abc.af.mil
-notify update netman1.netsol.com:4343:domain:netsol.com
-notify inssec dmeister.internic.net:4343:domain:netsol.com
-notify delsec dmeister.internic.net:4343:domain:netsol.com2.3.12 register 📝
This directive lets the client add, modify, or delete information that exists, or should exist, in the server's database 🗂️ During the exchange, all attributes of an object must be sent. The client must wait to send the registration data until the %ok response is received from the server. No skipping ahead, bestie 🙅♀️
Format for use:
-register<SP><mode><SP>(on:<action><SP><e-mail contact>
<SP><authority info>)The mode is either on or off:
<mode>{on|off}
on: This required argument starts the
registration process.
off: This required argument ends the registration
process.The following arguments are only required if the mode argument is sent with the value on:. They're the action you want to take on the object:
(<action>){add|mod|del}
add: This conditionally required argument
indicates that the object being sent should
be added to the server's database.
mod: This conditionally required argument
indicates that the object being sent should
be modified and should already exist in the
server's database.
del: This conditionally required argument
indicates that the object being sent should
be deleted from the server's database.Then there's the sender info and the proof that you are who you say you are 🕵️♀️
(<e-mail contact>){%Memail} This conditionally required
argument identifies the sender of
the registration information.
(<authority info>){%s} This required argument contains
information used to authenticate
the person sending the registration
information. The method used must
be identified using the -private
directive. Work must be done to
identify usable authentication
methods for unsupervised
delegation. This is beyond the
scope of this document. However,
the authors have made an effort to
allow flexibility in the
implementation of an authentication
system.🚨 The authentication method has to be identified with the -private directive. The authors didn't pin down which methods to use for unsupervised delegation, since that's out of scope here, but they did leave room for flexibility.
Example of use:
-register on add scottw@netsol.com
Object-type:referral
Referral:netman1.netsol.com:4343
Domain-Name:netsol.com
IP-Network:192.153.247.0
IP-Network:198.41.0.0
-register off2.3.13 object 🧸
RWhois data is a collection of objects with defined attributes ✨ You can get an object's attributes by issuing the -schema directive. Every object must, at a minimum, define the attribute object-type. That attribute gives the name of the object that gets displayed in response to the -object directive. A client can use this to check that a server contains the object it wants. It's also possible to grab every object on a server and show them to the user as a menu to pick from 🍓
Format for use:
-object<SP>[object][object]{%s} This optional argument identifies the object
requested. If no argument is sent, all objects
contained in the server will be returned.Example of use:
-object domain2.3.14 define 🔍
Format strings that describe an object's attribute format can include format macros 🧩 You can find more about how format macros are defined in Section 6. The -define directive lets the client ask for the definition of a format macro.
Format for use:
-define<SP>[macro name][macro name]{%s} This optional argument identifies the name of
the macro to display. If no arguments are
sent, the server must return the definition
of all macros contained in the server.Example of use:
-define server2.3.15 private 🔐
The -private directive lets the client say which authentication method it wants to use. More research still needs to happen around client authentication, and this directive is there so people can try things out 🧪
Format for use:
-private<SP><action><SP><method><SP>[data]<action>{auth|encr} This required argument identifies the action
the directive is taking. Currently the value
for this argument can be auth for
authentication or encr for encryption.
<method>{%s} This required argument contains the name of
the method to be used. The value must be
recognized by the server or an error will be
sent. It is beyond the scope of this
document to identify the possible method to
be used.
[data]{%s} This optional argument must be supplied if
required by the method identified in the
previous argument.Example of use:
-private auth pass1 xxjdk998uuThat example is a simple password exchange 🔑 It's beyond the scope of this document to figure out which authentication technique would best suit this protocol. Development is underway to pin down the authentication needs and to experiment with potential solutions 🌸
2.3.16 X- 🦋
This directive is the prefix for extended directives that the client and server have agreed on between themselves 🤝 Both the client and server must know about the extended directives in order to use them. Extensions can cover things like NetHelp, white pages, and lots more. If an extension is public, it should be documented in an RFC and made available through the -directive directive.
Format for use:
-X-<directive name><SP>[directive arguments]<directive name>{%s} This required argument identifies the
name of the directive being issued.
[directive arguments]{?} This optional argument is dependent upon
the required or optional arguments of
the extended directive. There may be
multiple directive arguments.Example of use:
-X-date2.3.17 directive 📜
Which directives a server allows can vary from server to server 🎀 The client can issue the -directive directive to check whether a server allows a specific directive, or to get a list of every acceptable directive for that server.
Format for use:
-directive<SP>[directive][directive][%s] This optional argument identifies the directive
being requested. If no arguments are sent, all
of the directives accepted by the server must
be sent.Example of use:
-directive X-date2.3.18 display 🖥️
The -display directive sets the display mode of the server, or lets the client list the display modes it's capable of 💻 If you send this directive without arguments, the server returns all of its available display methods.
Format for use:
-display<SP>[action]<SP>[method][action]{activate|capable}
The `activate' setting enables a certain
display mode, while a `capable' setting sends
the display mode the client is capable of.
[method]{%s} This optional argument indicates the display
method desired by the client.Example of use:
-display swip
-display mime2.3.19 language 🌸
okay so the -language directive is how you set the server's language mode, or how the client tells the server which language modes it can handle 💅 If you send it with no arguments, the server will spill every language it has available ✨
Format for use:
-language<SP>[language][language]{%s} This OPTIONAL argument indicates the language
desired by the client.Example of use:
-language german2.4 RWhois Client Model 🧚
Server <-------> Client
START:
<------ Connection (record time to connect)
If no server type...Wait up to specified
time for------> "%RWhois" response
(recommend wait of at least 5 seconds)
if "%RWhois" is not received from server, assume that it is
not an RWhois server
goto QUERY:
else if "%RWhois" is received from server
<------- send "-RWhois -VX.X"
--------> receive "%ok"
DIRECTIVE: if directive for server
<------- send directive
-------> receive server response
if "%ok" received
goto DIRECTIVE:
if "%error" received
process error then goto DIRECTIVE:
else if no more commands for server
goto QUERY:
QUERY:
<-------- send query
--------> Receive and display response
PROCESS: if "%referral" received
if first referral
restart server list
else
add to server list
if "%see-also" received
insert server into server list
if in holdconnection mode
goto DIRECTIVE:
if no directive (%)
goto END:
goto PROCESS:
END:
server will disconnect
if more servers on Queue and multi or referral mode active
goto START:ok this part is lowkey important 👑 Every single time the RWhois client gets a %referral or %see-also response from the RWhois server, it MUST compare the host:port:query with the ones it has already run. If it finds out it's being sent to repeat the same query on a server it already visited, it MUST NOT repeat that query 🙈
For example, the prototype RWhois client keeps a server trail and checks each new directive against the entire list. If a recursive act is about to happen, the client will notify the user and exit. The original Whois client just opens a TCP connection, sends the query, and displays the response. The RWhois client MUST be more robust so it can handle multiple server queries, servers that do not exist, and recursive referrals. It MUST also remain connected while sending directives and receiving responses. All of these features got folded into the experimental RWhois client 🎀
3. RWhois Server Model 🦋
This section describes the functionality of the RWhois server.
3.1 Output Display and Restriction Keywords 💜
The RWhois server will behave similarly to the original whois server in terms of display formats and restrictions. The following are REQUIRED in the RWhois server.
Display Format Keywords:
EXPand (*) Expand
~ no sub displays
SUBdisplay (%) sub displays
SUMmary ($) Give a short summary for the query on one to
many hits (defaults on multiple hits).
Full (=) Give the full record output on one to many
hits (defaults on one hit only).The following was added to whois post RFC 954 [RFC-954] and is part of the RWhois requirements:
dump (#) Display the record in a parsable format.In addition to the above, the RWhois server MUST accept additional pre-query directives such as Boolean queries and attribute=value query combinations. The capability to perform partial matches is requested by postfixing a * or . at the end of the search item for unknown characters. This capability is REQUIRED for an RWhois server.
Example:
Example: last-name=williamson and first-name=scottData Restriction Format Keywords: The following restriction keywords are found in the RFC 954 [RFC-954] whois server:
!(handle) Query on Handle only
mailbox Query on all records for person
person Query on User records only
host Query on Host records only
domain Query on Domain records only
network Query on Network Records only
asn Query on Autonomous System Numbers onlyThe RWhois server MUST allow restriction of search to any object contained on that server. With the exception of the ! restriction format keyword, the above listed restriction keywords represent defined objects. In the prototype software, each of these objects are defined in configuration files, not hard-coded into the server. New objects, and therefore restriction keywords, SHOULD be easily designed with no code change necessary to the server ✨
3.2 Responses: Server to Client Interaction 💬
Responses are sets of data that servers send in response to a client directive. Responses from an RWhois server MUST be prefaced with the % character at the start of a line. Responses are divided into two groups: those that are REQUIRED to provide minimal RWhois interaction, and those that are used to achieve the desired characteristics of a fully functional distributed system. A server MUST respond with an error message indicating that a directive is not available on the server, and therefore does not have the REQUIRED responses 🫶
3.3 Required Responses 🍓
The following sections describe the REQUIRED RWhois server responses.
3.3.1 RWhois
The %RWhois response is used to identify a server as an RWhois server. Clients that treat RWhois servers differently will need this response to enable the RWhois capabilities.
Format for use:
RWhois<SP>V-<Spec version #><SP><server name><SP>[imp name and
version #]<Spec version #>[V-%2.2f] This REQUIRED response indicates
the version number of the RWhois
protocol specification that the
software is capable of handling.
The version described in this
document is V-1.0.
<server name>[%s] This REQUIRED response is the host
name of the computer hosting the
RWhois server.
[imp name and version #][%s] This OPTIONAL argument contains
information about the server
implementation. It is RECOMMENDED
that the version number of the
software be indicated. This
version MAY differ from the
specification version number.Example of use:
%RWhois V-1.0 rs.internic.net (Network Solutions V-1.6)3.3.2 referral
The %referral response instructs the client to query another server (which could be a whois, RWhois, or whois++ server). Referrals are cumulative. The first referral received during a session MUST replace the default server list. Any subsequent referrals received MUST be appended to the end of the server list.
In the non-Uniform Resource Location (URL) response format below, the authority area equals the reduced query. There are three types of referral. The type can be determined by the client evaluating the authority area which is part of the %referral response.
If the authority area received from a referral response is equal to the original query, then it is a link type referral. If the authority area is not equal to the query, then it is a reduction type referral. If no authority area is sent, then it is a punt type referral. (Punt means the server is not a root and cannot answer the query and therefore is referring the client to a level up the tree or to a server that can better answer the query.) [NOTE: the punt type referral MAY be used to direct a client into the whois++ mesh type.]
The client MAY receive multiple referrals from a single query. If the SOA for each of these referrals is the same, then the first referral is the primary server and all subsequent servers are secondary. Each of the servers will report the SOA for the authority area in question.
Format for use:
%referral<SP><server>[:type]<SP>[authority area]
%referral<SP>url:<url><server>{%Mserver} This REQUIRED argument identifies the
server that the client should re-connect
with.
[type]{%Mstype} This OPTIONAL argument identifies the
server type. This could save wait time for
the client trying to identify a server
which is non-RWhois.
<authority area>{%s} This OPTIONAL argument identifies the
authority area that caused the referral for
the query in question. Using this value as
the argument for the -soa directive to
the referral server SHOULD result in a
positive response. If this is not the
case, the referral is considered bad.
<url>{%Murl} This REQUIRED argument defines the Uniform
Resource Location (URL) string that points
to the resource containing the information
desired.Example of use:
%referral nic.ddn.mil:43 .mil
%referral url:http://www.netsol.com/3.3.3 ok
The %ok response MUST be sent by the RWhois server at the completion of every task or to positively acknowledge a directive.
Format for use:
%ok3.3.4 error
The %error response is used to indicate an error condition to the client. Refer to Section 5 for details on the error reporting scheme. It is important to note that only the error number will be used to determine the client's action. The text message will only be used to make the error readable by humans connected using telnet or an old whois client. The only exception to this rule is the error message used to indicate problems with registration transactions. The format for these message can be found in Section 5 🙈
Format for use:
%error<SP><error number><SP>[error text]<error number>{%d} This REQUIRED argument is the error number
identified in Section 5. The client can use
this number to categorize errors.
[error text]{%s} This OPTIONAL argument is the text that
describes the error message. This message
MUST be consistent for each error. Variables
SHOULD NOT be added to this message. This
message is only to make the error message
human readable. Message sent following an
error code associated with the registration
process will contain the line number of the
attribute that is incorrect.Example of use:
%error<SP>400<SP>Invalid Server Directive3.4 Optional Responses 🌈
The following are OPTIONAL RWhois server responses.
3.4.1. see-also ✨
okay so the %see-also response is basically the server going "hey bestie, go ask THIS other server for more info" 🦋 The client has to reconnect with that server. See-also servers should be inserted into the server list just after the current server. If you get multiple see-alsos from one query, each new one goes after any see-alsos you already got. 💅 They should be extra info that's related to the current query, no random stuff.
One example use is showing autonomous system info for an IP network number, or router interface info for an IP host number. 🌸
Format for use:
%see-also<SP><server>[:type]:<query>
%see-also<SP>url:<url><server>{%Mserver}: required. This is the server the client should reconnect with.[type]{%Mstype]: optional. This tells the client the server type, which can save time for a client trying to figure out a server that isn't RWhois. 🧚<query>{%s}: required. This is the query that must be sent to the referred server. It can be different from the original query sent to the referring server. 💖<url>{%Murl}: required. This is the Uniform Resource Location (URL) string that points to the resource with the info you want. 🔗
Example of use:
%see-also prmd.merit.edu:43:handle=xxx
%see-also url:http://www.netsol.com/3.4.2. load 💜
the %load response tells you the current and average load of the computer running the RWhois server. ngl the measurement might look different depending on how the system's load mechanism works, and that's totally fine 🙈 This was added so people could experiment with sorting preferred servers to get better results for users. iconic experimenting energy 🔥
Format for use:
%load <SP><current><SP><average><current>{%2.2f}: required. This is the current load on the system hosting the RWhois server.<average>{%2.2f}: required. This is the average load on the system hosting the RWhois server.
Example of use:
%load 5.68 1.323.4.3. soa 🎀
the %soa response gives you info about the authority area in question. If the server doesn't have authority for that area, it must respond with the appropriate error message. SOA data must never be cached, and SOA records must originate on the server giving the answer. 🫶 The increment and refresh attributes are used for incremental updates to the secondary server. Deleted data will stay in the secondary server's cache until the refresh time is reached. This cuts down on the amount of data transferred and means the primary server doesn't have to keep deleted data around. Lowkey so smart 🧠✨
These are the minimum attributes required for the soa object:
object-type
authority
ttl
serial
refresh
increment
retry
tech-contact
admin-contact
hostmaster
primaryFormat for use:
%soa<SP>authority:<SP><authority area>
%soa<SP>ttl:<SP><ttl>
%soa<SP>serial:<SP><serial>
%soa<SP>refresh:<SP><refresh>
%soa<SP>increment:<SP><incremental>
%soa<SP>retry:<SP><retry>
%soa<SP>tech-contact:<SP><tech-contact>
%soa<SP>admin-contact:<SP><admin-contact>
%soa<SP>hostmaster:<SP><hostmaster>
%soa<SP>primary:<SP><primary><authority area>{%s}: the authority name of the SOA. For example, internic.net or 198.41.0.0/24. 🌈<ttl>{%d}: the time to live for data in this authority area that another server may cache. The server caching the data should consider it expired once it has been stored for the number of seconds in this attribute. ⏰<serial>{%Mserial}: the serial number of the data in the authority area. The serial number must be incremented every time data in the authority area changes, and it must be numeric. 🔢<refresh>{%d}: the time to completely remove cached data and transfer all data from the primary server. 🧹<increment>{%d}: the time to wait before checking for incremental updates from a primary server. ⏳<retry>{%d}: the time to wait before retrying a connection to a server that seems to be out of service. 🔁<tech-contact>{%Memail}: the e-mail address of the person or role account responsible for running the server. 👩💻<admin-contact>{%Memail}: the e-mail address of the person or role account responsible for the data on the server. 📇<hostmaster>{%Memail}: the e-mail address where changes to the server's data should be sent. A data edit tool can automatically send changes to update the data on the server via e-mail. 📬<primary>{%Mperm}: the primary server for the authority area. 👑
Example of use:
%soa authority: netsol.com
%soa ttl: 7200
%soa serial: 19940606203030
%soa refresh: 7200
%soa increment: 60
%soa retry: 1200
%soa tech-contact: markk@netsol.com
%soa admin-contact: stanb@netsol.com
%soa hostmaster: hostmaster@netsol.com
%soa primary: netman1.netsol.com:4343
%ok3.4.4. status 💅
the %status response shows the status of a bunch of important flags and values. The response must contain the following elements. 🍓
- Limit: the current limit set on the server. This value can be changed using the
-limitdirective. It's not the server's maximum limit. This value isn't disclosed so clients can't automatically set the highest limit possible and tank the server's performance. 🙅♀️ - Load: the current load of the host system.
- Cache: the current status of the cache flag (on or off).
- Holdconnect: the current status of the holdconnect flag (on or off).
- Forward: the current status of the forward flag (on or off).
- Authority records: the number of authority records in the server's database.
- Cached records: the number of records in the server's cache database.
- Display: the types of display modes the server is using. 🎨
Format for use:
%status<SP>limit:<SP><current limit>
%status<SP>load:<SP><current load>
%status<SP>cache:<SP><cache>
%status<SP>holdconnect:<SP><holdconnect>
%status<SP>forward:<SP><forward>
%status<SP>Authority:<SP><SOA number>
%status<SP>Cached:<SP><cached number>
%status<SP>Display<SP><mode>:<SP><type>See above for the description of these values.
<current limit>{%d}
<current load>{%2.2f}
<cache>{on|off}
<holdconnect>{on|off}
<forward>{on|off}
<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: summary3.4.5. xfer 🦋
the %xfer response sends all instances of an object. It answers the -xfer directive. The transfer can be limited by the directive's arguments. If there are no arguments, the server must send all of the objects in the database. Cached data must not be transferred this way 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 aren't required if the current response is an object instance separator. ✨
<object>{%s}: required. The name of the object being transferred.<attribute>{%s}: required. The attribute being sent.<value>{%s}: required. The value of the attribute. If it's 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
%xfer3.4.6. schema 🌸
the %schema response describes the attributes of an object. It answers 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>
%schemaThese arguments aren't required if the current response is an attribute separator. 💅
<attribute name>{%s}: required. The name of the attribute being described.<format string>{%s}: required. The allowed format for the attribute.<descriptive string>{%s}: required. What the attribute is used for.<indexed>{on|off}: required. Identifies attributes that are indexed.<required>{on|off}: required. Identifies attributes that are required.<multi-line>{on|off}: required. Says whether the attribute can span multiple lines.<type>{text|MIME|see-also|PostScript}: required. The type of the attribute.<unique-key>{on|off}: required. Says 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
%schema3.4.7. define 🧚♀️
the %define response tells the client about format macros. Every format macro used in the schema format definition string must be available to the client through the -define directive. Format macros can be nested. 🪆 It's the client's job to request any format strings it doesn't recognize from a server. And if the format strings change on a server, the serial number of the schemas that use the format must change. periodt 📌
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 🦋
okay so every visible object on an RWhois server MUST be identified when a -object directive comes in 💅 the %object response either confirms that an object exists or hands you the full list of every object the connected user can see 🫶
a blank %object line is the separator between objects, so it's giving tidy formatting 🎀
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:mailbox3.4.9 directive ✨
the %directive response shows off which directives the connected server allows 🌸 for every directive you MUST send the directive name, the description and the syntax attributes 😭 if someone asks about just one directive, you only have to return info on that one, no extras 💖
a %directive response with no arguments MUST be sent between directives, like a little breather between each one 🍓
Format for use:
%directive<SP>directive:<directive>
%directive<SP>description:<description>
%directive<SP>syntax:<format>
%directivethe arguments below are required except when you're 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 gives the client user a message 💜 it's never started by a directive, it just pops up 😭 whatever shows up between %info on and %info off should be shown to the user 🎀 the ideal use is a Message of The Day (MOTD), iconic 👑
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 off3.4.11 display 🦋
the %display response tells the client that the data after it is using the method you name 🌸 that method stays active until a %display response comes in with no arguments 💅 a server MUST send an error message to clients that have been identified as non-RWhois clients, no cap 💀 this response is how you get display methods like MIME [RFC 1521] or other special character sets, like the ones used for Japanese 🇯🇵✨
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...
%display3.4.12 X- 🧚
the %X- response is how extended responses show up 💜 the client MUST have prior knowledge of this response, bestie, it won't just magically work 😭
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 tells the client that the data after it will be in the language named 🫶 that language stays active until a %language response shows up with no arguments, and then the server goes back to English, the default 🇬🇧 a server MUST send an error message to clients that have been identified as non-RWhois clients, periodt 💅
Format for use:
%language:<SP><language>Example of use:
%language: german
RWhois Deutsche Version: 1.0
%language3.5 Query Reduction 👑
the critical part of the RWhois server is being able to shrink the query so you find a server that's closer to the data 🔥 the server's search algorithm goes like this:
- accept a query
- find any local matches - display them
- find any referrals - display them
- if no local or referral hits, reduce the query and goto step 3
here's an example with the query ietf.cnri.reston.va.us 🦋
- query whois for ietf.cnri.reston.va.us
- search rs.internic.net for information (no hits).
- search referrals for ietf.cnri.reston.va.us (no hits).
- search referrals for cnri.reston.va.us (no hits).
- search referrals for reston.va.us (no hits).
- search referrals for va.us (no hits).
- 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 RWhois, main character energy 👑 if you need an authoritative response, turning the cache off is step one 🧚 the client can also check whether the connected server has authority over the name/number space it cares about by sending the -soa <authority area> directive 🌸 if the server does have authority for that area, it MUST return important information about the authority area ✨ here's an exchange where a client checks whether 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 %ok3.7 Secondary Server Interaction 🎀
a server operating as a secondary will report an authoritative SOA for the authority area of the data it holds 💅 below is the interaction between the primary and the secondary 😭 in reality the secondary operation would be done with a client made specifically for that job 🤖
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 connection3.8 Registration Process 🦋
the following is the interaction that happens 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 %quit3.9 Out-of-Service 💀
servers being taken out of service SHOULD automatically refer the client back into the tree 😭 that's not possible if the system hosting the server is also out of service, though 🙈 in that case the client's robustness MUST be relied upon to return to the referrer and tell that server the referral was bad 💔 if the system will still be 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- Interaction: Client Directives and Acceptable Server Responses ✨
this section covers the responses to the different client directives 💖
4.1 General 🌸
these general responses can come back from any directive, so they won't be repeated under each one 🧚
%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... goodbye4.2 On Connection 🦋
these responses only happen after a successful connection to the server's host and the application has started up 🌈
%RWhois
%error<SP>501<SP>Service not available
%referral
%error<SP>503<SP>Idle time exceeded... goodbye4.3 <QUERY> 💜
these responses MAY come back after 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 expired4.4 -RWhois 🎀
%error<SP>300<SP>Not compatible with that version number4.5 -load ⭐
%load
%error<SP>335<SP>System's load not available4.6 -limit<SP>< value > 🍓
%limit
%error<SP>330<SP>Exceeded Max Records Limit
%error<SP>331<SP>Invalid Max Records Size4.7 -schema<SP>[object] 🧚
%schema
%error<SP>337<SP>Object's schema not found4.8 -xfer<SP>[object] 🚚
Here are the responses you can get back from -xfer<SP>[object]:
%xfer
%error<SP>332<SP>Nothing to transfer
%error<SP>337<SP>Object's schema not found4.9 -quit 👋
Sending -quit gets you this response:
%ok4.10 -cache<SP><on/off> 🧊
%error<SP>232<SP>Cache disabled4.11 -status ✨
%status4.12 -forward 🔁
%error<SP>431<SP>Not authorized to forward
%error<SP>433<SP>Bad reference on forward4.13 -soa 👑
%soa
%error<SP>333<SP>Not SOA for requested authority area4.14 -notify 📣
%error<SP>434<SP>Referral does not exist on this server
%error<SP>530<SP>Not authorized as secondary4.15 -register 📝
This one has the most responses, so get comfy 💅
%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 🫶
Nothing is listed under this directive in the original, so there are no responses to show here 🌸
4.17 -object 🎀
%object
%error<SP>336<SP>Object not defined4.18 -define 🧚
%define
%error<SP>435<SP>Macro not defined4.19 -X- 🦋
%X-
%error<SP>460<SP>Extended directive not recognized
%error<SP>461<SP>Extended directive not authorized4.20 -display 🌈
%display
%display<SP>436<SP>Display mode not allowed4.21 -language 💜
%language<SP>437<SP>Language not supported5. Error Codes 🚨
okay so the error code comes right after the %error response from the RWhois server, and the full definitions are below. The codes are descriptive on purpose, so a client can group messages and figure out what group action it needs to take before it does anything error-specific. 🧠 Codes should stay consistent, with no variable extensions, except for messages tied to the registration process.
Here's the important bit, bestie 👀 If a client sees a 6 in the second position and doesn't support the extended code it got back, the client must act on the first position code. For example, if a client gets %error 561 and doesn't support the extended error codes for the server it's connected to, it would exit based on the 5 in the first position. Fatal, no cap 💀
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 order5.1 Error Code List 📋
Here's the ordered list of RWhois error codes. Servers can extend these with implementation specific codes, and those extended codes will have a 6 in the second position ✨
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 secondary6. Attribute Format 🎀
Every attribute for objects on the RWhois server must be specified with a format specifier 📐 This is what lets client software interpret the data it gets back correctly. The RWhois format specifier is pretty much based on the C language scanf syntax, plus 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 can be presented as macros. Macros are defined using this 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]To grab macro definitions, send the -define directive to the server. Clients can remember definitions to save work. If a macro's definition changes, the serial number of every schema using that macro must change, so clients can reacquire the schema and format specifier macros 🔄
7. Quick Query (RWhois using UDP) ⚡
Setting up a TCP connection and chatting with an RWhois server can be a lot if you only have one question, so that overhead may be unnecessary. A separate document will describe the UDP facility for RWhois. Adjustments to the query must be made before it's a practical option. The only function allowed while using UDP is a single query, bestie 💖
8. References 📚
[RFC-954] Harrenstien, K., Stahl, M., and E Feinler, "NICNAME/
WHOIS", RFC 954, 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", RFC 1521, Bellcore, Innosoft,
September 1993.9. Security Considerations 🔒
Security issues are not discussed in this memo. 😱
10. Authors' Addresses 🖋️
Here are the authors and how to reach them 💌
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📦 where this page comes from
- ietf: rfc1714 1994-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms