------------------------------------------------------------------- APNIC Document identity Title: Updating information in the APNIC Whois Database Short title: database-update-info Document ref: APNIC-101 Version: 001 Date of original publication: 17 December 2002 Date of this version: 17 December 2002 Review scheduled: n/a Obsoletes: APNIC-067 Status: Active Comments: n/a -------------------------------------------------------------------- Updating information in the APNIC Whois Database Table of contents ----------------- 1. Introduction 1.1 Adding comments and space to make objects more readable 1.2 Creating, updating, and deleting objects in the APNIC Whois Database 2. Creating a new object 2.1 Obtain the object template 2.2 Complete the template 2.3 Send the object to the appropriate mailbox 2.3.1 Preventing new objects overriding similar existing objects 2.4 Special cases 2.4.1 person object 2.4.2 maintainer object 3. Updating an existing object 3.1 Obtain a copy of the existing object 3.2 Update the object template 3.3 Add a new changed attribute to the object 3.4 Send the object to the appropriate mailbox 3.5 Special cases: person, role, mntner, and route objects 3.5.1 person and role objects 3.5.2 mntner objects 3.5.3 route objects 4. Deleting an object 4.1 Special cases: person, role and mntner objects 5. Sending emails to the database 5.1 MIME support 5.2 PGP support 5.2.1 PGP and MIME encapsulation 6. Protecting objects in the APNIC Whois Database 6.1 Authentication and authorisation 6.2 Using maintainer objects to protect other objects 6.3 inetnum and inet6num 6.4 as-block 6.5 aut-num 6.6 route 6.7 domain 6.8 inet-rtr 6.9 set objects 6.9.1 as-set 6.9.2 route-set 6.9.3 peering-set 6.9.4 filter-set 6.9.5 rtr-set 7. Troubleshooting 7.1 Using keywords in emails to 7.2 Receiving acknowledgement messages 7.3 Correcting errors 7.3.1 Messages to the email address that submitted the object 7.3.2 Messages to maintainers/notify contacts 8. Further reading 1. Introduction _____________________________________________________________________ The APNIC Whois Database, based on RIPE v3 database software, stores information as "objects". Objects can store information about: - IP address ranges - routing policies - reverse DNS delegations - network contact information Numeric Internet resources must be properly and accurately registered in the APNIC Whois Database to fulfill the goals of global addressing policy. For more information, see section 10.3 of Policies for address space management in the Asia Pacific region. In addition, the APNIC Whois Database can be to assist with network troubleshooting and to reduce the incidence of network abuse. Therefore it is important to ensure that contact details registered in the database are up to date. Networks are responsible for ensuring that all their objects in the database are updated as needed. Objects are composed of standard attribute tags and values. Attribute tags must never be changed, as this will result in errors when those changes are submitted to the database. Values for particular attributes are specified in templates. Please take care to ensure appropriate values are specified in each template you submit. The object template includes information on how to complete the attribute values. Attribute Description prompts --------- ----------- * Attribute status: Mandatory Attribute must be included in the object. Failure to do so will result in errors. Optional Attribute may be omitted from the object. To omit an optional attribute you must also delete the attribute tag from the object template. Failure to do so will result in errors. Generated Attribute value is generated by the database. * Instances of attribute allowed: Single Attribute must appear only once in the object. Multiple Attribute may appear multiple times in the object. For example, you may wish to include more than one admin-c attribute. * Attribute search status: Primary key Primary keys distinguish an object from all other objects in the database. To update a primary key, you must to delete the entire object and then create a new object with the updated information. Lookup key Attribute can be queried in the database to return the object. Please note, however, that a lookup key does not uniquely identify an object. Inverse key Attribute can be used when performing an inverse query using the -i flag. For example, the query -i mntner will return all objects with the specified maintainer in the mnt-by attribute. 1.1 Adding comments and space to make objects more readable --------------------------------------------------------------- To help make objects easier to read and understand, it is possible to split an attribute over more than one line or add explanatory comments. Option Description ------ ----------- Space Use the space character to add extraspaces to the beginning of additional lines used for an attribute. Example: remarks: Send spam and abuse reports to Note: You cannot use space characters to add extra characters to the beginning of a first line of an attribute. Tab Use the tab character to indent additional lines of an attribute. Example: remarks: Send spam and abuse reports to + (plus Use the plus character to add blank lines within an character) attribute. Example: remarks: + Send spam and abuse reports to + + + Note: If you do not include the plus character, the database software will assume it has reached the end of the object. Any remaining attributes will be treated as a separate object. # (hash Use the hash character to insert explanatory character) comments into an object. The hash character can appear anywhere after the name of the attribute. Example 1: email: address1@example.net #preferred contact email: address2@example.net Example 2: email: # -- preferred contact -- # address1@example.net + email: # -- secondary contact -- # address2@example.net + 1.2 Creating, updating, and deleting objects in the APNIC Whois Database ------------------------------------------------------------------- There are two ways to create, update, or delete objects in the APNIC Whois Database: - Web-based forms - Email messages To update objects via web-based forms, please follow the instructions that accompany the web-based forms. Web-based forms exist for the following objects: Object URL ------ --- inetnum http://www.apnic.net/apnic-bin/inetnum.pl person http://www.apnic.net/apnic-bin/person.pl maintainer http://www.apnic.net/apnic-bin/maintainer.pl aut-num http://www.apnic.net/db/aut-num.html domain http://www.apnic.net/db/domain.html The rest of this guide explains how to use emails to create, update, and delete database objects. 2. Creating a new object _____________________________________________________________________ To create a new object via email, you must: - Obtain the object template - Complete the template - Send the object by email to the appropriate mailbox 2.1 Obtain the object template ---------------------------------- Query the APNIC Whois Database using the -t or -v flags to obtain a copy of the object template. Flag Description ---- ----------- -t returns the object template only -v returns the object template and descriptions about object attributes Example of a web-based whois query: -t person Example of command line whois query: whois -h whois.apnic.net -t person Example of an object template: person: [mandatory] [single] [lookup key] address: [mandatory] [multiple] [ ] country: [optional] [single] [ ] phone: [mandatory] [multiple] [ ] fax-no: [optional] [multiple] [ ] e-mail: [mandatory] [multiple] [lookup key] nic-hdl: [mandatory] [single] [primary/look-up key] remarks: [optional] [multiple] [ ] notify: [optional] [multiple] [inverse key] mnt-by: [mandatory] [multiple] [inverse key] changed: [mandatory] [multiple] [ ] source: [mandatory] [single] [ ] For more information on querying the APNIC Whois Database, see APNIC Whois Database query options. 2.2 Complete the template ----------------------------- Replace the attribute prompts with the information you want to appear in the database. Ensure that: - Mandatory attributes are completed - Optional attributes you choose to omit are deleted from the template - Attribute prompts such as "[optional]" are deleted Example of a completed object template: person: Ky Xander address: ExampleNet Service Provider address: 2 Pandora St Boxville address: Wallis and Futuna Islands country: WF phone: +680-368-0844 fax-no: +680-367-1797 e-mail: kxander@example.com nic-hdl: AUTO-1 remarks: ----------------------------- remarks: Send abuse reports to remarks: abuse@example.com remarks: ----------------------------- mnt-by: MAINT-WF-EXAMPLENET changed: kxander@example.com 20020821 source: APNIC 2.3 Send the object to the appropriate mailbox -------------------------------------------------- Submit the completed object by email to the appropriate mailbox at APNIC. With the exception of maintainer objects, send new objects to: Send new maintainer objects to: 2.3.1 Preventing new objects overriding similar existing objects To ensure that the database only accepts an object if it is not already in the database, use the keyword "NEW" in the email subject line. For example, use this if you are registering an inetnum object to prevent overriding any existing inetnum object with the same address range. For more information, see section 7.1. 2.4 Special cases: person and maintainer objects ---------------------------------------------------- Two objects need special care when you create them in the database: - person - maintainer These two objects are referred to by most other objects in the database; all objects (including person objects) must be protected by a maintainer and many objects (including maintainers) also refer to person objects as the tech-c, admin-c or zone-c. Because person and maintainer objects are dependent on each other, the first time you create them, you will need to submit both new objects to to be manually entered into the database: 1. Create new person and maintainer objects using the text form available at: http://ftp.apnic.net/apnic/docs/mntner-person-request 2. Submit the completed form to 3. Wait one business day for the APNIC Hostmasters to create your new maintainer and person objects. If you already have a existing maintainer or person object, and wish to create additional maintainer or person objects using your existing object, please see sections 2.4.1 and 2.4.2 for more information. 2.4.1 person object To create a new person object, you must follow the procedure below: 1. Create your new person object. 2. Include a temporary NIC-handle in the nic-hdl attribute with the format: -AP Field Description ----- ----------- initials Two to four letters generated by the database software. There are two ways the initials are generated: 1. The initials are generated from the names specified in the name attribute of a new person object by the database software. To do this, the object template must include the following nic-hdl attribute: nic-hdl: AUTO-1 2. The initials are specified by the person submitting the person object at the time of creation. To do this, the object template must include the following nic-hdl attribute: nic-hdl: AUTO-1 Where chosen-initials are specified by the user. Example: AUTO-1ENOC number A number from 1-999 generated by the database software. The next available number for the combination of letters that form the initials is assigned to the NIC-handle. AP Asia Pacific. All person and role objects in the APNIC Whois Database contain the suffix "AP". When creating a new person object, you must use one of the two nic-hdl attributes described above: nic-hdl: AUTO-1 nic-hdl: AUTO-1 You can use the same temporary NIC-handles to reference the new person in other objects contained in the same update email. The database software will automatically assign the generated NIC-handles to other objects in the update message that referred to the same temporary NIC-handle. If you wish to create more than one new person object in the email, you can increment the temporary NIC-handle for additional person objects. For example: nic-hdl: AUTO-2 If you are creating more than one person or role object in a MIME encoded PGP signed message, you may use AUTO-1 for each object. For more information, see section 5.2. 3. You must refer to an existing mntner object in the person object's mnt-by attribute. If you do not have an existing mntner object, see section 2.4 above. 4. Email the person object to: 5. You will receive an email from the APNIC Whois Database stating whether your update was a success or not. If there were errors, please see section 7.3. When you receive an email stating that your update was successful, your person object will be ready to use in the APNIC Whois Database. 2.4.2 maintainer object To create a new mntner object, you must follow the procedure below: 1. Create your new mntner object. - You must refer to an existing person object in the admin-c attribute. If you do not have an existing person object, see section 2.4 above. - In the referral-by attribute, you must include APNIC-HM. No other value will be accepted: referral-by: APNIC-HM 2. Email the mntner object to: 3. The APNIC Hostmasters will then authorise your request and create your mntner object in the database. This may take one business day to complete. 4. When you receive an email from the APNIC Hostmasters, your mntner object will be ready to use in the APNIC Whois Database. 3. Updating an existing object _____________________________________________________________________ To update an existing object via email submission, you must: Obtain a copy of the existing object - Update the object template - Add a new changed attribute to the object - Send the object to the appropriate mailbox 3.1 Obtain a copy of the existing object -------------------------------------------- Query the APNIC Whois Database to obtain a copy of the existing object. Web-based whois query: Query the APNIC Whois Database and copy the results into the update email. Command line whois query: Use the command line whois query to save the results directly into a file. Use the query format: whois -h whois.apnic.net Then use a text editor to update the object in the file. 3.2 Update the object template ---------------------------------- When updating objects you can: - Make changes to existing attributes - Delete optional attributes included in the original object - Add new optional attributes not included in the original object Note: if you attempt to update an attribute that is a primary key of an object, a new object will be created and the existing object will remain unchanged. To change the primary key of an object, create a new object with the updated primary key attribute and delete the existing object. For more information on updating person, role, mntner and route objects, see section 3.5. 3.3 Add a new changed attribute to the object ------------------------------------------------- Leave the first existing changed attribute in the object as this contains information on the date the object was created. If there are three or more changed attributes in the existing object, you may wish to delete some of the intermediate changed attributes. The new changed attribute should be in the format: changed: Where: Field Description ----- ----------- email-address Email address of person who last updated the database (this must be RFC 822 compliant) The database software will add the current date in the changed attribute after your email address. Please do not insert a date into the new changed attribute yourself. 3.4 Send the object to the appropriate mailbox -------------------------------------------------- Email the updated object to: You will receive an acknowledgement from the database software. If you receive the acknowledgement "Update NOOP:" (No operation performed) in the body of the acknowledgement email, it means you submitted an object identical to one already in the database. Note: if the object you are updating is protected by a maintainer object with an authentication method other than NONE, you will need to supply the appropriate password or other authentication information. See section 5 for more information. 3.5 Special cases: person, role, mntner, and route objects -------------------------------------------------------------- If you need to update an attribute that is a primary key for an object, first delete the existing object then create a new object in its place. This has an affect on the following object types in particular: - person - role - mntner - route 3.5.1 person and role objects If you change the NIC-handle of an existing person or role object, a new object will be created and the existing object will remain unchanged. In addition, if you attempt to change the person or role attribute of a person or role object, the update will also fail. To prevent a large number of unreferenced person and role objects in the APNIC Whois Database, APNIC strongly recommends deleting the original object and submitting a new object to the database. 3.5.2 mntner objects If you attempt to change the mntner attribute of an existing mntner object, the database software will assume you are trying to create a new mntner object and, because only APNIC Hostmasters can authorise new mntner objects, the submission will fail. To create a new maintainer with the updated mntner attribute, you must send an email to: In the email please include: - a copy of both the existing and new mntner objects - a brief explanation why you would like your old mntner replaced with a new mntner with a modified mntner attribute Please note that if you do this, you must remember to replace the mntner referenced in database objects with the new mntner. 3.5.3 route objects Sometimes it is necessary to update the origin attribute of a route object. However, if you try to update the existing route object, a new route object will be created and the existing object will remain unchanged. Each route object will have the same prefix specified in the route attribute, but different Autonomous Systems specified in the origin attributes. This is a useful function if you are multihoming. However, if you wish to replace the object completely, you first must delete the existing route object and then submit a new route object to the database. 4. Deleting an object _____________________________________________________________________ To delete an existing object via email, you must: - Obtain a copy of the existing object - Add a special delete attribute to the object - Send the object to the appropriate mailbox For information on how to obtain a copy of the existing object, see section 3.2.1. A special attribute called delete must be added to the end of the existing object. The delete attribute uses the format: delete: Where: Field Description ----- ----------- free-text the reason for deleting the object Note: if the object you are deleting is protected by a maintainer object with an authentication method other than NONE, you will need to supply the appropriate password or other authentication information. See section 6 for more information. Example of deleted object: person: Ky Xander address: ExampleNet Service Provider address: 2 Pandora St Boxville address: Wallis and Futuna Islands country: WF phone: +680-368-0844 fax-no: +680-367-1797 e-mail: kxander@example.com nic-hdl: KX9-AP remarks: ----------------------------- remarks: Send abuse reports to remarks: abuse@example.com remarks: ----------------------------- mnt-by: MAINT-WF-EXAMPLENET changed: kxander@example.com 20020821 source: APNIC delete: duplicate person object password: privatepassword02 An object will only be deleted if the object in the email exactly matches the object in the database. Example: whois -h whois.apnic.net -i tech-c,admin-c,zone-c KX9-AP 4.1 Special cases: person and mntner objects ------------------------------------------------ Before deleting a person or role object make sure it is not referenced by other objects. To find objects where the role or person object is referenced, perform an inverse query using the '-i' flag. If you are not sure whether other objects contain references to the person or role object to be deleted, do NOT delete that object. Note: The database software will not allow you to delete a person, role or mntner object that is referenced by any other object. However, as all person and role objects must refer to a maintainer, and all maintainers must refer to NIC-handles in the tech-c and admin-c attributes, the database software will not permit you to delete your person object while it is still referenced by your maintainer object. Therefore, to delete a person or role object along with its mntner object, you must: 1. Update the mntner you wish to delete with a different person object's NIC-handle in the tech-c and admin-c attributes. - If you have another person object, please use this object. - If you do not have another person object you can use for this purpose, create a new person object, specifying MAINT-NEW in the mnt-by attribute. Once the temporary person object has been created, specify this person object's NIC-handle in the mntner object to be deleted. 2. Once the mntner no longer references the person object you wish to delete, you can delete that person object 3. Delete the mntner 4. If you created a temporary person object, delete the new person object 5. Sending emails to the database _____________________________________________________________________ 5.1 MIME support -------------------- The APNIC Whois Database software supports MIME. This allows: - Cryptographic signing of messages by mail client software that places the signature in a separate MIME part Note: the database software also accepts: - MIME encoded messages containing a single body part - Non-MIME encoded signed mail as a single body part - Different authentication methods to apply to separate body parts within the email - Nested signing of messages when updating objects whose authorisation must be derived from more than one source The following headers are recognised by the software: - Multipart/signed - Multipart/alternative - Multipart/mixed - Multipart/unknown - Application/pgp-signature - Text/plain The database software will send a warning for each unsupported content-type found. The warning will be reported to the user (see section 7.7). Each MIME part is treated as a separate message: - Authentication is valid only within a single part - AUTO NIC-handle assignment is made only within a single part (see also section 5.2) 5.2 PGP support ------------------- The APNIC Whois Database software supports PGP-signed messages. CAUTION: Avoid lines that begin with "From" in the body of the message as this may trigger signature verification. 5.2.1 PGP and MIME encapsulation You must submit the message as multipart/signed composite-type: 1. Create the text document containing the object to be submitted 2. Add the text document to the email as the first body part 3. Add the PGP signature as the second body part as an application/pgp-signature MIME discrete-type When submitting multiple new person or role objects, each object is treated as a separate message. This means that all new person and role objects may use AUTO-1 in the nic-hdl attribute instead of incrementing the AUTO to AUTO-2, AUTO-3 for each additional object in the submission. To do this: 1. Create each new person or role object in separate text documents 2. Add the text documents to the email body 3. Add the PGP signature as an application/pgp-signature MIME discrete-type If one of the signatures fails in a nested signed portion, the whole portion is rejected. 6. Protecting objects in the APNIC Whois Database _____________________________________________________________________ The APNIC Whois Database is an important source of information for the Internet community. Therefore it is important that the information in the database is accurate and not vulnerable to unauthorised changes or additions. To protect objects, the APNIC Whois Database uses maintainer objects. When objects are submitted to the APNIC Whois Database, the software checks that the person submitting the objects has the authority to update existing objects or create new objects within a hierarchical structure, such as hierarchical route or inetnum objects. Objects can only be changed by including in the email submission the authentication method of the maintainer object protecting the object. Hierarchical objects can only be created if you include the authentication method of object or obejcts controlling the creation of objects within that hierarchy. 6.1 Authentication and authorisation ---------------------------------------- Authentication takes place when the database software checks the password or private key given in a submission against the password or public key lodged in the database. If the two match, the person making the email submission is authenticated. Authorisation takes place after the submission has been authenticated. The database software checks that you are authorised to create or modify the object you submitted. If the object is associated with a hierarchy of objects (for example, hierarchical allocation and assignment inetnum objects), the software will check that you have permission to create, update, or delete objects within that hierarchy. Usually, this will be determined by the inclusion of higher objects' maintainer objects' auth methods in the submission. For details on specific hierarchical objects, see section 6.3. 6.2 Using maintainer objects to protect other objects --------------------------------------------------------- The mntner object is used to authorise changes to: - objects directly protected by the maintainer - objects in a hierarchical structure beneath the object protected by the maintainer. For example, a route object must pass the mntner authorisation of the aut-num and inetnum objects it refers to. Objects can refer to maintainer object in the following attributes: - mnt-by - mnt-lower - mnt-routes - mbrs-by-ref - cross-mnt The maintainer contains one or more authentication (auth) attributes. Each auth attribute consists of: - A keyword to identify the authentication method - The authentication information needed to use that method This is displayed in the format: auth: Example: auth: CRYPT-PW /3xnXDDY/auyg When submitting an object that requires authorisation from a mntner to the database, you must supply the authentication information for that mntner in the submission. The type of authentication information you must provide depends on the authentication method specified in the mntner object. Authentication methods currently supported by the database are described below: Authentication Description keyword -------------- ----------- NONE No authorisation checks are performed on objects protected by a maintainer with this authentication method. APNIC strongly discourages the use of this method as it allows anyone to change objects protected by maintainers with this method. CRYPT-PW Stored in the auth attribute as a fixed encrypted password in UNIX crypt format. This is a relatively weak form of authentication. Disadvantages of this method include: - Database submissions must include the clear text text password which may be intercepted - The encrypted form of the password is exposed in the maintainer object and may be subject to password guessing attacks To authenticate changes to objects protected by maintainers using this method, the object must contain the pseudo-attribute password anywhere in the object in the format: password: Example: password: secret02NoW The pseudo-attribute cannot appear in mail headers and cannot continue over more than one line. PGPKEY Stored in the auth attribute as a signature identity pointing to a public key certificate. The public key certificate is stored in a separate key-cert object. To authenticate changes to objects protected by maintainers using this method, the submission must be signed by the corresponding private key. Advantages of this method: - This is the strongest auth method currently available in the APNIC Whois Database. Disadvantages of this method: - Users must learn PGP signing techniques. For more information, see: http://www.pgpi.org APNIC does not guarantee that any public key stored in the APNIC Whois Database belongs to any specific entity. The APNIC Whois Database is not a certificate authority. Important points to note: 1. You may include more than one auth attribute in a maintainer object. However, be aware that the authentication is only as secure as the weakest authentication method listed. 2. You may include more than one mnt-by, mnt-lower, mnt-routes or mbrs-by-ref attribute in an object. - This is useful if you do not wish to reveal your auth method information to another person or organisation. The other person or organisation can still have the ability to update objects, but has their own separate mntner and auth method information. - To include multiple mntners in an object, you need to include the appropriate authentication information for the existing mntner referenced in the object. You do not need to pass the auth method of the additional mntner object. 3. If there are multiple mntners mentioned in the same attribute type of an object, you need to pass the authentication of only one of those maintainers. This has two major implications: - If you are the original maintainer of an object and decide to insert additional mntners in the same attribute for the object, the additional mntners can delete your mntner at any time without passing your auth method. - The security on the protected object is only as strong as the weakest auth method used by the mntner objects. For example, if one mntner uses NONE and the other uses PGPKEY, it is possible for anyone to change objects protected by both these maintainers. 6.3 inetnum and inet6num ---------------------------- The inetnum and inet6num objects can represent both allocations and assignments of addresses. These are stored in a hierarchical structure. APNIC maintains the top level inetnum and inet6num objects in the hierarchy. When APNIC allocates or assigns address space to an organisation, APNIC retains the authority to update the allocation or assignment object by placing the APNIC maintainer in the mnt-by attribute. If you wish to update details in an object detailing an allocation or assignment of address space from APNIC to your organisation, please contact: hostmaster@apnic.net If your organisation is allocated address space by APNIC, APNIC will place your mntner object in the allocation object's mnt-lower attribute to give you authority to create customer allocation and assignment objects within the allocation range. To create objects within the address range specified by the allocation object, you must pass the auth method of the mntner object specified in the mnt-lower attribute. Note: If you are sub-allocating address space to customer organisations, be sure to include a mnt-lower attribute that gives your customer sole authority to create assignments within that address range. Failure to include a mnt-lower attribute means there is no protection against unauthorised inetnum or inet6num objects being created within that address range. 6.4 as-block ---------------- The as-block object is used to control the creation of aut-num objects. Top-level as-block objects are maintained by APNIC. Smaller as-blocks may be created by APNIC for NIRs to allow the NIRs to create aut-num objects for their members. The mnt-lower attribute of the as-block object specifies maintainers with the authority to create smaller as-blocks or aut-num objects within the range of AS numbers protected by the as-block. If there is no mnt-lower, the maintainer specified in the mnt-by attribute is authorised to create smaller as-block objects or aut-num objects. The mnt-by attribute specifies the maintainer whose auth method must be passed to modify the as-block object itself. 6.5 aut-num ---------------- The maintainer of as-block objects have sole authority to create new aut-num objects in the APNIC Whois Database (see section 6.4 above for more information on how as-blocks protect creation of aut-num objects). In practice, this means only APNIC and the NIRs can create new aut-num objects. If you need an aut-num object to be created, please submit an APNIC AS Number Request Form. The mnt-by attribute specifies the maintainer whose auth method must be passed to update an exisiting aut-num object. The mnt-lower and mnt-routes attributes are used to authorise the use of the AS number in route objects. For more information, see section 6.6 below. 6.6 route ------------- To create a new route object, the database seeks authorisation from two objects associated with the route in the database: - All route objects must be authorised by the aut-num object referenced in the origin attribute. - In addition to the aut-num object, authorisation is sought from one of the following two objects: 1. A less specific route object 2. The inetnum object matching or encompassing the prefix of the new route object The relationship between these three objects to a new route object is explained below. Object Relationship to route object creation ------ ------------------------------------- aut-num The aut-num object must be an AS number contained in the APNIC Whois Database. The route object must pass one of the authentication methods of the mntner objects specified in the aut-num. less specific More specific route objects may be created for route multihomed networks using non-portable assigned space. In this case, authorisation to create the more specific route object may be given by mntner objects listed in the less specific route object. Note: Authorisation to create more specific route objects may also be obtained from mntner objects specified in associated inetnum objects. inetnum If no less specific route object is found, the software will look for authorisation from the smallest inetnum object that encompasses the prefix specified in the new route object. Authorisation to create route objects in specified in the following attributes of inetnum, aut-num and less specific route objects: Attribute Description --------- ----------- mnt-routes Used to explicitly state which mntner objects can be used to create route objects. mnt-lower In the absence of a mnt-routes attribute, this attribute is used. Note: if the mnt-routes attribute is present, the mnt-lower attribute may still be used to create or update the route object. mnt-by In the absence of mnt-routes and mnt- lower attributes,the mnt-by attribute is used. Note: if the mnt-routes and mnt-lower attributes are present, the mnt-lower attribute may still be used to create or update the route object. 6.7 domain -------------- Top-level /8 reverse domain objects are maintained by APNIC to control unauthorised creation of reverse domains within APNIC allocation and assignment ranges. Creation of more specific reverse domain objects is authorised by the mnt-lower attribute of the reverse domain object. 6.8 inet-rtr ---------------- Creating an inet-rtr object does not require the authorisation of the address range or AS number specified in the object. inet-rtr objects can be grouped together to form router set (rtr-set) objects. There are two ways an inet-rtr object can be a member of an rtr-set object: 1. Use the member-of attribute of the inet-rtr object to list rtr-set objects it wishes to be a part of. The mbrs-by-ref attribute of the rtr-set object must authorise this inclusion by specifying the mntner of the inet-rtr. 2. Use the members attribute of the rtr-set object to explicitly include the inet-rtr object in the set. In this case, the inet-rtr object cannot refer to the rtr-set object in the inet-rtr object's member-of attribute. Attempts to refer to the rtr-set so will result in an authorisation failure. It is good practice to use the remarks attribute to identify the rtr-set to which this this inet-rtr belongs. (Note: It is not possible to use the member-of attribute for this purpose.) 6.9 set objects ------------------- This section covers: - as-set - route-set - peering-set - filter-set - rtr-set Members of a set may be specified by in two ways: 1. The set object can explicitly include a member in the members attribute. Any object listed in the members attribute cannot refer to the covering set object in its own member-of attribute. Attempts to do so will result in an authorisation failure. As any objects listed in the members attribute cannot explicitly state which set they are a part of, it is good practice to use the remarks attribute to make a note of the set the object belongs to. 2. The set object can specify the maintainers of objects it will allow to be its members in the set object's mbrs-by-ref attribute. If this is used, please be aware that objects protected by the maintainer are not automatically included in the set. Instead, the maintainer must choose which objects they maintain should be part of the set. To include an object as a member of the set, you must refer to the name of the set in the object's member-of attribute. If the mbrs-by-ref attribute is not used, the set will only include objects specified the members attribute. 6.9.1 as-set The as-set may be either non-hierarchical or hierarchical depending on how the object is named. * Non-hierarchical as-set objects Non hierarchical as-set objects must begin with 'AS-' and cannot include AS numbers within the as-set object's as-set attribute. Non-hierarchical as-set names should only be used to create as-set objects that can be used across many networks, for example, unallocated AS numbers. Example: AS-UNALLOCATED-ASNs To create or update a non-hierarchical as-set object, you do not need to pass the authorisation of any objects, except the maintainer referenced in the mnt-by attribute. * Hierarchical as-set objects A hierarchical as-set object lists AS numbers as well as as-set in its as-set attribute. - Each AS number and as-set name must be separated by a colon. - There must be at least one valid set-name in the attribute. - More than one as-set may be specified in the attribute. - Each as-set listed must begin with 'AS-'. - AS numbers must begin with 'AS'. Hierarchical as-set names should be used when creating sets of AS numbers specific to your own, your customers', or yourpeers' networks. APNIC recommends the following format to allow you to manage multiple as-set your network: :AS-CUSTOMERS :AS-PEERS Example: AS1:AS-CUSTOMERS To create or update a hierarchical as-set object, you must pass the auth method of the mntner of aut-num or as-set objects to the left of the name of the as-set object you are creating. For example, in AS1:AS-CUSTOMERS, the as-set example given above, authorisation would be needed from AS1. Authorisation is determined by first using the mnt-lower attribute of maintainer specified in the associated aut-num or as-set objects. If the mnt-lower is absent, the mnt-by attribute is used. 6.9.2 route-set A route-set object may be either non-hierarchical or hierarchical depending how the object is named. * Non-hierarchical route-set objects Non hierarchical route-set objects must begin with 'RS-' and cannot include anything other than a single route-set name in the route-set attribute. Non-hierarchical route-set names should only be used to create route-set objects that can be used across many networks, for example, denied routes. Example: RS-DENIED-ROUTES To create or update a non-hierarchical route-set object, you do not need to pass the authorisation of any objects except the maintainer referenced in the mnt-by attribute. * Hierchical route-set objects A hierarchical route-set object lists one or more of the following in the route-set attribute in addition to the route-set name beginning with 'RS-' that defines the route-set: - Route set - AS number - AS set Hierarchical route-set names should be used when creating sets of routes specific to your own or your customers' routes. APNIC recommends the following format to allow you to manage multiple route-set objects for you and your customer networks: :RS- Example: AS1:RS-CUSTOMERS Please note: - Each item listed must be separated by a colon. - There must be at least one valid route-set name in the attribute beginning with 'RS-'. To create or update a hierarchical route-set object, you must pass the auth method of the mntner of objects to the left of the name of the route-set object you are creating. For example, in the example given above, authorisation would have to be given by AS1. Authorisation is determined by first using the mnt-lower attribute of maintainer specified in the associated inetnum, aut-num, as-set or route-set objects listed. If the mnt-lower is absent, the mnt-by attribute is used. 6.9.3 peering-set A peering-set object can be created without needing to pass the authorisation of the maintainer of any aut-num, as-set, inet-rtr or rtr-set objects specified in the peering attribute. To update a peering-set object, you must pass the auth method of the mntner specified in the peering-set object's mnt-by attribute. 6.9.4 filter-set A filter-set object can be created without needing to pass the authorisation of the maintainer of the aut-num, filter-set or address prefix specified in the filter attribute. To update a filter-set object, you must pass the auth method of the mntner specified in the filter-set object's mnt-by attribute. 6.9.5 rtr-set An rtr-set object may be either non-hierarchical or hierarchical depending how the object is named. * Non-hierarchical rtr-set objects Non hierarchical rtr-set objects must begin with 'RTRS-' and cannot include anything other than a single rtr-set name in the rtr-set attribute. Non-hierarchical route-set names are best used when using an RPSL compliant database to manage internal network configurations. Example: RTRS-EXAMPLENET-SYDNEY To create or update a non-hierarchical rtr-set object, you do not need to pass the authorisation of any objects except the maintainer referenced in the rtr-set object's mnt-by attribute. * Hierchical rtr-set objects A hierarchical rtr-set object lists one or more aut-num in the route-set attribute in addition to the route-set name beginning with 'RTRS-' that defines the route-set. Hierarchical rtr-set names should be used when creating sets of routers specific to your own or your customers' routers. APNIC recommends the following format to allow you to manage multiple rtr-set objects for your network: :RTRS- Example: AS1:RTRS-EXAMPLENET-FUTUNA-SITE Please note: - Each item listed must be separated by a colon. - There must be at least one valid rtr-set name in the attribute beginning with 'RTRS-'. To create or update a hierarchical rtr-set object, you must pass the auth method of the mntner of objects to the left of the name of the route-set object you are creating. For example, in the example given above, authorisation would have to be given by AS1. Authorisation is determined by first using the mnt-lower attribute of maintainer specified in the associated inetnum, aut-num, as-set or route-set objects listed. If the mnt-lower is absent, the mnt-by attribute is used. 7. Troubleshooting _____________________________________________________________________ 7.1 Using keywords in emails to -------------------------------------------------------- You can use keywords when sending email to to modify the response you receive from the database. The keywords are not case sensitive. Keyword Description ------- ----------- HELP Returns links to web pages with information on how to update objects in the database. Note: If you include this keyword in an email that includes an object you wish to be submitted to the database, the database software will ignore the object and simply reply to you with the web page links. HOWTO Returns the same information as "help". NEW Tells the database to only accept new objects. If the object already exists, the submitted object will be rejected. 7.2 Receiving acknowledgement messages ------------------------------------------ You should always receive an acknowledgement message when submitting objects to the database. If you do not receive an acknowledgement: - Your e-mail address is unknown and the acknowledgement mail bounced. Please check that your email address is correct. - Your e-mail address is correct and your update arrived during a database maintenance window. Please wait a couple of hours for the database to respond to your submission, or refer to the APNIC maintenance schedule. - If neither of these situations apply, please contact for assistance. All objects sent to are parsed. The acknowledgement message will tell you if your submitted objects were successfully parsed and entered in the database: - If your submission was error free, the acknowledgement will put "SUCCEEDED:" in the subject line and in the body of the email, it will state: "Your update was SUCCESSFUL." - The database will reject any deviations from accepted object formats. The acknowledgement will include "FAILED:" in the subject line and in the body of the email, it will state: "Part of your update FAILED." The acknowledgement will then list errors found in the object submission. All errors must be rectified before the object will be accepted. See section 6.2 for information on how to correct errors. Note: The database will ignore any text that does not comply with the standard object format: attribute-name: attribute-value For example, if you include your signature, the database will ignore the signature and process the objects in the rest of the email. However, if you include text in your email that uses a colon ':', the database will try to read it as an object and produce a "FAILED" result. It is also important to note that a "FAILED" message in the acknowledgement subject line does not necessarily mean every object in the email update has failed. Please read the acknowledgement message carefully to see which items have failed and which items have been successfully submitted. 7.3 Correcting errors ------------------------- Syntax and invalid attribute value errors are sent to the email address the object was submitted from. Authorisation errors are also sent to the email address associated with the maintainer in the mnt-by attribute. Below is a list of errors you may receive when submitting objects to the database: 7.3.1 Messages to the email address that submitted the object Error message Description ------------- ----------- Authorisation failed, You failed to meet the authentication method request forwarded to specified in the auth attribute of the mntner maintainer. object protecting the object. The owner of the mntner object will receive notification that a failed object update was submitted from your email address. Please contact the maintainer of the object to check auth method you must use. Hierarchical You failed to meet the authentication method authorisation failed, specified for a mntner of an overlapping request forwarded to object or an object governing the creation of maintainer more specific objects. This error can occur when you try to create new inetnum, inet6num, route and reverse domain objects that overlap with the range of existing objects of the same type. If you are registering an assignment or sub-allocation and receive this error, it could mean that you have attempted to create an inetnum or inet6num object that overlaps with existing objects in the database. Please check the range of your object before resubmitting. If you are attempting to create a route object,it may mean that you have failed the auth method of the maintainers of the inetnum and aut-num objects governing the creation of route objects that reference them. Status ALLOCATED You tried to change the status attribute of an PORTABLE or ASSIGNED inetnum or inet6num object to portable address PORTABLE can be set space. only by the following mntner(s): Only APNIC and the NIRs have the authorisation APNIC-HM MAINT-NIR to allocate portable address space tonetworks. MAINT-CNNIC-AP MNT- If you are assigning or sub-allocating address APJII-ID MNT-KRNIC-AP space to customer networks, the space must be MAINT-TW-TWNIC MAINT- be returned to you if that customer ceases JPNIC connectivity with you. Therefore, the resource can only be non-portable. Object already exists You submitted an object to the database that already exists and included the keyword NEW in the subject line. The keyword NEW ensures that only new objects can be submitted to the database. If the object already exists in the database, that is, it has the same primary key(s), the submission will be rejected. To update the existing object, remove the keyword NEW from the subject line. To create a totally new object, first delete the existing object from the database. First attribute, You misspelled the first attribute tag of the "", object or omitted the first tag entirely. is not a known RPSL class Please check the first attribute of your object and resubmit. Primary key You omitted an attribute that is a primary key "" is for the object. missing The primary key uniquely identifies an object from all other similar objects in the database. Please add the primary key specified in the error message in your next submission. Required attribute You submitted an object without a mandatory "" attribute. is missing All mandatory attributes must be included. Only attributes marked optional may be omitted. Please add the attribute specified in the error message in your next submission. Attribute You included more than one instance of an "" attribute that can only appear once in the appears more than object. once Please remove all but one of the instances of the attribute specified in your next submission. Name of a person or You changed the person or role attribute. role object cannot be changed The person and role attributes are primary keys for the object and therefore cannot be changed. If you wish to change the details of a person or role attribute, you will need to delete the existing person or role object and then create new one with the updated details. mntner objects cannot You changed the mntner attribute. be created automatically. This The mntner attribute is the primary key for object has been the object and cannot be changed. The database forwarded to apnic- assumes you are trying to create a new dbm@apnic.net for maintainer. However, as maintainers can only authorisation. No be created by APNIC Hostmasters, your attempt further action from to change the object failed. your part is required If you wish to change the details of a mntner attribute, you will need to delete the existing maintainer object and then submit a new one with the updated details to . Syntax error in You used invalid syntax for the attribute "" Different attributes values have different syntax. Please check the syntax needed for the attribute specified before resubmitting this object. No such source You did not specify APNIC in the source attribute. No other source values will be accepted. Please check that you have not mistyped APNIC. No such country You have not specified a two letter country [] code from the ISO 3166 specification. Note: While not an ISO 3166 standard, the two letter code, AP (Asia Pacific), is also accepted by the database. Date in the future in You submitted an object with a future date in 'changed' attribute: the changed attribute. APNIC recommends that you do not include the date when adding a new changed attribute to an object. Please delete the date and the database will add the current day's date to the attribute for you. Alternatively, please change the date to the current date and resubmit. Unknown object In one of the object's attributes, you referenced specified an object that does not exist in the APNIC Whois Database. If you referred to an object that exists in a database other than the APNIC Whois Database, the submission will automatically fail. You cannot refer to a NIC-handle or maintainer registered in another database. Please create the appropriate object in the APNIC Whois Database. Please check that you have not mistyped the name of an object that exists in the APNIC Whois Database. The following You may have included your signature in the paragraph does not email. The database ignores anything that does look like an object, not conform to the object structure: so ignoring it: : You do not need to resubmit objects in your submission unless there are additional errors specified for those objects. 7.3.2 Messages to maintainers/notify contacts Message Description ------- ----------- This is to notify you Notifies the email address of the object's that some object(s) in maintainer or email address listed in the the APNIC whois which notify attribute of any changes to the you either maintain or object.A copy of the previous and updated or are listed as to-be- objects will be included in the email. notified have been added, deleted or changed. The update causing these changes had the following mail headers: This is to notify you Notifies the maintainer that there has that some objects in been an attempt to update an object in which you are mentioned which the maintainer is listed in the as a maintainer were mnt-by attribute. requested to be changed, but *failed* the proper The attempt to update the object failed authorisation for any the authorisation method specified in of the mentioned the maintainer object's auth attribute. maintainer. Please contact the A copy of this will be sent to the sender of these changes maintainer. A similar error message will about changes that need also be sent of the person who tried to to be made to the update the object. following objects. The mail message Note: if you have attempted to update an causing these failures inetnum representing an allocation by had the following APNIC, it will automatically fail; this mail headers: message will be forwarded to APNIC Hostmasters, who maintain all allocation objects in the database. Please contact APNIC to request changes to your allocation details. SUBJECT: APNIC Whois Notifies the maintainer of a route that a Database: Addition of more specific route has been created within overlapping routes the prefix of the larger route object. The addition of the route object... Alternatively, a route object was created created new overlaps that overlaps an existingroute. with your following routes ... If you have any questions about error messages, send an email containing as much information as possible to: 8. Further reading _____________________________________________________________________ APNIC Whois Database query options http://www.apnic.net/db/search/all-options.html Attributes of APNIC Whois Database objects http://www.apnic.net/db/ref/attributes/index.html RFC 2622 Routing Policy Specification Language (RPSL) http://www.ietf.org/rfc/rfc2622.txt RFC 2650 Using RPSL in practice http://www.ietf.org/rfc/rfc2650.txt