A SUMMARY format response consists of a single set of responses,
consisting of a line listing the number of matches to the specified
query, followed by a list of all template types which satisfied the
query at least once.
The START line shall begin with a '#' in the first column, be
followed by one white space character, the word "SUMMARY", a white
space character, the handle for the server, and a terminating
newline.
All following lines until the TERMINATION line starts with a leading
space. The first line shall begin with the string "matches: ", be
followed by a space and the number of responses to the query and
terminated by a newline. The second line shall begin with the string
"templates: ", be followed by a newline separated list of the name of
the template types which matched the query. Each line following the
first which include the text "templates:" must begin with a '-'
instead of a space.
2.4.3.5. SERVER-TO-ASK Response
A SERVER-TO-ASK response consists of information to the client about
a server to contact next to resolve a query. If the server has
pointers to more than one server, it will present additional SERVER-
TO-ASK responses.
The SERVER-TO-ASK response will consist of a START line and a number
of lines with attribute-value pairs, separated by CRLF. Each line is
indented with one space. The end of a SERVER-TO-ASK response is
indicated with a TERMINATION line.
Each START line consists of a '#' in the first column, followed by
one white space character, the word "SERVER-TO-ASK", a white space
character, the handle of the server and a terminating newline.
1. "Server-Handle" - The server handle of the server pointed at.
(req.)
2. "Host-Name" - A cached host named for the server pointed at. (opt.)
3. "Host-Port" - A cached port number for the server pointed at.
(opt.)
Other attributes may be present, depending on the index server.
2.4.4. System Generated Messages
All system generated messages must begin with a '%' as the first
character, a space as the second one, followed by a three digit
number, a space and an optional text message. The total length of the
line must be no more than 81 characters long, including the
terminating CR LF pair. There is no limit to the number of system
messages that may be generated.
The format for multiline replies requires that every line, except the
last, begin with "%", followed by space, the reply code, a hyphen,
and an optional text. The last line will begin with "%", followed by
space, the reply code, a space and some optional text.
System generated messages displayed before or after the formatted
response section are expected to refer to operation of the system or
refer to the entire query. System generated messages within the
output of an individual record during a FULL reponse are expected to
refer to that record only, and could (for example) be used to
indicate problems with that record of the response. See Appendix E
for a description of system messages.
2.5. Compatibility with Older WHOIS Servers
Note that this format, although potentially more verbose, is still in
a human readible form. Responses from older systems that do not
follow this format are still conformant, since their responses would
be interpreted as being equivalent to optional text messages, without
a formatted response. Clients written to this specification would
display the responses as a advisory text message, where it would
still be readible by the user.
3. Miscellaneous
3.1. Acknowledgements
The WHOIS++ effort began as an intensive brainstorming session at the
24th IETF, in Boston Massachusetts. Present at the birth, and
contributing ideas through this early phase, were (alphabetically)
Peter Deutsch, Alan Emtage, Jim Fullton, Joan Gargano, Brad
Passwaters, Simon Spero, and Chris Weider. Others who have since
helped shape this document with feedback and suggestions include
Roxana Bradescu, Patrik Faltstrom, Kevin Gamiel, Dan Kegel, Michael
Mealling, Mark Prior and Rickard Schoultz.
3.2 References
[ALVE95] Alvestrand H., "Tags for the Identification of
Languages", RFC1766, UNINETT, March 1995.
[HARR85] Harrenstein K., Stahl M., and E. Feinler,
"NICNAME/WHOIS", RFC954, SRI, October 1985.
[IIIR] Weider C., and P. Deutsch, "A Vision of an
Integrated Internet Information Service", RFC1727
Bunyip Information Systems, Inc., December 1994.
[POST82] Postel J., "Simple Mail Transfer Protocol", STD 10,
RFC821, USC/Information Sciences Institute,
August 1982.
3.3. Authors' Addresses
Peter Deutsch
BUNYIP INFORMATION SYSTEMS, Inc.
310 St-Catherine St West,
Suite 202,
Montreal, Quebec H2X 2A1
CANADA
EMail: peterd@bunyip.com
Rickard Schoultz
KTHNOC, SUNET/NORDUnet/Ebone Operations Centre
100 44 STOCKHOLM
SWEDEN
EMail: schoultz@sunet.se
Patrik Faltstrom
BUNYIP INFORMATION SYSTEMS, Inc.
310 St-Catherine St West,
Suite 202,
Montreal, Quebec H2X 2A1
CANADA
EMail: paf@bunyip.com
Chris Weider
BUNYIP INFORMATION SYSTEMS, Inc.
2001 S. Huron Parkway, #12
Ann Arbor, MI 48104
USA
EMail: clw@bunyip.com
Appendix A - Some Sample Queries
author=chris and template=user
The result will consist of all records where attribute "author"
matches "chris" with case ignored. Only USER templates will be
searched. An example of a matching record is "Author=Chris Weider".
This is the typical case of search.
schoultz and rick;search=lstring
The result will consist of all records which have one attribute value
matching "schoultz" exactly and one having "rick" as leading
substring, both with case ignored. One example is "Name=Rickard
choultz".
value=phone;search=substring
The result will consist of all records which have attribute values
matching *phone*, for example the record "Name=Acme telephone inc.",
but will not match the attribute name "phone". (Since "value" term
specifier is the default, the search term could be "phone" as well as
"value=phone".)
search-all=Peter ; search=substring;case=consider
The result will consist of all records which have attribute names,
template names or attribute values matching "Peter" with respect to
case. One example is "Friend-Of-Peter: Yes".
ucdavis;search=substring and (gargano or joan):include=name,email
This search command will find records which have records containing
the words "gargano" or "joan" somewhere in the record, and has the
word "ucdavis" somewhere in a word. The result will only show the
"name" and "email" fields.
Appendix B - Some sample responses
1) FULL format responses:
# FULL USER SERVERHANDLE1 PD45
Name: Peter Deutsch
email: peterd@bunyip.com
# END
# FULL USER SERVERHANDLE1 AE1
Name: Alan Emtage
email: bajan@bunyip.com
# END
# FULL USER SERVERHANDLE1 NW1
Name: Nick West
Favourite-Bicycle-Forward-Wheel-Brand: New Bicy
+cles Acme Inc.
email: nick@bicycle.acme.com
My-favourite-song: Happy birthday to you!
-Happy birthday to you!
-Happy birthday dear Nick!
-Happy birthday to you.
# END
# FULL SERVICES SERVERHANDLE1 WWW1
Type: World Wide Web
Location: the world
# END
--------------------
2) An ABRIDGED format response:
# ABRIDGED USER SERVERHANDLE1 PD45
Peter Deutsch peterd@bunyip.com
# END
# ABRIDGED USER SERVERHANDLE1 AE1
Alan Emtage bajan@bunyip.com
# END
# ABRIDGED USER SERVERHANDLE1 WWW1
World Wide Web the world
# END
--------------------
3) HANDLE format responses:
# HANDLE USER SERVERHANDLE1 PD45
# HANDLE USER SERVERHANDLE1 AE1
# HANDLE SERVICES SERVERHANDLE1 WWW1
--------------------
4) A SUMMARY HANDLE format response:
# SUMMARY SERVERHANDLE1
Matches: 175
Templates: User
- Services
- Abstracts
# END
Appendix C - Sample responses to system commands
C.1 Response to the LIST command
# FULL LIST SERVERHANDLE1
Templates: USER
-SERVICES
-HELP
# END
C.2 Response to the SHOW command
This example shows the result after issuing "show user":
# FULL USER SERVERHANDLE1
Name:
Email:
Work-Phone:
Organization-Name:
City:
Country:
# END
C.3 Response to the POLLED-BY command
# FULL POLLED-BY SERVERHANDLE1
Server-handle: serverhandle2
Cached-Host-Name: sunic.sunet.se
Cached-Host-Port: 7070
Template: USER
Field: ALL
# END
# FULL POLLED-BY SERVERHANDLE1
Server-handle: serverhandle3
Cached-Host-Name: kth.se
Cached-Host-Port: 7070
Template: ALL
Field: Name,Email
# END
C.4 Response to the POLLED-FOR command
# FULL POLLED-FOR SERVERHANDLE1
Server-Handle: serverhandle5
Template: ALL
Field: Name,Address,Job-Title,Organization-Name,
+Organization-Address,Organization-Name
# END
# FULL POLLED-FOR SERVERHANDLE1
Server-Handle: serverhandle4
Template: USER
Field: ALL
# END
C.5 Response to the VERSION command
# FULL VERSION BUNYIP.COM
Version: 1.0
Program-Name: kth-whoisd
Program-Version: 2.0
# END
C.6 Response to the CONSTRAINTS command
# FULL CONSTRAINT COMEDIA.SE
Constraint: format
Default: full
Range: full,abridged,summary,handle
# END
# FULL CONSTRAINT COMEDIA.SE
Constraint: maxhits
Default: 200
Range: 1-1000
# END
# FULL CONSTRAINT COMEDIA.SE
Constraint: search
Default: exact
Range: exact,substring,lstring
# END
# FULL CONSTRAINT COMEDIA.SE
Constraint: maxfull
Default: 20
# END
C.3 Response to the COMMANDS command
# FULL COMMANDS SERVERHANDLE1
Commands: commands
-constraints
-describe
-help
-list
-polled-by
-polled-for
-show
-version
# END
Appendix D - Sample whois++ session
Below is an example of a session between a client and a server. The
angle brackets to the left is not part of the communication, but is
just put there to denonte the direction of the communication between
the server or the client. Text appended to '>' means messages from
the server and '<' from the client.
Client connects to the server
>% 220-Welcome to
>% 220-the whois++ server
>% 220 at ACME inc.
<name=Nick:hold
>% 200 Command okay
>
># FULL USER ACME.COM NW1
> name: Nick West
> email: nick@acme.com
># END
># SERVER-TO-ASK ACME.COM
> Server-Handle: SUNETSE01
> Host-Name: whois.sunet.se
> Host-Port: 7070
># END
># SERVER-TO-ASK ACME.COM
> Server-Handle: KTHSE01
># END
>% 226 Tranfer complete
<version
>% 200 Command okay
># FULL VERSION ACME.COM
> Version: 1.0
># END
>% 226 Tranfer complete
>% 203 Bye
Server closes the connection
In the example above, the client connected to a whois++ server and
queried for all records where the attribute "name" equals "Nick", and
asked the server not to close the connection after the response by
using the global constraint "HOLD".
The server responds with one record and a pointer to two other
servers that either holds records or pointers to other servers.
The client continues with asking for the servers version number
without using the HOLD constraint. After responding with protocol
version, the server closes the connection.
Note that each response from the server begins system message 200
(Command OK), and ends with system message 226 (Transfer Complete).
Appendix E - System messages
A system message begins with a '%', followed by a space and a three
digit number, a space, and an optional text message. The line message
must be no more than 81 characters long, including the terminating CR
LF pair. There is no limit to the number of system messages that may
be generated.
A multiline system message have a hyphen instead of a space in column
6, immediately after the numeric response code in all lines, except
the last one, where the space is used.
Example 1
% 200 Command okay
Example 2
% 220-Welcome to
% 220-the whois++ server
% 220 at ACME inc.
The client is not expected to parse the text part of the response
message except when receiving reply 600, in which case the text part
is the name of a character set that will be used by the server in the
rest of the response. The valid values for characters sets is
specified in the "characterset" list in the BNF listing in Appendix
F.
The theory of reply codes is described in Appendix E in STD 10, RFC
821 [POST82].
------------------------------------------------------------------------
List of system response codes
------------------------------
110 Too many hits The number of matches exceeded
the value specified by the
maxhits constraint. Server
will still reply with as many
records as "maxhits" allows.
111 Requested constraint not supported One or more constraints in
query is not implemented, but
the search is still done.
112 Requested constraint not fullfilled One or more constraints in
query has unacceptable value
and was therefore not used,
but the search is still done.
200 Command Ok Command accepted and executed.
The client must wait for a
transaction end system message.
201 Command Completed successfully Command accepted and executed.
203 Bye Server is closing connection
220 Service Ready Greeting message. Server is
accepting commands.
226 Transaction complete End of data. All responses to
query are sent.
430 Authentication needed Client requested information
that needs authentication.
500 Syntax error
502 Search expression too complicated This message is sent when the
server is not able to resolve
a query (i.e. when a client
sent a regular expression that
is too deeply nested).
530 Authentication failed The authentication phase
failed.
600 <token> Subsequent attribute values
are encoded in the charater
set specified by <token>.
Table V - System response codes
------------------------------------------------------------------------
Appendix F - The WHOIS++ BNF Grammar
whois-command = ( system-command [":" "hold"]
/ terms [":" globalcnstrnts] ) NL
system-command = "constraints"
/ "describe"
/ "commands"
/ "polled-by"
/ "polled-for"
/ "version"
/ "list"
/ "show" [1*SP string]
/ "help" [1*SP string]
/ "?" [string]
terms = and-expr *("or" and-expr)
and-expr = not-expr *("and" not-expr)
not-expr = ["not"] (term / ( "(" terms ")" ))
term = generalterm / specificterm
/ shorthandle / combinedterm
generalterm = string *(";" localcnstrnt)
specificterm = specificname "=" string
*(";" localcnstrnt)
specificname = "handle" / "value"
shorthandle = "!" string *(";" localcnstrnt)
combinedterm = string "=" string *(";" localcnstrnt)
globalcnstrnts = globalcnstrnt *(";" globalcnstrnt)
globalcnstrnt = localcnstrnt
/ "format" "=" format
/ "maxfull" "=" 1*digit
/ "maxhits" "=" 1*digit
/ opt-globalcnst
opt-globalcnst = "hold"
/ "authenticate" "=" auth-method
/ "name" "=" string
/ "password" "=" string
/ "language" "=" language
/ "incharset" "=" characterset
/ "ignore" "=" string
/ "include" "=" string
format = "full" / "abridged" / "handle" / "summary"
/ "server-to-ask"
language = <The language code defined in RFC1766 [ALVE95]>
characterset = "us-ascii" / "iso-8859-1" / "iso-8859-2" /
"iso-8859-3" / "iso-8859-4" / "iso-8859-5" /
"iso-8859-6" / "iso-8859-7" / "iso-8859-8" /
"iso-8859-9" / "iso-8859-10" / "utf-8" /
charset-value
charset-value = 1*char
localcnstrnt = "search" "=" searchvalue /
"case" "=" casevalue
searchvalue = "exact" / "substring" / "regex" / "fuzzy"
/ "lstring"
casevalue = "ignore" / "consider"
auth-method = "password"
string = 0*char
char = "\" specialchar
/ <Characters 0-255 (decimal) except specialchar>
specialchar = " " / <tab> / "=" / "," / ":" / ";" / "\" /
"*" / "." / "(" / ")" / "[" / "]" / "^" /
"$" / "!" / "?"
digit = "0" / "1" / "2" / "3" / "4" /
"5" / "6" / "7" / "8" / "9"
NL = <CR LF (decimal 13 10)>
NOTE: Significant blanks must be escaped. The following
characters, when significant to the query, may be preceded
and/or followed by a single blank:
: ; , ( ) = !
Appendix G - Description of Regular expressions
The regular expressions described in this section is the same as used
in many other applications and operating systems. It is though very
simple and does not include logical operators AND and OR.
Searches using regular expressions are always using substring
matching except when the regular expression contains the characters
'^' or '$'.
Character Function
--------- --------
<any except those listed in this table> Matches itself
. Matches any character
a* Matches zero or more 'a'
[ab] Matches 'a' or 'b'
[a-c] Matches 'a', 'b' or 'c'
^ Matches beginning of
a token
$ Matches end of a token
Examples
---------
String Matches Matches not
------- ------- -----------
hello xhelloy heello
h.llo hello helio
h.*o hello helloa
h[a-f]llo hello hgllo
^he.* hello ehello
.*lo$ hello helloo