Installation Notes for ISC OpenReg
----------------------------------

This file documents the steps needed to install the software
packages that the ISC OpenReg system requires be present on
the target system.  The ISC OpenReg system has been tested
on NetBSD, Slackware Linux and BSD/OS.  It is expected to run
on most modern unix based releases, subject to the availability
of the available software packages described below.

Shell Syntax Note:
------------------
This file assumes that the user is using the Bourne Shell,
or compatible shell (sh, bash, ksh or zsh).  If you are using a
C-Shell (csh, tcsh) shell, you will need to change the
syntax for exporting environmental variable from:

	export variable=value

to:
	setenv variable value


The list of required packages is:
---------------------------------
	Openssl 0.9.6i
		This package is often required to replace a system
		supplied version of openssl.  All versions of openssl
		prior to this *should* *not* be used, due to
		known security holes in all previous releases.

	Stunnel 4.03, 4.04
		Stunnel 4.04 is a feature release, not a bug fix release.
		None of the new features are required by OpenReg.

	ISC Bind9 (tested with 9.2.1, 9.2.2)
		This component is required for some of the portability
		and utility libraries installed.  Additionally, the
		nameserver dynamic update code requires the use of BIND9.

	James Clark's expat XML parser/library (tested with 1.95.5)
		This component is used as the basis of the high-speed
		XML parsing that the frontend process must perform.

	PostgreSQL v7.2.x (tested with x=2,3,4) or 7.3.x
		NOTE: multibyte character support *must* be compiled
		into the PostgreSQL 7.2.x distribution.  The multibyte
		support in PostgreSQL 7.2.x is not compiled into
		the system by default.  The installer must specify
		this explicitly on the command line during the
		configuration of the system.

		No changes should be necessary for PostgreSQL v7.3.x,
		as the multibyte support is the default for v7.3.x.

	Perl 5.6.1 (Perl 5.8.0 may also work)
		If your operating system has a version of perl5
		installed prior to 5.6.1, you will need to install
		a newer version.  The ISC OpenReg code uses several
		features of perl5 that have been introduced in the
		5.6.x releases.

		It is expected that the ISC OpenReg system will
		work with perl 5.8.0, but this has not been verified.

	Various Perl modules (detailed below)

General Installation comments:
------------------------------
	The approach taken towards the installation of the various
	additional software components needed by the ISC OpenReg system
	is to install them into /usr/local/<packagename> and then
	symlink any needed components into /usr/local/lib and
	/usr/local/bin as needed.

	Comments generally proceed the installation instructions for
	each package, along with location information about where
	the package may be retrieved from.


openssl 0.9.6i:
---------------
	# http://www.openssl.org -- general information
	# source code:
	# http://www.openssl.org/source/openssl-0.9.6i.tar.gz

	./config --prefix=/usr/local/openssl --openssldir=/usr/local/openssl
	make
	make test
	make install

stunnel 4.0.3:
--------------
	# http://www.stunnel.org -- general information
	# source code:
	# http://www.stunnel.org/download/stunnel/src/stunnel-4.03.tar.gz

	./configure --with-ssl=/usr/local/openssl --prefix=/usr/local/stunnel
	make
	make install
	mkdir -p /usr/local/sbin
	cd /usr/local/sbin
	ln -s ../stunnel/sbin/stunnel

ISC Bind9:
----------
	# this is installed into the /usr/local/bind9 hierarchy
	# and a symlink is installed into /usr/local/bin so that
	# the ISC OpenReg configure script can find the ISC libraries

	# http://www.isc.org/products/BIND/ -- general information
	# source code:
	# ftp://ftp.isc.org/isc/bind9/9.2.2/bind-9.2.2.tar.gz

	./configure --prefix=/usr/local/bind9
	make
	make install
	cd /usr/local/bin
	ln -s ../bind9/bin/isc-config.sh

