HOWTO document for . --------------------------------------- This is an extract from Chapter 2 of ripe-157, which is available from: For information on querying the TEST database, use whois -h test-whois.ripe.net HELP 2.2 Creating, Updating and Deleting an Object: 2.2.1 Creating a new object: To create a new object, follow this procedure: * get 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) Getting the template: Use whois -t . See Section 2.1.1 for details on how to obtain the template of any object. Example [spoor] $ whois -h whois.ripe.net -t person gives person: [mandatory] [single] address: [mandatory] [multiple] phone: [mandatory] [multiple] fax-no: [optional] [multiple] e-mail: [optional] [multiple] nic-hdl: [optional] [single] remarks: [optional] [multiple] notify: [optional] [multiple] mnt-by: [optional] [multiple] changed: [mandatory] [multiple] source: [mandatory] [single] (2) modification of the template; (i) Now fill in the appropriate details in the tem- plate. Do not leave attributes with values such as "[optional]", or "[multiple]". (ii) Attributes which are mandatory should .B not .R be empty. Otherwise, the update will be rejected by the database software. (iii) Attributes which are optional may be left empty, but they will be removed by the database software. Example: person: Ambrose Magee address: RIPE NCC Network Co-ordination Centre [.....stuff deleted.....] phone: +31 20 592 5065 fax: e-mail: ambrose@ripe.net [.....stuff deleted.....] 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: Ambrose Magee address: RIPE Network Co-ordination Centre (NCC) address: Kruislaan 409 address: NL-1098 SJ Amsterdam address: The Netherlands [.....stuff deleted.....] (iv) If you are completing a person template or want to reference a person in an another object, you should use a RIPE handle ('nic-hdl:'). You can also use NIC handles from other registries such as the InterNIC if you are also registered there. NIC-han- dles 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 get yourself a RIPE NIC-handle by putting the following in the NIC handle field: nic-hdl: AUTO-1 OR nic-hdl: AUTO-1YourInitials The second case advises the database software to use YourInitials (no more then 4 characters) for build- ing the NIC handle while the first case asks the database software to find the initials itself. You can use the same identifiers (AUTO-1 or AUTO-1YourInitials) 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. Example: domain: perl.com admin-c: AUTO-1 tech-c: AUTO-2 [ ... stuff deleted ...] person: Ambrose Magee nic-hdl: AUTO-1 [ ... stuff deleted ...] person: Larry Wall nic-hdl: AUTO-2 [ ... stuff deleted ...] N.B. The same rules apply when obtaining a NIC-han- dle for a role object. (iv) Put today's date and your e-mail address in the "changed" attribute. The format of the date must be YYMMDD. (v) use of "mnt-by" attribute; 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 main- tainer object in the "mnt-by" field Example: person: Ambrose Magee [....stuff deleted....] mnt-by: AMRM-MNT [.....stuff deleted.....] More information on maintainer objects may be found in Section 2.3. (vi) use of the keywords "NEW" and "ASSIGN"; You can ensure 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. N.B. at the moment, these keywords are case insensi- tive. Avoid putting strings such as "Old person object with new address" or "Re-assign address space" in your `Subject' line. (3) send the object to the appropriate mailbox. : is an automatic mailbox and all e-mails that create, update or delete objects (see above for exceptions) should be sent to this address. 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. : Questions and bug reports should be sent to . You are recommended to send as much information as possible. 2.2.2 Updating an existing object: How to update an existing object This is done by sending in the new 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.ripe.net >Temporary- File Example: [spoor] $ whois -h whois.ripe.net AMRM1-RIPE > update-file (2) Load the TemporaryFile into your favorite editor and make your changes or additions to the object. It is recommended to use NIC handles instead of the person names for references to person objects to guarantee that your object points to a single per- son. See Section 2.2.1 for more information. 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: it is wise to delete the old person, role or route object before adding the new objects for the follow- ing 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 dif- ferent 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 differ- ent 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 recog- nize 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: E-mailAddress Date where 'E-mailAddress' is an RFC822 E-mail address specifying who made the change and 'Date' is the date of the change in either YYYYMMDD or YYMMDD for- mat. (4) Send your message to . (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. 2.2.3 Deleting an object: This is done by sending in the whole object just like an update and adding a special attribute, 'delete', to it: delete: It is recommended that the reason for deleting the object be put as the value of the delete attribute. Example: person: Ambrose Magee address: RIPE Network Coordination Centre (NCC) address: Kruislaan 409 address: NL-1098 SJ Amsterdam address: Netherlands phone: +31 20 592 5065 fax-no: +31 20 592 5090 e-mail: ambrose@ripe.net nic-hdl: AMRM2-RIPE notify: ambrose@ripe.net changed: ambrose@ripe.net 970110 source: RIPE delete: Duplicate person object. The deletion is only accepted if the object in the message is .B exactly 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 a '-i' query; see Section 2.1.1. Example: [spoor] $ whois -h whois.ripe.net -r -i tech- c,admin-c,zone-c AMRM1-RIPE Some people might have used their name as a refer- ence instead of their NIC-handle, so you should also do a look-up on that. If you're not sure that you were the only one refer- encing 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. Authorization, notification and acknowledgement mes- sages for deletes are handled exactly the same way as for ordinary updates. 2.2.4 Warning and Error messages: The syntax of all objects sent to is rigorously checked. Acknowledge- ment 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 cor- rection was made. Example: suppose this object is sent to . person: Ambrose Magee [.....stuff deleted.....] changed: ambrose@ripe.net The following warning message would be generated: WARNING: added current date to "changed" field. (d) Fatal mistakes will .B not .R be corrected and the object will .B not .R be accepted into the database. An acknowledgement message will be sent, which will identify the error. Example: suppose this object is sent to . route: 193.0.0.139/32 descr: x1.ripe.net origin: AS3333 changed: ambrose@ripe.net 961221 source: RIPE The following warning message would be generated: -------------------------------------------------------- Update FAILED: [route] 193.0.0.139/32 route: 193.0.0.139/32 descr: x1.ripe.net origin: AS3333 notify: ambrose@ripe.net changed: ambrose@ripe.net 961221 source: RIPE *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 mes- sages, you may send e-mail to . This mailbox is checked regularly. Please send as much information as possible.