Changeset 217 for trunk/INSTALL

Timestamp:

01/05/12 16:45:32 (13 years ago)

Author:

Kris Deugau

Message:

/trunk

Really check in the copy-pasted partly-rewritten INSTALL

For sure this time.

File:

• trunk/INSTALL (modified) (1 diff)

trunk/INSTALL

@@ -1 @@
-Requires:
- CGI::Simple
- HTML::Template
- CGI::Session
- Crypt::PasswdMD5
- Net::Whois::Raw
- Text::Wrap (core) - for WHOIS response linewrapping
- Net::DNS
+$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.