RFC 2167

Referral Whois (RWhois) Protocol V1.5

📅 published June 1997, from ietf

RFC 2167: Referral Whois (RWhois) Protocol V1.5 🎀

Title block, bestie, read this first 💅

Series: Network Working Group
RFC number: 2167
Title: Referral Whois (RWhois) Protocol V1.5
Authors: S. Williamson, M. Kosters, D. Blacka, J. Singh, K. Zeilstra
Organisation: Network Solutions, Inc.
Category: Informational
Date: June 1997
Obsoletes: RFC 1714
Updates: nothing listed in the header

Status of This Memo ✨

okay so this memo is just giving information to the Internet community 🦋 It does not specify an Internet standard of any kind, so nobody is required to follow it like a rulebook. Distribution of this memo is unlimited, so share it with everyone you know 💜

Abstract 🌸

this memo describes Version 1.5 of the client/server interaction of RWhois. RWhois is a distributed system for finding, fetching, and keeping directory information up to date. It's primarily hierarchical by design, which means it can route a query deterministically using hierarchical tags, sending the user closer to whoever maintains the information. RWhois can be called a generic directory services protocol, but what makes it iconic is its integrated, hierarchical architecture and its query routing mechanism 👑

1. Introduction ✨

okay, history time 🧚 Way back when ARPANET was getting going, the SRI-NIC ran a centralized Whois database. It held host and network information about the systems on the network, plus the email addresses of the people using those systems [RFC 954]. ARPANET grew into the global Internet, with countless people and hundreds of thousands of end systems. Honestly, the sheer size and effort of keeping one centralized database together is exhausting, so the Internet needs a decentralized way to store and retrieve this info 😭

The original Whois was meant to be a central directory of resources and people on ARPANET. It just couldn't keep up with the bigger Internet. RWhois builds on the Whois idea in a hierarchical, scaleable way. It mainly focuses on distributing "network objects", which are the data representing Internet resources or people. It also uses how naturally hierarchical those network objects are (domain names, Internet Protocol (IP) networks, email addresses) to find the requested information more accurately 🎀

RWhois borrows from other established Internet protocols, which is so smart. Its structure draws a lot from the Domain Name System (DNS) [RFC 1034], and it takes directory service ideas from other directory efforts, mainly [X.500]. It's also influenced by older Internet protocols like the Simple Mail Transport Protocol (SMTP) [RFC 821] 🍓

This RWhois specification defines both a directory access protocol and a directory architecture. The directory access protocol spells out the syntax of the client/server interaction. It covers how an RWhois client can search for data on an RWhois server, or how the client can change data on the server. It also covers how the server reads input from the client, and how the client should read the results the server sends back. The architecture part is the conceptual framework behind the protocol. It explains the ideas the protocol is built on and describes its structural elements. The protocol implements the architecture 🦋

This document uses language like SHOULD and SHALL that have special meaning as specified in "Key words for use in RFCs to Indicate Requirement Levels". [RFC2119] 💅

2. Architecture 🌈

2.1 Overview

RWhois is a distributed database, which is giving "split the work" energy 💖 The data is spread across multiple servers so the databases stay manageable. This section is about how the data gets split between those servers. The basis for splitting is the lexically hierarchical label (or tag). That's a text string whose position in a hierarchy can be figured out from the string itself ✨

All data can follow some kind of hierarchy, even if it seems kinda arbitrary. Take person names. They can be grouped by geography: people in particular towns go into town groups, town groups go into state (or province) groups, and state groups go into a country group. So one name belongs in a town group, a state group, and a country group. But if you only have a name, you can't tell where it belongs in that hierarchy 🙈 That means a person name is not lexically hierarchical.

Some data is different, though, because you can work out its position just by reading it. Phone numbers are a great example. A phone number is grouped by country code, area code, local exchange, and local extension. Looking at a phone number tells you which of those groups it's in. For instance, 1-303-555-2367 is in country code 1, area code 303, local exchange 555, and has a local extension of 2367. So a phone number is lexically hierarchical 💜

Two types of data like this are widely used on the Internet: domain names and IP networks. Domain names use a label-dot system, reading from the more specific label to the more general one, left to right. For example, war.west.netsol.com is part of west.netsol.com, which is part of netsol.com, which is part of com. IP networks are lexically hierarchical labels too, written in Classless Inter-Domain Routing (CIDR) notation. Their hierarchy isn't easy to figure out with simple text manipulation, though. For example, 198.41.0.0/22 is part of 198.41.0.0/16, which is part of 198.40.0.0/15. Instead, an IP network's hierarchy is found by converting the network to binary notation and applying successively shorter bit masks 🔥

Very little real data is lexically hierarchical by nature, but people make label systems (or namespaces) to manage data and to keep things unique. Examples include Social Security Numbers, ISBNs, and the Dewey Decimal System 🌸 RWhois uses lexically hierarchical labels, domain names and IP networks, to split its data. It does this with two ideas: authority areas and referrals. An authority area is tied to an RWhois server and a lexically hierarchical label, and that label is considered its name. An authority area is a piece of the distributed database that speaks with authority about its assigned part of the hierarchy. All data tied to a particular lexically hierarchical tag should be located within that authority area's database. Authority areas are explained further in Section 2.4 ✨

RWhois points clients toward the right authority area by generating referrals. A referral is a pointer to another server that is presumed to be closer to the desired data. The client uses that referral to contact the next server and ask the same question. The next server might respond with data, an error, or another referral (or referrals). By following this chain of referrals, the client will eventually reach the server with the right authority area 🧚 In the RWhois architecture, referrals are generated by identifying a lexically hierarchical label and decoding the label to find the next server. Referrals are explained further in Section 2.5 💖

When a number of RWhois servers with authority areas come online and are told about each other, they form an RWhois tree. The tree has a root authority area, which is the group that contains all the other groups. The root authority area must keep pointers to the servers and authority areas that form the first level of the hierarchy. The authority areas in that first level are then responsible for keeping pointers to the authority areas below them, and for keeping a pointer to the root 👑

2.2 Design Philosophy

The design goals for the RWhois protocol are as follows.

It should be a directory access protocol. The server should be able to access and update the data residing on it 🫶
It should facilitate query routing. An unresolved query should be redirected to a server that is presumed to be closer to the desired data 🦋
It should enable data replication. The server should be able to duplicate its data on another server 🌈
The server should be lightweight and delegate more functions to the client 🍓

The concepts used to achieve these design goals are explained in the rest of the document ✨

2.3 Schema Model

okay, schema is a word that gets used two different ways, so let's clear it up 🎀 As a directory service, RWhois uses various database schema to store and represent data. In this document, schema has two definitions. The first is the entire structure of a database, meaning all the tables and fields that make up a complete database. When schema is used this way, it's called "database schema". A database schema is made of attributes, classes, and objects. The second is a single piece of the database, like one table with its fields. When schema is used this way, it's just called "schema", or it's named after the piece it describes, like contact schema or domain schema. In that usage, schema is equivalent to "class", which is defined below 💜

There is no standard database schema in the RWhois architecture. Each authority area is presumed to be able to define its own local schema. However, an authority area that's part of a larger RWhois tree is expected to have some part of its schema pertain to the lexically hierarchical label that the RWhois tree is based on. An authority area's schema may not change throughout much of an RWhois tree 🌸

(part 1 of 12, more coming bestie 🧚💖)

2.3.1 Attributes ✨

okay so an attribute is a named field, and it's the smallest typed unit in the whole database schema 🧚 it's basically the same idea as a field in a relational database. on its own it isn't really data. it just gives data a type. once a piece of data has been typed by an attribute, we call it a value, and the pair is an attribute-value pair. in RWhois you separate them with a colon, like this:

First-Name:Bill

attributes have a bunch of properties 💅 some are mandated by the RWhois protocol and some are up to each implementation. the implementation-dependent ones usually mirror the database system the server is running. here's the protocol-mandated list:

