README file for mod_whoisd apache module
----------------------------------------

This document describes mostly general capabilities of the whois server.
The rest of documentation must be generated by doxygen. To generate
documentation type "make doc" (assuming you have installed doxygen) and then
you can start browsing web docs at doc/html/index.html.

In documentation generated by doxygen you can find:

  *) General description of mod_whoisd
  *) Configuration description
  *) Installation guide
  *) TroubleShooting

If you don't have installed doxygen tools or you don't want to install it,
you can view the raw doxygen source file doc/mainpage.h.

The whois implementation conforms to RFC 3912, which specifies only on-the-wire
protocol. Other documents which influenced our implementation are RFC 954 and
ripe database reference manual.

Whois service publishes information about objects stored in whois database.
There are several object types:

  * domain
  * nsset
  * contact
  * registrar

An object is defined by its attributes. Attribute is a pair of name and value.


Format of whois output
----------------------

Comments begin with two letters at the beginning of line: '%' and space
character. Each response from server is prefixed by disclaimer followed by
server version and current timestamp. All this is a part of comment.

Each object record is a set of attributes, each attribute is on separate line.
Attribute's name and value are separated by colon, which immediatelly follows
the name. Between the colon and the value may be unspecified number of spaces.
If attribute has multiple values, then the attribute is repeated for each value.
Blank line denotes end of object record. There may be more objects in one
server response if they are relevant to user's query. End of response is marked
by two blank lines. The maximal number of objects returned in one response
is limited.

If the server encounters a problem, an error message is returned as a query
result. The format of an error message is as follows:

%ERROR:#:<message>

where # is the error code and message is a short description of the problem,
possibly followed by a more descriptive message, each line of which starts
with % followed by a white space and a text.


Object templates
----------------

Here we define templates for the objects. Not all attributes of objects must be
present in an output. Some of them are optional and some attributes of the
contact object may be hiden as a result of registrant's wish.  Domain template
is used for "ussual domains" as well as for ENUM domains.  For ENUM domains is
the attribute registrant never displayed (for common domains is this attribute
always published) and the attribute validated-to is there only for ENUM
domains. The fourth column of templates marks attributes which can be used
in search. Primary key unambiguously identifies the object within the scope
of one object type. Inverse key can be used for search of object
and the name inverse implies that we proceed from bottom to up in a tree
representing relationships among objects.

-- Domain template --

domain:       [mandatory]  [single]    [primary key]
registrant:   [optional]   [single]    [inverse key]
admin-c:      [optional]   [multiple]  [inverse key]
temp-c:       [optional]   [multiple]  [inverse key]
nsset:        [optional]   [single]    [inverse key]
registrar:    [mandatory]  [single]    [ ]
status:       [optional]   [multiple]  [ ]
registered:   [mandatory]  [single]    [ ]
changed:      [optional]   [single]    [ ]
expire:       [mandatory]  [single]    [ ]
validated-to: [optional]   [single]    [ ]

-- Nsset template --

nsset:        [mandatory]  [single]    [primary key]
nserver:      [mandatory]  [multiple]  [inverse key]
tech-c:       [mandatory]  [multiple]  [inverse key]
registrar:    [mandatory]  [single]    [ ]
created:      [mandatory]  [single]    [ ]
changed:      [optional]   [single]    [ ]

-- Contact template --

contact:      [mandatory]  [single]    [primary key]  [not hidable]
org:          [optional]   [single]    [ ]            [not hidable]
name:         [mandatory]  [single]    [ ]            [not hidable]
address:      [mandatory]  [multiple]  [ ]            [not hidable]
phone:        [optional]   [single]    [ ]            [hidable]
fax-no:       [optional]   [single]    [ ]            [hidable]
e-mail:       [mandatory]  [single]    [ ]            [hidable]
registrar:    [mandatory]  [single]    [ ]            [not hidable]
created:      [mandatory]  [single]    [ ]            [not hidable]
changed:      [optional]   [single]    [ ]            [not hidable]

-- Registrar template --

registrar:    [mandatory]  [single]    [primary key]
org:          [mandatory]  [single]    [ ]
url:          [mandatory]  [single]    [ ]
phone:        [optional]   [single]    [ ]
address:      [mandatory]  [multiple]  [ ]


Schema of object relations
--------------------------


             DOMAIN-------------------NSSET
            /  |   \                 /  |
           /   |    \               /   |
 REGISTRANT ADMIN-C  \             /   TECH-C
          \  TEMP-C   \           /    /
           \       \   \         /    /
            \       \   \       /    /
             \       \__ \     / ___/
              \_________REGISTRAR   

Registrant, admin-c, temp-c and tech-c are all of the same type - the contact.
The tree is rooted at the domain object and the dependency links run from there
to registrar.  When displaying information about an object all objects which
are referenced in that object are displayed too and so on recursivelly. There
is one exception to this rule and it is the registrar object which is not
displayed unless it is a primary subject of user's query. The next table
summarizes what we get for objects if we ask for certain type of object by its
primary key.

 domain:
    1 domain
    1 registrant
    n admin-c objects
    n temp-c objects
    1 nsset (optional)
    n tech-c objects (only if there is nsset)

 nsset:
    1 nsset
    n tech-c objects

 contact:
    1 contact

 registrar:
    1 registrar


Flags and options accepted by server
------------------------------------

Usage:   whois [options] [[type] value]

If the server encounters option that it does not understand, it prints
a help message which starts by comments and returns no data. The following
options are accepted by server, it is more-or-less a small subset of options
accepted by RIPE whois server.


  -r            Switch off recursion. Only the object which is primary target
                of query is returned.
  -T type       Type of object to lookup (domain, nsset, contact, registrar).
                There may be more types separated by comma without spaces
                between them. The types are case-insensitive.
  -i attr       Lookup object by its attribute. Attribute can be any of
                attributes from object templates marked by flag "inverse key".
                Attribute name is case-insensitive.
  -q version    Returns version of whois server.
  -q indexes    Returns list of attributes which can be used in search. The
                attributes have form object:attribute.
  -q templates  Returns templates for all four object types.

There's yet another way how to specify a type of object to lookup. Just prefix
the object's identifier with the name of a type. The following two examples are
equivalent:

 $ whois -T domain nic.cz

 $ whois "domain nic.cz"

The -q parameter can be used only once and not in combination with any other
option. The -i parameter can be used only once.

Error codes
-----------

Here is a list of possible error codes accompanied by their description.
We tried to stay compatible with RIPE DB error codes where possible.

%ERROR:101: no entries found
%
% No entries found.

%ERROR:107: usage error
%
% Unknown option, invalid combination of options or invalid value for option
% was specified.

%ERROR:108: invalid request
%
% Invalid character in request, request not properly terminated or too long.

%ERROR:201: access denied
%
% Access from the host has been permanently denied because of excessive
% querying.

%ERROR:501: internal server error
%
% Query didn't succeed becauseof server-side error. Please try again later.

Questions and answers
---------------------

Q: Does the whois server support wildcard search?
A: No, the wildcard symbols are handled as any other characters.

Q: Does the whois server support persistent connections?
A: No, one connection = one query.

Q: Do you provide your own implementation of whois client?
A: No, but existing implementations can be easily used if you take care of
   quoting of switches, which are not known to the client.

Q: Is your server compatible with RIPE whois?
A: No, but we tried to stay compatible where possible. Generally we implement
   only a subset of switches and options implemented by RIPE server. If you
   use an option which the RIPE server understands to, but our doesn't, than the
   server returns error and help message.

Q: What is the meaning of attribute temp-c?
A: It is a mysterious attribute of domain, which was introduce to ease
   transition from old domain registration model to new one. It is a burden of
   domains registered in old model. The new domains cannot have this attribute.

