    HOWTO document for <auto-dbm@ripe.net>.
    ---------------------------------------


    This is an extract from Chapter 2 of ripe-157,
    which is available from:
    
    <http://www.ripe.net/docs/ripe-157.html>
    <ftp://ftp.ripe.net/ripe/docs/ripe-157.ps>
    <ftp://ftp.ripe.net/ripe/docs/ripe-157.txt>

    This document also contains an extract from
    Part I of ripe-189, which is available from

    <http://www.ripe.net/docs/ripe-189.html>
    <ftp://ftp.ripe.net/ripe/docs/ripe-189.ps>
    <ftp://ftp.ripe.net/ripe/docs/ripe-189.txt>

    You should read both documents.


    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.
                     <hostmaster@ripe.net> for new autonomous system
                     objects, <ripe-dbm@ripe.net> for new mntner
                     objects and <auto-dbm@ripe.net> for all other
                     objects.

                (1)  Getting the template:

                Use whois -t <type of object>.
                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:     [mandatory]   [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 not 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.
		
		(iv) Attributes which are generated will be automatically
		created and will have a value generated 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:     Singel 258
                address:     NL-1016 AB  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.


                <auto-dbm@ripe.net>:

                <auto-dbm@ripe.net> 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.


                <ripe-dbm@ripe.net>:

                Questions and bug reports should be sent to <ripe-
                dbm@ripe.net>.  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 <search string> >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 <auto-dbm@ripe.net>.

                (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: <free text>

                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:     Singel 258   
                address:     NL-1016 AB AMSTERDAM
                address:     Netherlands
                phone:       +31 20 535 4444
                fax-no:      +31 20 535 4445
                e-mail:      ambrose@ripe.net
                nic-hdl:     AMRM2-RIPE
                notify:      ambrose@ripe.net
                changed:     ambrose@ripe.net 19970110
                source:      RIPE
                delete:      Duplicate person object.




                The deletion is only accepted if the object in the
                message is exactly the same as the object in the 
		database.  Please 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 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 <auto-
                dbm@ripe.net> 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 <auto-
                dbm@ripe.net>.


                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 not be corrected and
                the object will not be accepted into the
                database.  An acknowledgement message will be sent,
                which will identify the error.

                Example: suppose this object is sent to <auto-
                dbm@ripe.net>.

                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 <ripe-dbm@ripe.net>.
                This mailbox is checked regularly.  Please send as
                much information as possible.


Extract from Part I, ripe-189
=============================


  2.2 Creating, Updating and Deleting an Object
       
   2.2.1 Handling of the changed attribute

       [since 2.1.3] Comparison of objects which is performed when
       processing updates and deletions ignores the changed attributes.
       Thus, a deletion of an object supplied without changed attribute
       lines would be succesful, if other attributes match.
       On the other hand, if an updated object is sent that differs from
       the existing version only in the changed attributes, no operation
       will be performed and a NOOP will be returned.
       
   2.2.2 Duplicate person object warning

       [since 2.2] While creating a new person object, a check is
       performed if there exists another person object with the same name
       in the database. A warning is issued if such object is found.
       It is also checked if contact data in both objects are identical -
       address, phone and fax attributes are compared, case- and
       whitespace-insensitive. In case that another object contains
       identical data, it is mentioned in the warning text.
       
    Example

       Suppose that objects for the same person exist in the database,
       with nic-handles ABC123-RIPE and AB1234-RIPE, containing different
       information but assigned the same name. If you try to add a copy
       of ABC123-RIPE using AUTO-1 as a nic-handle (and thus requesting
       creation of a new object), the following warning will be issued:
          WARNING:     Other person object(s) with the same name exists:
          WARNING:     ABC123-RIPE(same contact data too)
          WARNING:     AB1234-RIPE
       
   2.2.3 Notifications

       [since 2.1] Whenever an object is created with a notify attribute,
       notification is sent to that address, as well as the usual
       acknowledgement.

       [since 2.1] New concise format for acknowledgements and
       notifications has been introduced. All acknowledgments are now of
       type LONGACK, so specifying LONGACK in subject line of the e-mail
       message is no longer necessary.
       
   2.2.4 Referential integrity checks

       [since 2.2] New checks have been implemented to ensure integrity
       of the database.
       While creating or modifying an object which has references to
       other objects in its admin-c, tech-c, zone-c, cross-nfy, mnt-by,
       cross-mnt, or origin attributes, these referenced objects are
       checked to see if they exist in the database. The update is
       refused if reference to nonexisting object is found.
       While deleting person, role, mntner or aut-num object a reverse
       lookup is performed to find objects referencing the object being
       deleted. If any objects are found that reference the object in
       question, then the delete operation is refused and an error
       message is issued stating the number and types of objects
       referencing the object being deleted.
       Currently, only the RIPE database is checked for references -
       other sources (RADB etc) are not searched.
       Please note that to delete an object that is referenced, two
       separate messages must be sent:
          + the first one, changing references in other objects so that
            the object to be deleted is no longer referenced,
          + and the second one, actually deleting the object.
       The messages must be processed in the correct order. The easiest
       way to ensure that is to wait until the notification of first
       update is returned before sending the second message.
       
   2.2.5 Refined parsing of subject line keywords

       The code for parsing subject lines of mail messages sent to
       <auto-dbm@ripe.net> has been substantially changed.

       [since 2.1] A minor bug was fixed, thus enabling the intended way
       of parsing subject line keywords only if they appeared as complete
       words, eg. 'new object' and not 'My Apple Newton'. Also made to be
       case-insensitive.

       [since 2.2] The code for parsing subject line keywords has been
       fully rewritten.
       Keywords will trigger options ONLY if they are alone in subject
       line, i.e. no non-keyword words are found. Otherwise, the whole
       subject line will be ignored and a warning message will be issued.
       
    Recognized keywords

       The following keywords are recognized:
       
        NEW
                make sure the object does not exist
                
        HELP
                send help text
                
        HOWTO
                send (the same) help text
                
        ASSIGN (*)
                make sure the inetnum does not exist
                
        LONGACK (**)
                send long acknowledgment
                
        (*) 
                ASSIGN is now obsolete. This functionality has been
                dropped, since a general NEW keyword exists. If ASSIGN is
                found in subject line, it will be ignored and a warning
                message will be issued, but all other valid keywords will
                be processed.
                
        (**)
                LONGACK is now the format of all acknowledgments, so the
                keyword is silently ignored.
                
    Multiple keywords

       In addition, to prevent ambiguity when multiple keywords are
       specified, a list of allowed combinations of keywords has been
       defined. If the combination of recognized keywords is not one of:
       
        ASSIGN NEW
                
        ASSIGN LONGACK
                
        ASSIGN NEW LONGACK
                
        LONGACK NEW
                
        HELP HOWTO
                
       then the whole subject line will be ignored and a warning message
       will be issued.
       
    Examples of keyword usage

       If a mail message is sent to <auto-dbm@ripe.net> saying

          Subject: NEW person object for John

       then the following warning will be issued:

          Warning: unknown keywords found in subject line:
          person object for John

          Thus, all keywords in subject line were ignored.


       If a mail message contains:

          Subject: NEW LONGACK ASSIGN

       then the following warning will be issued:

          Warning: obsolete keyword ASSIGN found in subject line was ignored.

       There will be no warning for LONGACK, but it will not change the
       layout of the acknowledgment in any way. The NEW functionality
       will be activated.

       Finally, if a mail message contains:

          Subject: NEW HELP

       and no objects in the message body, then the following warnings
       will be issued:

          *** No objects were found ***

          Warning: this combination of keywords in subject line is not allowed.
          Thus, all keywords in subject line were ignored.
       
