------------------------------------------------------------------- APNIC Document identity Title: APNIC Registry Database Record Addition, Modification and Deletion Instructions Short title: database-update-info Document ref: APNIC-067 Version: 001 Date of original publication: August 1998 Date of this version: August 1998 Review scheduled: n/a Obsoletes: APNIC-057 Status: Obsolete Comments: Obsoleted by upgrade of the APNIC Whois Database to RIPE v3 database software on 20 August 2002. See APNIC-101. -------------------------------------------------------------------- APNIC Registry Database Record Addition, Modification and Deletion Instructions 1. Introduction --------------- The APNIC Registration database is based on software originally written at the European registry, RIPE-NCC. Each record in the database is composed of a series of fields separated by one or more blank lines with each field consists of two parts, the "tag" and the "value". You should not modify the tags as they appear in the fields or errors will be returned when you submit your update. Values for particular fields are specified in templates and care must be taken to insure appropriate values are specified. The first line of a template denotes the record type, e.g., an Internet address template's first line is 'inetnum', thus the record is known as an "inetnum object". This first line is also used as the primary key for the record, thus should you wish to modify the first field of the record, the only possible way to do so will be to delete the record entirely and add a new record with the corrected information. These instructions describe how to add, modify, or delete records in the APNIC Registry Database. Electronic requests will be processed immediately unless the database is being re-indexed in which case your request will be queued until the indexing finishes. If you do not receive a response from the APNIC Database system within 24 hours, please contact APNIC apnic-dbm@apnic.net. 2.0 Creating a new object ------------------------- To create a new object, follow this procedure: * obtain the template; * modify the template; * send the object to the appropriate mailbox, i.e. for new autonomous system objects, for new 'mntner' objects and for all other objects. (1) Obtain the template: Use 'whois -h whois.apnic.net "-t "' to obtain a template describing the fields of an object, for example: % whois -h whois.apnic.net "-t person" person: [mandatory] [single] [primary/look-up key] address: [mandatory] [multiple] [ ] country: [optional] [single] [ ] phone: [mandatory] [multiple] [ ] fax-no: [optional] [multiple] [ ] e-mail: [optional] [multiple] [look-up key] nic-hdl: [optional] [single] [primary/look-up key] remarks: [optional] [multiple] [ ] notify: [optional] [multiple] [inverse key] mnt-by: [optional] [multiple] [inverse key] changed: [mandatory] [multiple] [ ] source: [mandatory] [single] [ ] The template description returned by the whois server indicates if the field is required (mandatory) or not (optional) and how many occurrences of the field there can be in a template, either [single] indicating exactly one of these fields may exist in a template or [multiple] indicating more than one may exist in a template (the last column describes how the field is indexed and not discussed further here). In the example given above, there can be exactly one "person" field in a person object, however there can be 0 or more "fax-no" fields (that is, the fax-no field is optional). You may also find specific templates with descriptions of their fields in the various application forms (e.g., isp-address-request, maintainer-request, etc.) (2) Modify the template: Once you have a template, fill in the appropriate details. Do not leave attributes with values such as "[optional]", or "[multiple]" in the template you submit as they will result in errors. You can either delete the optional fields you do not need or you can leave them empty. Fields which are mandatory should NOT be left blank or deleted, otherwise the update will be rejected by the database software. Example: person: David Conrad address: Asia Pacific Network Information Center address: Level 1, 33 Park Road address: P. O. Box 2131 address: Milton, QLD 4064 phone: +61-7-3367-0490 fax: e-mail: davidc@apnic.net [.....stuff deleted.....] changed: davidc@apnic.net 19980307 source: APNIC The empty attribute "fax" will be deleted by the database software. Attributes which are described in the template as "single" must be on only one line. Attributes which are described as "multiple" may be on more than one line, but the attribute name must be at the beginning of each line. The "address" attribute in the person object is an example of an attribute that may be multiple. person: David Conrad address: Asia Pacific Network Information Center address: Level 1, 33 Park Road address: P. O. Box 2131 address: Milton, QLD 4064 [...] If you are completing a person template or want to reference a person in an another object, you should use a NIC handle ('nic-hdl:'). NIC-handles will give you a unique identifier attached to a person which you can use as a reference. This avoids problems with different persons having the same name. You can obtain an APNIC NIC-handle by putting the following in the NIC handle field: nic-hdl: AUTO-1 (that's a one, not an 'ell'). This will result in the database software deriving your first and last initial and creating an APNIC handle from those initials. For example, if you submitted the following person object: person: David Conrad address: Asia Pacific Network Information Center address: Level 1, 33 Park Road address: P. O. Box 2131 address: Milton, QLD 4064 country: AU [...] nic-hdl: AUTO-1 [...] the database software would generate a NIC handle of the form DC###-AP where ### is the next available number that insures the NIC handle starting with DC generated is unique. Alternatively, you can specify the initials to use as the prefix for the handle instead of having the database software generate them itself. If you specify the nic-hdl as: nic-hdl: AUTO-1 where (without the '<' and '>') are no more than 4 characters, the database software will use those initials to create the handle. For example: person: David Conrad address: Asia Pacific Network Information Center address: Level 1, 33 Park Road address: P. O. Box 2131 address: Milton, QLD 4064 country: AU [...] nic-hdl: AUTO-1RC [...] the database software would generate a NIC handle of the form RC###-AP where ### is the next available number that insures the NIC handle starting with RC. You can use the same identifiers (AUTO-1 or AUTO-1) in the same update message in other objects as a reference. The database software will then fill in the freshly assigned NIC handles in the objects. Note that you can also use other numbers (example: AUTO-2) so that you can update more person objects and objects that reference the persons in one E-mail message. For example: inetnum: 202.12.28.0 - 202.12.28.255 [...] admin-c: AUTO-1 tech-c: AUTO-2 [...] person: David Conrad [...] nic-hdl: AUTO-1 [...] person: Yoshiko Chong [...] nic-hdl: AUTO-2 [...] will result in two new handles being created, one of the form DC###-AP filled in for the admin-c and David Conrad's nic-handle fields and the other, YC###-AP filled in for the tech-c and Yoshiko Chong's nic-hdl fields. Next, put today's date and your e-mail address in the "changed" attribute. The format of the date should be YYYYMMDD (YYYY = year, MM = month, DD = day, e.g., 19980307 would mean March 7, 1998). Optionally, but highly recommended, you can protect your objects with maintainer objects by adding a `mnt-by:' attribute. For some objects this is even mandatory. Put the name of the maintainer object in the "mnt-by" field and, if necessary, supply the (plain text) password that allows for updates of the object. For example: person: David Conrad [...] mnt-by: MAINT-DRC password: YeahRite [...] Note that if you do not use a maintainer object, the objects you submit to the APNIC database can be modified by anyone. Also, please note that you cannot update objects not protected with a AUTH CRYPT-PW maintainer object via the APNIC Web interface. (3) Send the object to the appropriate mailbox. When you have finished modifying your template, you must submit it to the appropriate mailbox at APNIC. In most cases, this will be , however if you are submitting a new maintainer request or a new autonomous system number request, you'll need to submit it to or respectively. You can insure that the database will only accept your object if it is not already in the database by using the keywords "NEW" and "ASSIGN". Put "NEW" in the `Subject' line of your e-mail if you want the database to only accept new objects. Use the keyword "ASSIGN" if you want the database to only accept new inetnum objects. Note: at the moment, these keywords are case insensitive. Avoid putting strings such as "Old person object with new address" or "Re-assign address space" in your "Subject" line as your update may be rejected inadvertently. If you require a detailed acknowledgement, put the keyword "LONGACK" in the `Subject' line of your e-mail. You will always receive an acknowledgement, even if "LONGACK" is not in the `Subject' line. If you do not receive an acknowledgement, the reason could be that your e-mail address is unknown and therefore the acknowledgement mail has bounced or has been lost. If the e-mail address is correct, it is possible your update arrived during the periodic database cleanup procedure done nightly (around 3 AM JST). If you submitted your request at the wee hours of the morning and do not receive a response within a couple of hours, please contact to determine the status of your update. 3. Updating an existing object ------------------------------ To update an existing object, you will need to send in a new object containing the changes and all the unchanged fields from the existing object. Probably the easiest way to do this is to get a copy of the old object, change or add the fields you want to change or add, and then put a new 'changed:' attribute in the object. Here are the steps in more detail: (1) Get a copy of the existing object; you can do this using % whois -h whois.apnic.net > Example: % whois -h whois.apnic.net DC23-AP > update-file (2) Load the into your favorite editor and make your changes or additions to the object. If you are updating a person or role object with a new or different NIC handle, or if you are updating a route object with a new or different origin, please note that it is wise to delete the old person, role or route object before adding the new objects for the following reasons: (a) the database will treat two person objects with the same name but with different NIC handles, as different objects; (b) the database will treat two person objects with the same name as different objects, if one object has a NIC-handle, but the other does not; (c) the database will treat route objects with the same "prefix length" representation, but with different origins as different route objects; (d) the database handles role objects in the same way as it handles person objects. If you do not delete the old objects first, then the database will see the old and new objects as different objects and the update request will be treated as the creation of a new object instead of an update of the old object. The database will however recognize that a person object is an update if the only difference between the old and new object is that the old object did not have a NIC handle. (3) Add a "changed" attribute. This attribute has the following syntax: changed: where is an RFC822 e-mail address specifying who made the change and is the date of the change in YYYYMMDD format. (4) Send your message to . Note that if the object you are trying to delete is protected by a maintainer object, you'll need to supply the appropriate password or other authentication information. (5) You will receive an acknowledgement. If you send in an object that is identical to one that is already in the database, the acknowledgement message will say "NOOP" meaning "NO OPeration"; i.e. the object in the database is not modified. 4. Deleting an object --------------------- To delete an object, send in the object you wish to delete just like an update and adding a special attribute "delete" to it. The delete attribute has the following format: delete: and it is recommended that the reason for deleting the object be put as the value of the delete attribute. Note that if the object you are trying to delete is protected by a maintainer object, you'll need to supply the appropriate password or other authentication information. Example: person: David Conrad address: Asia Pacific Network Information Center address: Level 1, 33 Park Road address: P.O. Box 2131 address: Milton, QLD 4064 country: AU e-mail: davidc@apnic.net nic-hdl: DC99-AP mnt-by: MAINT-DRC changed: davidc@apnic.net 980307 source: APNIC delete: duplicate person object password: YeahRite A deletion request is only accepted if the object in the message exactly matches the version in the database. The easiest way to insure this is to obtain the object to be deleted by querying the whois server for the object, saving the returned object to a file, adding the delete attribute to that file and then sending that file to . Note: be very careful when deleting person or role objects unless you are sure that the person or role object is not referenced by other objects. You can find objects that reference a certain person by doing an inverse query with the '-i' option, e.g.,: % whois -h whois.apnic.net -r -i tech-c,admin-c,zone-c DC23-AP If you're not sure that you were the only one referencing a certain person object, do NOT delete that person object. It will not affect the database very much if there are some obsolete person objects. 5. Warning and Error Messages ----------------------------- The syntax of all objects sent to is rigorously checked. Acknowledgement messages are generated by these syntax checks. (a) You will always receive an acknowledgement that your update has been received. (b) If there are no mistakes in your update, you will receive an acknowledgement message saying "No errors were found in your update". (c) Minor, but not fatal mistakes will be corrected and the object will be accepted into the database. The acknowledgement message will indicate what correction was made. For example, suppose this object is sent to : person: David Conrad [.....stuff deleted.....] changed: davidc@apnic.net The following warning message would be generated: WARNING: added current date to "changed" field. (d) Fatal mistakes will NOT be corrected and the object will NOT be accepted into the database. An acknowledgement message will be sent, which will identify the error. For example, suppose this object is sent to : route: 202.12.28.129/32 descr: teckla.apnic.net origin: AS4777 changed: davidc@apnic.net 19980307 source: APNIC The following warning message would be generated: -------------------------------------------------------- Update FAILED: [route] 202.12.28.129/32 route: 202.12.28.129/32 descr: teckla.apnic.net origin: AS4777 changed: davidc@apnic.net 19980307 source: APNIC *ERROR*: mandatory field "mnt-by" missing Objects that just generated a WARNING have been updated as shown. Objects that generated an *ERROR* have NOT been updated as requested. Please re-submit corrected objects. ------------------------------------------------------- (e) If you have any questions about any error messages, you may send e-mail to . This mailbox is checked regularly. Please send as much information as possible. 6. Authorization and Authentication ----------------------------------- Currently, the APNIC Database authorization and authentication mechanisms use the "Maintainer Object" described in ftp://ftp.apnic/apnic/docs/maintainer-request. Prior to the modifications or deletions being processed, the APNIC database software will check the MNT-BY fields of the object to be updated and apply the appropriate authenticity verification mechanisms defined in that object. Note that these verification mechanisms are far from fool proof and are primarily intended to defeat accidental erroneous updates -- they should not be relied upon to securely protect records. You should periodically review records you have registered within the APNIC database and notify APNIC should you detect anything amiss. APNIC maintains extensive update logs to help track down erroneous updates should this be necessary. For more information on the APNIC "Maintainer Object", please see ftp://ftp.apnic.net/apnic/docs/maintainer-request 6.0 Acknowledgements -------------------- This document in derived in large part from documents written by the staff of the European Registry, RIPE-NCC . In addition, the software APNIC uses is derived from software developed by RIPE-NCC.