Changeset 433 for trunk/INSTALL


Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/INSTALL

    r419 r433  
    11$Id$
     2
     3Requirements
     4============
     5
     6- Any CGI-capable web server that can execute arbitrary files or
     7  files with administrator-defineable extensions
     8- PostgreSQL >= 7.4.  It should be possible to (fairly) trivially patch
     9  the code for any other DBMS that supports:
     10  - an IP address/CIDR netblock data type
     11  - higher/greater, lower/less than, contains, and is-contained-by
     12    operators
     13- Perl >= 5.6
     14  - Standard modules:
     15    These should be included in any base Perl install
     16    - File::Path
     17    - CGI::Carp
     18    - POSIX
     19    - Sys::Syslog
     20  - Extra modules:
     21    - NetAddr::IP >= 4.x.  3.x may work, however 4.x has been out for
     22      more than 4 years.
     23    - DBI
     24    - DBD::Pg
     25    - Sys::SigAction.  This isn't strictly required;  it's used in an
     26      example hook for validating customer IDs against an external
     27      database.  It could arguably be replaced with sigaction() from the
     28      POSIX module when using Perl >= 5.8.2.  See eg Sys::SigAction on
     29      CPAN (http://search.cpan.org/~lbaxter/Sys-SigAction-0.11/lib/Sys/SigAction.pm)
     30      for some thoughts on the gritty details.
    231
    332Installing the IPDB
    433===================
    534
    6 1) Untar in a convenient location.  Note that all URLs referenced internally currently assume they will be
    7 presented at http://host/ip/.
     351) Untar in a convenient location.  You should be able to simply use the
     36unpacked tarball as-is, or you can run "make install" to install files
     37in /usr/local/lib/ipdb-#VERSION#, with configuration modules in
     38/usr/local/etc/ipdb-#VERSION#.
    839
    9 2) Edit cgi-bin/MyIPDB.pm:  you need to set the database DSN and company info.  You
    10 should probably also set the syslog facility and default custid.
     40The Makefile supports substitution on most standard
     41GNU/FHS-ish paths, so you could also run:
    1142
    12 3) Edit cgi-bin/CustIDCK.pm as needed to validate customer IDs.
     43  make install prefix=/opt
     44
     45to install it under /opt.
     46
     47The Makefile also supports DESTDIR for packaging, so you can use:
     48
     49  make install libdir=/usr/lib sysconfdir=/etc DESTDIR=/tmp/ipdbpkgroot
     50
     51to install for packaging under /tmp/ipdbpkgroot with the core scripts
     52and HTML packaged under /usr/lib/ipdb-#VERSION#, and the configuration
     53modules packaged under /etc/ipdb-#VERSION#.
     54
     552) Configuration:  These module files will either be in the cgi-bin/
     56directory from the unpacked tarball, or /usr/local/etc/ipdb-#VERSION#
     57if installed with 'make install'.
     58  a) Edit MyIPDB.pm:  you need to set the database DSN and
     59    company info.  You should probably also set the syslog facility and
     60    default custid.
     61  b) Edit CustIDCK.pm as needed to validate customer IDs.
    1362
    14634) Create the database, and the inital tables using cgi-bin/ipdb.psql.
    1564
    16 5) User lists can be maintained two basic ways:
     655) Configure your webserver to call the IPDB scripts at an appropriate
     66web path.  A webroot pointing to the HTML files (first level under
     67the ipdb-#VERSION#/ tarball directory, or /usr/local/lib/ipdb-#VERSION#)
     68with a symlink or alias for ip/ -> . should work fine;  a server alias
     69under an existing virtual host should work as well.
    1770
    18   a) Use the built-in user manager to add and remove users.  This requires mod_auth_pgsql, configured
    19 with read/write access to the IPDB users table.  A default user admin, password admin, is created in step 4 above
    20 - make sure to create a new user as an admin, and remove the default user.
     71Note that all URLs referenced internally currently assume they will be
     72presented at http://host/ip/;  you cannot put the IPDB at
     73http://host/noc/misc/ipdb/.
    2174
    22   b) Maintain an external .htpasswd file of your own, configured however you like.  In this case the
    23 access-pwd-update.pl script should edited to match the .htpasswd filename/path and should be called from cron to
    24 make sure new users get added to the database, and old ones get deleted.  This extra maintenance of user lists is
    25 necessary to support the access controls, which are stored in the database.
     75The directory containing the HTML and scripts must have at least the
     76following Apache directives (or other server equivalent) set:
    2677
    27 You will have to either temporarily create a user "admin", so that user can grant other users priviledges, or run
    28 the following on the database:
     78  Options ExecCGI IncludesNoEXEC FollowSymlinks
    2979
    30 UPDATE users SET acl='bacdsA' WHERE username='newadminuser';
     806) User lists can be maintained two basic ways:
     81
     82  a) Use the built-in user manager to add and remove users.  This
     83    requires mod_auth_pgsql, configured with read/write access to the
     84    IPDB users table.  A default user admin, password admin, is created
     85    in step 4 above - make sure to create a new user as an admin, and
     86    remove the default user (or at least change its password).
     87
     88  b) Maintain an external .htpasswd file of your own, configured and
     89    maintained however you like.  In this case the access-pwd-update.pl
     90    script should edited to match the .htpasswd filename/path and should
     91    be called from cron to make sure new users get added to the
     92    database, and old ones get deleted.  This extra maintenance of user
     93    lists is necessary to support the access controls, which are stored
     94    in the database.
     95
     96You will have to either temporarily create a user "admin", so that user
     97can grant other users priviledges, or run the following on the database:
     98
     99  UPDATE users SET acl='bacdsA' WHERE username='newadminuser';
    31100
    32101Replace 'newadminuser' as appropriate.
    33102
    34 If you don't do this, nobody will be able to make any changes;  access-pwd-update.pl only grants read access.
     103If you don't do this, nobody will be able to make any changes; 
     104access-pwd-update.pl only grants minimal read access to new users.
    35105
     1067) (optional) Pick a log facility by setting $IPDB::syslog_facility in
     107MyIPDB.pm, and tweak your syslog configuration to direct IPDB logging
     108to a custom log.  Most logging is at the level of "info" or "warn". 
     109Full changes are not logged.  Logging verbosity isn't very high, so it
     110may be acceptable to leave the log stream at the defaults.
    36111
    37 Basic installation should now be complete!  Add your ARIN, RIPE, LACNIC, AfriNIC, or APNIC allocations and start
     112---
     113
     114Basic installation should now be complete!  Log in as an admin user,
     115add your ARIN, RIPE, LACNIC, AfriNIC, or APNIC allocations and start
    38116documenting your netblock usage.
    39117
    40 If you want to export rWHOIS data, see http://www.unixadmin.cc/rwhois/ for a place to start on setting up an
    41 rWHOIS server.  Note that db2rwhois.pl creates and maintains the net-<cidr> trees, all you have to do is
    42 configure the daemon itself.  Schedule runs of cgi-bin/extras/db2rwhois.pl followed by rwhois_indexer.  You'll
    43 need to fill in correct organization contact info in MyIPDB.pm.
     118If you want to export rWHOIS data, see http://www.unixadmin.cc/rwhois/
     119for a place to start on setting up an rWHOIS server.  Note that
     120db2rwhois.pl creates and maintains the net-<cidr> trees, all you have
     121to do is configure the daemon itself.  Schedule runs of
     122cgi-bin/extras/db2rwhois.pl followed by rwhois_indexer (every hour
     123should be plenty often).  You'll need to fill in correct organization
     124contact info in MyIPDB.pm.
Note: See TracChangeset for help on using the changeset viewer.