How can we help you?
WHOIS DB - Reference Manual
Reviewed for AFRINIC usage by: Adiel Akplogan
Document ID: afsup-dbref200501-Draft
Date: 20 January 2005
Abstract
This document describes the functionality of the AFRINIC Database that uses the Routing Policy Specification Language (RPSL) [1] to represent all Database objects. Though this document tends to be self-contained, the reader is encouraged to read the RPSL [ 1 ] and RPSS [ 2 ] specifications for more detailed information, examples of usage and definitions. For a tutorial on RPSL, the reader should read the RPSL applications document [ 3 ]
Tabel of content
Introduction 1.0 Queries in the AFRINIC Database 1.1 Queries using primary and lookup keys 1.2 IP address lookups 1.2.1 Default lookup for IP ranges in the AFRINIC Database 1.2.2 More and less specific queries 1.3 Inverse queries 1.4 Getting all the members of set objects 1.5 More/less specific lookups for in-addr.arpa and ip6.arpa domains 1.6 Referral mechanism for domains 1.7 Access control for queries 1.8 Other server features 2.0 Updates in the AFRINIC Database 2.1 Format of an update message 2.2 Creating, modifying and deleting an object 2.2.1 Object processing 2.2.2 Creating a new object 2.2.3 Modifying an existing object 2.2.4 Deleting an object 2.3 E-mail updates 2.3.1 MIME support 2.3.2 PGP support 2.3.3 Subject line processing 2.4 Updates using networkupdate utility 2.5 Acknowledgements and Notifications 2.5.1 Acknowledgements 2.5.2 Notifications 2.6 Data protection 2.6.1 Authorisation model 2.6.2 Protection of individual objects 2.6.3 Protection of aut-num object space 2.6.4 Protection of address space 2.6.5 Protection of objects with hierarchical names 2.6.6 Protection of domain object space 2.6.7 Protecting membership of a set [**] 3.0 Mirroring of the AFRINIC Database Appendices
Conventions used in this document
Within this document, the following conventions are used:
<label> indicates a placeholder or syntax specification [option] indicate an optional text or command argument.
Please note that in object templates the square brackets "[ ]" are used to specify type of an attribute. "attribute:" indicates an attribute.
Introduction
The AFRINIC Network Management Database contains information about IP address space allocations and assignments. Routing registry in the AFRINIC region will be performed at this point by RIPE NCC.This Database does not contain any information about Domain Name. Please see the IANA ccTLD Database for a full list of the ccTLD administrators.
The information in the AFRINIC Database is available to the public for agreed Internet operation purposes, but is under copyright. Please see Appendix A3 "Copyright information".
The phrase "AFRINIC Database" is often used to refer to the interface software rather than the information that is stored in the database. In ambiguous situations, this reference manual will make clear what is being discussed.
This document describes the functionality of AFRINIC database (bases on version 3.0 of the RIPE NCC WHOIS). This version uses the Routing Policy Specification Language (RPSL) [1]. It also integrate the Routing Policy System Security(RPSS) [2] to provide authorization mechanisms to enable a higher level of security for the routing registry. Note that this last functionality is not yet used by AFRINIC.
This document is self-contained. However, it does not contain examples of usage and illustrations of principles and concepts related to the AFRINIC Database functionality and implementation. The "AFRINIC Database User's Manual" [5] and the "AFRINIC Database Operations Manual" [5] will fill this gap and provide examples and detailed information on how to interact with the AFRINIC Database and how to configure and run AFRINIC Database server software. The reader is also encouraged to read the RPSL [1] and RPSS [2] specifications for more detailed information, examples of usage and definitions. For a tutorial on RPSL, the reader should read the RPSL applications document [3].
1.0 Queries in the AFRINIC Database
This section describes the functionality provided in the AFRINIC Database to enable users to retrieve database objects. Querying the database is done using a client who uses the Whois protocol [12] to query and get the responses.
This database incorporated mechanism to enable the whois server to automatically track query responses and limit the retrieval of contact information from the AFRINIC Database is also described in this section. The intention is to limit non-operational uses of the data (such as advertising) while permitting the operational uses of the database to be carried out.
There is a set of general rules about server responses:
- Output starting with the % sign is either a server response code or an informational message. A comment contains a white space after the % sign, while server messages start right after the % sign. Please see Appendix A2 "AFRINIC Database response codes and messages" for more information.
- An empty line ("\n\n") is an object delimiter.
- Two empty lines mean the end of a server response.
- When using the referral mechanism, the output of the referred server is passed to the client without modification. See section 1.6"Referral mechanism for domains" for more information.
The general format of a query is:
[-query_flags [query argument]] <lookup-key>
1.1 Queries using primary and lookup keys
Normal queries are performed using primary and lookup keys as an argument to a query. These queries are presented in Table 1 . Please refer to the document "Object types in AFRINIC database " for primary and lookup keys definition for a class.
1.2 IP address lookups
Probably, the most important service provided by the AFRINIC Database is to provide information about IP networks in the Internet. This information is stored in the database in the form of inetnum.
The inetnum and inet6num store information about ranges of IP addresses.
For IPv4, the prefix is a 32-bit integer written in dotted quad notation and having the value of the lowest IP address in the range. The prefix length is an integer number in the range 0-32 (e.g. 193.0.0.0/22 specifies the range of 1024 IPv4 addresses starting with, and including, 193.0.0.0).
The inetnum objects represent an IPv4 address space in range notation where the range is explicitly specified as two 32-bit integers written in dotted quad notation separated by a dash ("-") (e.g. 93.0.0.0-193.0.3.255, which specifies the same range as above).
When dealing with IPv6 address ranges, only the standard IPv6 prefix notation is allowed (prefix length must be in the range 0-128 and the prefix is a 128-bit integer, written in hexadecimal groups of 2 bytes separated by colons and with the possible use of shorthand notation for strings of consecutive 0s).
When querying the database for information about a range of IP addresses, the user can use as search keys the following range notations:
- a prefix, which has the same meaning as above;
- an explicit range, also as above;
- a single IP number, which when used as an argument to a query is interpreted as a range of exactly 1 address.
These types of queries are presented in Table 2 . The remainder of this section describes how a user can request different types of information to be returned, relative to a particular range of IP addresses.
Before going into details, it is useful to define three concepts frequently used in this type of queries and which are defined relative to the user-specified (reference) range:
- A less specific range is a range that contains the whole of the reference range and is bigger (contains more IP addresses) than the reference range.
- A more specific range is a range contained within the reference range and contains less IP addresses than the reference range.
- An exact match refers to a range that is identical to the reference range.
1.2.1 Default lookup for IP ranges in the AFRINIC Database
When no flags are specified and the query key sent to the whois server is a range of IP addresses (either IPv4 or IPv6, expressed as a single IP address, two IP addresses separated by a hyphen ("-") or a range of IP addresses in prefix notation), the AFRINIC whois server will try to find an exact match for that range.
If an exact match is found, it is returned. If not, a lookup for the smallest less specific range is performed and this is returned.
1.2.2 More and less specific queries
Sometimes the exact match is not the desired information. In that case there is a set of flags that modify the response of the whois server. This set of 4 flags ("-M", "-m", "-L" and "-l" ) provides two generic types of queries known as more and less specific queries.
1.2.2.1 Less specific queries
These refer to queries triggered by the use of the "-l" and "-L" flags. These queries will return information about ranges of IP addresses that fully contain the user-supplied range and may contain more addresses.
The "-L" flag requests that the server return the exact match, if any, and all the objects containing information about IP ranges that are bigger than the user-supplied range and fully contain it.
The "-l" flag requests that the server NOT return the exact match but only the smallest of the IP ranges that is bigger than the user-supplied range and that fully contains it. This is usually referred to as the one level less specific range.
1.2.2.2 More specific queries
These refer to queries triggered by the use of the "-m" and "-M" flags. These queries will return information about ranges of IP addresses that are fully contained in the user-supplied range and contain fewer addresses.
The "-M" flag requests that instead of returning the exact match, the server should return all the sub-ranges completely contained within the user-provided range no matter what their size is.
The "-m" is the more specific equivalent of the "-l" flag. It requests that instead of returning the exact match, the server should return sub-ranges that are fully contained within the user-provided range. But instead of reporting all existing sub-ranges, it will only return the biggest ranges contained in the user range. These are usually called one level more specific.
1.3 Inverse queries
Inverse queries are performed on inverse keys as defined in the AFRINIC Database object templates. For a complete listing of these templates, please refer to the document "Object types in AFRINIC database". By issuing this type of query, the client requests all objects that reference
the object with the key specified as a query argument to be returned by the Database. One can also request an inverse query for several attributes (e.g. find out which objects reference a specific mntner object by "mnt-by:", "mnt-lower:" attributes).
In such case, the query flag should be represented by a comma-separated list of attributes to be searched. No white space is allowed in the list.
Please refer to Table 4 for a complete list of supported inverse queries.
1.4 Getting all the members of set objects
In RPSL[3] there are two ways in which an object can be a member of a set object.
The first one is by listing objects in a "members:" attribute in the set object. This is the kind of member relationship present in "Representation of IP Routing Policies in a Routing Registry"[4] (e.g. "as-list:" attribute in as-macro objects).
The other way of specifying a membership relation is through the use of the "member-of:" attribute. This attribute can be used in the route, aut-num and inet-rtr classes. The value of the "member-of:" attribute identifies a set object that this object wants to be a member of.
However, specifying member-of is not enough. The set object must also have a "mbrs-by-ref:" attribute listing the maintainer of the object wanting to be a member of the set. That is, the set owner must validate the membership claim of an object with a "member-of:" attribute, and it does that by matching the mnt-by line of the object with one of the maintainers in the "mbrs-by-ref:" attribute of the set object.
1.5 More/less specific lookups for in-addr.arpa and ip6.arpa domains
AFRINIC Database supports IP lookups including the "-x", "-m", "-M", "-l" and "-L" functionality for reverse delegation domains. To request that reverse delegation domains are to be looked up, use the "-d" flag in your Whois IP lookup query.
1.6 Referral mechanism for domains
The referral mechanism provides a way for administrators of domain registries to instruct the whois server to reply to the user by fetching data from the domain registry database rather than from local data. Its implementation consists of two different parts:
- Domain name stripping: When no matching domain object is found in the database with the name specified in the query, the domain name is stripped towards higher-level domains (xxx.yyy.zzz becoming yyy.zzz) and the lookup is repeated until a domain object is found or the search string becomes empty. For backwards compatibility, if the domain object found by domain stripping does not contain a "refer:" attribute, then it is considered that no objects are found and an appropriate message is displayed. Please see Appendix A2 "AFRINIC Database response codes and messages" for more information.
- The "refer:" attribute: The "refer:" attribute gives domain name administrators the possibility to point the whois server to an authoritative server for information about the domain name. This attribute specifies the hostname, port and referral type that the server should use to redirect the query. Please see Appendix A1 "Object attributes" for the syntax of this attribute.
If a query to the whois server results in the retrieval of a local object that contains a "refer:" attribute, the server will connect to the remote server and issue a whois query for the requested domain name. Whatever is returned is then sent to the user. This mechanism is disabled by including the "-R" flag in the original query.
1.7 Access control for queries
This section describes the mechanism for controlling how many database objects a particular whois client can retrieve from the whois server. The objective is to control and prevent abusive use of the Database done by systematic queries for contact information potentially used for non-agreed purposes (e.g. spam).
Therefore, the access control system is limiting only the amount of contact information (number of person and role objects) that can be retrieved in a certain amount of time. No limitations exist on the number of other objects.
However, one should keep in mind that many lookups for object types, other than person and role, also return contact information by default. To avoid being blocked in such cases, it is advisable to use the "-r" query flag.
Every time a person or role object is retrieved, a counter is decreased. When it reaches zero, the query execution is aborted and the connection is terminated, displaying an error message to the client (see "Access errors" in Appendix A2 "AFRINIC Database response codes and messages"), also a counter of exceeds (denials) is incremented. The Database may limit the number of denials, after which the host is permanently blocked from access to the AFRINIC Database. The Database Administration may also block a client manually in case any abusive behaviour is discovered.
The counter recovers in time. The host can resume querying contact information after the counter has recovered so that the host gets a non-zero limit for contacts next time. Accounting is based on the IP address of a client.
The AFRINIC Database server provides a facility for proxy clients (for example, web servers running cgi interfaces to the AFRINIC Database) that allows accounting to be based not on the IP address of the proxy, but rather of the clients that use this proxy to query the AFRINIC Database. The "-V" flag supports this feature. In such case, the format of the query is as follows:
-V <version>,<ipv4-address>
where
<version> is a client tag that usually represents the software version that the proxy uses;
<ipv4-address> is the IPv4 address of the client that queries the Database using the proxy.
Note that the proxy's IP address should be registered in the access control list of the AFRINIC Database. Please contact AFRINIC Database Administration if you need this option.
1.8 Other server features
The AFRINIC Database server supports the retrieval of certain information about itself and the data sets served using a "-q" query flag.
The "-q " flag takes arguments that make the server reply with information that is not extracted from the Databases it serves but rather about the system setup. This flag can currently take two arguments:
*version (usage: -q version). Display version information for the server software.
* sources (usage: -q sources). List all available sources. The format of the output is:
<source>:<NRTM_protocol_version_#>:<mirroring>:<first>-<last>
Where
<source> - is the string that identifies the Database
(e.g. AFRINIC); <NRTM_protocol_version_#> identifies the version of the mirroring protocol.
<mirroring> can take one of the following values:
-- Y/N/X - can mirror/cannot mirror/obscured
<first> is the lowest serial number available
<last> is the most recent serial number available.
The following semantics apply:
Y:<first>-<last> mirroring allowed, serials from range first-last available.
N:<first>-<last> mirroring not allowed for administrative reasons. Ask Database Administration for permission.
N:0-<last> mirroring physically not possible (e.g. static snapshot of serial last).
X:<message> no mirroring allowed. An explanation is given in the <message>.
Tables 1 to 6 contain all query types supported by the AFRINIC Database:
Table 1 Queries using primary and lookup keys
|
Flag |
Lookup Key(s) |
Effect |
|
<ip-lookup> (IPv4 address prefix, range or single address) |
Returns inetnum , route objects with exact match on the specified key. If the exact match does not exist, the objects with the smallest less specific match are returned. When a single address is specified, an inet-rtr object whose "ifaddr:" attribute matches the query argument is also returned. |
|
|
<ip-lookup> (IPv6 address or IPv6 prefix) |
Returns an inet6num object with exact match on a specified key. If the exact match does not exist, the object with the smallest less specific match is returned. |
|
|
<as-number> |
Returns an aut-num object whose "aut-num:" attribute matches the query argument and an as-block object with the range containing the aut-num object, if it exists. |
|
|
<As-number> - <as-number> (range of <as-number> separated by "-") |
Returns an as-block object whose primary key defines a range that matches or fully contains the range specified in the query argument. |
|
|
<domain-name> |
Returns domain and inet-rtr objects whose primary keys match the query argument. For domains, a referral query may be performed. In such case the actual query is performed by the referred server and the results are transparently passed to the client. See section 2.7 "Referral mechanism for domains" for more information. |
|
|
<irt-name> |
Returns an irt object whose primary key matches the query argument. |
|
|
<Person-name> |
Returns all person and role objects whose "person:" or "role:" attributes contain the name specified in the query argument. |
|
|
<set-name> |
Returns a set whose primary key matches the query argument. |
|
|
<nic-handle> |
Returns a person or role object whose "nic-hdl:" attribute matches the query argument. |
|
|
<mntner-name> |
Returns a mntner object whose primary key matches the query argument. |
|
Flag |
Lookup Key(s) |
Effect |
|
-l |
<ip-lookup> |
Returns first level less specific inetnum , inet6num or route objects, excluding exact matches. |
|
-L |
<ip-lookup> |
Returns all level less specific inetnum , inet6num or route objects, including exact matches. |
|
-m |
<ip-lookup> |
Returns first level more specific inetnum , inet6num or route objects, excluding exact matches. |
|
-M |
<ip-lookup> |
Returns all level more specific inetnum , inet6num or route objects, excluding exact matches. |
|
-x |
<ip-lookup> |
Requests that only an exact match on a prefix be performed. If no exact match is found, no objects are returned. |
|
-d |
<ip-lookup> |
Enables lookups on reverse delegation domains. Can be used with "-x", "-m", "-M", "-l" and "-L" flags. |
|
-c |
<ip-lookup> |
Returns the smallest, less specific inetnum or inet6num object containing the reference to an irt object. The result of this lookup is an inetnum or inet6num object and referenced contacts, if name recursion is not disabled ("-r" flag). It does not contain the referenced irt object, nor contact information about the team. Please refer to [11] for more information about the irt object. |
|
Flag |
Lookup Key(s) |
Effect |
|
-i ac |
<nic-handle> or |
Returns all objects whose "admin-c:" attributes match the query argument. |
|
-i ah |
<nic-handle> or |
Returns all limerick objects whose "author-c:" attribute matches the query argument. |
|
-i pn |
<nic-handle> or |
Returns all objects whose "admin-c:", "tech-c:", "zone-c:", "author:" or "cross-nfy:" attribute matches the query argument. |
|
-i ct |
<mntner-name> |
Returns all route and aut-num objects whose "cross-mnt:" attributes matches the query argument. |
|
-i cn |
<nic-handle> or |
Returns all route and aut-num objects whose "cross-nfy:" attribute matches the query argument. |
|
-i iy |
<e-mail> |
Returns all irt objects whose "irt-nfy:" attribute matches the query argument. |
|
-i la |
<as-number> |
Returns all inet-rtr objects whose "local-as:" attribute matches the query argument. |
|
-i mi |
<irt-name> |
Returns all inetnum and inet6num objects whose "mnt-irt:" attribute matches the query argument. |
|
-i mr |
<mntner-name> |
Returns all set objects ( as-set , route-set and rtr-set ) whose "mbrs-by-ref:" attribute matches the query argument. |
|
-i mo |
<set-name> |
Returns all objects whose "member-of:" attribute matches the query argument and their membership claim is validated by the "mbrs-by-ref:" attribute of the set. Absence of the "mbrs-by-ref:" attribute means that the membership is only defined by the "members:" attribute of the set. |
|
-i mb |
<mntner-name> |
Returns all objects whose "mnt-by:" attribute matches the query argument. |
|
-i ml |
<mntner-name> |
Returns all objects whose "mnt-lower:" attribute matches the query argument. |
|
-i mn |
<e-mail> |
Returns all mntner objects whose "mnt-nfy:" attribute matches the query argument. |
|
-i mu |
<mntner-name> |
Returns all aut-num , inetnum and route objects whose "mnt-routes:" attribute matches the query argument. |
|
-i ny |
<e-mail> |
Returns all objects whose "notify:" attribute matches the query argument. |
|
-i ns |
or (IPv4/IPv6 address) |
Returns all domain objects whose "nserver:" attribute matches the query argument. |
|
-i or |
<as-name> |
Returns all route objects whose "origin:" attribute matches the query argument. |
|
-i rb |
<mntner-name> |
Returns all mntner objects whose "referral-by:" attribute matches the query argument. |
|
-i rz |
or (IPv4/IPv6 address) |
Returns all inetnum and inet6num objects whose "rev-srv:" attribute matches the query argument. |
|
-i sd |
<domain-name> |
Returns all domain objects whose "sub-dom:" attribute matches the query argument. |
|
-i tc |
<nic-handle> or |
Returns all objects whose "tech-c:" attribute matches the query argument. |
|
-i dt |
<e-mail> |
Returns all mntner objects whose "upd-to:" attribute matches the query argument. |
|
-i zc |
<nic-handle> or <person-name> |
Returns all objects whose "zone-c:" attribute matches the query argument. |
Table 4 Query support for tools
|
Flag |
Lookup Key(s) |
Effect |
|
-F |
Produces output using shorthand notation for attribute names. Produces slower responses. |
|
|
-K |
Requests that only the primary keys of an object be returned. The exceptions are set objects, where the "members:" attributes will also be returned. This flag does not apply to person and role objects. |
|
|
-k |
(optional normal query) |
Requests a persistent connection. After returning the result, the connection will not be closed by the server and a client may issue multiple queries on the same connection. Note that the server implements a "stop-and-wait" protocol, where no next query can be sent before receiving a reply for the previous one. Use RIPE whois client to be able to send queries in batch mode. Except the first "-k query", "-k" without an argument closes the persistent connection. |
|
-g |
(mirroring request) |
Request a NRTM stream from the server. See section 4.0 "Mirroring of the RIPE Database" for more information. |
Table 5 Miscellaneous queries
| Flag | Argument |
Effect |
|
-R |
Switches off use of the referral mechanism for domain lookups, so that the database returns an object in the RIPE database with the exact match with the lookup argument, rather than doing a referral lookup. |
|
|
-r |
Switches off recursion for contact information after retrieving the objects that match the lookup key. |
|
|
-T |
(comma separated list of object types, no white space is allowed) |
Restricts the types of objects to lookup in the query. |
|
-a |
Specifies that the server should perform lookups in all available sources. See also "-q sources" query. |
|
|
-s |
(comma separated list of sources, no white space is allowed) |
Specifies which sources and in which order are to be looked up when performing a query. |
Table 6 Informational queries
|
Flag |
Argument |
Effect |
|
-q |
sources |
Returns the current set of sources along with the information required for mirroring. See section 2.9 "Other server features" for more information. |
|
-q |
version |
Displays the current version of the server. |
|
-t |
<object-type> |
Requests a template for the specified object type. |
|
-V<client-tag> |
Sends information about the client to the server. |
|
|
-v |
<object-type> |
Requests a verbose template for the specified object type. |
The following notations are used in this table:
<object-type> means full or abbreviated name of a specific class;
<client-tag> is a string without a white space that usually bears the name of the client's software.
Please refer to section 2.8 "Access control for queries" for more information about using this flag for proxy clients. Other notations are explained in Table A1.
2.0 Updates in the AFRINIC Database
To create a new object, update an existing one, or delete an object from the AFRINIC Database, an update message should be sent to the Database for processing. Two types of submissions are possible:
* Updates via e-mail which is the main public interface, and on-line;
* Updates via "networkupdate" interface. This method is internal, and is only used from authorised nodes; typically, nodes belonging to the internal office LAN of the AFRINIC.
2.1 Format of an update message
If sending the message via e-mail, the message may also be a MIME encoded message. The update is normally in plain text. In the former case, each valid MIME part is treated as a separate message. The update message may contain more than one object. Please see section 2.3.1 "MIME support" for more information.
In an update message an object should be textually represented as a list of attribute-value pairs. Each attribute-value pair is written on a separate line. The attribute name starts at column 0, followed by character ":" and followed by the value of the attribute. The attribute, which has the same name as the object's class, should be specified first. An attribute's value can be split over multiple lines, by having a space, a tab or a plus ("+")
character as the first character of the continuation lines. The character "+" for line continuation allows attribute values to contain blank lines. More spaces may optionally be used after the continuation character to increase readability. The order of attribute-value pairs is significant. No empty attributes (an attribute with empty value) are allowed, unless the type of an attribute value is <free-form>. Object definition starts with the
class attribute and ends with the first blank line ("\n\n"). No blank lines are allowed within the object.
An object's definition may contain comments. A comment can be anywhere in an bject's definition, it starts at the first "#" character on a line and ends at the first end-of-line character. A comment cannot start at column 0. White space characters can be used to improve readability.
For more information on the format of the objects, please see document "AFRINIC Database bjects and attributes".
Each part of the message that is not recognised as a database object is ignored and the error message is issued in the acknowledgement.
2.2 Creating, modifying and deleting an object
To create, update or delete objects, a message containing the objects should be prepared following object templates and sent to the database for processing. One message may contain several objects, each of them may require different operation: creation, modification or deletion.
2.2.1 Object processing
As a general rule, the order of objects in the message is not changed. The database processes objects one by one, so it is the user's responsibility to ensure that all references can be resolved. The only exception is related to using "AUTO" NIC handles for automatic assignment of a value for the "nic-hdl:" attribute in the person or role objects. In such cases, objects with "AUTO" NIC handles are processed before any other object that can reference them is processed.
While processing an object, the server performs the following checks:
- Verifies that the syntax of an object is correct.
- Verifies that the object passes authorisation checks.
- Verifies that all references can be resolved without conflicts.
- Verifies that the operation does not compromise referential integrity. This is performed for the deletion of an object to ensure that it is not referenced from any other object in the AFRINIC Database.
- Verifies that the requested NIC handle is not in use and can be allocated. This is performed only for the creation of person or role objects that request a particular NIC handle.
If all checks were passed successfully, the server creates the object in the AFRINIC Database. If one of these steps fails, the operation fails for the object. This is reflected in the acknowledgement message and, under certain conditions, in notification messages.
After the database finishes processing the whole message, an acknowledgement message is composed and sent to the sender of the original update as specified in the "Reply-to:" field or "From:" field in the update message, if "Reply-to:" was not specified.
Also in some cases, notification messages are sent. Please see section 2.5.2 Notifications" for more information.
2.2.2 Creating a new object
If an object with the same primary keys as the object in the update message does not exist in the database, the assumed operation is object creation. For person and role objects creation, one can use "AUTO NIC handles", requesting the server to automatically assign a NIC handle. In such case, the value of the "nic-hdl:" attribute should be:
nic-hdl: AUTO-1[<initials>]
If the <initials> (2 to 4 characters) are specified, then the server will try to use them for constructing the NIC handle. If the <initials> are omitted, the server will guess the initials from the "person:" or "role:" attribute.
2.2.3 Modifying an existing object
If an object with the same primary keys as the object in the update message already exists in the database, the assumed operation is object modification. The server compares the old and new versions of the object and reports a no-operation error if they are identical. When comparing the versions, white space characters are not considered.
2.2.4 Deleting an object
The object deletion is requested by adding a special attribute "delete:" to the object:
delete: <comment>
The deletion is only accepted if the object in the message is exactly the same as the one in the database about to be deleted. When comparing the versions, white space characters are not considered. Also, operation cannot succeed if the object is referenced from any other objects in the Database.
2.3 E-mail updates
A mail message containing an update should be sent to the e-mail address of the AFRINIC Database robot: auto-dbm@AFRINIC.net. After processing the message, an acknowledgement is sent back to the user, containing information about which object updates succeeded and which failed, along with the reason for failure. In some cases notification messages are sent to relevant users. Please see section 3.5.2 "Notifications" for more information.
2.3.1 MIME support
The Database software supports MIME. This feature is meant mainly to make the cryptographic signing of the message easier when using mail agents that place the signature in a separate MIME part, not included in the body of the message.
It also allows the definition of scopes of authorisation within the message (e.g. parts where different passwords apply) and nested signing of messages which may be necessary under some conditions when updating objects whose authorisation must be derived from more than one party.
The following rules apply when submitting updates using MIME encapsulation.
A. The software recognises the following headers and appropriate actions are taken:
- multipart/signed
- multipart/alternative
- multipart/mixed
- multipart/unknown
- application/pgp-signature
- text/plain
All other content-types are treated as text/plain.
B. Each MIME part is treated as a separate message with the following implications:
- Authorisation information is valid only within a single part, except for MAIL-FROM type, which is valid across the entire message.
- AUTO NIC handle assignment is made only within a single part (see next section 2.3.2 "PGP support").
2.3.2 PGP support
The Database supports PGP-signed messages. The following rules apply when submitting updates using this authorisation scheme.
When using MIME encapsulation a PGP-signed portion of an update message should be submitted using multipart/signed composite type. In this case the first body part contains the update message (which may also be a MIME encapsulated message), and the second body contains a PGP-signature encapsulated with application/pgp-signature MIME discrete type. Regarding AUTO NIC handle assignment, the PGP-signed portion is treated as a separate message. If one of the signatures fails in a nested signed portion, the whole portion is rejected.
2.3.3 Subject line processing
The three keywords valid in a subject line of an update message are NEW, HELP and HOWTO. Use NEW keyword by itself if you want the database to only accept new objects. HOWTO and HELP keywords can be used to get a help text that contains information about how to query and update the database (in this case the body of the message is ignored). If there is more than one keyword or there is a non-keyword in the subject line, then all the subject line is ignored.
2.4 Updates using networkupdate utility
No MIME encapsulation is possible when using networkupdate. No PGP authentication is possible when using networkupdate.
2.5 Acknowledgements and Notifications
2.5.1 Acknowledgements
Processing of every valid object in the submission message (that is every object in plain text parts, supported MIME parts and/or valid PGP signed portions) is reflected in the acknowledgement message. This message contains information about whether the creation, modification or deletion has been successful or not. When there is a MIME part with an unsupported type in the incoming message, a warning will be added to the acknowledgement, saying that that MIME part is ignored. The acknowledgement message is sent back to the sender's e-mail address ("Reply-To:" or "From:", if the former is not specified).
The acknowledgement message starts with the header of the original update message as a quotation followed by the results of the updates performed for every valid object of the message.
The format of a successful operation report is:
<operation_name> OK: [ <object_type> ] <object_key>
where
<operation_name> may be New, Update, Delete, depending on the operation performed.
<object_type> is the class of the object that was processed.
<object_key> is the primary key of the object.
For example:
Update OK: [person] FOO12770-AFRINIC
Failed updates are reported as:
<operation_name> FAILED: [ <object_type> ] <object_key>
followed by the text of the object with more detailed explanation of what caused the failure.
There are several reasons why the operation may fail for the object. They are:
- syntax error
The submitted object is syntactically incorrect. Please consult Appendix A1 for the description of attributes. - referential integrity violation
If an object references objects (by means of "admin-c:", "tech-c:", "zone-c:", "mnt-by:", etc. attributes) that do not exist in the database, creation or modification operations will fail. For the deletions, it is not allowed to delete an object that is referenced from any other object. - authorisation failure
When authorisation checks fail, the operation fails. Please refer to section 2.6 "Data Protection" for more information.
2.5.2 Notifications
There are three types of notifications:
- normal notifications
- forward messages
- cross notifications.
2.5.2.1 Normal notifications
Normal notifications are sent:
- when an object with a "notify:" attribute is updated. The "notify:" attribute of the old version of the object is used if the object was already in the database, and the "notify:" attribute of the new object is used if the object is a new one.
- when an object that is maintained (that is, it has a "mnt-by:" attribute) is updated, and the maintainer(s) have "mnt-nfy:" attributes. The e-mail boxes mentioned in the "mnt-nfy:" attributes of the relevant maintainers must be used.
- When an inetnum, route or a domain object is created in a space protected by a less specific object (by "mnt-lower:" attribute of the object).
- when a reference to an irt object is added to or removed from an inetnum or inet6num object (by means of "mnt-irt:" attribute), and the irt object contains an "irt-nfy:" attribute(s). The e-mail boxes mentioned in the "irt-nfy:" attributes are used.
2.5.2.2 Forward messages
When an update fails to pass authorisation checks, that object in the update message is forwarded to the e-mail address specified in the "upd-to:" attribute of the relevant maintainer(s).
2.5.2.3 Cross notifications
Cross notifications are sent:
- when a new or deleted route object overlaps with another route object. A notification will be sent to the sender of the route object.
- When a new or deleted route object overlaps with another route object that has a "cross-nfy:" or "cross-mnt:" attribute. Notification must be sent to the "mnt-nfy:" attributes of the maintainers mentioned in the "cross-mnt:" attribute and to the "e-mail:" attributes of the person and role objects whose NIC handle is mentioned in the "cross-nfy:" attribute of the overlapping route objects.
- When a new or deleted route object overlaps with another route object whose "origin" is an aut-num object that has "cross-nfy:" or "cross-mnt:" attributes. Notification must be sent to the "mnt-nfy:" attributes of the maintainers mentioned in the "cross-mnt:" attribute and to the "e-mail:" attributes of the person or role objects whose NIC handle is mentioned in the "cross-nfy:" attribute of the aut-num object.
2.6 Data protection
The AFRINIC Database provides mechanisms to control who can make changes in the database and what changes they can make. The distinction of "who" vs. "what" separates authentication from authorisation.
- Authentication is the means to determine who is attempting to make a change.
- Authorisation is the determination of whether a transaction passing a specific authentication check is allowed to perform a given operation.
Different portions of the database require different levels of protection. Some pplications require authentication based on strong encryption. In other cases strong encryption may not be necessary or may not be legally available. For this reason, multiple authentication methods are supported by the server.
2.6.1 Authorisation model
The mntner objects serve as a container to hold authentication filters. A reference to a maintainer within another object defines authorisation to perform operations on the object or on a set of related objects. Such reference is provided by means of the "mnt-by:", "mnt-lower:", "mnt-routes:" and "mbrs-by-ref:" attributes. The maintainer contains one or more "auth:" attributes. Each "auth:" attribute begins with a keyword identifying the authentication method followed by the authentication information needed to enforce that method.
When submitting an update that requires authorisation from a mntner, authentication information valid for that mntner should be supplied. Different methods require different authentication information, as will be shown below.
Authentication methods currently supported include the following:
Method / Description
NONE
No authorisation checks are performed.
MAIL-FROM*
This is a very weak authentication check and is discouraged. The authentication information is a regular expression over ASCII characters. The maintainer is authenticated if the "From:" field in RFC 822 mail headers are matched by this regular expression. Since mail header forgery is quite easy, this is a very weak form of authentication.
CRYPT-PW
This is a relatively weak form of authentication. The authentication information is a fixed encrypted password in UNIX crypt format. The maintainer is authenticated if the transaction contains the clear text password of the maintainer. Since the password is in clear text in transactions, it can be captured by snooping. The encrypted form of the password is no longer displayed in the output of a query,in order to protect it from password guessing attacks. Authentication information is supplied using a "password:" pseudo-attribute. The value of this attribute is a clear-text password. It can appear anywhere in the body of the message, but not within mail headers. Line continuation is not allowed for this attribute.
MD5-PW
This scheme is based on the MD5 hash algorithm and provides stronger authentication than CRYPT-PW. The authentication information stored in the database is a passphrase encrypted using md5-crypt algorithm, which is a concatenation of the "$1$" string, the salt, and the 128-bit hash output. Because it uses 8-character salt and an almost unlimited passphrase, this scheme is more stable against dictionary attacks. The encrypted form of the password is filtered from whois query output to protect it from cracking attacks. Authentication information is supplied using a "password:" pseudo-attribute. The value of this attribute is a clear-text passphrase. It can appear anywhere in the body of the message, but not within mail headers. Line continuation is not allowed for this attribute, the attribute and the passphrase should fit on one line. If the key gets split across multiple lines this will be treated as a syntax error.
PGPKEY
Strong form of authentication. The authentication information is a signature identity pointing to a public key certificate, which is stored in a separate object. The maintainer is authenticated if the transaction is signed by the corresponding private key. AFRINIC does not guarantee that a key belongs to any specific entity; it is not a certificate authority. Anyone can supply any public keys with any ownership information to the database and these keys can be used to protect other objects by checking that the update comes from someone who knows the corresponding secret key.
* MAIL-FROM authentication scheme is not valid in the AFRINIC Database.
2.6.2 Protection of individual objects
Individual objects can be protected with a mntner object. The mntner is referenced by the "mnt-by:" attribute in the object. The attribute type is multiple, so several mntners can protect the object. Only those mntners referenced by the "mnt-by:" attributes are authorised to modify or delete the object. Note that authentication checks are OR-ed, so if at least one mntner is authenticated, the operation is authorised. That means that object protection is as weak as the weakest authentication method used in the mntners referenced by the object. When the "mnt-by:" attribute is added to an object for the first time (as part of object creation or modification), the operation should pass authentication checks for the mntner(s) referenced by this attribute.
2.6.3 Protection of aut-num object space
Protection of aut-num object space is done using an as-block class. The mntner that authorises the creation of more specific as-block objects or aut-num objects is specified by the "mnt-lower:" attribute of the as-block object. When no "mnt-lower:" attribute is specified, the "mnt-by:" attribute is used.
2.6.4 Protection of address space
Address space allocations and assignments are represented by the inetnum and inet6num objects. The "mnt-lower:" attribute is used to reference a mntner that authorises the creation of more specific inetnum or inet6num objects. When no "mnt-lower:" attribute is specified, the address space is unprotected.
2.6.5 Protection of objects with hierarchical names
Many RPSL objects do not have a natural hierarchy of their own but allow hierarchical names. Some examples are the object types as-set and route-set. An as-set may have a name corresponding to no naming hierarchy such as "AS-Foo" or it may have a hierarchical name of the form "AS1:AS-BAR". When a hierarchical name is not used, authorisation for objects such as as-set and route-set corresponds to the rules for individual objects described in section 3.6.2 "Protection of individual objects".
If hierarchical names are used, then the addition of an object must be authorised by the object whose key is named by everything to the left of the rightmost colon in the name of the object being added.
Authorisation is determined by first using the "mnt-lower:" maintainer reference or, if absent, by using the "mnt-by:" reference.
2.6.6 Protection of domain object space
Protection of the domain object space is done with the "mnt-lower:" attribute. When used in the domain object, this attribute references the mntner that authorises the creation of domain objects directly below in the domain tree registered in the AFRINIC Database. For example, a top-level domain object (ccTLD) protects the creation of the second-level domain objects, third-level domain objects if there is no corresponding second-level domain object, etc. Note that the top-level domain object (ccTLD or gTLD) cannot be created in the AFRINIC Database by users, only by the Database administrator.
2.6.7 Protecting membership of a set
When membership of a set is specified through the use of the "member-of:" attribute, the server checks the validity of the membership when creating or updating an object-member. This "member-of:" attribute can be used in the route, aut-num and inet-rtr classes. The value of the "member-of:" attribute identifies a set object that this object wants to be a member of.
However, specifying "member-of:" is not enough. The set object must also have a "mbrs-by-ref:" attribute listing the maintainer of the object wanting to be a member of the set. That is, the set owner must validate the membership claim of an object with a "member-of:" attribute, and it does that by matching the mnt-by line of the object with one of the maintainers in the "mbrs-by-ref:" attribute of the set object. If the claim is not valid at the time when the server creates or modifies an object-member (route, aut-num or inet-rtr), the operation fails. If the "mbrs-by-ref:" attribute is missing, the set is defined explicitly by the "members:" attribute.
3.0 Mirroring of the AFRINIC Database
Near real time mirroring (NRTM) is a mechanism that enables whois servers, other than the primary for a given database, to have an up to date copy of all the data in the main server by getting modifications as they are processed by the main server.
Periodically (defined by configuration, usually around every 15 minutes) the remote server connects to the main server and requests all the modifications that have been processed since the last connection. When all the data is retrieved the connection is closed, until it is time for a new connection.
In AFRINIC Database the NRTM server listens on a port that is different from the whois port (43).
The AFRINIC whois server generates a sequence number every time it processes an update in the database. For the purpose of generating this serial numbers, the server describes all modifications to the database in terms of two atomic operations: deletion and addition.
When sending data to a mirror server, the main server will send one of two strings (ADD or DELETE) followed by two newline characters and the corresponding object (either the object as it was before deletion or the object as it should be added or modified). If the "ADD" string is followed by an object already existing in the database, then this operation is considered as a modification. Near real time mirroring is requested with the "-g" flag. The arguments to this flag are:
-g < source> :<NRTM_Protocol_version_#>:<first>-<last>
where
* <source> is the string that identifies the Database (e.g. AFRINIC).
* <NRTM_protocol_version_#> a version of the mirroring protocol that the <source> supports (2 for AFRINIC).
* <first> is the lowest serial number requested.
* <last> is the most recent serial number requested or the keyword LAST that tells the main server to send all updates up to the most recent one available at the time of the query. Note that the server will never yield the last object processed, or display that it is available for mirroring. This is done to protect secondary servers in case the last update causes database corruption and server crash.
A client may request a persistent connection by including the "-k" flag with a mirroring request ("-g" query). In this case, the last argument is ignored and the new objects are supplied by the server as soon as they are processed. The client is responsible for closing the connection.
The "-q sources" flag may be used with the mirror server to retrieve information regarding available mirroring possibilities. Please see section 2.9 "Other server features" for more details.
Note that the server never returns the latest serial when serving a mirroring request. So, if the latest serial causes a server crash and database corruption, it never propagates to the secondary servers. The latest serial is not displayed with the "-q sources" query as well.
At the beginning of the data stream, the main server will send the following string:
%START Version: NRTM_Protocol_version_# source first-last
For example: %START Version: 2 AFRINIC:1539595-1539597
After the last piece of data is sent to the mirror server, the main server will send the string:
%END source to signal the end of transmission.
For example:
%END AFRINIC