.. _Whois Protocol: Whois Protocol ============== Server location --------------- The host name for the WHOIS server is :: whois.srs.net.nz. This can also be found by an SRV record under the .nz domain: :: _nicname._tcp.nz. SRV whois.srs.net.nz. The WHOIS server only operates on port 43 Query Format ------------ The query consists of a single domain name ending in "nz". No wildcards are permitted and the query string is used literally to match a domain name in the register. The domain name in the query must be a well formed domain name. A trailing full stop (.) indicating an absolute domain name may be present or omitted. If it is present it will be silently discarded, as all domains are assumed to be fully qualified. The server accepts queries in UTF-8 or in ASCII. If the query is in UTF-8 then it may include the Unicode characters for the macronised vowels (ā, ē, ī, ō, ū) natively, otherwise IDN domains must be queried for in Punycode. The query string must not begin with a hyphen (-) (domain names may not begin with a hyphen anyway). Query strings beginning with a hyphen are reserved for future expansion, to allow passing "command line" flags to the whois server. Currently no flags are defined or permitted. Query strings that do not match the input format will be rejected with a 5xx query_status: response and associated human readable error description, as described below. Response Format --------------- The response consists of a series of UTF-8 encoded lines, terminated by CR LF pairs. There are two types of lines in the response format: #. Field-value lines containing a response field on a single line. These are described below #. Comment lines identified by an initial percentage symbol (%). The comment lines are intended for human consumption and need not be decoded by a program interacting with the whois server. However they should be displayed to the user initiating the query. Fields ------ The following is a list of all possible field-value fields in the order in which they will appear. The fields version, query_datetime, domain_name, and query_status will always be present. All others will be omitted if they contain no data. The following table contains a list of all possible field-value fields in the order in which they will appear. The fields version, query_datetime, domain_name, and query_status will always be present. The following fields will not be present: * Registrant, Admin, and Technical contact details * domain_datebilleduntil All others will be omitted if they contain no data. Full domain details may be available via the domain search tool on the `DNCL website `_ There is no provision for fields to be wrapped onto a second line; all data associated with a given field will be on the same line. The maximum likely length of a field varies from field to field, but no fields will be longer than 1024 characters. The fields may be separated by comments. .. csv-table:: :header: "Field", "Details", "Note" :delim: | version | The version field contains the version number of the output format of the whois server, consisting of a major and a minor part, separated by a full stop (.). The major number will be incremented when the format has changed in a manner that is not compatible with a program parsing the older format (for example, the addition of new fields, or new formatting for existing fields). The minor number will be incremented for any other change.| query_datetime | The date and time that the query was performed, in local time at the location of the whois server. The date and time is formatted as described in RFC3339.| domain_name_idn | If the domain is an IDN, this field will contain the domain name in the script intended by the registrant, encoded in UTF-8.| domain_name_language | If the domain is an IDN, this field will contain a string describing the language and script, which will always be .NZ LATIN.| domain_name_hex | If the domain is an IDN, this field will contain the domain name with non-ASCII characters encoded in a unicode hex format (for example, mcron.co.nz).| domain_name | The domain name as stored in the register. Generally this will be the same as the domain name which was queried (from the query string). In the case of queries for IDNs, it will be the encoded domain name stored in the register, formatted according to RFC 3492.| query_status | The status or error code as detailed below| domain_dateregistered | The date and time at which the domain was entered into the register, formatted according to RFC 3339.| domain_datebilleduntil | The date and time on which the current payment for the domain registration ends, formatted according to RFC 3339.| domain_datelastmodified | The date and time on which the registration was last modified, formatted according to RFC 3339. This field may be omitted if no modifications have been made since the domain was first registered.| domain_datecreated | The date and time on which the domain first appeared in the registry, formatted according to RFC 3339.| domain_datecancelled | If the domain has been cancelled, the date and time on which it was cancelled, formatted according to RFC 3339.| domain_datelocked | If the domain has been locked (for example, by the registry while a dispute is resolved), the date and time on which the domain was locked, formatted according to RFC 3339.| domain_delegaterequested|yes or no, depending on whether the domain is marked for export into the DNS zone as a delegation. If no, then the domain will not appear in the DNS even if all other information (for example, suitable nameservers) is present to otherwise allow it to do so. If set to yes, then the domain will appear in the DNS providing the other criteria are satisfied.| domain_signed| yes or no, depending on whether the domain has DS records in the registry. If set to yes then DS records will be present in the DNS if the domain is delegated and has sufficient namservers to be present in the DNS. If no then the domain has no DNSSEC DS records.| registrar_name | Free format name of the registrar.| registrar_address1 | Free format first line of the postal or physical address of the registrar.| registrar_address2 | Free format second line of the postal or physical address of the registrar. This field will be omitted if the postal or physical address is listed entirely in the address1 field.| registrar_city | Free format name of city or other locality for the postal or physical address of the registrar.| registrar_province | Free format name of the province or region or state for the postal or physical address of the registrar. This field will be omitted if the postal or physical address does not list a province/region/state.| registrar_postalcode | Free format postal code for the postal or physical address of the registrar. This field will be omitted if the postal or physical address does not include a postal code.| registrar_country | Two letter country code of the postal or physical address of the registrar, followed by the country name in parenthesis as referenced in ISO3166.| registrar_phone | Contact phone number for the registrar. The phone number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number.| registrar_fax | Contact fax number for the registrar. The fax number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number.| registrar_email | Contact email address for the registrar.| registrant_contact_name | Free format name of the registrant.| registrant_contact_address1 | Free format first line of the postal or physical address of the registrant. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_address2 | Free format second line of the postal or physical address of the registrant. This field will be omitted if the postal or physical address is listed entirely in the address1 field. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_city | Free format name of city or other locality for the postal or physical address of the registrant. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_province | Free format name of the province or region or state for the postal or physical address of the registrant. This field will be omitted if the postal or physical address does not list a province/region/state. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_postalcode | Free format postal code for the postal or physical address of the registrant. This field will be omitted if the postal or physical address does not include a postal code. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_country | Two letter country code of the postal or physical address of the registrant, followed by the country name in parenthesis as referenced in ISO3166.| registrant_contact_phone | Contact phone number for the registrant. The phone number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_fax | Contact fax number for the registrant. The fax number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number. |Will not be returned if :ref:`Privacy ` is enabled for this contact. registrant_contact_email | Contact email address for the registrant.| admin_contact_name | Free format name of the admin contact.| admin_contact_address1 | Free format first line of the postal or physical address of the admin contact. |Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_address2 | Free format second line of the postal or physical address of the admin contact. This field will be omitted if the postal or physical address is listed entirely in the address1 field. |Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_city | Free format name of city or other locality for the postal or physical address of the admin contact. |Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_province | Free format name of the province or region or state for the postal or physical address of the admin contact. This field will be omitted if the postal or physical address does not list a province/region/state. |Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_postalcode | Free format postal code for the postal or physical address of the admin contact. This field will be omitted if the postal or physical address does not include a postal code.|Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_country | Two letter country code of the postal or physical address of the admin contact, followed by the country name in parenthesis as referenced in ISO3166.| admin_contact_phone | Contact phone number for the admin contact. The phone number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number. |Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_fax | Contact fax number for the admin contact. The fax number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number. |Will not be returned if :ref:`Privacy ` is enabled for this contact. admin_contact_email | Contact email address for the admin contact.| technical_contact_name | Free format name of the technical contact.| technical_contact_address1 | Free format first line of the postal or physical address of the technical contact. |Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_address2 | Free format second line of the postal or physical address of the technical contact. This field will be omitted if the postal or physical address is listed entirely in the address1 field. |Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_city | Free format name of city or other locality for the postal or physical address of the technical contact. |Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_province | Free format name of the province or region or state for the postal or physical address of the technical contact. This field will be omitted if the postal or physical address does not list a province/region/state. |Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_postalcode | Free format postal code for the postal or physical address of the technical contact. This field will be omitted if the postal or physical address does not include a postal code.|Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_country | Two letter country code of the postal or physical address of the technical contact, followed by the country name in parenthesis as referenced in ISO3166.| technical_contact_phone | Contact phone number for the technical contact. The phone number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number. |Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_fax | Contact fax number for the technical contact. The fax number is formatted with a leading plus sign (+), followed by the country code, followed by a space, followed (if given) by an area code, followed by a space, followed by a free format E.164 style phone number. |Will not be returned if :ref:`Privacy ` is enabled for this contact. technical_contact_email | Contact email address for the technical contact.| Nameserver Fields ^^^^^^^^^^^^^^^^^ These fields will appear for each nameserver recorded in the register for delegation of that domain, in the order they were listed by the registrar as _01, _02, and so on. There will not be any gaps in the sequence. ================================ ================================= Field Details ================================ ================================= ns_name_01 The domain name of the nameserver held in the register ns_ip4_01 The IPv4 address of the name server held in the register, formatted as a dotted quad (for example, NN.NN.NN.NN). Any well-formed IPv4 address may appear. ns_ip6_01 The IPv6 address of the name server held in the register, formatted in the same format as it was received by the register. Any well formed IPv6 address may appear. ... ns_name_99 As above. ns_ip4_99 As above. ns_ip6_99 As above. ================================ ================================= Linked Domain Fields ^^^^^^^^^^^^^^^^^^^^ These fields may appear for any unregistered domain name at the second level under .nz if certain requirements in the DNCL Registering, Managing and Cancelling Domain Names Policy are met. These linked domain names will show any domain names registered at the third level that are linked to the unregistered second level domain. There will not be any gaps in the sequence. ================================ ================================= Field Details ================================ ================================= linked_domain_name_01 the registered third level domain name that is linked to the domain name ... linked_domain_name_99 As above ================================ ================================= DNSSEC Fields ^^^^^^^^^^^^^ The DS records for a domain will be returned in a Whois transactions. ================================ ================================= Field Details ================================ ================================= ds_rdata_01 Shows each DS record published to the registry in the format: ... ds_rdata_99 As above ================================ ================================= Status codes and Error codes ---------------------------- The availability status of the domain name which was queried, or a code indicating the error that occurred. The field contains a three digit number followed by a space followed by a human readable string explaining the status number (that string may include spaces, and is considered to +run from the space after the three digit number to the end of line). In the case of successful queries, these human readable strings will correspond to the strings used by the SRS XML protocol to indicate domain status. There are three groups of status codes: ================================ ================================= Status Code ================================ ================================= 2xx Successful query 4xx Server error (temporary errors) 5xx Client error (permanent errors) ================================ ================================= The allocated successful query status codes are: ================================ ================================= ================================= Status Code Description ================================ ================================= ================================= 200 Active Indicating that the domain is active in the register, 210 PendingRelease Indicating that the domain is no longer active but is in the period prior to being released for general registrations 220 Available Indicating that the domain is not currently registered and hence available for registration. 230 Prohibited For reasons of confusion, this domain name cannot be registered directly at the second level. These names include 'gov', 'government', 'com', 'edu', 'nic' and all macron variations of the current 15 second levels 250 Conflicted Indicating that the domain is not currently registered and is not currently available for registration. The Conflicted status means there are at least two registrations at the third level that have rights over this domain and so its registration at the second level needs to go through the Domain Name Commission conflicted process before it can be registered. 270 Reserved Indicating that the domain is reserved by the registrant of the registered third level domain (shown in the linked_domain_nn field) and is only available for registration by that registrant. 280 Resolved A domain status indicating the domain name was conflicted but which agreement has been reached as to which registrant of the registrations at the third level is entitled to register it. ================================ ================================= ================================= The allocated server error status codes are: ================================ ================================= Status Code ================================ ================================= 400 Error sending request to backend 410 Error receiving response from backend 420 Invalid response received from backend 430 Error translating response from backend 440 or 441 :ref:`Request has been denied/blocked <440 Request Denied>` 490 Timeout before response received from backend 495 System overloaded; cannot start new request 499 System Error ================================ ================================= All errors in this category are temporary in nature, and the requests should be retried at a later stage. Timeouts may be caused by load on the systems, and so it is appropriate to retry, once, after a short delay. The other statuses may require longer to resolve, and it would be appropriate to present the error to the user, and allow them to retry at a later stage. The allocated client error status codes are: ================================ ================================= Status Code ================================ ================================= 500 Invalid characters in query string 510 Domain is not managed by this register 520 This domain is not available for registration (Note. Second Level Domains e.g. co, org, net etc) 590 Client Timeout ================================ ================================= All errors in this category are permanent. The request should not be retried as is. Instead the request should be reviewed to ensure that it is well formed, and appropriate for the whois server. .. only:: internal RewriteSourceIP ----------------- .. warning:: The following feature is only available for use by the registry/DNC. The Whoisd server provides internal-only functionality allowing the DNC website to pass through an alterative source IP which is used for rate limiting and logging. The source IP address must be added to /home/srs-whois/etc/whoisd.config in the format: :: $main::config{'RewriteSourceIP'}{'ips'} = { '192.168.22.50' => 'DNC', } Format ~~~~~~ Requests must be sent through in the format of {ip}:::{domain} for example: :: echo 127.0.0.2:::internetnz.net.nz | nc srstest.srs.net.nz 43 or :: whois -h srstest.srs.net.nz 127.0.0.1:::testdomain.net.nz