SpringSource Enterprise Ready Server 4.0.0 Apache 2.2
Initial build date 6/20/2008       published 7/16/2008


README-ers-4.0.0-apache-2.2.9-<platform>-20080716.txt
=====================================================

Thank you for using SpringSource Enterprise Ready Server.  This README file
contains important information regarding this release.  We recommend
that you read the entire document.


What's in this README file
==========================

- What's changed in ERS 4.0.0
- Who should apply this package
- Platform Specific Prerequisites
- Warnings
- Contents of this add-on release
- Changes, Enhancements and Fixes
- Coming in next release
- Installation Instructions
- Example Installation Walk-through on Linux


What's changed in ERS 4.0.0
===========================

SpringSource Enterprise Ready Server 4.0.0 reflects a departure in the way
the features are downloaded and deployed to production servers.  This
product traditionally was packaged into a single installation package.
With 4.0.0, this single package is sliced into apache, tomcat and java
components.  For example, Apache HTTP Server is packaged for the current
2.2.9 release, as well as the legacy versions 2.0.63 and 1.3.41.    

  ers-4.0.0-apache-2.2.9
  ers-4.0.0-apache-2.0.63
  ers-4.0.0-apache-1.3.41

These packages include openssl 0.9.8h, perl 5.8.8, modperl 2.0.4 for 
apache-2.2.9 and -2.0.63, modperl 1.30 for apache-1.3.41, php 5.2.6 for 
apache-2.2.9, and php 4.4.8 for apache-1.3.41 and -2.0.63.  Sparc 8 supports
32 bit CPU's.  For all other platforms both 32 bit and 64 bit CPU's are 
supported, with both native 32 and 64 bit builds of all server components in 
the apache-2.2.9 package, and a host of support libraries. 

Similarly, the tomcat servers are divided into three packages of Tomcat
and three packages of Java;

  ers-4.0.0-tomcat-6.0.18
  ers-4.0.0-tomcat-5.5.26
  ers-4.0.0-tomcat-4.1.37

  ers-4.0.0-java-6.0.0.06
  ers-4.0.0-java-5.0.0.15
  ers-4.0.0-java2-1.4.2.17

We strongly recommend java 1.4.2 for tomcat 4.1.37 deployments, otherwise
users of tomcat 6.0 or 5.5 may choose java 5 or 6 based on the version
which best supports their applications on a per-server instance basis.
Both java5 and java6 packages offer 32 or 64 bit CPU modes, either within
the same javaN.N/ directory toggled with the java -d32 or -d64 flag,
or with a second javaN.N-64 directory for the native 64 bit CPU support.

The purpose of this division is to simplify deployment of one or more
components across the enterprise, such as deploying only apache server
on outward facing boxes and deploying only tomcat on the back end
application server cluster boxes.  This simplifies redeploying updated
packages for one group of components without affecting another.  This
finally allows packages to complete regression testing and quality
assurance phases independently of other modules.


Who should apply this package 
===============================
This package should be applied if you want to take advantage of the new 
features of Apache HTTP Server 2.2.  See 
  <http://httpd.apache.org/docs/2.2/new_features_2_2.html>

This package supports for PHP 5.2 exclusively with Apache 2.2.  
PHP 5.2 will not be distributed for Apache 1.3 or 2.0, contrawise
PHP 4 will not distributed for Apache 2.2.  For info on new features
in PHP 5.x and for migrating PHP 4.x applications see
  <http://us2.php.net/manual/en/migration5.php>

This package updates Apache 2 support from modperl 1.99 RC4 to modperl 
release 2.0.4, which renamed all modperl symbols from Apache::packages 
to Apache2::packages.  It will be necessary to simply rename these in
previously developed applications.  For additional migration notes 
for classic modperl for Apache 1.3 see
  <http://perl.apache.org/docs/2.0/user/porting/compat.html#Description>

This package is a stand alone component of Enterprise Ready Server 
release 4.0.0.  Apply this package to an existing ERS 3 installation
to add the Apache 2.2 server with PHP 5.2 and modperl 2.0 support.  
Do not apply this add-on to an ERS 2.x installation.

This release is phased as SpringSource seeks to deliver this as quickly
as possible to all customers on all platforms.  This means that the 
platforms in the largest demand will be released first, without delay 
due to platform specific issues that may arise in the Quality Assurance 
process.  If your platform is not in the current list, please rest
assured that SpringSource is working to deliver your platform as quickly
as possible.


Platform Specific Prerequisites
===============================

AIX - TBD


Linux PowerPC:
 - Minimum Kernel version - 2.6.9
   [Equivalent to RHEL 4 or greater]

 - Patch Linux to support IBM.s Java 5 release


