source: branches/stable/INSTALL@ 868

Last change on this file since 868 was 508, checked in by Kris Deugau, 13 years ago

/branches/stable

Prep-for-release cleanup of buglets found making sure the demo
install works

  • Clean up instructions for creating the database. Apparently the PL/pgSQL "language" module required for the last-modified triggers can't be installed by a regular user, and isn't available by default. O_o
  • Fix a missed $IPDB::webpath-in-single-quotes
  • Add a quick hack to allow automagical allocation from private net ranges. See #38.
  • Partially convert some critical bits to use bound parameters in SQL for new allocations. See #34, mostly cleaned up already on /trunk or /branches/htmlform
  • Set $privdata = internally so that an allocation via admin tools doesn't error out
  • Property svn:keywords set to Id
File size: 6.0 KB
RevLine 
[419]1$Id: INSTALL 508 2011-11-16 21:28:37Z kdeugau $
2
[433]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
[419]32Installing the IPDB
33===================
34
[433]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#.
[419]39
[433]40The Makefile supports substitution on most standard
41GNU/FHS-ish paths, so you could also run:
[419]42
[433]43 make install prefix=/opt
[419]44
[433]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
[508]634) As a Postgres superuser, create a database user and the database:
[419]64
[508]65shell> psql template1
66pg# create user ipdb with password "ipdbpwd";
67pg# create database ipdb owner ipdb;
68
69Add the PL/pgSQL language to the database. This is not strictly
70necessary but there are triggers on the poolips and allocations table
71to automatically update a last-modified column.
72
73pg# \c ipdb
74pg# create language plpgsql
75
76Create the inital tables using cgi-bin/ipdb.psql:
77
78shell> psql -U ipdb ipdb <cgi-bin/ipdb.psql
79
[433]805) Configure your webserver to call the IPDB scripts at an appropriate
81web path. A webroot pointing to the HTML files (first level under
[507]82the ipdb-#VERSION#/ tarball directory, or /usr/local/lib/ipdb-#VERSION#)
83should work fine; a server alias under an existing virtual host should
84work as well.
[419]85
[507]86Set $IPDB::webpath (the web path to your IPDB install) in MyIPDB.pm.
87Straight out of the tarball it should work at the webroot, but if you
88want it in a subdirectory, you'll need to set this variable to get all
89of the internal links to behave properly.
[419]90
[433]91The directory containing the HTML and scripts must have at least the
92following Apache directives (or other server equivalent) set:
[419]93
[507]94 Options ExecCGI IncludesNoEXEC
[419]95
[433]966) User lists can be maintained two basic ways:
[419]97
[433]98 a) Use the built-in user manager to add and remove users. This
99 requires mod_auth_pgsql, configured with read/write access to the
100 IPDB users table. A default user admin, password admin, is created
101 in step 4 above - make sure to create a new user as an admin, and
102 remove the default user (or at least change its password).
103
[507]104 b) Use the built-in user manager as in a) but create a short script to
105 export the user list to a standard .htpasswd file. This may be
106 useful if mod_auth_pgsql isn't easily available.
107
108 c) Maintain an external .htpasswd file of your own, configured and
[433]109 maintained however you like. In this case the access-pwd-update.pl
110 script should edited to match the .htpasswd filename/path and should
111 be called from cron to make sure new users get added to the
112 database, and old ones get deleted. This extra maintenance of user
113 lists is necessary to support the access controls, which are stored
114 in the database.
115
[507]116 You will have to either temporarily create a user "admin", so that user
117 can grant other users priviledges, or run the following on the database:
[433]118
[507]119 UPDATE users SET acl='bacdsA' WHERE username='newadminuser';
[433]120
[507]121 Replace 'newadminuser' as appropriate.
[419]122
[507]123 If you don't do this, nobody will be able to make any changes;
124 access-pwd-update.pl only grants minimal read access to new users.
[419]125
[433]1267) (optional) Pick a log facility by setting $IPDB::syslog_facility in
127MyIPDB.pm, and tweak your syslog configuration to direct IPDB logging
128to a custom log. Most logging is at the level of "info" or "warn".
129Full changes are not logged. Logging verbosity isn't very high, so it
130may be acceptable to leave the log stream at the defaults.
[419]131
[433]132---
133
134Basic installation should now be complete! Log in as an admin user,
135add your ARIN, RIPE, LACNIC, AfriNIC, or APNIC allocations and start
[419]136documenting your netblock usage.
137
[433]138If you want to export rWHOIS data, see http://www.unixadmin.cc/rwhois/
139for a place to start on setting up an rWHOIS server. Note that
140db2rwhois.pl creates and maintains the net-<cidr> trees, all you have
141to do is configure the daemon itself. Schedule runs of
142cgi-bin/extras/db2rwhois.pl followed by rwhois_indexer (every hour
143should be plenty often). You'll need to fill in correct organization
144contact info in MyIPDB.pm.
[440]145
146If you're just running from the unpacked tarball directory, you may need
147to create symlinks in cgi-bin/extras/ for IPDB.pm and MyIPDB.pm,
148pointing to ../IPDB.pm and ../MyIPDB.pm respectively. Otherwise
149db2rwhois.pl won't be able to find these modules.
Note: See TracBrowser for help on using the repository browser.