Changeset 433 for trunk/INSTALL

Timestamp:

07/16/10 17:48:19 (14 years ago)

Author:

Kris Deugau

Message:

/trunk

Distribution-preparation rollup:

• Clean up links in footer.inc
• Extend/complete INSTALL
• .spec file tweaks
• Add GPL3 as COPYING
• Remove obsoleted files from Makefile MANIFEST
• Shuffle install process to allow side-by-side multiversion installation (sort of related to #14)

File:

• trunk/INSTALL (modified) (1 diff)

trunk/INSTALL

@@ -1 +1 @@
 $Id$
+
+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.  Note that all URLs referenced internally currently assume they will be 
-presented at http://host/ip/.
+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#.
 
-2) Edit cgi-bin/MyIPDB.pm:  you need to set the database DSN and company info.  You 
-should probably also set the syslog facility and default custid.
+The Makefile supports substitution on most standard 
+GNU/FHS-ish paths, so you could also run:
 
-3) Edit cgi-bin/CustIDCK.pm as needed to validate customer IDs.
+  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) Create the database, and the inital tables using cgi-bin/ipdb.psql.
 
-5) User lists can be maintained two basic ways:
+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#) 
+with a symlink or alias for ip/ -> . should work fine;  a server alias 
+under an existing virtual host should work as well.
 
-  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.
+Note that all URLs referenced internally currently assume they will be 
+presented at http://host/ip/;  you cannot put the IPDB at 
+http://host/noc/misc/ipdb/.
 
-  b) Maintain an external .htpasswd file of your own, configured 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.
+The directory containing the HTML and scripts must have at least the 
+following Apache directives (or other server equivalent) set:
 
-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:
+  Options ExecCGI IncludesNoEXEC FollowSymlinks
 
-UPDATE users SET acl='bacdsA' WHERE username='newadminuser';
+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) 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 read access.
+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!  Add your ARIN, RIPE, LACNIC, AfriNIC, or APNIC allocations and start 
+---
+
+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.  You'll 
-need to fill in correct organization contact info in MyIPDB.pm.
+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.