Linux X86/64:
 - Minimum Kernel version - 2.4.21


HP/UX 11.11 (32 bit)
 - Default user/group for Apache run time is www/www.  This user must
   exist on the system, or you must change the directives to refer to a
   user/group that does exist. [nobody/nobody does not work on HP/UX]

 - the /dev/(u)random driver depot package must be installed on any
   HP/UX 11.11 platform

 - HP/UX 11.23 includes the /dev/(u)random drivers by default


Solaris
 - Kernel patch 118833-18 is required of all customers on sparcv9
   configurations.


Windows
 - Windows 2000 SP 3 or later, 2003 SP 1 or later, 2008, or 2008 64-bit
   edition supported


Warnings
========

1. This package includes an updated PERL binary and libraries.  The 
single perl5.8 binary is shared between all existing, installed 
apache1.3, apache2.0 and new apache2.2 instances. The new perl5.8/ 
tree will overwrite the existing one.  As this package is built to 
a newer baseline, it is possible but not expected that this perl5.8/ 
tree could conflict with the previously shipped modperl1.3/ and 
modperl2.0/ trees when loading mod_perl.so.  Please use caution in 
applying this patch to any shared deployment, test as described below.  
Or consider using -x "perl5.8*" to avoid unpacking this more modern 
perl tree, if modperl will not be used with Apache 2.2.

PERL users - please test in the following manner:
 - Back up existing perl5.8 tree by renaming it 
 - Be prepared to restore it and install 2.2 patch to alternate location 
   in case of any failures
 - In a failure, provide your support rep with operating system,
   version, platform and cpu details

2. ers-server.pl will not convert Apache 2.0 syntax to Apache 2.2.  You 
   can use the --migrate flag to clone an existing 2.0 instance to 2.2, 
   but you will have to manually convert any deprecated 2.0 
   configuration file directives. See:
   <http://httpd.apache.org/docs/2.2/upgrading.html>

3. The tools/ subtree now requires the user to run the script
     tools/bin/tools-env.sh
   This script sets up library paths, adds tools to your path (over any 
   system-installed flavors), .conf file paths and man pages for the
   utilities included in tools/bin/.  Frequent users of tools/ should 
   consider adding this to their login .profile script.

4. For all platforms this patch is delivered as a self-extracting ZIP 
   archive (e.g. not a tar.gz archive).  Self extracting zip files will 
   expand themselves, or if you would prefer, you may find your platform 
   supports unzip, or you may obtain an unzip utility from 
     http://www.info-zip.org/UnZip.html 
   to expand the patch with additional options.