Attribute: the name of the attribute 🏷️
Description: a natural language description of the attribute 📝
Type: broadly tells the protocol how the attribute is used. there are three standard types: TEXT, ID, and SEE-ALSO. the default is TEXT, meaning the value is a text string. ID means the attribute contains the ID of another RWhois object (this is used for database normalization 🤓). SEE-ALSO means the attribute contains a pointer (a Uniform Resource Identifier (URI)) to some other kind of external data, like a World Wide Web page or an FTP site 🌐
Format: an interpretable string describing the acceptance format of the value. the server (and optionally the client) SHOULD match the value against the format string to decide if it's acceptable. the format property is a keyword for the syntax of the format string, then a colon, then the format string itself. right now the only keyword recognized is "re", which means POSIX.2 extended regular expressions 🎯
Indexed: a true or false flag saying this attribute should be indexed, which means it can be searched 🔍
Required: a true or false flag saying this attribute MUST have a value in an instance of the class 🫶
Multi-Line: a true or false flag saying this attribute MAY have multiple instances in a class, but all of those instances are treated as multiple lines of the same attribute instance. this lets normal line terminators end values 📜
Repeatable: a true or false flag saying there MAY be multiple instances of this attribute in a class, and each instance is interpreted as a separate instance (unlike Multi-Line). this flag is mutually exclusive with Multi-Line: if Multi-Line is true, then Repeatable MUST be false and vice versa 🙅‍♀️
Primary: a true or false flag saying this attribute is a primary key. if more than one attribute in a class is marked as primary, those attributes together form a single primary key. the primary key is meant to force uniqueness among class instances, so there can be only one instance of a primary key in a database. the Primary flag implies the attribute is also REQUIRED 🔑
Hierarchical: a true or false flag saying this attribute is lexically hierarchical 🌳
Private: a true or false flag saying whether or not this attribute is private (that is, publicly not viewable). it defaults to false. if it is true, then only the clients that satisfy the authentication/encryption requirements of a guardian (described below) can view the attribute-value pair 🕵️‍♀️

2.3.2 Class 🧁

okay a class is a collection of attributes. it's a structure, not data 💖 it's equivalent to a relational database table, and it's also equivalent to the second definition of schema from above.

a class also has some properties that people call its "meta" information:

Version: a time/date stamp used to quickly detect when a class definition has changed 🕰️
Description: a natural language description of the class 📖

2.3.3 Object 🎁

an object is an instance of a class. it's data with a type of <class>. 💜

2.3.4 Base Class 👑

so RWhois doesn't have or advocate any one standardized schema, BUT it does impose a few requirements 🥹 it requires that all defined classes inherit attributes from a particular base class (or base schema). the RWhois specification doesn't require that inheritance actually be implemented. instead, all classes MUST include the attributes defined in the base class.

the base class has the following attributes:

Class-Name: contains the name of the class the object belongs to. it's the type of the object itself. it is of type TEXT and is REQUIRED 🏷️
Auth-Area: contains the name of the authority area the object belongs to. together with Class-Name, it definitively defines the type of the object. it is of type TEXT and is REQUIRED 🗺️
ID: a universal identifier for the object 🆔 it's formed by choosing a string that's unique within an authority area and appending the authority area to it, with a period separating the local string from the authority area name. the only restrictions on the local string are that it MUST be unique within the authority area and not contain the period character. this attribute is hierarchical in nature. it's always generated by the server (for example, during a register operation). it is of type TEXT and is REQUIRED 🌸
Updated: a time/date stamp for the last modification of the object. it's informational AND a form of record locking. it stops two clients from modifying the same object at the same time 🔒 it is of type TEXT and is REQUIRED ⏰
Guardian: a link to a guardian object (more on those below). its value is the ID of a guardian object. it is of type ID and is OPTIONAL. it's repeatable, since an object can have multiple guardians 🛡️
Private: a true or false flag saying whether or not an object is private (publicly not viewable). it defaults to false. if it's true, then only the clients that satisfy the authentication/encryption requirements of one of the object's guardians can view the object. if the object is publicly viewable, the Private attribute property of each of its attributes still applies 🙈
TTL: the "time-to-live" of a given object 🧚 it's included only if the object has a different time-to-live than the default given in the Start of Authority information. its value is specified in seconds. it is of type TEXT and is OPTIONAL ⏳

the RWhois specification defines two standard classes that SHOULD be included in all implementations: the referral and guardian classes 🎀

2.3.5 Referral Class 🔗

the referral class holds referral information (typically for link referrals) 💅 it's made up of attributes from the base class, the protocol-specific attributes below, and any installation-specific attributes.

Referred-Auth-Area: contains the name of the authority area the referral points to. it's used as a search key during query routing 🧭 it is of type TEXT and is REQUIRED. it's repeatable, since referrals can point to servers hosting more than one authority area 🌍
Referral: contains the referral itself. it's an RWhois URL 🪄 it is of type TEXT and is REQUIRED. it's repeatable, since more than one server can host a Referred-Auth-Area 🫧

2.3.6 Guardian Class 🛡️💖

