source: branches/stable/INSTALL@ 868

$Id: INSTALL 508 2011-11-16 21:28:37Z kdeugau $

Requirements
============

- Any CGI-capable web server that can execute arbitrary files or 
  files with administrator-defineable extensions
- PostgreSQL >= 7.4.  It should be possible to (fairly) trivially patch 
  the code for any other DBMS that supports:
  - an IP address/CIDR netblock data type
  - higher/greater, lower/less than, contains, and is-contained-by 
    operators
- Perl >= 5.6
  - Standard modules:
    These should be included in any base Perl install
    - File::Path
    - CGI::Carp
    - POSIX
    - Sys::Syslog
  - Extra modules:
    - NetAddr::IP >= 4.x.  3.x may work, however 4.x has been out for 
      more than 4 years.
    - DBI
    - DBD::Pg
    - Sys::SigAction.  This isn't strictly required;  it's used in an 
      example hook for validating customer IDs against an external 
      database.  It could arguably be replaced with sigaction() from the 
      POSIX module when using Perl >= 5.8.2.  See eg Sys::SigAction on 
      CPAN (http://search.cpan.org/~lbaxter/Sys-SigAction-0.11/lib/Sys/SigAction.pm) 
      for some thoughts on the gritty details.

Installing the IPDB
===================

1) Untar in a convenient location.  You should be able to simply use the 
unpacked tarball as-is, or you can run "make install" to install files 
in /usr/local/lib/ipdb-#VERSION#, with configuration modules in 
/usr/local/etc/ipdb-#VERSION#.

The Makefile supports substitution on most standard 
GNU/FHS-ish paths, so you could also run:

  make install prefix=/opt

to install it under /opt.

The Makefile also supports DESTDIR for packaging, so you can use:

  make install libdir=/usr/lib sysconfdir=/etc DESTDIR=/tmp/ipdbpkgroot

to install for packaging under /tmp/ipdbpkgroot with the core scripts 
and HTML packaged under /usr/lib/ipdb-#VERSION#, and the configuration 
modules packaged under /etc/ipdb-#VERSION#.

2) Configuration:  These module files will either be in the cgi-bin/ 
directory from the unpacked tarball, or /usr/local/etc/ipdb-#VERSION# 
if installed with 'make install'.
  a) Edit MyIPDB.pm:  you need to set the database DSN and 
    company info.  You should probably also set the syslog facility and 
    default custid.
  b) Edit CustIDCK.pm as needed to validate customer IDs.

4) As a Postgres superuser, create a database user and the database:

shell> psql template1
pg# create user ipdb with password "ipdbpwd";
pg# create database ipdb owner ipdb;

Add the PL/pgSQL language to the database.  This is not strictly
necessary but there are triggers on the poolips and allocations table
to automatically update a last-modified column.

pg# \c ipdb
pg# create language plpgsql

Create the inital tables using cgi-bin/ipdb.psql:

shell> psql -U ipdb ipdb <cgi-bin/ipdb.psql

5) Configure your webserver to call the IPDB scripts at an appropriate 
web path.  A webroot pointing to the HTML files (first level under 
the ipdb-#VERSION#/ tarball directory, or /usr/local/lib/ipdb-#VERSION#)
should work fine;  a server alias under an existing virtual host should
work as well.

Set $IPDB::webpath (the web path to your IPDB install) in MyIPDB.pm.
Straight out of the tarball it should work at the webroot, but if you
want it in a subdirectory, you'll need to set this variable to get all
of the internal links to behave properly.

The directory containing the HTML and scripts must have at least the 
following Apache directives (or other server equivalent) set:

  Options ExecCGI IncludesNoEXEC

6) User lists can be maintained two basic ways:

  a) Use the built-in user manager to add and remove users.  This 
    requires mod_auth_pgsql, configured with read/write access to the 
    IPDB users table.  A default user admin, password admin, is created 
    in step 4 above - make sure to create a new user as an admin, and 
    remove the default user (or at least change its password).

  b) Use the built-in user manager as in a) but create a short script to
    export the user list to a standard .htpasswd file.  This may be
    useful if mod_auth_pgsql isn't easily available.

  c) Maintain an external .htpasswd file of your own, configured and 
    maintained however you like.  In this case the access-pwd-update.pl 
    script should edited to match the .htpasswd filename/path and should 
    be called from cron to make sure new users get added to the 
    database, and old ones get deleted.  This extra maintenance of user 
    lists is necessary to support the access controls, which are stored 
    in the database.

    You will have to either temporarily create a user "admin", so that user
    can grant other users priviledges, or run the following on the database:

      UPDATE users SET acl='bacdsA' WHERE username='newadminuser';

    Replace 'newadminuser' as appropriate.

    If you don't do this, nobody will be able to make any changes;  
    access-pwd-update.pl only grants minimal read access to new users.

7) (optional) Pick a log facility by setting $IPDB::syslog_facility in 
MyIPDB.pm, and tweak your syslog configuration to direct IPDB logging 
to a custom log.  Most logging is at the level of "info" or "warn".  
Full changes are not logged.  Logging verbosity isn't very high, so it 
may be acceptable to leave the log stream at the defaults.

---

Basic installation should now be complete!  Log in as an admin user, 
add your ARIN, RIPE, LACNIC, AfriNIC, or APNIC allocations and start 
documenting your netblock usage.

If you want to export rWHOIS data, see http://www.unixadmin.cc/rwhois/ 
for a place to start on setting up an rWHOIS server.  Note that 
db2rwhois.pl creates and maintains the net-<cidr> trees, all you have 
to do is configure the daemon itself.  Schedule runs of 
cgi-bin/extras/db2rwhois.pl followed by rwhois_indexer (every hour 
should be plenty often).  You'll need to fill in correct organization 
contact info in MyIPDB.pm.

If you're just running from the unpacked tarball directory, you may need 
to create symlinks in cgi-bin/extras/ for IPDB.pm and MyIPDB.pm, 
pointing to ../IPDB.pm and ../MyIPDB.pm respectively.  Otherwise 
db2rwhois.pl won't be able to find these modules.