PostgreSQL v7.2.4:
------------------
	# this is installed into the /usr/local/pgsql hierarchy

	# http://www.postgresql.org -- general information
	# source code
	# http://www.postgresql.org/ftpsite/

	./configure --prefix=/usr/local/pgsql --enable-multibyte
	make
	make install

	# the postgresql libraries must be added to the system's
	# dynamic linker cache files.
	# this works on most Linux computers (and BSD/OS 4.x)
	echo '/usr/local/pgsql/lib' >> /etc/ld.so.conf
	/sbin/ldconfig

	# Create PostgreSQL passwd and group entries
	# PostgreSQL should run as a pseudo user that doesn't have
	# general write permissions to anyplace on the system except
	# for the data storage areas.

	# As an example, on a Slackware system, the following group
	# entry was created:
	#    postgres::28:
	# And the following passwd entry:
	#    postgres:x:28:28:PostgreSQL:/var/lib/postgres:/bin/bash
	/usr/sbin/vigr
	/usr/sbin/vipw

	# create the home directory for the user, and chown it appropriately:
	mkdir -p ~postgres 
	chown postgres:postgres ~postgres

	# Initialize the PostgreSQL database directory location
	# On our slackware computer, we segregated the databases
	# into /var/db/pgsql

	mkdir -p /var/db/pgsql
	chown postgres:postgres /var/db/pgsql

	# the next four commands need to be run as user "postgres"
	su - postgres
	/usr/local/pgsql/bin/initdb -D /var/db/pgsql

	# start the database daemon
	/usr/local/pgsql/bin/pg_ctl -D /var/db/pgsql -l logfile start

	# create another database administrator known as 'pgsql'
	# this is the database username that the OpenReg creation
	# scripts will use by default 
	/usr/local/pgsql/bin/createuser --createdb --adduser pgsql

	# create a user for use by the OpenReg system -- the running
	# OpenReg daemons will use this user for accessing the database.
	# this user does not need database creation privledges
	/usr/local/pgsql/bin/createuser --adduser --no-createdb srs

	# exit from the postgres user's shell
	exit

	# add the daemon to the list of things to be run at startup:
	# on our Slackware machine, this is done by appending a
	# command into the /etc/rc.d./rc.local script, that will get
	# run at system startup.
	echo 'su - postgres /usr/local/pgsql/bin/pg_ctl -D /var/db/pgsql -l /var/lib/postgres/logfile start' >> /etc/rc.d/rc.local

	# On a BSD/OS host, the system will send a signal to all processes
	# started while the machine is single user, as it turns multiuser.
	# The following code was added to the rc.local script to make it
	# work properly on BSD/OS 4.3:

	PGDATA=/var/db/pgsql; export PGDATA
	su -m postgres - << EOF
	cd $PGDATA || exit
	PATH=$PATH:/usr/contrib/bin
	rm -f logfile
	daemon /usr/local/pgsql/bin/postmaster -D ${PGDATA} > logfile 2>&1 
	EOF
 
James Clark's expat XML parser/library:
---------------------------------------
	# http://sourceforge.net/projects/expat/ -- general information

	./configure --prefix=/usr/local/expat
	make
	make install
	cd /usr/local/include
	ln -s ../expat/include/expat.h
	cd ../lib
	ln -s ../expat/lib/libexpat.a

Perl 5.6.1:
-----------
	# Note that installing Perl 5.6.1 is not required on most
	# modern operating systems.

	# TBD

Perl packages installed:
------------------------
	# as part of the installation of various perl modules, you will
	# need to configure the CPAN perl module, to inform it where to
	# build modules, store files lists and so forth.  A complete
	# tutorial of how to do this is beyond the scope of this document.
	# The first time the CPAN module is invoked, it will ask the
	# needed configuration questions.

	# The following environmental variable is used to force the perl
	# Net::FTP module to use passive mode transfers when doing FTP.
	# This is needed for some packet filtering implementations.

	export FTP_PASSIVE=1

	perl -MCPAN -e 'install Test::Harness'
	perl -MCPAN -e 'install Test::Simple'
	perl -MCPAN -e 'install Test::More'
	perl -MCPAN -e 'install Bundle::CPAN'

	perl -MCPAN -e 'install Event'
	perl -MCPAN -e 'install Time::HiRes'
	perl -MCPAN -e 'install MIME::Base64'

	# database abstraction modules
	perl -MCPAN -e 'install Bundle::DBI'

	# XML processing modules
	perl -MCPAN -e 'install XML::NamespaceSupport'
	perl -MCPAN -e 'install XML::Parser'
	perl -MCPAN -e 'install XML::SAX'
	perl -MCPAN -e 'install XML::SAX::Expat'
        perl -MCPAN -e 'install XML::Writer'
        perl -MCPAN -e 'install XML::Writer::String'

PostgreSQL Perl Module:
-----------------------
	# two environmental variables need to be set, so that perl
	# can find the PostgreSQL installation files it will need when
	# building the database support libraries

	export POSTGRES_INCLUDE=/usr/local/pgsql/include
	export POSTGRES_LIB=/usr/local/pgsql/lib
	perl -MCPAN -e 'install DBD::Pg'

	# additionally, two patches need to be applied to the the
	# DBD::Pg module, to work around issues with PostgreSQL's
	# handling of pending transactions interfering with
	# the 'vacuum' command

	# patches have been prepared for both version 1.13 of the
	# DBD::Pg module, as well as the 1.21 version of the module

	# it is probably easiest to install these patches after the
	# CPAN module has installed the unmodified DBD::Pg module.
	# Assuming that you configured CPAN to install into the
	# /var/cpan directory, the following commands will apply the
	# patches and re-install the patched DBD::Pg module

	cd /var/cpan/build/DBD-Pg-1.21
	patch < /path/to/openreg/distribution/patches/DBD-Pg/1.21/patch-aa
	patch < /path/to/openreg/distribution/patches/DBD-Pg/1.21/patch-ab
	export POSTGRES_INCLUDE=/usr/local/pgsql/include
	export POSTGRES_LIB=/usr/local/pgsql/lib
	perl Makefile.PL
	make clean
	perl Makefile.PL
	make
	make test
	make install

