source: trunk/INSTALL@ 217

$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
    - CGI::Carp
    - POSIX
    - Text::Wrap - for WHOIS response linewrapping
  - Extra modules:
    - CGI::Simple
    - HTML::Template
    - CGI::Session
    - Crypt::PasswdMD5 (primary password encryption)
    - Digest::MD5 (for imported VegaDNS passwords)
    - Net::Whois::Raw
    - Net::DNS
    - DBI
    - DBD::Pg
    - NetAddr::IP >= 4.x.  3.x may work, however 4.x has been out for
      more than 4 years.

Installing DeepNet DNS Administrator
====================================

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/dnsadmin-#VERSION#, with configuration modules in
/usr/local/etc/dnsadmin-#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 datadir=/usr/share sysconfdir=/etc DESTDIR=/tmp/dnsdbpkgroot

to install for packaging under /tmp/dnsdbpkgroot with the core scripts
and HTML packaged under /usr/share/dnsdb-#VERSION#, and the configuration
modules packaged under /etc/dnsdb.

2) Configuration:  These module files will either be in the cgi-bin/
directory from the unpacked tarball, or /usr/local/etc/dnsdb
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.