
Document: HELP & HOWTO use the RIPE database
Version:  961003

Author:  David Kessens
E-mail:  ripe-dbm@ripe.net


Introduction
------------


This document describes how to access and create/change/delete your data
in the RIPE (or test!) database. Also included is a section with hints
and tips. At the end of the document is a chapter with pointers to more
extensive documentation.

The latest version of this document will always be available by using
'HELP' as your 'SearchString' (See 'How to access the database') when
accessing the RIPE database or by sending an E-mail to
<auto-dbm@ripe.net> with HELP in the 'Subject:' line. We try to keep this
document as up-to-date as possible. If you have any comments or additions
please send E-mail to <ripe-dbm@ripe.net> but please always check the
most recent version of this document first.


What is the RIPE Network Management Database?
---------------------------------------------

One of the activities of RIPE is to maintain a database of European IP
networks, AS numbers, their contact persons, routing policies and other
useful data for Internet Network Management (See section 'More
documentation' for pointers to other documents on the different objects
that are stored in the database). This database is called the RIPE
Network Management Database or simply the "RIPE Database". The
information held in this database is available to the public for the
purpose of coordinating IP networking. So note that the RIPE database is
*not* a general white pages service but is information that supports the
work of network operators (NICs and NOCs) throughout Europe and
worldwide.

For instance, if a user in network A cannot reach a machine in network B,
then the network manager of network A can find the technical contact
person of network B, to locate and solve the problem. Also information
that supports router configuration and routing troubleshooting is
available.

The information in the database is maintained centrally by the RIPE NCC.
Access to the database is currently available at the RIPE NCC and several
mirror sites in and outside Europe.

##############################################################################
# Any use of material in the RIPE database to target advertising or similar  #
# activities are expressly forbidden and will be prosecuted. RIPE requests   #
# to be notified of any such activities or suspicions thereof.               #
##############################################################################


How to access the database
--------------------------

The database software uses a 'whois' (RFC954) server with some special
RIPE specific extensions. Therefore, it is preferred to access the
database with a 'whois' client program or even better the RIPE 'whois'
version. The source code of the RIPE 'whois' client program can be
obtained from :
  
  ftp://ftp.ripe.net/tools/ripe-whois-tools-VERSION.tar.gz

The section 'More documentation' contains pointers to other documents on
the different type of objects that are stored in the database and can be
queried for. The standard RIPE 'whois' interface allows (except for some
exceptions) only searching for the names of the objects. If you also want
to search for other strings in the objects, you can use the WAIS
interface, however it doesn't support the special options that are
provided in the RIPE 'whois' interface.


Querying the database with 'whois' :


- whois -h whois.ripe.net SearchString
  
  (Examples: $ whois -h whois.ripe.net DK13-RIPE
             $ whois -h whois.ripe.net -T person David Kessens
             $ whois -h whois.ripe.net HELP)

  Usage: whois [-aFrSv] [-h host] [-s source] [-T type] [-L|-m|-M] SearchString

  Where:
  
  -a              search all databases
  -F              fast raw output (implies -Fr)
  -h hostname     search alternate server
  -i attributes   find the objects that reference the searchkeys in
                  the specified attributes
  -L              find all Less specific matches
  -m              find first level More specific matches
  -M              find all More specific matches
  -p port         connect to other port then the default whois port    
  -r              turn off recursive lookups
  -s source       search databases with source "source"
  -S              tell server to leave out "syntactic sugar"
  -t type         requests template for object of type "type"
  -T type         only look for objects of type "type"

  Please note that most of these flags are NOT understood by non RIPE 
  'whois' client programs. Sometimes the following work around will work :

  Instead of 
  
  whois -h whois.ripe.net -T person David Kessens 

  you can use

  whois -h whois.ripe.net "-T person David Kessens" 


The following other methods for accessing the database are available :

- http://www.ripe.net/

  and choose 'Database' under 'Services'

  OR


