=== Overview for the impatient: === Unpack the archive, install prerequisite code (the PHP interface to MaxMind's GeoIP system, some PEAR modules, and the perl module Regexp::Optimize), create the appropriate databases, tables, and users in MySQL, adjust the database connection (DSN) parameters and other local installation config parameters, make only the html directory visible to the web (preferably behind some access control) and the system should be ready to use. Load data into the system, analyze referring hosts and source IP addresses, add systems to white- or blacklists, then use the blacklists to protect your system from abusive traffic. === Some words for the impatient or skittish: === Note that this document may look daunting at first. It may in fact be daunting. Take a deep breath and read it before doing anything so you aren't surprised by anything. I know the pain of getting 3/4 of the way through an involved application installation just to find out that I need to do something deal-killingly disastrous or impossible like run *BSD, configure imake/xmkmf, or recompile the kernel. Not that *BSD or kernel recompilation is unspeakably bad, but knowing those were requirements ahead of time would saved me a lot of time, effort, and frustration. I don't know the history behind it, but every time I've had to use imake I've been left weeping uncontrollably on the floor after a few hours of fruitless remisconfiguration (this was back in my Solaris 2.6 days; Sun helpfully provided much of the initial misconfiguration.) So please, read all this before you start. === Expected sysadmin competencies and privileges: === [General] Some of these tasks probably need to be performed as root or at least via sudo. The application itself needs no root privilege, but during development I installed a lot of modules on a site-wide basis. Ideally that should not be necessary, but I haven't tested this allegedly ideal case. [MySQL] You should know how to administer MySQL, including create databases, tables, & users, restrict access, and test connections and queries. [Perl] You should be able to install perl modules, either site-wide or locally. If you're not familiar with CPAN, learn now by visiting http://www.cpan.org/ [PHP] You should be able to configure PHP via php.ini or equivalent. [PHP] You should be able to install PHP modules site-wide or locally, using pear or manually. See http://pear.php.net/manual/en/installation.getting.php for instructions on installing PEAR. If you want to install modules in a local PEAR repository, see http://pear.php.net/manual/en/installation.shared.php === Software prerequisites: === [General] Make sure you have Apache, PHP, perl and MySQL installed. [General] Make sure you have a source of Apache logs in combined format, either as flat files or as database tables as used by mod_log_sql. [PHP-PEAR] Make sure you have the PEAR DB module installed (http://pear.php.net/package/DB). You can use 'pear list | egrep DB' to see if it's installed and use 'pear install DB' to install it. [PHP] Install the GeoIP module available from MaxMind (see http://www.maxmind.com/app/php for references, http://www.maxmind.com/download/geoip/api/php/ for downloads, and http://www.maxmind.com/download/geoip/database/ for the current version of MaxMind's free country database.) [PHP] DEPRECATED - Smarty is now included with the blacklist.tar.gz distribution. If you want to use a different version, change the $LIB_smarty variable in bl/lib/config.inc.php. Previous text contained in {braces}: {Make sure you have Smarty installed (http://smarty.php.net). N.B.: I installed my version under /usr/share/php/Smarty; if you put it somewhere else, you will need to adjust include_path in php.ini or edit bl/lib/config.inc.php to point at the Smarty installation directory.} [PHP] DEPRECATED - phpwhois is now included by default. {Install the phpwhois class available at Sourceforge (http://sourceforge.net/projects/phpwhois) N.B.: I installed my version under /usr/share/php/Smarty; if you put it somewhere else, you will need to adjust include_path in php.ini or edit bl/lib/config.inc.php to point at the phpwhois installation directory.} [Perl] Make sure you have Regexp::Optimize installed (use 'perl -MCPAN -e install Regexp::Optimize' or see http://search.cpan.org/search?query=Regexp%3A%3AOptimize&mode=module) === Optional items: === [PHP-PEAR] (N.B.: Promote to 'required' when it's added to production) Make sure you have the PEAR Net_IPv4 module installed (http://pear.php.net/package/Net_IPv4). [PHP-PEAR] (N.B.: Promote to 'required' when it's added to production) Make sure you have the PEAR Net_URL module installed (http://pear.php.net/package/Net_URL). [Perl] If you intend to manually load Apache logs into the database with bl/contrib/mod_log_sql/mysql_import_combined_log.pl, verify the modules Date::Parse, DBI, and DBD::mysql are installed (i.e. with 'perldoc Module::Name', via CPAN with 'CPAN> m /Module::Name/', or RPM with 'rpm -qa', or the most definite way with 'perl -MModule::Name -e 'print $Module::Name::VERSION, "\n";') [Javascript] The policy manager ships with v4.1.4 of Erik Bosrup's Overlib library, available at http://www.bosrup.com/web/overlib/ . Feel free to update that if you feel it's necessary (it goes in bl/html/js; otherwise change bl/templates/header.tpl to reflect its new location.) [Perl] Regexp::Common is pretty useful. [Apache] mod_log_sql is great for Apache 1.3.x (I'm having trouble with is under Apache 2.0.x under SuSE 9.1 - suggestions appreciated.) Get it at http://www.outoforder.cc/projects/apache/mod_log_sql/ [Apache] mod_access_rbl is great for Apache 1.3.x. Get it from http://www.blars.org/mod_access_rbl.html. Blars has blocked my workplace, my home network, and pretty much most of the internet, so don't be surprised if that link comes up 403; I got a copy by searching with http://www.google.com/search?q=mod_access_rbl - Installation instructions at http://chris.quietlife.net/?p=439 were instrumental in getting it working. I love it. Apparently, a nice person in Yokohama, Japan (aka Tsukamoto Hiroshi, http://www.h1r.org/) has hacked mod_access.c for Apache 2.x, providing a diff at http://ore.dyndns.org/web/mod_access_rbl.diff and installation instructions at http://ore.dyndns.org/web/mod_access_rbl.html (wonky translation from japanese to english available from Google via http://translate.google.com/translate?hl=en&sl=ja&u=http://ore.dyndns.org/web/mod_access_rbl.html). Salient points are: > Method of using. After applying this patch > [http://ore.dyndns.org/web/mod_access_rbl.diff] to the > httpd-2.0.xx/modules/aaa/mod_access.c, the configure && make && sudo > make install it does or, > > % Apxs -c mod_access.c > # apxs -i -n mod_access.libs/mod_access.so > > When with it does, the mod_access of the dnsbl search function being > attached is is installed. The original mod_access.so which does not > have RBL function is superscribed. With this in httpd.conf > and .htaccess > > # third party illegitimate available proxy server the access from > # removal > deny via http.dnsbl.sorbs.net > # China and Korea removal > deny via cn-kr.blackholes.us I am certain Google's translation does not do Tsukamoto-san justice here but that's what you get. See also http://www.gotroot.com/tiki-view_blog_post.php?blogId=2&postId=34 . Hiro's patch and the one posted at gotroot.com are identical as of 2005-03-04, though gotroot.com's docs are more legible for those of us in ISO-8859-1-land. If you can get this working, let me know - let's try to send Hiro a decent set of tranlated instructions. === Installation instructions: === Unpack this archive outside your webserver document root. Ensure the bl/templates_c and bl/cache directories are writable by the webserver. (e.g.: chmod -R a+w bl/templates_c bl/cache) Ensure all files directories are readable by the webserver. (e.g.: chmod -R a+rx bl) Create a database named 'apachelogs' and a table named 'access_log' (see docs for mod_log_sql, see bl/contrib for schema.) If you are already using mod_log_sql, you can skip this part. If you are not using mod_log_sql, import Apache combined logs into the database with bl/contrib/mod_log_sql/mysql_import_combined_log.pl If you have other logs in combined format, you can import those as well. Create a database named 'accesspolicy' and tables named 'incidents' and 'policy'. mysqladmin -u root -p create accesspolicy mysql -u root -p accesspolicy < bl/schema/bl_schema.mysql Create a database user with the following privileges: SELECT, INSERT, UPDATE, and DELETE privilege on 'accesspolicy', SELECT privilege on 'apachelogs', and SELECT privilege on any Movable Type databases (if any). SELECT privilege on any Wordpress databases (if any). Test this account. Adjust the 'shebang' path of bl/lib/list2regexp.pl to point at your local perl installation. Confirm the script compiles with perl -wc list2regexp.pl Use 'perldoc list2regexp.pl' or 'list2regexp.pl --help' for docs. Copy bl/lib/dbauth.sample.php to bl/lib/dbauth.php and change it to use the database user account you just created. Copy bl/html/config.sample.php to bl/html/config.php and change BASEDIR, BASEURL, and other variables as necessary to point at the proper URLs and file locations for this installation. Adjust bl/html/.htaccess to allow legitimate users. Copy or symlink bl/html to a web-accessible directory. === Tips and optional stuff: === == Documentation == You can regenerate the API and codebase documentation with phpDocumentor (http://pear.php.net/package/phpDocumentor/) Edit bl/phpdoc.ini to set the correct directory for generated documentation and run: phpdoc -c /full/path/to/bl/phpdoc.ini == Additional data sources == If you are not using Movable Type, you can set $pagemeta{'has_movabletype'} = 0; in bl/lib/config.inc.php Similarly, if you are not using Wordpress, you can set $pagemeta{'has_wordpress'} = 0; This only stops the display of links to load_mt_log.php and load_wp_comments.php in bl/template/header.tpl; if you really want that capability disabled, delete or chmod load_mt_log.php or load_wp_comments.php to be unreadable by the webserver. If you know that you have Movable Type but no databases are showing up in the 'load Movable Type logs' screen, first check that the database user for the blacklist system has proper SELECT privileges on the MT databases. If that works, it could be that the blacklister is making poor assumptions about what the MT database is called. In load_mt_log.php you'll find: ---- function get_live_mtdb_list ($dbh) { $mtdb = array(); // Q1: get list of live log tables $rmtdb = array(); $mtquery = array(); $mtquery[] = "SHOW DATABASES LIKE '%movable%'"; $mtquery[] = "SHOW DATABASES LIKE '%mt%'"; ... ---- If your database isn't named something like *mt* or *movable*, you can add another $mtquery[] line to specify your database name or pattern. Example: Say your MT database is called 'myfirstblog' - add the line: $mtquery[] = "SHOW DATABASES LIKE 'myfirstblog'"; to search for it. Consult the MySQL database docs for the proper syntax of "SHOW DATABASES" or for more info. Similarly for Wordpress, the code assumes a Wordpress database is named *wordpress* or *wp* - if it isn't, you can change the database search pattern in load_wp_comment.php: ---- function get_live_wpdb_list ($dbh) { $wpdb = array(); // Q1: get list of live log tables $rwpdb = array(); $wpquery = array(); $wpquery[] = "SHOW DATABASES LIKE '%wordpress%'"; $wpquery[] = "SHOW DATABASES LIKE '%wp%'"; ... ---- In either case, the code also looks for the table mt_log in MT databases, or for tables named *_comment in Wordpress databases; if those tables aren't found, the database won't be listed in the load screen. This is all fairly brittle, but only live testing will suggest better solutions. At least it's documented... === System Operation: === See USING. -- Bob Apthorpe $Id: INSTALL,v 1.8 2005/03/11 05:59:51 apthorpe Exp apthorpe $ vi:ts=4:tw=72: