README.md 6.25 KB
Newer Older
Mattias Päivärinta's avatar
Mattias Päivärinta committed
1
2
3
4
5
Purpose
=======
The purpose of the Whois Selftest Tool is to help gTLD applicants prepare for
[Pre-Delegation Testing]( http://newgtlds.icann.org/en/applicants/pdt) (PDT) by
providing pre-PDT Whois output validation.
matsduf's avatar
matsduf committed
6

Mattias Päivärinta's avatar
Mattias Päivärinta committed
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Scope
=====
While Whois Selftest Tool _does_ validate Whois output and it _does_ strive to
reflect the state of PDT Whois output validation, it _is not_ authoritative on
the outcome of PDT and it _is_ subject to change.

Disclaimer
----------
The Whois Selftest Tool and the actual Whois testing under PDT are not equal.
We strive to make the two as equal as possible, but here is no guarantee that 
successfully running the Whois Selftest Tool means
that the same Whois system will pass the Whois testing under PDT. For example,
the parts of Whois tests under Whois that include DNS lookups and TCP
connections are not included in the Whois Selftest Tool. For a complete
reference of the Whois tests under PDT see the PDT Whois documents.

Version history
===============
* v1.0.0 - Initial public release (2015-12-03)
26
* v1.1.0 - Updated public release (2016-01-08)
27
* v1.2.0 - Updated public release (2016-02-02)
Mattias Päivärinta's avatar
Mattias Päivärinta committed
28
* v1.3.0 - Updated public release (2016-02-26)
29
30

The v1.1.0 release primarily matches the updates to the PDT Whois TP and TCs in the version 2.9 document release. It also handles the issue with IDN in the v1.0.0 release and corrects found bugs.
Mattias Päivärinta's avatar
Mattias Päivärinta committed
31

32
The v1.2.0 release primarily matches the updates to the PDT Whois TP in the the version 2.10 document release. It also corrects found bugs.
33

Mats Dufberg's avatar
Mats Dufberg committed
34
35
36
37
38
The v1.3.0 release includes two updates of the PDT Whois TP that will be included in the next document release:

* If the Domain Status is "ok" then the fragment in the URL in the Domain Status field may be "ok" or "OK".
* If a field is empty (key is there, but no value) there may be one space character (U+0020) after the colon, i.e. trailing space is permitted.

Mattias Päivärinta's avatar
Mattias Päivärinta committed
39
40
41
42
43
44
Specification compatibility matrix
----------------------------------
Refer to this compatibility matrix when deciding which version of Whois Selftest
Tool to use.

<table>
45
46
  <tr>
    <th>Whois Selftest Tool version</th>
Mats Dufberg's avatar
Mats Dufberg committed
47
    <th>PDT Document Release</th>
48
49
50
  </tr>
  <tr>
    <td>v1.0.0</td>
Mats Dufberg's avatar
Mats Dufberg committed
51
    <td>2.8</td>
52
53
54
  </tr>
  <tr>
    <td>v1.1.0</td>
Mats Dufberg's avatar
Mats Dufberg committed
55
    <td>2.9</td>
56
  </tr>
57
58
  <tr>
    <td>v1.2.0</td>
Mats Dufberg's avatar
Mats Dufberg committed
59
    <td>2.10</td>
60
  </tr>
Mattias Päivärinta's avatar
Mattias Päivärinta committed
61
62
  <tr>
    <td>v1.3.0</td>
Mats Dufberg's avatar
Mats Dufberg committed
63
    <td>2.10 plus two updates described above</td>
Mattias Päivärinta's avatar
Mattias Päivärinta committed
64
  </tr>
Mattias Päivärinta's avatar
Mattias Päivärinta committed
65
66
67
68
</table>

Roadmap
=======
69
The plan is to solve know issues and any bugs of importance. New versions will be released
Mattias Päivärinta's avatar
Mattias Päivärinta committed
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
when fixes are stable.

References
==========
The [Pre-Delegation Testing]( http://newgtlds.icann.org/en/applicants/pdt)
microsite hosts the following documents relevant to the Whois Selftest Tool:

* The PDT\_Whois\_TC\_CLI and PDT\_Whois\_TC\_Web documents, within the PDT Test
  Specifications zip, specifies the test cases that the Whois Selftest Tool
  partially implements.
* The PDT\_Whois\_TP document, within the PDT Test Specifications zip, specifies
  the format specification that the Whois Selftest Tool implements.

In the PDT\_Whois\_TP you can find references to other useful documents.

Licensing
=========
Whois Selftest Tool is distributed under the terms of [this license]( LICENSE).

Dependencies
============
 * Ubuntu Linux version 12.04
 * Perl, version 5.14 or higher
 * Standard Perl libraries found on CPAN.org
   * DateTime
   * File::Slurp
   * File::Which
   * Net::IDN::Encode
   * Net::IP
   * Readonly
   * Regexp::IPv6
   * Test::Differences
   * Test::MockObject
   * Text::CSV
   * Text::CSV\_XS
   * URI
   * YAML::Syck
107
 * wget
Mattias Päivärinta's avatar
Mattias Päivärinta committed
108
109
110
111
112
113
114
115

The Whois Selftest Tool has been developed on Unbuntu Linux, but we have tried to
avoid Linux specific coding. There is, however, no guarantee that it works on
other OSs.

Installation
============
Clone the project repository and choose version according to the specification
116
compatibility matrix. In the normal case, choose the latest version.
Mattias Päivärinta's avatar
Mattias Päivärinta committed
117

Mattias Päivärinta's avatar
Mattias Päivärinta committed
118
119
    $> git clone https://github.com/dotse/Whois-Selftest-Tool.git <srcdir>
    $> cd <srcdir>
Mattias Päivärinta's avatar
Mattias Päivärinta committed
120
121
    $> git checkout <version>

Mattias Päivärinta's avatar
Mattias Päivärinta committed
122
Install Whois Selftest Tool scripts and libraries.
Mattias Päivärinta's avatar
Mattias Päivärinta committed
123

Mattias Päivärinta's avatar
Mattias Päivärinta committed
124
125
126
127
    $> perl Build.PL
    $> ./Build
    $> ./Build test
    $> ./Build install
Mattias Päivärinta's avatar
Mattias Päivärinta committed
128

129
130
To check the installation run the scripts with `--help`. Before the whois-test
script can be run, the EPP database must be fetched.
Mattias Päivärinta's avatar
Mattias Päivärinta committed
131

Mattias Päivärinta's avatar
Mattias Päivärinta committed
132
    $> whois-fetch-epp-repo-ids --help
133
134
    $> whois-fetch-epp-repo-ids
    $> whois-test --help
Mattias Päivärinta's avatar
Mattias Päivärinta committed
135

Mattias Päivärinta's avatar
Mattias Päivärinta committed
136
137
138
139
After installing, you can find documentation for this module with the
perldoc command.

    perldoc PDT::TS::Whois
Mattias Päivärinta's avatar
Mattias Päivärinta committed
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

Before use
==========
Before you use the tool, make sure that you have read the documents listed
in the reference above. Some error messages may be difficult to understand
without referring to the PDT\_Whois\_TP document.

Usage
=====
The Whois Selftest Tool provides the two commands `whois-fetch-epp-repo-ids`
and `whois-test`. If you have followed the installation above, always go to
your `<programdir>` and run the commands from there or else the scripts will
not be able to find its libraries in the `PDT` directory. You probably have to
prepend the commands with `./` just as in the instructions above.

`whois-fetch-epp-repo-ids` fetches the EPP Repository Identifiers registered
with IANA and stores them in a text file inside the user's home directory.

`whois-test` validates the Whois responses according to the format specification
in the PDT\_Whois\_TP document.

The database of EPP Repository Identifiers is a prerequisite for running
`whois-test` command, so `whois-fetch-epp-repo-ids` must be run at least once
before `whois-test` is used for the first time.  After that, run
`whois-fetch-epp-repo-ids` again to update the database every time 
the Whois Selfttest Tool is to be used.

See the man pages for the respective commands for details on how to run them.
(You can use the `--man` option to view the man pages)

Known issues
============
172

173
* The description of the two types of replies on queries for nameserver objects is a bit unclear. For full understanding, please see the PDT Test Case WhoisCLI03 found in the PDT\_Whois\_TC\_CLI document listed in the references above.
Mattias Päivärinta's avatar
Mattias Päivärinta committed
174
175
176
177
178
179
180

Reporting bugs
--------------
If you think you've found a bug, please search both the list of known issues and
the [issue tracker](https://github.com/dotse/Whois-Selftest-Tool/issues) to see
if this is a known bug.  If you cannot find it, please report it to the issue
tracker.