source: trunk/INSTALL@ 433

Last change on this file since 433 was 433, checked in by Kris Deugau, 14 years ago

/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)
  • Property svn:keywords set to Id
File size: 5.1 KB
Line 
1$Id: INSTALL 433 2010-07-16 21:48:19Z kdeugau $
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.
31
32Installing the IPDB
33===================
34
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#.
39
40The Makefile supports substitution on most standard
41GNU/FHS-ish paths, so you could also run:
42
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.
62
634) Create the database, and the inital tables using cgi-bin/ipdb.psql.
64
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.
70
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/.
74
75The directory containing the HTML and scripts must have at least the
76following Apache directives (or other server equivalent) set:
77
78 Options ExecCGI IncludesNoEXEC FollowSymlinks
79
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';
100
101Replace 'newadminuser' as appropriate.
102
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.
105
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.
111
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
116documenting your netblock usage.
117
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 TracBrowser for help on using the repository browser.