Installation Information For RIP Whois Server
*********************************************


If You Are In A Hurry:
======================

Don't be. Take your time, fetch a cup of tea, coffee, or your favorite
beverage, relax, and read the rest of this file.


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 gcc at ftp://ftp.gnu.org/gnu/gcc/

	- GNU Make (3.79.1)
		Get it at ftp://ftp.gnu.org/gnu/make/

	- glib (1.2.8)
		Get it at ftp://ftp.gtk.org/pub/gtk/

	- MySQL Server + Client libraries (3.23.36)
		Get it at http://www.mysql.net/download.html


Optional:

	- PERL (5.005_03). It is only needed for the ripe2rpsl converter
	  and the remadmin.pl remote administration interface.
		Get it at http://www.cpan.org/
	  For remadmin.pl, you will also need the Net::Telnet module.
		Get it at http://www.cpan.org/modules/by-module/Net/

	- The c-client library, from the IMAP distribution (imap-2000a).
	  It is needed for MIME parsing in dbupdate.
		Get it at ftp://ftp.cac.washington.edu/imap/

	- GNU Privacy Guard (1.0.4). You don't need it if you don't plan  
	  to use dbupdate.
		Get it at http://www.gnupg.org/download.html

	- zlib is required by the RAToolSet RPSL parser in dbupdate.
	  	Get it at http://www.info-zip.org/pub/infozip/zlib/

	- If you want to regenerate the defs, you also need java (1.1.7)
	  and an XML parser.

	- There are some header files in certain modules
	  which are generated by m4. If you want to change them, you need
	  to have GNU m4 (1.4) installed in your system. 
	  You can get it at ftp://ftp.gnu.org/gnu/m4/ .

	- Some source files in the RPSL parser and in the ER module
	  are generated with Lex and Yacc templates. You will need
	  flex (2.5.4) and GNU bison (1.25) if you want to change them.
	  Please note that we experienced problems with bison 1.28.
	  You can get these packages at:
	  ftp://ftp.gnu.org/non-gnu/flex/
	  ftp://ftp.gnu.org/gnu/bison/

We tested the software on Solaris/SPARC 2.6, 7 and 8, and on 
Solaris/Intel 7.  We currently compile releases on Solaris, FreeBSD
(4.1), and Linux (RedHat 6.2 kernel 2.2.x)


More effort will be put on testing on other platforms in the future.

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 "build.sh", which is a wrapper to "configure",
	 and set your site-specific variables,
         namely GLIBCONF, MYSQLINC, MYSQLLIB, CCLIENTDIR. 
	 You can also choose your compiler and change the compiler flags 
	 if necessary.
      c. Issue "./build.sh --prefix=<your_prefix>" in the root directory
	 of the tree. You can supply any other argument that "configure" 
	 would accept. We suggest to use a special directory as the 
	 prefix, e.g. /usr/local/whois_rip (the suggested default).

         Note to FreeBSD users:  You need library that supports
         gethostbyname_r(), the multithreaded DNS lookup call.  The
         bind8 package provides this.  You must then add this option
         when invoking build.sh:
 
             --includedir=/usr:/usr/local:/usr/local/include/bind

         If you wish to install BIND yourself, you may need to use the
         following syntax:

             $ CFLAGS="-I/usr/local/bind/include -L/usr/local/bind/lib" 
             $ export CFLAGS
             $ sh build.sh

         Also, you should install DES encryption if you want to support
         dbupdate using crypted passwords.
      d. Issue "make". This will compile all the modules, then whois_rip,
	 loader, dbupdate and mr.
      e. Issue "make install". All the relevant files will be installed
	 in <your_prefix>.

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 use your own objects, if you have them.
      b. 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
      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 see the section "Near-Real-Time Mirrors"
	 below for details.
      d. If you are not a Near-Real-Time Mirror but want to
	 become one, please contact <ripe-dbm@ripe.net>.

3. Load the databases.

4. Run whois_rip.

5. Run dbupdate if you need.

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

7. Check the logfiles (see the section "Logfiles" below).

8. Setup the infrastructure utilities (see the section "Infrastructure"
   below).


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,
and we will refer to your installation prefix with ${prefix}.


CONFIGURATION
-------------

The setup of variables that will make the RIP server work is
contained in two configuration files.

The "main" configuration file contains a number of configurable variables
for the server. It is a generic configuration file; you can use the same
file for all the different parts of the server (rip, load, dbupdate).

