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

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. 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>.


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. Therefor, 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.tar.Z

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
  -L              find all Less specific matches
  -m              find first level More specific matches
  -M              find all More specific matches
  -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 :

- 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:     RIPE Network Coordination Centre (NCC)   
   [..])


- http://www.ripe.net

  and choose 'Search the RIPE Database'

  OR

- telnet info.ripe.net

  and choose 'Search RIPE Network Management Database'.

  OR

- 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 <testdb@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

Creation of maintainer ('mntner') objects is allowed for everybody in
contrast to the real RIPE database. However, you will receive a warning
that this is not the normal behavior.

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 find the
  first free handle by using :

  $ finger handle.INITIALS@whois.ripe.net

  Use instead of INITIALS the initials of your name, but don't use more
  then 4 characters. Note that this method does NOT reserve the handle
  for you. Please send in your template as soon as possible after finding
  the first free handle to avoid collisions with people with the same
  initials trying to update their own object at the same time. If
  somebody else used already your handle in the mean time your template
  will be rejected and you should use 'finger' to find the next new one. 
  Don't forget the '-RIPE' suffix part of the handle in your 'nic-hdl:'
  attribute. This suffix is part of the handle and guarantees that it is
  unique in all the registry databases, e.g. the InterNIC has no suffix
  (for historical reasons), RIPE the -RIPE suffix and APNIC the -APNIC
  suffix.

  (Example:

   Your name might be: 
   
   Larry Wall
   ^     ^

   Type in:

   $ finger handle.LW@whois.ripe.net

   Output:
   
   [dbase.ripe.net]
   First free handle: LW6-RIPE  


   Add the following attribute to your person object and send it in as
   fast as possible to avoid clashes with other people (experience learns
   that this doesn't happen to often ;-)):
   
   nic-hdl: DK21-RIPE

- 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.

- 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

- 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: E-mailAddress [why]

'E-mailAddress' is an RFC822 E-mail address specifying who deleted the
object
[why] is optional free text explaining why the deletion took place.

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:      david@ripe.net 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 (including tabs!) as the one in the database about to be
deleted. Note that since there is currently no way to find out if a
person object is referenced by other objects, it is recommended to be
very careful with deleting person objects (Please don't delete me ;-)).
If you're not sure that your 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.

- 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.

- Be careful when deleting person objects. Other objects might have 
  references to the person you want to delete. You can't check if other
  objects have references to the person you want to delete with the 
  current software. 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
  but will 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.

- 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 inform you that your request has been forwarded 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-049.{txt|ps}   - Template for Domains
  - ripe-119.{txt|ps}   - Template for Networks and Persons
  - ripe-120.{txt|ps}   - On 'mntner' (maintainer) objects
  - ripe-126.{txt|ps}   - RIPE handles and the 'status' 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 !
  

- Old/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-130.{txt|ps}   - On 'advisory' attributes  
