$Id: INSTALL,v 1.5 1998/12/09 14:38:54 roman Exp $

REQUIREMENTS

Since the beta releases of 2.1 the database software now requires
perl5.

See RELEASE-NOTES for systems that are tested with the software.

QUESTIONNAIRE

If you are using the ripe database software in a production system we
ask that you fill in the questionnaire in the QUESTIONNAIRE file and
return it to us.

INSTALLATION

Note: The installation procedure for 2.1 has changed from previous
releases.

You should unpack this distribution in your usual build area,
typically this is /usr/local/src.

Once you have unpacked the distribution you see the following files &
directories:

  Makefile        - makefile for this distribution - don't change
  Makefile.config - site specific parameters you might need to change
  INSTALL         - this file
  README	  - a README
  SECONDARIES	  - a description on how to run a mirror/secondary database
  RELEASE-NOTES   - notes on this release
  src/            - source directory containing necessary sources
  man/            - directory containing manual pages for executables and
	            configuration file (beware: most are quite old)
  doc/            - directory containing some documentation (more coming)
  etc/            - directory for help and sample config file 'ripedb.config'
  build-tools/	  - some short (portable) perl scripts used to build and
		    install the package.

The various empty installation directories of previous releases are
not included in the distribution.

1. edit 'Makefile.config' to include the site specific configuration. 

  Typically you should only need to change the first two parameters
  'INSTALLDIR' and 'PERL' to specify where you want the package to be
  installed and where your perl5 binary lives.  If the various standard
  tools are not in your path you may need specify specific paths. If you
  want to test the distribution in the build directory set INSTALLDIR to
  the full path name of the directory Makefile.config is in.

2. run 'make config' to build the Makefiles in the subdirectories.

   this also adds the '#!.../perl' line to the top of some scripts
   used to build the package in the build-tools/ directory.

   The Makefiles don't use any implementation specific directives so
   they should be compatible with any make program you have.

3. run 'make' to build the executable scripts.

4. run 'make install' to install the package.

   this will create the various directories and install the executables,
   manuals, configuration and support files.

   The directories created are...

   bin/            - the system executables
   lib/            - database library perl routines
   doc/		   - help documentation given out by whois and mail
   data/           - actual data text files and indexes
   locks/          - lock files
   tmp/		   - temporary files
                     This directory should be owned (and be writable) by the
                     user that owns the whole database software. 
                     Don't use /tmp for temporary files!
   serials/        - directories for storing the serial files                  

   Note: 'make install' won't overwrite your ripedb.config but it will
         overwrite the documentation files in doc/. If you have 
	 local help files make sure you have a copy of these and then
	 re-install them.

5. edit etc/ripedb.config

  A sample ripedb.config file is generated by 'make install' in 

    .../etc/ripedb.config-example

  Copy it to ripedb.config and edit it. You should at least do the
  following...

  The fields that have file names are set with the paths from
  Makefile.config so you shouldn't need to change them.

  Add DBFILE lines pointing to your database files.
  If you just want to test the software with a couple of

  Change UID to be the user that 'owns' the database. Used if run
  as root on port 80.

  Put your local email addresses in...
    DEFMAIL
    HUMAILBOX
    AUTOBOX  (see step 6)

  Check the path to your local MTA in
    MAILCMD

  Change the various texts used to generate mail messages so they refer
  to your own site.

  Check through the rest of the file to see that it is reasonable for
  your site. Don't change the Object definitions at the end of the file
  unless you know what dependencies there are in the code.

  See the file SECONDARIES for more information on how to run your own RIPE
  database mirror and the possibility for a nearly real-time mirror!

  To allow updates by mail you need to get your MTA to deliver mail for
  the address you defined in AUTOBOX to the dbupdate program.

  Create a .forward file (for sendmail) in the home directory of the
  database user with the following contents:

    "|bin/doupdate"

  and make the small shell script:

    bin/doupdate
    ----
    #!/bin/sh

    INSTALLDIR="yourtopdir";

    RIPEDBCNF=$INSTALLDIR/etc/ripedb.config ; export RIPEDBCNF
    cat | $INSTALLDIR/bin/dbupdate -M

    # end of script 
    ----

  to make sure that it picks up the right configuration or just run
  '|./bin/dbupdate -M' from .forward.

6. Create empty database files.

   Use newdb program. The newdb program is provided to facilitate creation 
   of empty database and index files, now indispensable for database in 
   SPLIT mode to work with integrity checks. 

   The syntax of newdb is now following:
   
   newdb [-f] filename 
              creates a data file and the corresponding index file.
   newdb [-f] -a 
              creates all data files and the corresponding index files.
              It relies on ripedb.config being properly set up, as it
              extracts the name of the database and object types from it.

   newdb refuses to overwrite an existing file unless option -f (force
   creation) is given.

   This step is of course not necessary if you upgrading your software only 
   and have database files already :-)

7. Testing

  Once you have installed the package you can try a few tests.
  These examples assume that your current directory is the 
  installation directory.

  NOTE: If you are copying data from a production database 
   set the TESTMODE option in the configuration file. This will
   stop notifications going to the people mentioned in the objects!

  Create a person object ...

  $ ./bin/dbupdate
  person: Fred Flintstone
  address: Bedrock
  phone: +99 1234 567 890
  nic-hdl: FF99
  changed: me@my.site 
  source: TEST
  ^D

  If there are no errors, check the 'data' directory for the following

    -rw-r--r--     949 testdb.pn
    -rw-r--r--   16384 testdb.pn.db
    -rw-r--r--     643 testdb.ro
    -rw-r--r--   16384 testdb.ro.db

  the role files will also be created as they share the same lookup
  keys.

  Retrieve the object...

    ./bin/whoisd FF99

  should return the object you entered.

  Create a inetnum obj to check that the classless indexes are also
  created...

  $ ./bin/dbupdate 
  inetnum:     192.168.0.0 - 192.168.0.255
  netname:     RFC1918-C-SPACE
  descr:       rfc1918 C space
  country:     EU
  admin-c:     FF99
  tech-c:      FF99
  changed:     me@my.site 971014
  source:      TEST

  You should now have these files as well...

     -rw-r--r--  1183 testdb.in
     -rw-r--r-- 16384 testdb.in.cl.db
     -rw-r--r-- 16384 testdb.in.db

7. To set up a server to mirror whois.ripe.net see the file
   SECONDARIES.

