INSTALL at [7c39ff9950]

File INSTALL artifact 9ce09cb60c part of check-in 7c39ff9950


                 Installing PacketBL

Table of Contents:
	I.   Notes
	II.  Prerequisites
	III. Installation
	IV.  Configuration
	V.   Command Line Arguments


I. NOTES
	*NOTE* This document may very will be inaccurate, if at all possible
	you should refer to
		http://www.rjmsoftware.org
	for authoritative information.  Also feel free to use the bugzilla to
		report bugs/ask for features.  I have turned off the mailing
		list due to spam.

II. PREREQUISITES
	1. libconfig (required)

	2. iptables (required)
		Iptables' library "ipq" (IP Queuing library) is required, it
		provides the necessary hooks to allow PacketBL to accept
		packets from the QUEUE target and process them.

	3. FireDNS (optional)
		FireDNS is a library that queries all configured nameservers in
		parallel and once it gets an answer from one of them reports
		this.  It can make name resolution MUCH faster, especially when
		a configured nameserver is unreachable or down.

III. INSTALLATION
	1. PacketBL uses a GNU autoconf style `configure' script for
	   configuration.  To invoke this script run the `configure' script
	   within the top-level source directory, for example:
		./configure
	   There are a few options that can be passed to the `configure' script
	   that will affect the way PacketBL is built (in addition to the
	   standard autoconf `configure' script options):
		a. --with-cache
			This option will enable the experimental caching
			mechanism.  This may introduce unexpected problems.
			If you encounter any problems you should post a bug
			report to the PacketBL bugzilla (for details, see
			bugzilla.rjmsoftware.org)
		b. --with-firedns
			This option will cause PacketBL to use FireDNS's name
			resolution routines when testing IPs against DNS RBLs.
			Read above for more information on FireDNS.
		c. --with-stats
			This option will enable the experimental statistic
			gathering code, which will require an extra thread to
			handle incoming connections to a UNIX domain socket.
		d. --with-stats-socket=/path/to/socket
			This option allows one to specify the path to the UNIX
			domain socket that is used for communications between
			the PacketBL daemon and the "packetbl_getstat" process.
			Default is /tmp/.packetbl.sock.

IV. CONFIGURATION
	To be replaced.  A sample config file is provided.

V. COMMAND LINE ARGUMENTS
	1. PacketBL supports a minimal number of command line arguments, since
	   most configuration should be done in the configuration file (see
	   previous section).  The following is a complete list of supported
	   command line arguments:
		a. "-q"
			The "-q" option causes PacketBL to be quiet, it is
			identical to setting "Quiet" to "yes" in the
			configuration file.
		b. "-V"
			The "-V" option causes PacketBL to print out its
			version number and other relevant information to
			standard output and exit successfully.
	   Command line arguments always override their configuration file
	   counter-parts where appropriate.  Unknown command line arguments
	   cause PacketBL to terminate in error immediately at startup.