The "source" configuration file is a separate file which contains all the
information relevant to each of the sources that you want the software to
handle. Its location is indicated in the SOURCEFILE variable inside the
main configuration file.

We have included example configuration and source files in the
distribution: they are called rip.config.example and
sources.config.example . You can find them in the conf/ subdirectory.
Both files contain a description of each variable; many variables
contained in the main configuration file are also present in ripe-dbase
whois version 2.3 software, so if you have used that software you will be
familiar with them.

There is a small number of variables which are not yet in use; these are
marked with the tag "[not implemented yet]".


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

Before loading a database, make sure that you have a MySQL user with all
permissions configured in your MySQL DB.

The database creation and loading process is controlled by the script
${prefix}/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 config_file db_name [source [serial]]

The variables to change are:

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.
GLIBCONF   - location of your glib-config script.
MYSQLLIB   - location of your MySQL libraries.

You also need to appropriately modify your configuration files. The most
important variables to configure are RIPADMIN and the entries in the
source configuration file.

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 ${prefix}/bin/whois_rip. 

To start the service:

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

$ cd ${prefix}/bin/
$ ./whois_rip <config_file_name>

where <config_file_name> points to a main configuration file. It is a
good idea to use the same configuration and source files that you used
for database loading; note that there is a bunch of variables that are
used by whois_rip and not by loader, so you may want to add customization
to your config file.

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 $NOTIFY e-mail address upon restart. If the number of
crashes exceeds a variable $CRASHES, it sends a mail to $NOTIFY and does
not restart the server, thus avoiding mail flooding. To use it, modify
the site-specific variables inside the script, then simply type:

$ ./rip <config_file_name>

Depending on the desired operation mode you need to define the opMode
entry for each SOURCE in the source configuration file.

Its most common values are:
0 - static, no update thread
2 - update server (serving requests from dbupdate)
4 - NRTM client


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

The "${prefix}/bin/dbupdate" program is used to create/delete/update
objects.

Usage of dbupdate:

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

-M: Read from a mail message. This flag will activate the MIME parser.

-S: Send all notifications and acknowledgements to DEFMAIL. For debugging
    purposes.
      
-f: Read from a file. 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. Corresponds to the "TESTMODE" variable
    in the config file.


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

UPDSOURCE: dbupdate does not support updating multiple sources; you
should have, in the config file of dbupdate, one and only one "UPDSOURCE"
line with the name of the source you want to update and some relevant
information. The description of the UPDSOURCE variable can be found in
the main config file.

You can also modify many other variables in the config file. Some of the
most important are:
LOCKDIR
OVERRIDECRYPTEDPW
TMPDIR
MAILCMD
HUMAILBOX
AUTOBOX
PGPPATH
GPGCMD



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

The RIP server can only mirror a RPSL stream. If you want to mirror a
RIPE-181 database (like the current RIPE Database at whois.ripe.net), 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 host 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.

Please note that if you are an authorized Near-Real-Time Mirror of the
RIPE Database, and you want to mirror the RIPE Database using the new
software, we will provide you with a direct RPSL stream to connect to;
you won't have to use the Mirror Reflector. Just contact
<ripe-dbm@ripe.net>.


Logfiles
========

There are many definitions of logfiles in the main config file. We
suggest you to set them all in order to have a complete view of the
server operations. Please note that the intermediate directories must
exist; the log system only creates the files if necessary.

The most important files you will want to check are:
QRYLOG
RIPERRLOG
RIPUPDLOG (if you run a NRTM client)
DBUPDLOG, UPDLOG and ACKLOG (if you run dbupdate).


Infrastructure
==============

This package comes with some infrastructure tools that can be used to
maintain the database. They are not compiled nor installed automatically.
Up to now, the following tools are available:

  - Remote Administration Interface: you can find it under
    utils/remadmin.pl . This script connects to the configuration port
    of your server to perform administrative tasks such as pausing and
    restarting updates, checking the status of the threads, etc. It is
    actually a non-interactive interface to 
    "telnet <server> <configport>".
    Currently, you need PERL and the module Net::Telnet to use this
    interface. It will be eventually rewritten in C.

  - Serials/History Cleanup: This utility connects directly to the
    SQL Database and cleans up old history and serial entries. Please
    read the file README under utils/hs_cleanup .

  - Text Export: This utility builds plain text files, such as the ones
    used for loading, from a v3.0 whois server. For more details,
    please check the file README under utils/text_export .