5. The ERS Tomcat package requires Perl for its initial installation and 
   configuration. If your system does not already have Perl installed you 
   have two choices:
	1 - Install a system Perl. [An option for Windows users is 
            ActiveState Perl found here:
            http://www.activestate.com/Products/activeperl/index.mhtml]

	2 - Install an ERS Apache package, which includes Perl.

6. For all users running Tomcat only and relying on system Perl, make the
following modification to ers-server.pl.  Change the path in the first
(shebang) line to point to your system Perl location.

   Modify:

      #!/bin/sh <ERS_install_dir>/perl5.8/bin/perl

   CHANGE TO:

      #!/bin/sh <system_path_to>/bin/perl


Contents of this add-on release
===============================
This package adds the following new components:

 - Apache HTTP Server 2.2.9
 - PHP 5.2.6, which introduces object oriented development to PHP.
 - modperl 2.0.4 (the entire modperl package in apache2.2/modules/perl/. 
                  apache2.2 does not use the old directory modperl2.0/.)
 - Apache 2.2 server instances test-apache2.2 and test-apache2.2-64
   Caution; use these server examples for testing and validation only.

This package provides updates for the following existing ERS 3.x 
components:

 - perl5.8 (updates existing perl to 5.8.8 compiled with the most 
   most current, appropriate options)
 - ers-server.pl (supports Apache 2.2 server instance creation)
 - fixrootpath.pl (updates the paths of additional files)
 - tools/ directory is updated with new content and designed to be 
   portable, separable from the rest of the package.
 - For apache2.2, openssl is updated to release 0.9.8h, libexpat 
   is updated to 2.0.1, libapr and libaprutil are updated to 1.3.2.


Changes, Enhancements, Fixes
============================
1. Added support to PHP 5.2 for libxml2, libxslt, openssl, openldap,
libiconv, zlib compression and zts threading support for worker MPM.

2. mod_snmp for Apache 2.2 has been built against zlib and OpenSSL to 
enable secure communications to an snmpv3 client.  The corresponding
snmp tools and snmpd for master agent configuration reside in tools/
(the snmp2.0/ directory is deprecated).

3. The tools/ tree is designed to be portable.  A shell script 
"tools/bin/tools-env.sh" is provided to set environment variables 
which must be run prior to using the scripts in the tools tree.  
See "Warnings" section above.  The tools/ tree is now independent of 
the rest of the ERS environment and can be moved and used on a different 
box.  When moving the tools/ tree to a different box, bring along 
fixrootpath.pl as well, and run it once you have dropped tools/ into 
its new destination.  The fixrootpath.pl script will change/enable the 
tools-env.sh script which is required to be run before use.  The tools 
tree can be used for SSL certificate management using the openssl 
command, as well as password file management.

   Procedure for Moving the Tools Tree:
   ====================================
   1. Expand the Apache 2.2 component into a temp directory.
   2. Copy fixrootpath.pl and the tools/ tree to new destination. 
      - fixrootpath.pl goes in the parent directory of tools/ 
        (one dir above tools/).
   3. Run fixrootpath.pl from the parent directory of tools/.  It will 
      update tools/bin/tools-env.sh and set the paths in that file.
   4. Run tools/bin/tools-env.sh script to add the tools/ tree paths to 
      your user environment. 
      Optional - Add tools-env.sh to .profile to make permanent
   5. Use the tools.


Coming in ERS Release 4.0.0
===========================
The following features have been explicitly requested, and SpringSource
will meet the following requests in an upcoming iteration of the 
ERS apache 2.2.9 component, as entirely loadable modules:

1. Added libxml2, libxslt, openssl, openldap, and zlib compression
   support for Perl.

2. Support in ERS 4.0.0 for libgd/png/jpeg, Berkeley databases, 
   Oracle, SQLite and PostgreSQL and MySQL clients, for php and perl.

3. Apache 2.2 authentication support leveraging Berkeley databases, 
   Oracle, SQLite and PostgreSQL and MySQL clients.


Installation Instructions
=========================

1) If this is a new installation, place the package(s) in the desired 
   installation location.  This will become the ERS home.  All packages 
   (Apache, Java, Tomcat) should be placed in the same location.  
   On Windows, do not install into a path that contains space characters.

   If this is an upgrade to a 3.0 or 3.1 ERS installation, copy the 
   appropriate package file to the base directory where the Enterprise 
   Ready Server was originally installed. (Example /opt/ers/, although 
   another path could have been chosen).  This is the directory that 
   contains the 'apache2.0', 'perl5.8', 'tomcat5.0', 'servers' and other 
   server component directories.

2) Change to that base directory at a Unix shell prompt (or on Windows,
   in a cmd Command Prompt window.)

3) Stop all running httpd Apache server instances.  The following steps 
   will fail if you have any servers using modperl from the SpringSource 
   Enterprise Ready Server installed in this directory.

4) Self-Extract the files from this patch release by using the file name 
   as a command.  Install any Apache packages first, then any Java packages, 
   and finally any Tomcat packages (using "java -jar" as noted below):

   For example, LINUX users will use these commands:

      cd /opt/ers
      ./ers-4.0.0-apache-2.2.9-x86-linux-glibc2-20080716.zip.sfx

   Other UNIX variants will be similar. Invoke the file name at the 
   command line to extract the corresponding platforms:

      ./ers-4.0.0-apache-2.2.9-sparc-sun-solaris-10.x-20080716.zip.sfx
      ./ers-4.0.0-apache-2.2.9-x86-solaris-10.x-20080716.zip.sfx

  * When unzipping, answer -YES- to overwrite fixrootpath.pl and 
    ers-server.pl.

   NOTE: TOMCAT Packages are extracted using the Java -jar command.  This 
   is why java packages need to be installed before Tomcat packages.

   Example:

   J5sdk\bin\java  -jar ers-4.0.0-tomcat-6.0.18-windows-2008-07-25.sfx.jar

5) Run the fixrootpath.pl perl script to Correct the root paths.
   from within this SpringSource Enterprise Ready Server root directory.

   perl fixrootpath.pl

   If perl is not otherwise installed, on Windows use the command:

   perl5.8\bin\perl.exe fixrootpath.pl

   This script, with no additional arguments, will transform each
   occurance of @@PRODUCT_ROOT@@ in any script or configuration file
   in the product tree with the working directory from which it is
   launched.  This script must be run with at least perl 5.005, and 
   cannot be run in multibyte character encoding such as UTF8.  Unset 
   the LANG or LC_*** variables to remove any UTF8 or other encodings
   before invoking fixrootpath.pl.


Example Installation walk-through on Linux
==========================================
<<comments are in double angle brackets>>

<<1. create or change to the ERS install root>>
# mkdir /local0/ers4
# cd /local0/ers4