- WAIS

  use the following source:
  
  (:source
       :version  3
       :ip-name "wais.ripe.net"
       :tcp-port 210
       :database-name "ripe-database"
       :cost 0
       :cost-unit :free
       :maintainer "ripe-dbm@ripe.net"
       :description "This WAIS database contains the RIPE Network Management
                     Database which is also available at:
                     ftp://ftp.ripe.net/ripe/dbase") 
  
   
  OR

- telnet whois.ripe.net 43
  
  and type your whois options and SearchString followed by a return.

  (Example:
   
   $ telnet whois.ripe.net 43
   
   Trying 193.0.0.194...
   Connected to dbase.ripe.net.
   Escape character is '^]'. 
   
   -T person Kessens
   
   Output:
   
   person:      David Kessens
   address:     [ ... stuff deleted ...]   


- E-mail :

  Send mail to <whois@ripe.net> with in the body text:

  whois SearchString

  Please note that this method doesn't support the whois options!


The TEST database 
-----------------


A test database is available if you want to exercise or do some tests.
Use the E-mail address <test-dbm@ripe.net> for updates instead of
<auto-dbm@ripe.net> that is used for the real RIPE database.

You can query the test database with:

whois -h test-whois.ripe.net SearchString

Currently, the creation of maintainer ('mntner') objects has to be 
approved by the the RIPE NCC.  Send requests to <ripe-dbm@ripe.net>.
This is to be changed in the near future.

Every object in the RIPE database has a source that is specified in the
'source:' attribute of an object. The real RIPE database only allows
updates for objects with an attribute 'source: RIPE'.

The test database allows updates with two different 'source:' attributes:

TEST
TEST2

but note that the test database will by default only search for objects
with attribute 'source: TEST'. Use the 'whois -s Source' or 'whois -a'
option to search for objects with other sources.

Note that the test database is also used by the maintainer of the
software. Therefore, your data could be changed/deleted at the
maintainers will ;-). Also, there might be some small differences between
the real RIPE database and the test database behavior and software.


How to create a new object
--------------------------


- Get the template by using:

  whois -t TemplateType      
  
  Example: 

  whois -h whois.ripe.net -t person


- If you are completing a person template or want to reference a person
  in an object, we recommend to use a RIPE handle ('nic-hdl:'). You can
  also use NIC handles from other registries as the InterNIC if you are
  also registered there. RIPE handles will give you a unique identifier
  attached to a person which you can use as a reference. This avoids
  problems with different persons with the same name. You can get
  yourself a 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 building 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:  David Kessens
  nic-hdl: AUTO-1
  [ ... stuff deleted ...]   
  
  person:  Larry Wall
  nic-hdl: AUTO-2
  [ ... stuff deleted ...]   
  

- You can protect your objects with maintainer objects by adding a
  'mnt-by:' attribute. For some objects this is even mandatory. More
  information on maintainer objects can be found in ripe-120.{txt|ps}.

- Fill in the template and send it to auto-dbm@ripe.net. Put 'LONGACK' in
  the 'Subject:' line of your E-mail message to get a more verbose
  acknowledgment.



How to update an existing object
--------------------------------

This is done by sending in the whole new object. Probably the easiest way
to this is to grab the old object, change/add the fields you want
to change/add and add a new 'changed:' attribute to it.

- Get the template by using:

  whois -h whois.ripe.net SearchString >TemporaryFile
  

  Example: 

  whois -h whois.ripe.net DK13-RIPE
 
- Load the TemporaryFile in your favorite editor and make your
  changes/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 person. See the section
  on NIC handles of 'How to create an object' for more information.
  
  Note the following if you are updating a person (or route) object with
  a new or different NIC handle (or origin of the route):
  
  Don't forget to delete the old person (route) object since the database
  will treat a person (route) object with the same name but without or
  different NIC handle (origin) as a different object. This means that
  the old and new object cannot be identified as the same object and the
  update request will be treated as a creation of an 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 didn't have a NIC handle.

- Add a changed: attribute. This attribute has the following syntax :
  
  changed: E-mailAddress Date

  'E-mailAddress' is an RFC822 E-mail address specifying who made the change
  and 'Date' is the date of the change in YYMMDD format.

- Send your message to <auto-dbm@ripe.net>


How to delete an old object
---------------------------

This is done by sending in the whole object just like
an update and adding a pseudo-attribute 'delete:' to it:

delete: Why I did the delete

Example:

person:      David Kessens
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:      david@ripe.net
nic-hdl:     DK13-RIPE
notify:      david@ripe.net
changed:     david@ripe.net 941207
source:      RIPE
delete:      Since I hate all these E-mails from my fans.

The deletion is only accepted if the object in the message is *exactly*
the same as the one in the database about to be deleted. Please be very
careful with deleting person objects if you are not sure if the object
is not referenced by other objects. You can find objects that reference a
certain person by doing a '-i' query:

Example: 

$ whois -h whois.ripe.net -r -i tech-c,admin-c,zone-c NIC-handle

note: some people might have used their name as a reference instead of
      their NIC-handle!

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 hurt the
database very much when there are some obsolete person objects.
Authorization and notification for deletes are handled exactly the same
way as for ordinary updates.


Hints and tips
--------------

- Section 'More documentation' contains pointers to other documents on
  the RIPE database objects and their syntax.

- You can get the latest version of this document by using 'HELP' as your
  SearchString or sending an E-mail message with 'HELP' in the 'Subject:'
  line to <auto-dbm@ripe.net>

- The 'whois' access method let's you only search for certain key values
  in the objects. The WAIS database has an index based on all the
  information in the database, however it doesn't support searches for
  more/less specific prefixes as the whois server does!

- Separate objects from each other and from other text by using
  empty lines. Start and end your mail message with a blank line to be sure
  that mailheaders and signatures will not be attached to the objects!

- Check for existing objects in the database before submitting an object.
  You can use the keyword 'NEW' in the 'Subject:' line of your message if
  you want the database to only accept new objects or 'ASSIGN' for only
  accepting new 'inetnum:' objects.

- Be careful when deleting person objects. Other objects might have
  references to the person you want to delete. You can check for
  references by doing a 'whois -h whois.ripe.net -r -i person SearchString'
  You can better don't delete them when you are not sure.

- Try to use NIC handles. They uniquely identify a person. This prevents
  updating another person with the same name and adding a person twice in
  the database. Please note that when you add a NIC handle to an existing
  person, your update will not be recognized as a *change* of your object
  when you also add other changes to the person object. It will then
  create a new entry. So, to avoid duplicate objects, please delete the
  old object without the NIC handle.

- Protection against other people changing your data is present in the
  database software. See ftp://ftp.ripe.net/ripe/docs/ripe-120.{txt|ps}
  for more details.
  
  - You can protect objects itself by using a 'mnt-by:' field.
  
  - You can protect against people *creating* (only creating) objects
    direct (one level) below in the hierarchy of an object type (only for
    'inetnum:/domain:' objects) by using your maintainer in a
    'mnt-lower:' attribute. The authorization method of this maintainer
    object will then be used upon creation of any object direct below the
    object that contains the 'mnt-lower:' attribute.

- Sending in 'domain:' objects doesn't mean that your domain is
  registered with a certain Top Level Domain. This is a 'For Your
  Information' object. Contact the the appropriate Top Level Domain
  maintainer for registering your domain.

- 'guardian:' attributes are old and should not be used anymore. They are
  still in the database for backward compatibility.
                          
- Old 'guarded objects' need manual updating. These are objects with a
  'guardian:' *and* without a 'mnt-by:' attribute. We don't accept this
  kind of object anymore. First submit a maintainer ('mntner', see
  ripe-120.{txt|ps}) to <auto-dbm@ripe.net>. After approval of the
  maintainer object, please add a 'mnt-by:' attribute to your old
  'guarded object' and send it to <ripe-dbm@ripe.net>. After this has
  been done your object can be updated and deleted with the normal
  automatic update procedure.

- You can get a template of every object by giving the command:

  whois -h whois.ripe.net -t ObjectType

- To get a verbose explanation about your database object creation/
  update/deletion trial, put the string LONGACK somewhere in the subject
  line of your message.

- Send all your (automatic) updates to auto-dbm@ripe.net If the database
  doesn't allow automatic deletion/creation/updating of an object it will
  tell you or forward your request to the human mailbox. If you use
  'mntner' objects you will be allowed to change/create all your objects
  yourself, even the 'mntner' object itself. Only the creation of an
  'mntner' object has to be approved by the RIPE NCC. See 'More info'
  where to find more documentation on 'mntner' objects.

- Should you have any more questions, please do not hesitate to ask
  questions at <ripe-dbm@ripe.net>.



More documentation
------------------


In the ripe document store (ftp://ftp.ripe.net/ripe/docs):

  - ripe-120.{txt|ps}   - On 'mntner' (maintainer) objects
  - ripe-127.{txt|ps}   - on Provider Independent vs Provider Aggregatable
                          address space and the advisory attribute
  - ripe-131.{txt|ps}   - On 'advisory' attributes  
  - ripe-181.{txt|ps}   - On routing policy database objects
                        
                          In ftp://ftp.ripe.net/pride/docs you can find : 
                        
                          guide-2.0.{txt|ps}.tar.Z
                          
                          with much ripe-181 related information. This
                          guide is very large and is not for starters !
  

- Older documents that still contain valuable information (mainly object
  templates) but also some other data and procedures that have been changed:

  - ripe-049.{txt|ps}   - Template for Domains
  - ripe-119.{txt|ps}   - Template for Networks and Persons


- Obsoleted documents, do NOT use/read:
    
  - ripe-050.{txt|ps}   - Template for Networks 
  - ripe-051.{txt|ps}   - Template for Persons
  - ripe-081.{txt|ps}   - On routing policy database objects
  - ripe-096.{txt|ps}   - On Authorization and Notification 
  - ripe-108.{txt|ps}   - On 'guardian:' attributes
  - ripe-117.{txt|ps}   - On 'guardian:' attributes
                          'guardian:' attributes are old and should not be 
                          used anymore. They are still in the database for 
                          backward compatibility.
  - ripe-126.{txt|ps}   - RIPE handles and the 'status' attribute                          
  - ripe-130.{txt|ps}   - On 'advisory' attributes  

