Installation Information For RIP
********************************

Prerequisites:
==============

These prerequisites are essential for the installation of RIP software.
Please make sure they are fulfilled before going on with the installation
procedure.

You need to have the following software installed into your system (the
version that we use is in brackets):
	- gcc (2.95.2), or the ucbcc compiler from Solaris Workshop (5.0)
		Get it at ftp://ftp.gnu.org/gnu/gcc/
	- GNU Make (3.78.1)
		Get it at ftp://ftp.gnu.org/gnu/make/
	- glib (1.2.7)
		Get it at ftp://ftp.gtk.org/pub/gtk/
	- MySQL Server + Client libraries (3.22.29)
		Get it at http://www.mysql.net/download.html
	- PERL (5.005_03). It is only needed for the ripe2rpsl converter.
		Get it at http://www.cpan.org/
	- The c-client library, from the IMAP distribution (4.7b).
	  It is needed for MIME parsing in dbupdate.
		Get it at ftp://ftp.cac.washington.edu/imap/
	- GNU Privacy Guard (1.0.2). You don't need it if you don't plan to
	  use dbupdate wiht PGP authentication.
		Get it at http://www.gnupg.org/download.html
	- If you want to regenerate the defs, you also need java (1.1.7)
	  and an XML parser.

We tested the software on SPARC/Solaris 2.6 and 7, and on Intel/Solaris 7 .


Installation Procedure:
=======================

To run the database you need to perform the following steps:

0. Download the reimplementation software release and unpack it.
   If you are reading this file, you probably have already done this.:-)

1. Compile the code.
      a. Please check the "Prerequisites"; you will not be able to compile
         the code if these are not fulfilled.
      b. Edit the file "Makefile.site.generic", or rename it as
         "Makefile.site.$HOSTNAME" where HOSTNAME=`hostname` on your host.
         This file contains some site-specific variables you should modify,
         namely GLIBCONF, MYSQLINC, MYSQLLIB, CCLIENTDIR. 
	 You can also choose your compiler and change the compiler flags 
	 if necessary.
      c. Some variables are hardcoded in this version of the update module, 
	 so you must have a look in the modules/up/dbupdate.h file and change
         the appropriate #defines. See below "RUNNING DBUPDATE" for details.
      d. Issue "make" in the root directory of the tree.
         This will automatically compile whois_rip, loader, dbupdate and mr.

2. Download a database snapshot containing all the split object files 
   and the current serial number.
   You have here a few possibilities:
      a. You can download the example snapshot, containing
	 a few objects of all "old" types. This snapshot
	 is located at
	   ftp://ftp.ripe.net/ripe/dbase/reimp/objects.tar.gz
      b. You can use your own objects, if you have them.
      c. If you are an authorized Near-Real-Time Mirror,
	 you can try to mirror the RIPE Database using this software.
   	 You can find the split object files under
	   ftp://ftp.ripe.net/ripe/dbase/split
   	 And the current serial number is available at
	   ftp://ftp.ripe.net/ripe/dbase/RIPE.CURRENTSERIAL
	 Please note that in version 0.4.0 the near-real-time mirroring
	 functioning has changed: see the section "Near-Real-Time Mirrors"
	 below.
      d. If you are not a Near-Real-Time Mirror but want to
	 become one, please contact <ripe-dbm@ripe.net>.

3. Create and load the databases.

4. Run whois_rip.

5. Run dbupdate.

Steps 3,4,5 are explained in detail below.

6. Under utils/whoisRIP, you can find whoisRIP.c, a very simple whois
   client that you can use to query a RIP database. This whois client
   does not check the whois flags (except -h and -p) at the client side,
   but sends them to the server where they will be processed. It is
   handy to query the whois database with the new flags, which are not
   supported by the "classic" whois.

   To compile and install it, just cd to utils/whoisRIP and follow the
   instructions in the README file.


Preparing the Database and Running the Server:
==============================================

INTRODUCTION
------------

The service relies on the following databases:
- main database containing object tables, and
- administrative database currently containing access control table.

In the text below the term 'database' will reference the main database.

PROPERTIES AND CONFIGURATION
----------------------------

The setup of variables that will make the RIP server work is currently
mixed in two different files: the "properties" file and the
"configuration" file. Eventually, the properties file will disappear, and
all the variables will be set by the configuration file.

The properties file still contains some variables:

++++
[These variables are used by whois_rip]
SV.whois_port=43001   - port to answer whois queries
SV.config_port=43002  - port for configuration
SV.mirror_port=43003  - port for NRTM server

[These variables are used by whois_rip and loader]
DB.user=user1         - user name needed to access the database 
DB.password=mypswd    - password needed to access the database 
DB.host=dbhost.db.net - name of the host where the database resides 

CO.config_file=rip.config - name of the configuration file

SV.authenticate=0     - switch for the authentication in the admin
		        interface
++++

We have included a template for the PROPERTIES file in the
distribution, under the conf/ subdirectory. 
It is called PROPERTIES.example .


The configuration file, introduced in version 0.4.0, contains a number of
configurable variables for the server. It is a generic configuration file,
which can be used for all parts of the server (rip, load, dbupdate). 

We have included an example configuration file in the distribution: it is
called rip.config.example . You can find it in the conf/ subdirectory.
All variables are explained in this file; most of them are present 
in the current ripe-dbase whois software, so if
you have used that software you will be familiar with them.

Not all the variables are being used as of now; the file also comments if
the variable is used or not, by adding a "***used by: <program>*** string
to the used variables.

Most variables that were set up in the properties file are now set up in
the configuration file, with the new variable SOURCE. The example file
provided explains how this variable works.