<<OPTIONAL: back up any existing trees by renaming them, e.g.>>
[ers4]# mv apache2.2 apache2.2.original
[ers4]# mv perl5.8 perl5.8.original
[ers4]# mv php5.5 perl5.8.original

<<OPTIONAL: remove the snmp2.0/ tree which is now part of tools/.>>
[ers4]# rm -rf snmp2.0

<<2. copy in the Apache 2.2 add-on>>
[ers4]# cp
/raid/release/ers-4.0.0-apache-2.2.9-x86-linux-glibc2-20080716.zip.sfx .

<<3. change file mode to make it executable>>
[ers4]# chmod u+x ers-4.0.0-apache-2.2.9-x86-linux-glibc2-20080716.zip.sfx

<<4. invoke the file>>
[ers4]# ./ers-4.0.0-apache-2.2.9-x86-linux-glibc2-20080716.zip.sfx
   ...
replace ERS_LICENSE.txt? [y]es, [n]o, [A]ll, [N]one, [r]ename:
<<Answer "All" and the archive finishes by unpacking list of files.>>

<<5. Contents should now look like this>>
[ers4]# ls
apache2.2         ers-4.0.0-apache-2.2.9-x86-linux-glibc2-20080716.zip.sfx  
ers-server.pl     licenses        perl5.8-64  php5.2-64   tools  apache2.2-64  
ERS_LICENSE.txt   fixrootpath.pl  perl5.8     php5.2      servers

<<6. Invoke fixrootpath.pl>>
[ers4]# ./fixrootpath.pl

Replacing @@PRODUCT_ROOT@@ with /local0/ers4
/local0/ers4/ers-server.pl
/local0/ers4/php5.2/lib/php/peclcmd.php
   ...
<<script may take a few minutes as it looks through installation 
checking files.>>

<<7. Test the Apache 2.2 installation with the provided servers/test-apache2.2
or servers/test-apache2.2-64 instances>>

[ers4]# cd servers/test-apache2.2
[test-apache2.2]# bin/apache_startup.sh startssl
Starting Apache
Server started OK

<<Point browser to http://localhost:8080 or https://localhost:8443>>
   1. You will see a certificate warning from https:
   2. Authenticate to home page as covalent/covalent
   3. Test all examples

Once you have completed testing, stop Apache and proceed to create 
a production instance using ers-server.pl.


Manifest of ers-4.0.0-apache-2.2.9-<platform>-20080716.zip.sfx packages
===============================================================

The package archive file included in this package is named:

ers-4.0.0-apache-2.2.9-ppc-linux-glibc2-20080716.zip.sfx        
ers-4.0.0-apache-2.2.9-x86-linux-glibc2-20080716.zip.sfx
ers-4.0.0-apache-2.2.9-sparc-sun-solaris-10.x-20080716.zip.sfx  
ers-4.0.0-apache-2.2.9-x86-solaris-10.x-20080716.zip.sfx
ers-4.0.0-apache-2.2.9-sparc-sun-solaris-8.x-20080716.zip.sfx (only 32 bit version)

These are self-extracting zip images which can only be invoked on their
respective platform (either 32 or 64 bit CPU is fine, all are 32 bit
self extract stubs), or from another platform using the unzip utility.

These patch archive files contain (Linux example):

drwxr-xr-x   13 root     root         4096 Mar  2 19:34 apache2.2/
drwxr-xr-x   13 root     root         4096 Mar  2 19:34 apache2.2-64/
-rw-r--r--    1 root     root        14259 Dec 13 13:25 ERS_LICENSE.txt
-rwxr-xr-x    1 root     root        16504 Mar  2 18:35 ers-server.pl
-rwxr-xr-x    1 root     root         5206 Mar 30 18:47 fixrootpath.pl
drwxr-xr-x    2 root     root         4096 Mar 30 19:19 licenses/
drwxr-xr-x    5 root     root         4096 Mar  2 19:34 perl5.8/
drwxr-xr-x    5 root     root         4096 Mar  2 19:34 perl5.8-64/
drwxr-xr-x    8 root     root         4096 Mar  2 19:34 php5.2/
drwxr-xr-x    8 root     root         4096 Mar  2 19:34 php5.2-64/
drwxr-xr-x    3 root     root         4096 Mar 30 15:02 servers/
drwxr-xr-x    8 root     root         4096 Mar  2 19:34 tools/


Manifest of ers-4.0.0-tomcat-6.0.18-<platform>-2008-07-25.sfx.jar packages
===============================================================

The package archive file included in this package is named:

ers-4.0.0-tomcat-6.0.18-unix-2008-07-25.sfx.jar
ers-4.0.0-tomcat-6.0.18-windows-2008-07-25.sfx.jar