the guardian class holds security information, and the core idea is kind of iconic 👑 an object (or another structure) is "guarded" by containing a pointer to a guardian object [Guardian]. to modify, delete, or possibly view the guarded object, the authentication (or encryption, or both) scheme MUST be satisfied. guardians are intended to NOT have rank, so if an object is guarded by more than one guardian object, satisfying ANY one of those guardians is enough 🙌 (sorry, I had to make that one loud, but the spec's wording is that satisfying any one of them is sufficient.) a guardian object that doesn't have any Guardian attribute linking it to other guardians guards itself. that means the authentication scheme in the guardian object itself MUST be satisfied to modify, delete, or possibly view it 🔐

guardian objects are typically linked to actual database objects with the Guardian attribute from the base class. however, a guardian can also be linked to an entire authority area, in which case it becomes implicitly linked to all of the objects inside that authority area 🌈

the guardian class is made up of the base class, the protocol-specific attributes below, and any installation-specific attributes.

Guard-Scheme: contains a keyword indicating the authentication methodology. its value MUST be understood by both the client and server, and its value dictates the contents of the Guard-Info attribute. it is of type TEXT and is REQUIRED 🗝️
Guard-Info: contains the data the Guard-Scheme uses to verify the authentication. its actual format is dictated by the Guard-Scheme. for example, it could contain a password or Pretty Good Privacy (PGP) public key id [RFC 1991]. for security reasons, it SHOULD NOT be displayed, and its Private attribute property SHOULD be set to true. it is of type TEXT and is REQUIRED 🤫

🚨 bestie, this one's serious: Guard-Info is the secret sauce. keep it hidden, keep it private, and don't go showing it to just anyone 🙈

2.4 Authority Areas ✨

okay so authority areas are literally the MAIN CHARACTER concept of RWhois 💅 when someone builds an RWhois tree for a lexically hierarchical namespace, each piece of the hierarchy gets mapped to an authority area. the big deal is that an authority area can definitively control its own chunk of the hierarchy. so it can say, with total confidence, whether a hierarchical tag exists anywhere in the whole tree. it does that by returning the object that has the tag, returning a referral to a sub-authority area, or returning a response saying no objects were found. 🙌

this setup makes query routing super efficient 🦋 because the hierarchical label tells you exactly which piece of the hierarchy is responsible for it. for example, in the domain name namespace as served by RWhois, the root of the tree is an authority area called .. it delegates a us sub-authority area, which delegates va, co, md, and ca authority areas, and so on down the line. when the server for the va.us authority area gets asked about loudoun.va.us, it can authoritatively say either that no loudoun.va.us exists, or it can hand back an object for it or a referral to it. 🫶 but if that same server gets asked about howard.md.us, it can't answer authoritatively, so it MUST NOT pretend it can. it has to give a referral to its hierarchical parent (us or the root). no cap, the hierarchy is doing a lot of work here 😭

now, where you store data matters a LOT 🔥 because RWhois uses a specific query routing model, data has to be placed under the proper authority area. you can put a piece of data under the wrong authority area. like putting an object for howard.md.us under the va.us authority area. when that happens, the data is considered misplaced and can't be found within the RWhois tree. 💀 but here's the nuance: data SHOULD go under the lowest (most specific) authority area. it's also possible to put it in a higher (least specific) authority area, like putting an object for loudoun.va.us under the us authority. that MAY be acceptable, since in most cases the data would still be findable. ✨

on top of controlling a part of an RWhois hierarchy, an authority area is considered autonomous 🌸 each one is treated as a separate database by the protocol. it is RECOMMENDED that an authority area share some core schema with the rest of the RWhois tree, for interoperability reasons. 🎀 but each authority area isn't bound by the database schema of its hierarchical parent, or by any of its sub-authority areas. independent queen energy 👑

2.5 Query Routing 🧚

RWhois isn't just a directory access protocol, bestie. it can also route queries 🦋 routing a query means redirecting it to another server that's presumed to be closer to the data you want. so the server first figures out where the next server is. then it either forwards the query to that server and passes the result back to the client, OR it sends the location of that server back to the client. that location has to include the server's host name (or IP address), port number, and authority area. 💖

the location of the server a query gets routed to is called a referral 🌈 there are two types: punt referrals and link referrals. a punt referral points to a server further UP an RWhois tree, and a link referral points to a server further DOWN the tree. in Figure 1, when the server for the va.us authority area routes a query up to the server for the us authority area, that's a punt referral. but when it routes a query down to the server for the loudon.va.us authority area, that's a link referral. ✨

whether the server can use hierarchy to route depends on whether the search value in the query is lexically hierarchical. if it IS hierarchical, the server can generate punt or link referrals using the association of authority areas with those hierarchical labels. if it ISN'T, the server MAY send the query to a special index server 🔍 that gathers indexing info for both hierarchical and non-hierarchical data from the directory servers, and returns referrals to those servers [CIP]. and if the server gets one or more referrals back from the index server, it SHOULD return them to the client. 🫶

⚠️ important tea: the server MAY route a query whether or not it could actually resolve it. even if a query was resolved locally, the server MAY still return referrals to the client by sending the query to the index server. 😭

for example, say the server for the com authority area gets the domain Org-Name=IBM query. it may return all the domain objects for IBM within the com authority area. 🏢 it may ALSO return referrals to the server for the nl authority area, if that server has domain objects for IBM in the Netherlands and has fed the matching indexing info to the index server. that way the client gets info for BOTH the ibm.com and ibm.nl domains. iykyk, the routing is doing its best 🥹

2.5.1 Query Routing Rules 💅

RWhois servers route queries based on certain rules 🎀 the goal is to figure out where to send the query. a query can contain one or more query terms, and the routing rules get applied to each query term until a referral is found. here they are:

is the search value in the query term hierarchical? if not, move on to the next query term. 🙈
parse the hierarchical portion of the search value. is it within one of the authority areas? if not, move on to the next query term.
does the authority area that was found have any referral objects (instances of the referral class)? if not, return the 230 No objects found error to the client. 💀
is the hierarchical portion of the search value within the Referred-Auth-Area attribute of one of the referral objects? if it is, return the value of the Referral attribute of that referral object as a link referral to the client. 🦋
are the search values of some of the query terms hierarchical but NOT within any of the authority areas? if they are, return a punt referral to the client. 🌸
are the search values of ALL the query terms non-hierarchical? if they are, send the query to a special index server that gathers indexing info for both hierarchical and non-hierarchical data from the directory servers and returns referrals to those servers. if the server gets one or more referrals from the index server, return them to the client. 🔍

there can be MORE than one referral returned to the client 🌈 and those referrals may point to servers serving different authority areas. the client can follow them in any order it likes. 👑

the pseudo code for the rules above looks like this:

for each query term in the query
 if the search value in the query term is hierarchical
  if the search value is within one of the authority areas
    if the search value is within one of the referred authority areas
     the server sends link referral(s)
    else
     the server sends a "230 No objects found" error
    endif
  endif
 endif
endfor

if the search values of some of the query terms are hierarchical but
  not within any of the authority areas
 the server sends Punt referral(s)
endif

if the search values of all the query terms are non-hierarchical
 the server sends Referral(s) from an index server
endif

2.6 Data Replication 💖

an RWhois server can replicate (duplicate) data from another RWhois server, on a per-authority-area basis 🫧 replication makes the RWhois service more reliable. it also boosts throughput, because queries get spread across more than one server. main character reliability ✨

there can be two types of servers serving an authority area: a master server and a slave server. the master server is where data gets registered for an authority area, and it answers authoritatively to queries in that area. there MUST be one and only one master server for an authority area. the master is also called a primary server 👑

the slave server is where data gets replicated FROM the master for an authority area. it also answers authoritatively to queries in that area. there MAY be one or more slave servers for an authority area 🌷 the slave is also called a secondary server. and this part is key: a slave server MUST NOT register data for an authority area. 🙅‍♀️ it's a copycat, not the source. 🎀

it is RECOMMENDED that the master and slave servers for an authority area be geographically separate 🌍 that way, network unreachability at one site won't completely shut down the RWhois service for that authority area. the whole point is redundancy, babe 🫶

2.6.1 Data to Replicate 🦋

in RWhois, data is replicated on a per-authority-area basis 💅 the smallest unit a slave server can replicate is an attribute of a class. so a slave server can replicate data for all the classes, for some classes, or for only some attributes of some classes. it's very flexible, very iconic 🌈

the amount of data a slave server replicates each time is either ALL of the data, or just the data that has changed since the last replication. replicating all of the data is called complete replication 🧺 and replicating only what changed since the last replication is called incremental replication ✨

2.6.2 Start Of Authority Variables 💖

okay so every authority area has its own little set of admin variables 🎀 that live at the master server and control how data gets replicated. these are called the Start Of Authority (SOA) variables, and here's the whole lineup ✨

Serial-Number: this is the serial number of the data in an authority area 🔢. the master server SHOULD update this variable whenever the data in the authority area is changed. its value is a time/date stamp ⏰.
Refresh-Interval: this is the time interval before a slave server checks for complete replication. its value is specified in seconds ⏳.
Increment-Interval: this is the time interval before a slave server checks for incremental replication. its value is specified in seconds ⏳.
Retry-Interval: this is the time interval before a slave server tries again to connect to a master server that appears to be out-of-service 📵. its value is specified in seconds.
Time-To-Live: this is the default time to live for the data in an authority area at a slave server. the slave server SHOULD NOT answer authoritatively to queries for such stale data 🙈. its value is specified in seconds.
Admin-Contact: this is the email address of an individual or a role account responsible for the data integrity in an authority area at the master server 🧑‍💼.
Tech-Contact: this is the email address of an individual or a role account responsible for the operation of the master server for an authority area 🛠️.
Hostmaster: this is the email address of an individual or a role account to whom email messages to update the data in an authority area at the master server are sent 📬.
Primary-Server: this is the location of the master server for an authority area 📍. its value MUST contain both the host name (or IP address) and port number of the master server 👑.

3. Protocol 🧚

3.1 Overview

okay so the sections above covered the directory service architecture based on the RWhois protocol 🌸. the remaining sections get into the syntax of the protocol, which is basically the sequence and syntax of the info that gets swapped between a server and a client. there are five types of info that can be exchanged during a client/server session: directive, response, query, result, and info 💅.

3.1.1 Directive

a directive is a command that a client sends to a server to set a control parameter for the session, grab the meta-information (class definitions and SOA information) about an authority area, or grab the data in an authority area 🎯. the first character of a directive MUST be a "-". the server MUST support the "-rwhois" directive, and all other directives are OPTIONAL 🫶. the server MUST indicate in the banner which directives are implemented (see Section 3.1.9) 📣.

3.1.2 Response

a response is the info a server returns to a client for a directive 💌. it's made of one or more lines, and the last line always tells you whether the directive worked or flopped 😭. the first character of each response line MUST be a "%". if the server runs a directive successfully, the last response line MUST be "%ok". otherwise, it MUST be "%error <error-code> <error-text>". a line starting with "%ok" or "%error" MUST occur only once in a server response and MUST always be the last line 🔚. the server MAY send the "%info" response for special messages ✨.

a client MUST understand the "%ok", "%error", and "%info" responses 🧠. the client MUST also understand directive-specific responses if it uses the related directives to talk to the server. for example, if the client sends the "-schema" directive, the client MUST understand the "%schema" response 🦋.

3.1.3 Query

a query is a command that a client sends to a server to access the data in an authority area 🔍. the first character of a query MUST NOT be a "-". the server checks the first character of each command from a client to figure out whether it's a directive or a query, so this matters 🙈.

3.1.4 Result

a result is the info a server returns to a client for a query 🎁. it can be either the accessed data or referrals to other servers 🔀. it's made of one or more lines, and the last line always tells you whether the query worked. if the server returns either data or referrals for a query, the last result line MUST be "%ok". otherwise, it MUST be "%error <error-code> <error-text>" 💖.

3.1.5 Info

an info message is miscellaneous info that a server sends to a client 📝. the server MAY use it to send special messages, like a "message of the day" (MOTD) 🌈. the first info line MUST be "%info on", and the last info line MUST be "%info off" 🍓.

3.1.6 Client/Server Session

a typical RWhois client/server session goes like this 🎬:

The client connects to the server.
The server returns a banner identifying its protocol versions and capabilities.
The client sends one or more directives to the server.
The server returns the response to each directive.
The client finally sends a query to the server.
The server returns the query results.
The server closes the connection, unless the client has directed it not to close the connection.

3.1.7 Examples

okay here come the examples 🧁. the notation uses a prefix to show where the info comes from. a "C" means the client sends the data to the server, and an "S" means the server sends the data to the client 💜. a "#" makes the line a comment, and the space after the prefix isn't part of the data 🙈.

first up, a successful query 🎀:

# The client connects to the server.
# The server returns a banner identifying its protocol versions and
# capabilities.
S %rwhois V-1.5:00ffff:00 master.rwhois.net (Network Solutions V-1.5)
# The client sends a directive to limit the number of search hits
# to 20.
C -limit 20
# The server returns a successful response.
S %ok
# The client sends a query to search for rwhois.net domain.
C domain rwhois.net
# The server returns the data for rwhois.net domain.
S domain:ID:dom-1.rwhois.net
S domain:Auth-Area:rwhois.net
S domain:Class-Name:domain
S domain:Updated:19970107201111000
S domain:Domain:rwhois.net
S domain:Server;I:hst-1.rwhois.net
S domain:Server;I:hst-2.rwhois.net
S
S %ok
# The server closes the connection.

next, the link and punt referrals 🦋:

# The client connects to the server.
# The server returns a banner identifying its protocol versions and
# capabilities.
S %rwhois V-1.5:00ffff:00 master.rwhois.net (Network Solutions V-1.5)
# The client sends a directive to hold the connection until it sends
# a directive to close the connection.
C -holdconnect on
# The server returns a successful response.
S %ok
# The client sends a query to search for a.b.rwhois.net domain.
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
# The client sends a query to search for internic.net domain.
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
# The client sends a directive to close the connection.
C -quit
S %ok
# The server closes the connection.

and last, a query error 😬:

# The client connects to the server.
# The server returns a banner identifying its protocol versions and
# capabilities.
S %rwhois V-1.5:00ffff:00 master.rwhois.net (Network Solutions V-1.5)
# The client sends a query to search for c.rwhois.net domain.
C domain c.rwhois.net
# The server returns an error, since neither data nor referrals for
# c.rwhois.net domain are found within the rwhois.net authority area.
S %error 230 No objects found
# The server closes the connection.

3.1.8 Notation

the sections that follow use Augmented Backus-Naur Form (ABNF) notation to describe the syntax of the protocol 🧩. for more on that, see Section 2 of [RFC822] 📚. the notation in the examples uses a prefix to indicate from where the info comes. a "C" means the client sends the data to the server, and an "S" means the server sends the data to the client. a "#" makes the line a comment. the space after the prefix is not part of the data 💅.

3.1.9 General ABNF definitions ✨

okay so this is the grammar toolbox 🧰 every other rule in the spec is built out of these pieces, so it's giving foundation. bestie, look at the lexical tokens first 💅

Lexical Tokens

alpha = "a".."z" / "A".."Z"
digit = "0".."9"
hex-digit = digit / "a".."f" / "A".. "F"
id-char = alpha / digit / "_" / "-"
any-char = <ASCII 1..255,
           except LF (linefeed) and CR (carriage return)>

dns-char = alpha / digit / "-"
email-char = <see [RFC 822]>
space = " "
tab = <ASCII TAB (tab)>
lf = <ASCII LF (linefeed)>
cr = <ASCII CR (carriage return)>
crlf = cr lf

Grammar

year = 4digit
month = 2digit
day = 2digit
hour = 2digit
minute = 2digit
second = 2digit
milli-second = 3digit
host-name = dns-char *(dns-char / ".")
ip-address = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
email = 1*email-char "@" host-name
authority-area = (dns-char / ".") *(dns-char / "." / "/")
object-id = 1*id-char "." authority-area
host-port = (host-name / ip-address) ":" 1*5digit
class-name = 1*id-char
attribute-name = 1*id-char
attribute-value = 1*any-char
time-stamp = year month day hour minute second milli-second
on-off = "on" / "off"

ngl the time stamps are very picky 🕰️ the spec says the time-stamp must be in the Greenwich Mean Time (GMT) time zone. and since any-char is 1..255 ASCII, RWhois is an 8 bit protocol 🤯 that's the whole vibe.

Response

The general response for every directive and query is either %ok or %error. a %info response may also be sent, so there are three flavours total 🦋

response = ok-response crlf / error-response crlf / info-response
ok-response = "%ok"
error-response = "%error" space error-code space error-text
error-code = 3digit
error-text = 1*any-char
info-response = "%info" space "on" crlf *(*any-char crlf) "%info"
        space "off" crlf

Banner

okay this part is so important 🎀 the server must send a banner to the client when the connection is opened. the banner holds the version(s) of the protocol the server supports, plus a capability ID made of encoded bit flags that shows which directives are implemented. if the server supports more than one version, the lowest-numbered version must be listed first. the bits in extra-id are reserved for future use. at the end of the banner there should be a free-form string with the name of the server implementation. a server must support at least one version of the protocol, and may accept more versions for compatibility reasons 💜

rwhois-banner = "%rwhois" space version-list space host-name
      [space implementation] crlf
version-list = version *("," version)
version = version-number [":" capability-id]
        / "V-1.5" ":" capability-id
version-number = "V-" 1*digit "." 1*digit
capability-id = response-id ":" extra-id
response-id = 6hex-digit
extra-id = 2hex-digit
implementation = 1*any-char

Protocol

the whole RWhois protocol is basically a series of directives, responses, queries, and results. it's giving conversation 🫶

rwhois-protocol = client-sends / server-returns
client-sends = *(directives / rwhois-query)
server-returns = *(responses / rwhois-query-result)

3.2 Required Directives 👑

the server must implement the following directives. no skipping these, periodt 💅

3.2.1 rwhois 🌸

Description

okay so the -rwhois directive may be issued by the client at the start of every session 🎀 it tells the server which version of the protocol the client can handle. the server must respond with a banner containing the protocol version and the directives it implements. this banner is the same one sent when the connection is opened, except the server must indicate only one version number. the banner issued when opening a connection may contain more than one version number. the directive flags get encoded into three octets, which are described in Appendix D 🧚

ABNF

rwhois-dir = "-rwhois" space version-number [space implementation]
             crlf
rwhois-response = "%rwhois" space version space host-name
        [space implementation] crlf

Errors

300 Not compatible with version
338 Invalid directive syntax

Examples

# When a connection is opened, the server issues the banner.
S %rwhois V-1.0,V-1.5:00ffff:00 rs.internic.net (NSI Server 1.5.4)
# The client sends the rwhois directive.
C -rwhois V-1.5 NSI Client 1.2.3
S %rwhois V-1.5:00ffff:00 rs.internic.net (NSI Server 1.5.4)
S %ok

3.3 Optional Directives 🦄

the server should implement the following directives. these are the nice-to-haves that make the server feel extra ✨

3.3.1 class 🍓

Description

the -class directive lets the client grab the meta-information for one or more classes in an authority area 💖 the response must contain the description and version number of each specified class, and it may be expanded later with more attributes. when no class name is given, the server must return the meta-information for every class in the authority area. every class record must end with an empty %class line.

ABNF

class-dir = "-class" space authority-area *(space class-name) crlf
class-response = *class-record response
class-record = *class-line "%class" crlf
class-line = "%class" space class-name ":" "description" ":"
             1*any-char crlf
   / "%class" space class-name ":" "version" ":" time-stamp crlf
   / "%class" space class-name ":" meta-field ":" meta-value crlf
meta-field = 1*id-char
meta-value = 1*any-char

the following fields are required 🫶

 meta-field   meta-value  Description

 description  1*any-char  Class description.
                        Time/date stamp indicating version of class,

 version      time-stamp  must be updated after class definition is
                          changed.

Errors

338 Invalid directive syntax
340 Invalid authority area
341 Invalid class
400 Directive not available
401 Not authorized for directive

Examples

C -class rwhois.net domain host
S %class domain:description:Domain information
S %class domain:version:19970103101232000
S %class
S %class host:description:Host information
S %class host:version:19970214213241000
S %class
S %ok

3.3.2 directive 🔥

Description

the -directive directive lets the client find out what directives the server supports 👀 the response must contain the name and description of each specified directive, and it may be expanded later with more attributes. when no directive name is given, the server must return info about all the directives. every directive record must end with an empty %directive line.

ABNF

directive-dir = "-directive" *(space directive-name) crlf
directive-name = 1*id-char
directive-response = *directive-record response
directive-record = "%directive" space "directive" ":" directive-name
                   crlf *directive-line "%directive" crlf
directive-line = "%directive" space "description" ":" 1*any-char crlf
        / "%directive" space attribute-name ":" attribute-value crlf

Errors

338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive

Examples

Without parameters:

C -directive
S %directive directive:rwhois
S %directive description:RWhois directive
S %directive
S %directive directive:quit
S %directive description:Quit connection
S %directive
S %ok

With parameters:

C -directive quit
S %directive directive:quit
S %directive description:Quit connection
S %directive
S %ok

3.3.3 display 💅

Description

by default, the server uses the dump format for the output of a query result 📦 you can change the output format with the -display directive. when no parameter is given, the server must list all the display formats it supports. every display record must end with an empty %display line.

currently, only the dump format is standard, and the server must support it. other output formats may be added later. check Section 3.4 for the definition of the dump format 🌈

ABNF

display-dir = "-display" crlf
    / "-display" space display-name crlf
display-name = 1*id-char
display-response = *(display-record) response
display-record = "%display" space "name" ":" display-name crlf
*display-line "%display" crlf
display-line = "%display" space attribute-name ":"
               attribute-value crlf

Errors

338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive
436 Invalid display format

Examples

# Get the available display formats.
C -display
S %display name:dump
S %display
S %ok
# Change the active display format.
C -display dump
S %ok

3.3.4 forward 🦋

Description

the -forward directive tells the server to follow all the referrals and return the results to the client ✈️ this can be used to run an RWhois server as a proxy server. the default value must be off. when the value is set to on, the server must not return referrals.

ABNF

forward-dir = "-forward" space on-off crlf
forward-response = response

Errors

338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive

Examples

C -forward on
S %ok

C -forward off
S %ok

3.3.5 holdconnect 🧸

Description

normally, the server closes the connection after each query 🚪 this is controlled by the holdconnect state, which you can change with the -holdconnect directive. when the holdconnect state is set to off, the server must close the connection after a query. when it is set to on, the server must not close the connection after a query. by default, the holdconnect state must be set to off for each connection.

ABNF

holdconnect-dir = "-holdconnect" space on-off crlf
holdconnect-response = response

Errors

338 Invalid directive syntax
400 Directive not available
401 Not authorized for directive

Examples

C -holdconnect on
S %ok

C -holdconnect off
S %ok

3.3.6 limit 🌷

Description

when returning a query result, the server should limit the number of objects it sends back to the client 🔢 the -limit directive changes this limit. the default and maximum limit depend on the server. the client can check the current limit with the -status directive (see 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

okay so the -notify directive is literally doing four different jobs, and I'm obsessed 💅

if the server hands back a referral that errors out, the client can tell the server about the bad referral with the badref option 🙈
when the client follows referrals and hits the same referral twice, that's a recursive referral and it causes a referral loop 🌀 the client can report it to the server with 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 lets an RWhois server register itself as a slave server for an authority area with a master server. the master server may reject the request based on its registration policy 🙅‍♀️
the delsec option lets a slave server 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 is the client's way of closing the connection 🫶 but the server has to reply with %ok before it closes anything. no ghosting allowed 😭

ABNF

quit-dir = "-quit" crlf
quit-response = response

Errors

No errors. 🌸

Examples

C -quit
S %ok

3.3.9 register 🗂️

Description

the -register directive is how the client adds, modifies, or deletes objects in the server's database 💖 the client must wait for the %ok response before it sends any registration data. patience is a whole vibe 🧘‍♀️ this directive has these options:

the add option says the object being sent should be added to the server's database ✨
the mod option says the object being sent is a modification of an object already on the server's database. during a modify, the _NEW_ tag marks where the original (unmodified) object ends and the replacement object begins. so the identifying characteristics of the original go first, then the _NEW_ separator, then the entire replacement object 🪄
the del option says 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 matters for data replication because a slave server checks Serial-Number 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

Rules and details

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, who sent the registration information. the server should not use it to authenticate the sender 🙅‍♀️ (it's not an ID card, bestie)
for the add option, the client must send all the required attributes for the object, including the Class-Name and Auth-Area attributes. BUT the client must not send the ID and Updated attributes, because the server assigns those and sends them back in the response 🆔
for the mod option, the client must send the identifying information for the object to be modified, then the _NEW_ separator, then 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 goes first so the server can lock the record in the database 🔒
for the del option, the client must send the identifying information for the object to be deleted. that 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 lets the client grab the attribute definitions of one or more classes in an authority area 📚 if the client names specific classes, the server must return the attribute definitions for those classes. if not, the server must return the attribute definitions for every class in the authority area. every schema record must end with an empty %schema line, so keep an eye out for that ✨

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 💌

Okay bestie, -security is the directive that lets a client request or a server response get authenticated and/or encrypted 🔒✨ Right now RWhois has two standard security methods: password and PGP. Password is authentication only, but PGP does both authentication AND encryption 💅 This directive is how you securely access or update any information (meta or data) in an authority area that's 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 only available in the "request" direction. For password, the security-data is a cleartext password 🙈
The "pgp" security-method works in both the "request" and "response" directions. For PGP, the security-data tells you 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 to encrypt it with 🔑

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 lets the client grab the SOA information for one or more authority areas 💖 If 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 lets the client check various status flags on 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 is how the client (usually a slave server) transfers the data in an authority area 🍓 The client can control how much data comes across using one of these options:

serial-number: The client can transfer all the objects that have been added, modified or deleted since a certain time, by specifying the serial-number that marks 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 together 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 for adding an extra, non-standard directive 🧚 It can be implemented by running an external program, by internal functions, or by other means. It may interact with the client or simply produce output, just 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 runs an external program, the UNIX "date" command. The server runs the "date" command and sends its output back to the client 🕰️

C -X-date
S Mon Jan 6 13:21:20 EST 1997
S %ok

3.4 Query ✨

Okay so, the query is how a client digs up objects from the server's database. 🔍 The server must support these kinds of queries:

Unrestricted query: a single word or a quoted string. The server must return every matching object where one or more attributes match the query, no matter the class. 💖
Class-restricted query: a class name written in front of the unrestricted query. The server must return every matching object where one or more attributes of that specific class match. 🎀
Attribute-restricted query: looks like "<attribute-name>=<search-string>". The server must return every matching object where the specified attribute matches the query. ✨

The server may also implement these, which are giving extra main character energy 💅:

Boolean operator query: simpler queries stitched together with the "and" and "or" operators. 🔥
Wild card query: an asterisk (*) at the front and/or end of the search string. The server may support partial matching with the asterisk. 🌸

So when the server answers, it hands back the objects that match. If the server doesn't do complex queries (like wild cards or boolean operators), it may return the 351 Query too complex error. 💀 And when the number of objects found goes over the limit set by the -limit directive, the server should return the objects first, and then the 330 Exceeded maximum objects limit error. 🙈

The default output format is the dump format, which looks like <class-name>:<attribute-name>;<type character>:<attribute-value>. The type character is optional, and it tells you what type the attribute value is. It's a shorthand for the Type field of the attribute definition (see Section 2.3.1). These are the type characters:

Type          Attribute
character     Type

T             TEXT

I             ID

S             SEE-ALSO

When there's no type character, the client should assume "T". The server must provide the type character when the attribute type is ID or SEE-ALSO. The whole point is to help the client display the data nicely. For example, if a value is an ID, the client may tell the end-user that they can go fetch the object that ID points to. 🧚

The server may return one or more referrals in the form %referral rwhois://<host-name>:<port-number>/auth-area=<authority area>. The client can tell referrals apart by comparing their authority areas. If they all point to the same authority area, the client should follow just 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 send 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 one shows a query where nothing is found, so sad 🥺:

C vogon
S %error 230 No objects found

This one shows a query where two different objects come back:

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 one has a class restrictor, and the number of objects found goes over the limit set by the -limit directive, so the server throws the 330 error at the end:

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 attribute matching in action 🫶:

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 is 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 is 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

Multiple referrals pointing at 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

Multiple referrals pointing at 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

And last but not least, boolean operators plus wildcard matching, which is literally iconic 🍓:

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 gives you a reliable stream transport between a client and a server. In RWhois, TCP is the default transport protocol, because during one session a client can send more than one query, and the server can reliably send back a big amount of data for each one. 💅 By default, a TCP RWhois server should run on the standard, Internet Assigned Number Authority (IANA)-assigned port 4321. However, if port 4321 isn't available, it may run on an available port in the non-reserved range (1024 - 65535).

3.5.2 User Datagram Protocol (UDP) 🌸

UDP gives you an unreliable connectionless transport between a client and a server. In RWhois, UDP may be used as the transport protocol if a client only wants to quickly send one query, without the overhead of setting up 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 isn't 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 is about when and how a slave server should replicate data. It also covers the server registration and location mechanisms. 🧚

3.6.1 When to Replicate Data 💜

The time a slave server may replicate data for an authority area is determined by the SOA variables for that authority area. Here are the possible times:

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 changes and its "Serial-Number" gets updated, a master server may notify its slave servers to update the data immediately. 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 ✨

okay so bestie, to replicate data a slave server sends a series of directives to its master server 📨 and checks each response before it sends the next one 🧐. the next sections cover the protocols for complete and incremental replication 💖

Complete Replication

this is the protocol between a master server and a slave server for fully replicating data for an authority area 🌸

The slave server should connect to the master server. If there is a connection error, the slave server should log an error and exit.
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.
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.
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 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.
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.
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.
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 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.
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 👀

Here's an example 🧚 where a slave server completely replicates data for all the classes in an authority area. The notation uses a prefix to show where the info is coming from. An M means the master server sends the data to the slave server. An S means the slave server sends the data to the master server. A 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

this is the protocol for incrementally replicating data for an authority area, so only the changes get sent 🦋

The slave server should connect to the master server. If there is a connection error, the slave server should log an error and exit.
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.
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.
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 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.
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.
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.
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.
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.
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 👀

Here's the example where a slave server incrementally replicates data for all the classes in an authority area. Same notation as before: an M is the master sending data to the slave, an S is the slave sending data to the master, # starts a comment, and the space after the prefix isn't 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 is about 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

Okay bestie, so before an RWhois client can resolve a query in an authority area, it may need to find the master and slave servers for that area first 🔍✨. There are a few different server location mechanisms, and they go like this 🦋

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 get routed up or down the RWhois tree before it gets 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 get a list of servers serving that authority area 📋.

Next, the client should send the -soa <authority-area> directive to one of the servers from that list and parse the Primary-Server variable from the response 💅. The value of that variable is the master server 👑. The remaining servers in the list are the slave servers 🧚.

SRV RRs

The Server Resource Record (SRV RR) is defined for DNS, and it 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 [RFC 2052] like this:

Service.Proto.Name TTL Class SRV Priority Weight Port Target

An authority area identifier is generally a domain name or an IP address, so 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.

Here, 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 ✨

Security is a whole vibe in RWhois 🔐. It 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 means 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 talk about how to securely update and access the data in an authority area 💅.

4.1. Data Update

This is about being able to securely add, modify, or delete some information (meta or data) in an authority area 🎀. An authority area, as a 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 🔒. 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 being able 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 🤝. The master server may also encrypt the transferred data 🔐.

The second issue is being able 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.
[RFC 821] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, ISI, August 1982.
[RFC 822] Crocker, D, "Standards for the Format of ARPA Internet Text Messages", STD 11, RFC 822, University of Delaware, August 1982.
[RFC 954] Harrenstien, K., Stahl, M., Feinler, E., "NICNAME/WHOIS", RFC 954, SRI, October 1985.
[RFC 1034] Mockapetris, P. V., "Domain names - concepts and facilities", STD 13, RFC 1034, November 1987.
[RFC 1714] Williamson, S., Kosters, M., "Referral Whois Protocol", RFC 1714, Network Solutions, November 1994.
[RFC 1738] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994.
[RFC 1991] Atkins, D., W. Stallings, P. Zimmermann, "PGP Message Exchange Formats", RFC 1991, MIT, Comp-Comm Consulting, Boulder Software Engineering, August 1996.
[RFC 2052] Gulbrandsen, A., P. Vixie, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2052, Troll Technologies, Vixie Enterprises, October 1996.
[X.500] "The Directory: Overview of Concepts, Models and Service", CCITT Recommendation X.500, 1988.

Authors' Addresses 🦋

Scott Williamson (scottw@rwhois.net)
Mark Kosters (markk@internic.net)
David Blacka (davidb@rwhois.net)
Jasdip Singh (jasdips@rwhois.net)
Koert Zeilstra (kzeil@rwhois.net)

Postal Address:

505 Huntmar Park Drive
Herndon, VA 22070-5100
Telephone: 703-742-0400

Appendix A: Glossary Of Terms 📖

ABNF: Augmented Backus-Naur Form. Refined version of BNF, defined in [RFC 822]. See BNF.
Attribute: A named field and the smallest typed unit in a database schema. See Database Schema.
Authority Area: An autonomous part of an RWhois tree. It is associated and named after a particular piece of a hierarchy and is able to state authoritatively whether or not an instance of hierarchical data is present within the RWhois tree. See RWhois Tree.
Banner: A line sent by a server indicating which protocol versions it supports and which directives are implemented. This line is issued by the server after a connection is opened and as a response to the "-rwhois" directive. See Directive and Response.
Base Class: A class from which all defined classes in a database schema inherit attributes. See Attribute, Class, and Database Schema.
BNF: Backus-Naur Form. Language to precisely define the syntax of protocols and computer languages.
Class: A collection of attributes. See Attribute.
Complete Replication: The process of replicating all of the data for an authority area. See Replication.
Database Schema: A collection of all the classes forming an RWhois database. See Class.
Directive: A command that a client sends to a server to set a control parameter for the session, get the meta-information (class definitions and SOA information) about an authority area, or get the data in an authority area. See Class and SOA.
Guardian Class: A standard class that contains security information. An object is guarded by containing a pointer to a guardian object. See Class and Object.
Incremental Replication: The process of replicating the data that has changed since the last replication for an authority area. See Replication.
Info: The miscellaneous information that a server sends to a client.
Lexically Hierarchical Label: A text string whose position in a hierarchy is encoded in the string itself.
Link Referral: A pointer to another server that is further down an RWhois tree. It is used to route a query down the tree. See Referral and RWhois Tree.
Master Server: A server where the data is registered for an authority area. It answers authoritatively to queries in the authority area. It is also called a primary server. See Authority Area.
Namespace: A particular naming system defined by a set of rules describing the format of a name. Alternately, all of the names satisfying the rules.
Object: An instance of a class. It is data with a type of <class>. See Class.
PGP: Pretty Good Privacy. An authentication and encryption scheme.
Primary Server: See Master Server.
Punt Referral: A pointer to another server that is further up an RWhois tree. It is used to route a query up the tree. See Referral and RWhois Tree.
Query: A command that a client sends to a server to access the data in an authority area.
Query Routing: Redirecting a query to another server for resolution. See Query.
Referral: A pointer to another server that is presumed to be closer to the desired data. It is used to route a query. See Query Routing.
Referral Class: A standard class that contains referral information for an authority area. See Class and Referral.
Replication: A server duplicating data from another server on a per-authority area basis. See Authority Area.
Response: The information that a server returns to a client for a directive. See Directive.
Result: The information that a server returns to a client for a query. It can be either the accessed data or referrals to other servers. See Query and Referral.
RWhois Tree: A data information tree of RWhois servers where the data is arranged hierarchically in the authority areas. See Authority Area.
Schema: See Class.
Secondary Server: See Slave Server.
Slave Server: A server where the data is replicated from the master server for an authority area. It also answers authoritatively to queries in the authority area. It is also called a secondary server. See Master Server.
SOA: Start Of Authority. Administrative variables, defined at the master server, to control replication for an authority area. See Master Server and Replication.

Appendix B: RWhois ABNF ✨

Okay bestie, this appendix is the grammar cheat sheet for RWhois 💅 It's written in ABNF, which is the notation from Section 2 of [RFC 822], so every rule below is a little recipe for what a valid message looks like 🧚

General Definitions

Let's start with the building blocks 🍓

Lexical Tokens

alpha = "a".."z" / "A".."Z"
digit = "0".."9"
hex-digit = digit / "a".."f" / "A".. "F"
id-char = alpha / digit / "_" / "-"
any-char = <ASCII 1..255,
           except LF (linefeed) and CR (carriage return)>
dns-char = alpha / digit / "-"
email-char = <see [RFC 822]>
space = " "
tab = <ASCII TAB (tab)>
lf = <ASCII LF (linefeed)>
cr = <ASCII CR (carriage return)>
crlf = cr lf

Grammar

Here's where the real rules live, and they're giving structure 🎀

year = 4digit
month = 2digit
day = 2digit
hour = 2digit
minute = 2digit
second = 2digit
milli-second = 3digit
host-name = dns-char *(dns-char / ".")
email = 1*email-char "@" host-name
authority-area = (dns-char / ".") *(dns-char / "." / "/")
object-id = 1*id-char "." authority-area
host-port = (host-name / ip-address) ":" 1*5digit
ip-address = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
class-name = 1*id-char
attribute-name = 1*id-char
attribute-value = 1*any-char
time-stamp = year month day hour minute second milli-second
on-off = "on" / "off"

Quick heads up 🕰️ the time-stamp has to be in Greenwich Mean Time (GMT), so no local time zones allowed!

response = ok-response crlf / error-response crlf / info-response
ok-response = "%ok"
error-response = "%error" space error-code space error-text
error-code = 3digit
error-text = 1*any-char
info-response = "%info" space "on" crlf *(*any-char crlf) "%info"
        space "off" crlf

rwhois-banner = "%rwhois" space version-list space host-name
        [space implementation] crlf
version-list = version *("," version)
version = version-number [":" capability-id]
        / "V-1.5" ":" capability-id
version-number = "V-" 1*digit "." 1*digit
capability-id = response-id ":" extra-id
response-id = 6hex-digit
extra-id = 2hex-digit
implementation = 1*any-char

rwhois-protocol = client-sends / server-returns
client-sends = *(directives / rwhois-query)
server-returns = *(responses / rwhois-query-result)

directives = rwhois-dir / class-dir / directive-dir / display-dir /
        holdconnect-dir / limit-dir / notify-dir / quit-dir /
        register-dir / schema-dir / security-dir / soa-dir /
        status-dir / xfer-dir / x-dir

responses = rwhois-response / class-response/ directive-response/
        display-response/ holdconnect-response/ limit-response/
        notify-response/ quit-response/ register-response/
        schema-response / security-response/ soa-response/
        status-response/ xfer-response/ x-response

Required Directives

These are the must-have ones, the core of the whole protocol 👑

rwhois

rwhois-dir = "-rwhois" space version-number [space implementation]
             crlf
rwhois-response = "%rwhois" space version space host-name
        [space implementation] crlf

Optional Directives

These ones are extras, bestie, but they're iconic 🦋

class

class-dir = "-class" space authority-area *(space class-name) crlf
class-response = *class-record response
class-record = *class-line "%class" crlf
class-line = "%class" space class-name ":" "description" ":"
             1*any-char crlf
   / "%class" space class-name ":" "version" ":" time-stamp crlf
   / "%class" space class-name ":" meta-field ":" meta-value crlf
meta-field = 1*id-char
meta-value = 1*any-char

directive

directive-dir = "-directive" *(space directive-name)crlf
directive-name = 1*id-char
directive-response = *directive-record response
directive-record = "%directive" space "directive" ":"
        directive-name crlf *directive-line "%directive" crlf
directive-line = "%directive" space "description" ":" 1*any-char crlf
        / "%directive" space attribute-name ":" attribute-value crlf

display

display-dir = "-display" crlf
   / "-display" space display-name crlf
display-name = 1*id-char
display-response = *display-record response
display-record = "%display" space "name" ":" display-name crlf
*display-line "%display" crlf
display-line = "%display" space attribute-name ":" attribute-value
               crlf

holdconnect

holdconnect-dir = "-holdconnect" space on-off crlf
holdconnect-response = response

limit

limit-dir = "-limit" space 1*digit crlf
limit-response = response

notify

notify-dir = "-notify" space "badref" space referral-query crlf
        / "-notify" space "recurref" space referral-query crlf
        / "-notify" space "update" space host-port ":" authority-area
          crlf
        / "-notify" space "inssec" space host-port ":" authority-area
          crlf
        / "-notify" space "delsec" space host-port ":" authority-area
          crlf
referral-query = referral-url space [class-name space] query
notify-response = response

Peek at the query section 👀 that's where you'll find the definitions of referral-url and query.

quit

quit-dir = "-quit" crlf
quit-response = response

register

register-dir = register-on space "add" space maintainer-id crlf
        register-add register-off
        / register-on space "mod" space maintainer-id crlf
               register-mod register-off
        / register-on space "del" space maintainer-id crlf
               register-del register-off
register-on = "-register" space "on"
register-off = "-register" space "off" crlf
register-add = 1*(register-line crlf)
register-mod = 1*(register-line crlf) "_NEW_" crlf
               1*(register-line crlf)
register-del = 1*(register-line crlf)
maintainer-id = email
register-line = attribute-name ":" attribute-value
register-on-response = response
register-off-response = "%register" space "ID" ":" object-id crlf
                        response
        / "%register" space "Updated" ":" time-stamp crlf response
        / response

schema

schema-dir = "-schema" space authority-area *(space class-name) crlf
schema-response = *schema-record response
schema-record = *schema-line "%schema" crlf
schema-line = "%schema" space class-name ":" attribute-name ":"
        attribute-value crlf

security

security-dir = "-security" space "on" space direction space
        security-method [space security-data] crlf security-payload
        ["-security" space "off" crlf]
direction = "request" / "response"
security-method = "password" / "pgp" / 1*id-char
security-data = password-data / pgp-data / 1*any-char
password-data = 1*any-char
pgp-data = "signed" / "encrypt" [space key-id] / "signed-encrypt"
           [space key-id]
security-payload = *(*any-char crlf)
security-response = response

soa

soa-dir = "-soa" *(space authority-area) crlf
soa-response = *soa-record response
soa-record = *soa-line "%soa" crlf
soa-line = "%soa" space "authority" ":" authority-area crlf
   / "%soa" space "ttl" ":" 1*digit crlf
   / "%soa" space "serial" ":" time-stamp crlf
   / "%soa" space "refresh" ":" 1*digit crlf
   / "%soa" space "increment" ":" 1*digit crlf
   / "%soa" space "retry" ":" 1*digit crlf
   / "%soa" space "tech-contact" ":" email crlf
   / "%soa" space "admin-contact" ":" email crlf
   / "%soa" space "hostmaster" ":" email crlf
   / "%soa" space "primary" ":" host-port crlf
   / "%soa" space attribute-name ":" attribute-value crlf

status

status-dir = "-status" crlf
status-response = *status-line response
status-line = "%status" space "limit" ":" 1*digit crlf
   / "%status" space "holdconnect" ":" on-off crlf
   / "%status" space "forward" ":" on-off crlf
   / "%status" space "authority" ":" 1*digit crlf
   / "%status" space "display" ":" 1*any-char crlf
   / "%status" space "contact" ":" email crlf
   / "%status" space attribute-name ":" attribute-value crlf

xfer

xfer-dir = "-xfer" space authority-area *attribute-def
        [space serial-number] crlf
attribute-def = [space "class=" class-name]
                *(space "attribute=" attribute-name)
serial-number = time-stamp
xfer-response = *xfer-record response
xfer-record = *xfer-line "%xfer" crlf
xfer-line = "%xfer" space class-name ":" attribute-name ":"
            attribute-value crlf

X

x-dir = "-X-" x-directive [space *[x-arguments]] crlf
x-directive = 1*id-char
x-arguments = *any-char
x-response = *(*any-char crlf) response

Query

Almost there, bestie! 💜 This is the part where you actually ask the questions 🔥

rwhois-query = [class-name space] query crlf
query = query-string / attribute-query / query bin-boolean query
query-char = <any-char, except """, space, tab>
quoted-query-char = query-char / space / tab / "
query-string = 1*query-char ["*"] / """ 1*quoted-query-char ["*"] """
attribute-query = attribute-name "=" query-string
bin-boolean = "and" / "or"

rwhois-query-result = *(query-record / referral-record) response
query-record = 1*query-line crlf
query-line = class-name ":" attribute-name [";" type-char] ":"
        attribute-value crlf
type-char = "T" / "I" / "S"
referral-record = 1*(referral-line crlf)
referral-line = "%referral" space referral-url
referral-url = "rwhois" ":" "//" host-port "/" "auth-area="
               authority-area

Appendix C: Error Codes ✨

okay so when a server flops on a command (a directive or a query) 💀, it sends back an error response. here's the ABNF for it, bestie 🫶

error-response = "%error" space error-code space error-text
error-code = 3digit
error-text = 1*any-char

the error text is allowed to get a makeover 💅, but its meaning must remain the same. the server can also tack extra info onto it, like %error 333 Not master for authority area: foobar.com 🍓

the digit in each position of the error code is basically a vibe check 🔍:

 XXX    Description
 1XX    Information only, no action required
 2XX    Information, action required
 3XX    Specific command error, retry that command or try another one
 4XX    Serious for current command, may correct with another command
 5XX    Fatal, must disconnect
 X0X    System wide, no specific command
 X1X    System wide, no specific command
 X2X    Registration error
 X3X    Specific command
 X4X    Specific command
 X5X    Specific command
 X6X    Extended message (version specific)
 XXX    Sequential order

here's the full ordered list of RWhois error codes 📋. implementations can add their own codes too, but an implementation-specific code must have a "6" in the second position 🎀

 Code    Text
 120     Registration deferred
 130     Object not authoritative
 230     No objects found
 300     Not compatible with version
 320     Invalid attribute
 321     Invalid attribute syntax
 322     Required attribute missing
 323     Object reference not found
 324     Primary key not unique
 325     Failed to update outdated object
 330     Exceeded maximum objects limit
 331     Invalid limit
 332     Nothing to transfer
 333     Not master for authority area
 336     Object not found
 338     Invalid directive syntax
 340     Invalid authority area
 341     Invalid class
 342     Invalid host/port
 350     Invalid query syntax
 351     Query too complex
 352     Invalid security method
 353     Authentication failed
 354     Encryption failed
 400     Directive not available
 401     Not authorized for directive
 402     Unidentified error
 420     Registration not authorized
 436     Invalid display format
 500     Memory allocation problem
 501     Service not available
 502     Unrecoverable error
 503     Idle time exceeded

these codes are now obsolete, so retire them with honor 🪦 ⚰️: 100, 200, 231, 334, 335, 337, 421, 431, 432, 433, 434, 460, 461, and 530. they were defined in [RFC 1714] 🦋

Appendix D: Capability ID 🌸

the capability ID is how a server brags about which directives it can actually do 💅. to make one, you logical OR together all the hexadecimal numbers for the directives you've implemented 🧚. the result goes into the banner, which the server sends right after a connection opens, and it also goes out as the reply to the "-rwhois" directive 📣. heads up: the eight most significant bits of the capability ID are reserved for future use 🔮

 class        000001h
 directive    000002h
 display      000004h
 forward      000008h
 holdconnect  000010h
 limit        000020h
 notify       000040h
 quit         000080h
 register     000100h
 schema       000200h
 security     000400h
 soa          000800h
 status       001000h
 xfer         002000h
 X            004000h

Appendix E: Schema Definitions 🎀

Attribute Definition Model

the attribute definition model is the blueprint for each attribute 📐. here's the whole table, exactly as it is:

 Name         Type  Description

 Attribute    N     This is the name of the attribute.

 Description  S     This is a free-form description of the attribute.

 Type         T     This is a parameter that broadly indicates the use
                    of the attribute to the protocol. There are three
                    standard types: TEXT, ID, and SEE-ALSO. The default
                    is TEXT, which indicates that the value is a text
                    string.  ID indicates that the attribute contains
                    the ID of another RWhois object. This type of
                    attribute is used for database normalization. SEE-
                    ALSO indicates that the attribute contains a pointer
                    (a Uniform Resource Identifier (URI)) to some other
                    kind of external data; for example, a World Wide Web
                    page or FTP site.

 Format       S     This is an interpretable string that describes the
                    acceptance format of the value. The server (and
                    optionally the client) should match the value to the
                    format string to determine if the value is
                    acceptable.  The format of this property is a
                    keyword indicating the syntax of the format string,
                    followed by a colon, followed by the format string
                    itself. Currently, the only keyword recognized is
                    "re" for POSIX.2 extended regular expressions.

 Indexed      B     This is a true or false flag that indicates that
                    this attribute should be indexed (and therefore able
                    to be searched).

 Required     B     This is a true or false flag that indicates that
                    this attribute must have a value.

 Multi-Line   B     This is a true or false flag that indicates that
                    this attribute may have multiple instances in an
                    object; all the instances are to be considered as
                    multiple lines of the same attribute instance.

 Repeatable   B     This is a true or false flag that indicates that
                    there may be multiple instances of this attribute in
                    a class and each instance is to be interpreted as a
                    separate instance (in contrast to Multi-Line). This
                    flag is mutually exclusive with Multi-Line: if
                    Multi-Line is true, then Repeatable must be false
                    and vice versa.

 Primary      B     This is a true or false flag that indicates that
                    this attribute is a primary key. If more than one
                    attribute in a class is marked as primary, then
                    these attributes together form a single primary key.
                    The primary key is intended to be used to force
                    uniqueness among class instances. Therefore, there
                    can be only one instance of a primary key in a
                    database. The Primary flag implies that the
                    attribute is also required.

 Hierarchical B     This is a true or false flag that indicates that
                    this attribute is lexically hierarchical.

 Private      B     This is a true or false flag that indicates whether
                    or not this attribute is private (that is, publicly
                    not viewable). It defaults to false. If it is true,
                    then only the clients that satisfy the
                    authentication/encryption requirements of a guardian
                    are able to view the attribute-value pair.

the type column has its own rules 🧐, defined like this:

 Type  ABNF Definition

  B     "ON" / "OFF"
  N     1*id-char
  S     1*any-char
  T     "ID" / "SEE-ALSO" / "TEXT"

Base Class

every object gets these base attributes 🍰, and here's the table as written:

 Name       Type   Required  RepeatableDescription

 Class-Name TEXT   Y         N         This attribute is the name of the
                                       class to which the object
                                       belongs.

 Auth-Area  TEXT   Y         N         This attribute is the name of the
                                       authority area to which the
                                       object belongs.

 ID         TEXT   Y         N         This attribute is the universal
                                       identifier of the object.

 Updated    TEXT   Y         N         This attribute is a time/date
                                       stamp that indicates the time of
                                       last modification of the object.

 Guardian   ID     N         Y         This attribute is a link to a
                                       guardian object. Its value is the
                                       ID of a guardian object.

 Private    TEXT   N         N         This attribute is a true or false
                                       flag that indicates whether or
                                       not an object is private (that
                                       is, publicly not viewable). It
                                       defaults to false. If it is
                                       true, then only the clients
                                       that satisfy the
                                       authentication/encryption
                                       requirements of one of the
                                       object's guardians are able to
                                       view the object. If the object
                                       is publicly viewable, then the
                                       Private attribute property of
                                       each of its attributes still
                                       applies.

 TTL        TEXT   N         N         This attribute is the
                                       "time-to-live" of a given object.
                                       It is included only if an object
                                       has a different time-to-live than
                                       the default given in the Start of
                                       Authority information. Its value
                                       is specified in seconds.

Appendix F: Changes RWhois V1.0 - V1.5 📜

General

Multiple authority areas per server.
Data replication.
Revised schema model.
Revised query routing rules.
Revised error codes.
Removed unnecessary spaces in responses and results.

Directives

Class: New. Returns meta-information for a class.
Display: Can return supported display formats.
Load: Obsolete.
Notify: Syntax change.
Private: Obsolete.
Register: Syntax change.
Schema: Syntax change.
Security: Obsoletes Private.
Xfer: Syntax change.

Query

Display option removed.
Output format: Only the dump format is standard; optional type character added.
Attribute-restricted query.
Revised referral syntax.

📦 where this page comes from

ietf: rfc2167 1997-06
💖 girlified by claude-haiku-5-5 on 2026-10-17: a language model's rewrite of the original, under its terms