Note: The configuration file needs an auxiliary file, dictionary.txt,
which provides the definitions for the configuration variables. This file
must be present in the working directory. We have placed a copy of it in
bin/load, bin/rip and bin/dbupdate .


DATABASE CREATION AND LOADING
-----------------------------

The database creation and loading process is controlled by the script
bin/load/make_db. Before starting the script, you need to edit it in
order to change several variables according to your site configuration,
and call it with some arguments. The usage of make_db is:

make_db properties_file db_name [source [serial]]

The variables to change are:

SOURCE     - The source of your database (e.g. RIPE, RADB, APNIC...)
MYSQL      - location of your MySQL client.
HOST       - name of the host where the database resides.
USER       - user name needed to access the database.
PASSWORD   - password needed to access the database.
OBJDIR     - location of your object files from the snapshot.

You also need to define several variables in the properties file
referenced by the PROPERTIES variable. To run query server and NRTM client
you need to define the following:

DB.user=(same as $USER)
DB.password=(same as $PASSWORD)
DB.host=(same as $HOST)
CO.config_file=(path of your rip.config file)

In the configuration file defined by CO.config_file, you should change the
mode of your source to 7 (which allows the loading of dummy objects[*]).

As soon as this is done you may start bin/load/make_db script, which
will perform the following operations:

- create main ('db_name') and administrative (RIPADMIN) databases;
- load the database (I and II passes);
- create the necessary indexes.

After the script finishes look at the log files for errors.

Please note that if you are loading the whole RIPE Database, doing this
might take a fair amount of time, even several days. The more powerful
your machine is, the less it will take to do this task.


STARTING THE SERVICE
--------------------

The name of the RIP main server is bin/rip/whois_rip. 

To start the service:

$ cd bin/rip/
$ ./whois_rip <properties_file_name>

where <properties_file_name> points to a properties file similar to the
one we used for database loading.

The environment variable LD_LIBRARY_PATH should be set to
"$GLIBLIB:$MYSQLLIB" (where $GLIBLIB and $MYSQLLIB are your
site-specific directories for Glib and MySQL libraries).

In the same directory, you can find a wrapper called "rip"  which sets
LD_LIBRARY_PATH and restarts whois_rip whenever it dies, sending a mail
to a predefined e-mail address upon restart. To use it, modify the
site-specific variables inside the script, then simply type:

$ ./rip <properties_file_name>

Depending on the desired operation mode you need to define the Mode entry
in the SOURCE variable(s) inside the configuration file specified in
CO.config_file.

Its most common values are:
7 - when you want to launch query and update mode, allowing dummy objects[*]
1 - when you want to launch query and NRTM client mode, allowing dummy 
    objects[*]
_______________ 
[*] Dummy objects are temporary objects in the database created to
maintain referential integrity of the database when some object
references a non-existent other object. For example, while creating a
domain object, a dummy person object will be created for admin-c
attribute if it references a non-existent NIC handle. You may want to
use this feature when loading inconsistent data. When dummy creation is
disabled you will get referential integrity error when attempting to
create inconsistent objects.


RUNNING DBUPDATE
----------------

The "bin/dbupdate/dbupdate" program is used to create/delete/update
objects.

Usage of dbupdate:

dbupdate [-M] [-c <config_file>] [-t] [-T] [-f <full_path_filename>]

-M: If reading a mail message, this must be used. It will
      activate the MIME parser.
      
-f: If we are reading the objects from a file, this option
      must be used. Must be full path.
      
-c: to change the configuration file to be used. The default
      one is ./dbupdate.conf

-t: "trace", to print some debugging information.

-T: to run dbupdate in test mode, where the as-block
      and mntner objects can be created without overriding
      authorisation.


There are several variables that you can/should customize in the
configuration file.

SOURCE: dbupdate does not support updating multiple sources; you should
have, in the config file of dbupdate, one and only one "SOURCE"
line with the name of the source you want to update and some
relevant information. Only a few fields are actually relevant,
the others are dummy. Actually, the SOURCE variable was not
designed for this use. This is a temporary setup, and will be
fixed in the future.

SOURCE MYDB RIPWhoisHost,RIPWhoisPort,blah,blah,blah x RIPUpdateHost,RIPUpdatePort,blah,x,x x y,x

(The "x" represents dummy numbers, but the "y" must be there!)

An example SOURCE line for dbupdate could be the following:

SOURCE RIPE mickey,43001,foo,bar,BOF 0 mickey,43004,/db/whatever/,1,1 0 y,0


You should also modify:
OVERRIDECRYPTEDPW
ACKLOG
TMPDIR
MAILCMD
HUMAILBOX
PGPPATH

dbupdate does not need a properties file.

Please note! If you want to use the PGPKEY authentication scheme 
in your DB, you will need to install the GPG (GNU Privacy Guard)
package and have the "gpg" binary in your path (or in the path 
of your scripts) when you call dbupdate. This binary 
will be called by dbupdate to import keys and verify signatures.




Near-Real-Time Mirrors:
=======================

With version 0.4.0, there was an important change in the way
near-real-time mirroring works in RIP. The RIP server can now only mirror
a RPSL stream. If you want to mirror a RIPE-181 database (like the current
RIPE Database), you need to run a "mirror reflector".

This is a tiny program, provided in the distribution under "bin/mr", which
connects to a specified NRTM server (-h host -p port) and accepts requests
from a RPSL NRTM client (-l listen_port). It can obviously run in the NRTM
client itself.

After receiving a request, the mirror reflector converts the data stream
on the fly using a specified converter (-f converter); in the case of
RIPE181 to RPSL, you can use the "ripe2rpsl" perl script.

Your RIP server needs then to connect to the reflector instead of the real
server, so that it gets a converted RPSL stream.
