Getting Started With Enterprise Ready Server (ERS)

thumbsshameΔιακομιστές

17 Νοε 2013 (πριν από 3 χρόνια και 9 μήνες)

138 εμφανίσεις

Getting Started With Enterprise Ready
Server (ERS)
4.0
Copyright ©2010 VMware Inc.All rights reserved.
Table of Contents
1.Copyright Notice...............................................................................................................1
2.Overview of SpringSource ERS.......................................................................................3
2.1.ERS 4.0.2...............................................................................................................3
2.2.Changes to ERS Packaging and Deployment........................................................3
2.3.Complete Packages for ERS 4.0.2 - Version Contents..........................................3
2.4.What's New in ERS 4.0.x?.....................................................................................5
2.5.Alternative Packages for ERS 4.0..........................................................................7
3.Installing and Using ERS httpd........................................................................................9
3.1.Who Should Install ERS 4.0.x?.............................................................................9
3.2.Supported Platforms...............................................................................................9
3.3.Before You Install and Use ERS 4.0.2:Warnings...............................................11
3.4.Installing ERS 4.0................................................................................................13
3.5.Moving the tools/Tree.........................................................................................14
3.6.Manifest of ers-4.0.2-apache-2.2.15 Packages....................................................14
3.7.Example:Installation Walkthrough on Linux......................................................15
3.8.Description of the ERS httpd Directory Structure...............................................17
3.9.Starting and Stopping ERS httpd Instances.........................................................18
4.Installing and Using ERS Tomcat...................................................................................21
4.1.PlatformPrerequisites..........................................................................................21
4.2.Installing ERS Tomcat.........................................................................................22
4.3.Description of the ERS Tomcat Directory Structure...........................................24
4.4.Starting and Stopping ERS Tomcat Instances.....................................................25
5.Creating or Migrating ERS Instances.............................................................................27
5.1.Creating New ERS httpd or ERS Tomcat Instances............................................27
5.2.Migrating Existing ERS httpd Instances..............................................................28
6.Configuring Load Balancing Using ERS httpd..............................................................31
7.Upgrading FromERS 3.1 to ERS 4.0.............................................................................37
7.1.Overview of Upgrade...........................................................................................37
7.2.Upgrading:Typical Steps....................................................................................38
8.Additional Documentation..............................................................................................41
4.0 iii
iv Getting Started With ERS
1.Copyright Notice
Copyright © 2010 VMware Inc.All rights reserved.
VMware
Web
Site
Legal
Notice
Copyright Notice 1
4.0 1
2 Getting Started With ERS
2 Copyright Notice
2.Overview of SpringSource ERS
SpringSource Enterprise Ready Server (ERS) is the most comprehensive and widely distributed
solution for Apache HTTP Server and Apache Tomcat Application Server management.
ERS provides the following mission-critical benefits to Apache HTTP Server and Apache
Tomcat environments:
 Ability to easily install multiple instances of Apache HTTP Server and Apache Tomcat
running on a single server.
 Scalable management of multiple Web sites and servers;can run and manage hundreds of
instances of Apache HTTP Server and Apache Tomcat.
 Support for heterogeneous environments (32- and 64-bit architectures):Solaris Sparc,Solaris
x86,Linux,HP-UX,AIX,and Microsoft Windows.ERS can be updated and patched across
all servers at once.See
Supported
Platforms for details.
 Tight integration with Java,Perl,PHP,LDAP,and SSL.
2.1.ERS 4.0.2
The latest ERS offering,ERS 4.0.2,consists of Apache HTTP Server 2.2.15 (and related
components),Apache Tomcat Server 6.0.26,and Sun Java 6.ERS 4.0.2 updates the Apache
HTTP Server component,with the ers-4.0.2-apache-2.2.15 package.
2.2.Changes to ERS Packaging and Deployment
Prior to ERS 4.0.0,ERS consisted of a single installation package.Beginning with ERS 4.0.0,
the product is repackaged into separate components:Apache HTTP Server,Apache Tomcat,and
Sun Java.This division simplifies deployment of one or more components across the enterprise,
such as deploying only one specific version of Apache HTTP server on outward-facing boxes.It
simplifies redeployment of updated packages for one group of components without affecting
another.Also,packages can complete regression testing and quality assurance phases
independently of other modules.
2.3.Complete Packages for ERS 4.0.2 - Version
Contents
This section lists the complete contents of ERS 4.0.2.
What's
New
in
ERS
4.0.2 calls out
components that are new in ERS 4.0.2 and components that are updated fromERS 3.x.
Overview of SpringSource ERS 3
4.0 3
For a standalone Apache HTTP environment,download Package 1.For a standalone Apache
Tomcat environment,download packages 2 and 3,as Apache Tomcat is dependent on Java.(You
can add alternative,older packages to the environment.See
Alternative
Packages
for
ERS
4.0.
As each package becomes ready for GA release,it will be added to the download area.)
Package 1:Apache HTTP Server 2.2.15
Note
This document describes Apache HTTP features and functionality for ERS 4.0.x.For
general information about new features in Apache HTTP Server 2.2,see
the
Apache
website.
 Apache HTTP 2.2.15
 Apache mod_ftp 0.9.6 (derived fromand improves upon Covalent mod_ftp)
 Apache mod_fcgid 2.3.5 (a FastCGI invoker)
 PHP 5.2.13
 OpenSSL 0.9.8n
 OpenLDAP 2.3.43
 APR/APR-util both 1.3.9
 mod_jk 1.2.28
 mod_snmp (enables vhost-level metrics in Hyperic HQ,not included in original 4.0 release)
 libexpat 2.0.1
 libapr to 1.3.12
 libaprutil 1.3.9
 Perl 5.8.8
 mod_perl 2.0.4
 ASF 0.9.6
 Apache HTTP 2.2 server instances (test-apache2.2 and test-apache2.2-64).Caution:Use these
server examples for testing and validation only.
 ers-server.pl script
4 Getting Started With ERS
4 Overview of SpringSource ERS
Package 2:Apache Tomcat Server 6.0.26
Package 3:Java 6 (JVMor JDKexcept where restricted by license)
2.4.What's New in ERS 4.0.x?
ERS 4.0 makes significant changes and improvements over past versions.The sections that
follow discuss new and updated components.
New Components in ERS 4.0.2
4.0.2 adds the following new components:
 Apache HTTP Server 2.2.15
 PHP 5.2.13,which introduces object oriented development to PHP.
 modperl 2.0.4.The entire modperl package is in apache2.2/modules/perl/.Apache HTTP
Server 2.2 does not use the old directory modperl2.0/.
 Apache HTTP 2.2 server instances test-apache2.2 and test-apache2.2-64.
Caution:Use these server examples for testing and validation only.
 Apache mod_ftp 0.9.6 (derived fromand improving upon Covalent mod_ftp).
 Apache mod_fcgid 2.3.5 (a FastCGI invoker).
 mod_snmp (enables vhost-level metrics in Hyperic HQ).
Updates to ERS 3.x Components
ERS 4.0.2 updates ERS 3.x components as follows:
 Perl 5.8.8 (compiled with the most current,appropriate options).
 ers-server.pl script
 fixrootpath.pl script (updates the paths of additional files).
 tools/directory is updated with new content and is designed to be portable,separable from
the rest of the package.
 Open SSL is updated to release 0.9.8n,libexpat is updated to 2.0.1,libapr to 1.3.12,and
libaprutil to 1.3.9.
Overview of SpringSource ERS 5
4.0 5
PHP 5.2 with Apache HTTP Server 2.2.x Only
ERS 4.0 supports PHP 5.2 exclusively with Apache HTTP Server 2.2.The PHP 5.2 module will
not be distributed for Apache HTTP Server 1.3 or 2.0.ERS 4.0 contains the final PHP
distributions for ERS;future ERS releases will no longer include PHP.To facilitate this
transition,mod_fcgid is added to 4.0 releases,enabling users to plug into their own PHP
package,without loading PHP in the httpd process.For more information on new features and
migrating to PHP 5.x,see
the
PHP
website.
PHP 5.2 also supports libxml2,libxslt,Open SSL,Open LDAP,libiconv,zlib compression and
zts threading for worker MPM.
mod_fcgid Implementation of Connector to FastCGI
The mod_fcgid distributed with ERS 4.0.2 is an implementation of the connector to FastCGI
applications.This module allows the user to provision FastCGI providers such as PHP or Ruby
on Rails fromthird parties,running out-of-process fromthe server itself.
Many applications can be built to support FastCGI;consult your language or application
documentation for details.The application providing FastCGI services is launched by mod_fcgid
on the initial request,and reused for subsequent requests to that application or language
environment.
The bundled PHP 5.2 only includes php-cgi on Microsoft Windows architecture,where the
prefork MPM is not available to run single-threaded PHP applications.
For details on configuring an application,including the number of persistent processes created,
see
Apache
Module
mod_fcgid.
modperl 2.0.4 with Renamed modperl Symbols
ERS 4.0 packages update Apache 2 support frommodperl 1.99 RC4 to modperl release 2.0.4,
which renamed all modperl symbols fromApache packages to Apache 2 packages.You will
need to rename these in previously developed applications.See the
migration
notes for classic
modperl for Apache 1.3.
Legacy mod_ftp and Latest mod_ftp
ERS 4.0 provides two versions of mod_ftp.The version under the directory modules/covalent/is
the legacy package as distributed in the past for ERS Server and Covalent FTP Server products,
with minor bug fixes and corrections.The version under the directory modules/standard/
reflects the public module shipped by the Apache HTTP Project,which includes substantial
fixes,corrections,and support for evolving FTP standards and features,including IPv6 support.
6 Getting Started With ERS
6 Overview of SpringSource ERS
mod_snmp Enables Secure Communications to snmpv3 Clients
mod_snmp for Apache 2.2 is built against zlib and Open SSL to enable secure communications
to an snmpv3 client.(mod_snmp emits a warning at startup and shutdown when log messages
cannot be dispatched to the SSL agent.)
The corresponding snmp tools and snmpd for master agent configuration reside in tools/.
(The snmp2.0/directory is deprecated).These modules now ship with ERS 4.0.2;they were
omitted fromthe ERS 4.0.0 packages.The tools/tree includes a set of ucd-snmp command
line tools.
Note
See
Conflict
Between
mod_snmp
and
SNMPCONFPATH
Variable.
Open SSL 0.9.8n Supports SSLFIPS and
SSLInsecureRenegotiation Directives
A new mod_ssl directive SSLInsecureRenegotiation supports per-directory/per-server client
certificate renegotiation with legacy clients.Users are strongly cautioned to update all clients to
use only
the
new
TLS
Renegotiation
mechanism.
The OpenSSL 0.9.8n build is vendor-affirmed to comply with OpenSSL FIPS Security Policy
document v1.2.In order to use the FIPS 140-2 validated mode of operation (which relies on
NIST-approved,but slower algorithms) for mod_ssl cryptography,simply add the new'SSLFIPS
on'directive.A log entry will indicate whether FIPS mode is enabled or not.A warning that 512
byte temporary key generation is skipped will be logged at startup,this behavior is correct (512
byte keys are disallowed for FIPS use).See
Apache
Module
mod_ssl.
Portable tools/Tree
The tools/tree is designed to be portable.A shell script tools/bin/tools-env.sh is
provided to set environment variables that must be run prior to using the scripts in the tools tree.
See
tools/
Subtree
Requires
Script
to
Run
in
Current
Shell.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 changes and
enables the tools-env.sh script,which must be run before use.You can use the tools/
tree for SSL certificate management with the Open SSL command,as well as for password file
management.
2.5.Alternative Packages for ERS 4.0
Overview of SpringSource ERS 7
4.0 7
Apache Alternative Add-Ons
 Apache 2.0.63 Package,including FTP (can stand alone):Apache HTTP 2.0.63,mod_jk
1.2.26,Perl 5.8.8,PHP 4.4.8,OpenSSL 0.9.8h,OpenLDAP 2.3.39.Note:SNMP/mod_snmp
not included in initial release.
 Apache 1.3.41 Package (can stand alone):Apache HTTP 1.3.41,mod_jk 1.2.26,Perl 5.8.8,
PHP 4.4.8,OpenSSL 0.9.8h,OpenLDAP 2.3.39.Note:SNMP/mod_snmp not included in
initial release.
Apache Tomcat Alternative Add-Ons (require a JAVA package,or a pre-existing
JVM/JDK)
 Apache Tomcat 5.5.26
Sun Java Alternative Add-Ons
 Sun Java 5.0 Package:Default and recommended Java version for Tomcat 5.5.Some users
may want to run Tomcat 6 with Java 5.This is supported.
8 Getting Started With ERS
8 Overview of SpringSource ERS
3.Installing and Using ERS httpd
ERS httpd is a standalone component of Enterprise Ready Server (ERS) that has the Apache
HTTP Server as its core.ERS 4.0.2 updates the Apache HTTP component with the
ers-4.0.2-apache-2.2.15 package.You can install it as a new,first-time installation;
apply it to an existing ERS 3.x installation to add the Apache HTTP Server 2.2.15 with PHP 5.2
and modperl 2.0.x support;or apply it to upgrade your current version of Apache HTTP Server
2.2 to the latest for existing ERS 4.0.x installations.
3.1.Who Should Install ERS 4.0.x?
All ERS httpd users should apply ERS httpd 4.0.x.ERS 4.0.x corrects many problems in earlier
versions of Apache HTTP,especially legacy 2.0 and 1.3 servers,which you address by
upgrading.Both legacy releases 2.0 and 1.3 will be phased out over time,while support for the
Apache HTTP 2.2 package will continue.
Note
Do not apply ERS 4.0.2 to an ERS 2.x installation.
3.2.Supported Platforms
TCP/IPv6 is required on all platforms.Modern platforms have this support installed already.It is
not necessary to configure IPv6 adapters;simply install the IPv6 socket support drivers and
associated libraries.Vendor patch sets for compatibility with the current release of vendor or
IBM Java are recommended for all ERS httpd installations,because the operating systemflaws
that affect sockets and multi-threaded services for Java similarly affect ERS httpd and its support
libraries.
Table 3.1.ERS 4.0.x Platform Requirements
Operating System
Processor
Version
Requirements
Important Notes
Linux
x86 and x64
Minimumkernel
2.4.21.
Linux
PowerPC
Minimumkernel
2.6.9,equivalent to
RHEL 4 or later.
Patch Linux to
support IBM's Java 5
release.
Linux zSeries
x64
Minimumkernel 2.6.9
of s390x architecture,
equivalent to RHEL 4
or later.
The
s390x-linux-glibc2
ERS package provides
only 64-bit binaries.
Installing and Using ERS httpd 9
4.0 9
Operating System
Processor
Version
Requirements
Important Notes
32-bit is not supported
for this platform.
Patch Linux to
support IBM's Java 5
release.
IBM AIX
PowerPC
5.3 or later.
Patch AIX to support
IBM's Java 5.
HP/UX
PA-RISC
11.11 or later.
You must install the
/dev/(u)randomdriver
depot package on any
HP/UX 11.11
platform.HP/UX
11.23 includes the
/dev/(u)random
drivers by default.
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 will
not work on HP/UX
due to semaphore
permissions.)
Solaris
Sparc V8 and later
Solaris 8 and 9 (see
Important Notes).
Kernel patch
118833-18 is required
on Sparc V9
configurations.
Solaris 8 and 9 are
supported by the
sparc-sun-solaris-8.x
package on Sparc v8+
and later processors.
Use the Solaris 10.x
packages only on
Solaris 10 or higher.
Solaris
x86
Solaris 10.
ERS 4.0 for Solaris
contains only 32- bit
binaries.There is no
x86 support for
Solaris 8 or 9.
Windows Server (see
Important Notes)
x86 and x64
Windows Server 2003
and 2008.
Apache httpd 2.2 is
only supported on
10 Getting Started With ERS
10 Installing and Using ERS httpd
Operating System
Processor
Version
Requirements
Important Notes
Windows Server 2003
and Windows Server
2008 x86 32-bit and
64-bit editions.ERS
4.0 currently is
shipped only with
32-bit binary for
Windows,which is
compatible with and
supported on the x64
Server edition.
The
ers-4.0.0-apache-2.0.63
and
ers-4.0.0-apache-1.3.41packages
are the final ERS
packages to support
Windows 2000
Server,running SP 3
or later.
3.3.Before You Install and Use ERS 4.0.2:Warnings
Make sure you read the sections that follow before you install and use ERS httpd 4.0.2.
Do Not Overwrite Updated ers-servers.pl Script
ERS 4.0.2 has a unique,updated ers-servers.pl script.Make sure you do not replace it
with an older version by,for example,unpacking an ERS 4.0.0 component in the same tree as
the 4.0.2 script.It may be worthwhile to give this script a unique name,such as $ mv
ers-servers.pl ers-servers-402.pl.
Avoid Conflicts Between modperl Trees
This package includes an updated Perl binary and libraries.The single perl5.8 binary is shared by
all existing,installed Apache HTTP Server 1.3,Apache HTTP Server 2.0,and new Apache
HTTP Server 2.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
Installing and Using ERS httpd 11
4.0 11
loading mod_perl.so.Use caution in applying this patch to any shared deployment,and 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.
Test perl5.8 as follows:
Back up the existing perl5.8 tree by renaming it.Be prepared to restore it and install the 2.2
patch to an alternate location in case of failure.In a failure,give your support representative
operating system,version,platform,and CPU details.
ers-server.pl Script Does Not Convert Apache 2.0 Syntax to
Apache 2.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 must manually convert any deprecated 2.0
configuration file directives.See
the
Apache
2.2
upgrade
procedure.
Migrating Servers with ers-server.pl Script Requires Path to
Installed Java Tree
To migrate an ERS 2.x or 3.x deployed server using the./ers-server.pl script,you need a
path to an installed Java tree.Unpack an ers-4.0.0-java package under the ERS root,or use the
--javapath option to point to a deployed Java tree containing bin/java.
tools/Subtree Requires Script to Run in Current Shell
The tools/subtree now requires you to run a script in your current shell:
.tools/bin/tools-env.sh
Note the period-space prefix.This script sets up library paths and 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 script to their login
.profile script.
Note
Do not use the tools-env.sh script in conjunction with the httpsd service
process.The LD_LIBRARY_PATH and other configuration file environment
variables may interfere with the apache_startup.sh script and the loaded httpd
modules,including mod_snmp.
Conflict Between mod_snmp and SNMPCONFPATH Variable
12 Getting Started With ERS
12 Installing and Using ERS httpd
The SNMPCONFPATH variable interferes with the proper operation of mod_snmp.Because of
this flaw,avoid invoking the tools-env.sh script prior to apache_startup.sh.Adding
a statement'unset SNMPCONFPATH'to the apache_startup.sh script may deter the
conflict.
Self-Extracting ZIP
For all platforms ERS 4.0.2 is delivered as a self-extracting ZIP archive (not a tar.gz archive).
Self-extracting zip files will expand themselves.Alternatively,you can use unzip if your
platformsupports it,or you can
obtain
an
unzip
utility to expand the ZIP with additional options.
Note
If your operating systemis configured to support only 64-bit operation,an external
unzip utility is required.Do not use the jar utility to unpack these zip files,because
the filesystempermissions will not be unpacked correctly.
The packages are self-extracting zip images that you invoke on their respective platforms (either
32- or 64-bit CPU;all have 32-bit self-extract stubs except s390x),or fromanother platform
using the unzip utility.
3.4.Installing ERS 4.0
To install ERS 4.0:
1.If this is a new installation,place the package(s) in the desired installation location.This will
become the ERS home.Place all packages (Apache,Java) in the same location.On Microsoft
Windows,do not install into a path that contains spaces.
If this is an upgrade froman ERS 3.0 or 3.1 installation,copy the appropriate package file to
the base directory where the ERS was originally installed.(For 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 Microsoft Windows,in a cmd
Command Prompt window.)
3.Stop all running ERS httpd instances.The following steps will fail if you have any servers
using modperl fromSpringSource ERS installed in this directory.
4.Self-extract the files fromthis patch release by using the file name as a command.For
example,Linux users will use the following commands;other UNIX variants will be similar.
prompt$ cd/opt/ers
prompt$./ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx
Installing and Using ERS httpd 13
4.0 13
Invoke the file name at the command line to extract the corresponding platforms:
prompt$./ers-4.0.2-apache-2.2.15-sparc-sun-solaris-10.x-20100326.zip.sfx
prompt$./ers-4.0.2-apache-2.2.15-x86-solaris-10.x-20100326.zip.sfx
When unzipping,answer -YES- to overwrite fixrootpath.pl and ers-server.pl.
5.Run the fixrootpath.pl Perl script to correct the root paths.For example:
prompt$ perl fixrootpath.pl
Note
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.
If Perl is not otherwise installed,or on Microsoft Windows,use the Perl in the
ERS-HOME\perl5.8\bin directory.For example,on Windows:
prompt> cd c:\opt\ers
prompt> perl5.8\bin\perl.exe fixrootpath.pl
.
The fixrootpath.pl script,with no additional arguments,will transformeach occurrence
of PRODUCT_ROOT in any script or configuration file in the product tree with the working
directory fromwhich it is launched.
3.5.Moving the tools/Tree
To move the tools/tree:
1.Expand the Apache HTTP Server 2.2 component into a temp directory.
2.Copy fixrootpath.pl and the tools/tree to a new destination.fixrootpath.pl
goes in the parent directory of tools/,one directory above tools/.
3.Run fixrootpath.pl fromthe parent directory of tools/.It will update
tools/bin/tools-env.sh and set the paths in that file.
4.Run t ools/bin/tools-env.sh script to add the tools/tree paths to your user
environment.Optionally,add tools-env.sh to.profile to make permanent.
3.6.Manifest of ers-4.0.2-apache-2.2.15 Packages
14 Getting Started With ERS
14 Installing and Using ERS httpd
The immediately available package files included in this release are:
ers-4.0.2-apache-2.2.15-ppc-linux-glibc2-20100326.zip.sfx
ers-4.0.2-apache-2.2.15-sparc-sun-solaris-10.x-20100326.zip.sfx
ers-4.0.2-apache-2.2.15-sparc-sun-solaris-8.x-20100326.zip.sfx
ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx
ers-4.0.2-apache-2.2.15-x86-solaris-10.x-20100326.zip.sfx
ers-4.0.2-apache-2.2.15-x86-winnt-20100423.zip.exe
These packages contain:
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/
1
d-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/
1
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/
1
drwxr-xr-x 3 root root 4096 Mar 30 15:02 servers/
drwxr-xr-x 8 root root 4096 Mar 2 19:34 tools/
2
[1] *-64 directories are not present in sparc-sun-solaris-8.x,x86-winnt,and s390x-linux-glibc2
packages.The first two are 32-bit only,while s390x is distributed with only a 64-bit runtime in
the default directories.
[2] tools/tree utilities all require 32-bit support fromthe operating system,except for s390x.
3.7.Example:Installation Walkthrough on Linux
To install ERS 4.0.2 on Linux:
1.Create or change to the ERS install root:
prompt$ mkdir/opt/ers
prompt$ cd/opt/ers
2.Stop any running ERS httpd instances.For example:
prompt$ servers/my-http-server/bin/apache_startup.sh stop
3.Optionally,back up any existing trees by renaming them,for example:
prompt$ mv apache2.2 apache2.2.original
prompt$ mv perl5.8 perl5.8.original
prompt$ mv php5.5 perl5.8.original
4.Optionally,remove the snmp2.0/tree that is now part of tools/.
5.Copy in the Apache 2.2 add-on.For example,if you downloaded the file in your home
directory:
prompt$ cp ~/ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx.
6.Change file mode to make it executable:
Installing and Using ERS httpd 15
4.0 15
prompt$ chmod u+x ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx
7.Invoke the file to self-extract the contents:
prompt$./ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx
8.At the prompt,"Replace ERS_LICENSE.txt?[y]es,[n]o,[A]ll,
[N]one,[r]ename",select All.
The archive unpacks all files into the current directory.When it finishes,you should see the
following:
prompt$ ls
apache2.2 ERS_LICENSE.txt fixrootpath.pl perl5.8 php5.2 servers
apache2.2-64 ers-server.pl licenses perl5.8-64 php5.2-64 tools
See
Description
of
the
ERS
httpd
Directory
Structure for details about the directory structure.
9.Invoke the fixrootpath.pl perl script:
prompt$ perl fixrootpath.pl
It is assumed in the preceding command that Perl is in your PATH;if it is not,you can use the
Perl executable provided by ERS httpd:
prompt$ perl5.8/bin/perl fixrootpath.pl
On Microsoft Windows:
prompt> perl5.8\bin\perl.exe fixrootpath.pl
The script may take a few minutes as it checks all files in the installation.
10.Test the Apache HTTP Server 2.2 installation with the provided servers/test-apache2.2 or
servers/test-apache2.2-64 instances.For example,start the test-apache2.2 instance as
follows:
prompt$ cd servers/test-apache2.2
prompt$ bin/apache_startup.sh startssl
You should see the following mesage:
Starting Apache
Server started OK
11.Point browser to http://localhost:8080 or https://localhost:8443.
You will see a certificate warning fromhttps.
12.Enter username spring,with password spring to authenticate to the ERS httpd instance
home page.
16 Getting Started With ERS
16 Installing and Using ERS httpd
13.Test all examples by clicking on the links.
Once you have completed testing,stop Apache and create a production instance using
ers-server.pl.See
Creating
or
Migrating
ERS
Instances.
3.8.Description of the ERS httpd Directory Structure
The ERS httpd directory structure differs fromthe standard Apache HTTP directory layout in
that ERS separates the runtime binaries fromthe configuration data.To do this,you use or create
an ERS httpd instance that lives in a child-directory of the servers sub-directory of the main
ERS httpd home directory.The name of the instance is the name of the new directory in
servers.You then configure this instance as you want,using the standard Apache httpd files
in the servers/server-name/conf directory,such as httpsd.conf.You should
performall configuration work inside this server instance directory.You should never modify
any files under the binary directory (such as ERS-HOME/apache2.2 ).
Keeping the runtime binary files apart fromthe files that are configured by administrators or
end-users makes it easier to upgrade or apply patches to the code without running the risk of
overwriting or corrupting user data.It also enables administrators to run multiple server instances
independently.
After you install ERS httpd,you will see the following files and directories:
apache2.2/(Apache 2.2 binary runtime files only)
apache2.2-64/(64-bit Apache 2.2 binary runtime files only)
php5.2/(PHP binaries for use with Apache mod_php)
php5.2-64/(64-bit PHP binaries for use with Apache mod_php)
tools/(misc tools)
perl5.8/(PERL for use with Apache mod_perl)
perl5.8-64/(64-bit PERL for use with Apache mod_perl)
servers/(Servers directory contains all deployed data
- configs,logs,content,etc)
ERS_LICENSE.txt (ERS license file)
ers-server.pl (Perl script for creating or migrating ERS httpd instances)
fixrootpath.pl (Perl script for fixing root paths;run only once)
As previously described,a new installation of ERS httpd includes two sample instances in the
ERS-HOME/servers directory:test-apache2.2 and test-apache2.2-64.When
you subsequencly create new instances using the ers-server.pl script,they will be created
in this directory as well.
Each of the instance sub-directories of servers contains a separately configurable instance of
ERS httpd.An"instance"is a complete,discrete server configuration.You can create multiple
instances under the servers directory.You can run multiple instances at the same time if you
are careful not to use the same ports in two different instances.For example,the default HTTP
listening port is 8080,and only one instance on any computer is allowed to communicate on port
8080 at any one time.So if you wanted to have two ERS httpd instances running at the same
time on the same computer,you would configure one instance to use a port other than 8080.
Each instance directory contains subdirectories that contain all the data required to run a given
ERS httpd instance.This includes configuration data as well as all other data that is associated
with that instance's configuration.For example:
Installing and Using ERS httpd 17
4.0 17
prompt$ cd/opt/ers/servers/test-apache2.2
prompt$ ls
bin cgi-bin conf ftpdocs htdocs logs ssl temp var
The conf directory contains the ERS httpd configuration files.The bin directory contains the
startup scripts used to start and stop the test-apache2.2 instance of ERS httpd
(apache_startup.sh|bat.Each of these directories is specific to the test-apache2.2
instance.Each instance you create will have a similar set of directories.
3.9.Starting and Stopping ERS httpd Instances
This section is divided into two topics based on platform:

Unix

Windows
Unix
You start,stop,or restart an ERS httpd instance on Unix using the apache_startup.sh
script in the bin directory of the instance.
Warning:You always use the start script in the bin of the instance directory under
ERS-HOME/servers.Do not use the start script in the ERS-HOME/apache2.2/bin
directory.
For example,to start an ERS httpd instance called myserver,in which the ERS-HOME
directory is/opt/ers,follow these steps after starting a Unix terminal:
prompt$ cd/opt/ers/servers/myserver/bin
prompt$./apache_startup.sh start
You should see a message as follows:
Starting Apache:
Server started OK
To start the ERS httpd instance in SSL mode,use the startssl option:
prompt$./apache_startup.sh startssl
To test that the ERS httpd instance actually started,navigate to the http://host:port URL
in your browser,where host refers to the host computer (you can use localhost if your
browser is on the same computer) and port refers to the HTTP listen port number you provided
when you created the instance.The default value is 8080
For example,if you are using the default ports on your local computer,use this URL:
http://localhost:8080
18 Getting Started With ERS
18 Installing and Using ERS httpd
If the ERS httpd instance started successfully,you should see the welcome page.
To stop the instance immediately:
prompt$ cd/opt/ers/servers/myserver/bin
prompt$./apache_startup.sh stop
To stop the instance gracefully:
prompt$./apache_startup.sh gracefully
To restart a currently running instance:
prompt$./apache_startup.sh restart
Windows
You start,stop,or restart an ERS httpd instance on Windows by first installing it as Windows
service using the apache_startup.bat script in the bin directory of the instance directory,
and subsequently using the Windows Services console to start or stop it.
Warning:Use the scripts only in the ERS-HOME/servers/server-name/bin directory,
do not use the scripts in the ERS-HOME/apache2.2/bin directory.
For example,to install an ERS httpd instance called myserver,in which the ERS-HOME
directory is c:\ers\,follow these steps after starting a Windows command prompt:
prompt> cd c:\ers\servers\myserver\bin
prompt> apache_startup.bat install
To install it in SSL mode,use the installssl option:
prompt> apache_startup.bat installssl
Subsequently use the Windows Services console to start,stop,and restart the ERS http instance.
The name of the instance in the Windows Services console is ERS myserver httpsd.Also
use the Windows Services control panel to configure whether the ERS httpd service starts
automatically when Windows starts,and so on.
To test that the ERS httpd instance actually started,navigate to the http://host:port URL
in your browser,where host refers to the host computer (you can use localhost if your
browser is on the same computer) and port refers to the HTTP port number you provided when
you created the instance.The default value is 8080
For example,if you are using the default ports on your local computer,use this URL:
http://localhost:8080
If the ERS httpd instance started successfully,you should see the welcome page.
To uninstall the ERS httpd instance as a Windows service,use the following command:
Installing and Using ERS httpd 19
4.0 19
prompt> cd c:\ers\servers\myserver\bin
prompt> apache_startup.bat uninstall
20 Getting Started With ERS
20 Installing and Using ERS httpd
4.Installing and Using ERS Tomcat
The ERS Tomcat component of ERS 4.0 (subsequently called ERS Tomcat in this document)
uses Apache Tomcat 6.0 as its core,and then adds mission-critical benefits such as:
 Ability to easily install multiple versions,and then multiple instances,of ERS Tomcat on a
single server.
 Scalable management of multiple Web sites and servers;can run and manage hundreds of
instances of Tomcat.
 Support for heterogeneous environments (32- and 64- bit architectures):Solaris Sparc,Solaris
x86,Linux,HP-UX,AIX,and Win32.ERS can be updated and patched across all servers at
once.
 Tight integration with Java,Perl,and PHP.
Note:Unless otherwise noted,it is assumed in this section that you are going to install and use
ERS Tomcat on its own (in other words,you are not installing and using ERS httpd on the same
computer.)
ERS Tomcat is packaged in its own self-extracting JAR file with the following name:
ers-4.0.0-tomcat-6.0.X-platform-and-timestamp.sfx.jar
where X refers to a more specific version of Apache Tomcat 6.0 and
platform-and-timestamp refers to the platform(such as Unix or Windows) and a
timestamp of when the package was created,such as
ers-4.0.0-tomcat-6.0.26-unix-2010-03-19.sfx.jar.
For a summary of the changes in ERS Tomcat,see the following links:

Apache
Tomcat
6.0
Changelog

Apache
6.X
Vulnerabilities
4.1 PlatformPrerequisites
The following prerequsities apply to all platforms (Unix and Windows):
 You must download and install a JDK;ERS Tomcat does not provide one for you.
 Although SpringSource recommends that you use version 6 of the JVM,version 5 of the JVM
is supported.
 It is strongly recommended that you use the latest JVM release.
Installing and Using ERS
Tomcat
21
4.0 21
 JVM implementations fromHP,IBM and Sun are supported.
 The ERS Tomcat package requires Perl for its initial installation and configuration.If your
systemdoes not already have Perl installed you have two choices:
 Install a systemPerl.Windows users can
install
ActiveState
Pearl.
 Install an ERS httpd package,which includes Perl.
The following prerequsite applies only to Windows platforms:
 The service wrapper shipped with ERS Tomcat supports only 32-bit JVMs.This means that,
on Windows,you can install and use ERS Tomcat only with 32-bit JVMs.Because you can
use 32-bit JVMs on both 32-bit and 64-bit operating systems,you can install and use ERS
Tomcat on 32-bit and 64-bit Windows,as long as you use the 32-bit JVM.
You can use ERS Tomcat on Unix with both 32-bit or 64-bit JVMs.
4.2 Installing ERS Tomcat
The following procedure describes how to install ERS Tomcat 4.0;it is assumed that this is a
new installation and not an upgrade.
1.Download and install a JDK or JRE,if you do not already have one installed on your
computer.You can download a JDK fromthe
SpringSource
ERS
Download page or fromthe
Sun Web site (see
Sun
JDK
and
JRE
Downloads.)
After you install the JDK or JRE,set your JAVA_HOME environment variable to point to your
installation and update your PATH environment variable to point to the JAVA_HOME/bin
directory.
2.If your computer does not already have Perl installed,you must download it and install it.See
Platform
Prerequisites.
3.Open a terminal (Unix) or command window (Windows) and create the directory in which
you want to install ERS Tomcat.This will be the ERS home directory.The only exception is
if you have already installed ERS httpd on the computer;in this case,SpringSource suggests
you use the same home directory rather than create a new one so that the two ERS packages
are in the same location.
On Windows,do not create a directory using a path that contains spaces.
For example,on Unix:
prompt$ cd/opt
prompt$ mkdir ers
4.Download the ERS Tomcat distribution fromthe
SpringSource
Download
Center into the
22 Getting Started With ERS
22
Installing and Using ERS
Tomcat
ERS home directory you created in the preceding step (such as/opt/ers.)
The distribution is a self-extracting file with a name like
ers-4.0.0-tomcat-6.0.26-unix-2010-03-19.sfx.jar for both Unix and
Windows.
5.Change to the ERS home directory and extract the files fromthe downloaded distribution by
executing the JAR file.For example,on Unix:
prompt$ cd/opt/ers
prompt$ java -jar ers-4.0.0-tomcat-6.0.26-unix-2010-03-19.sfx.jar
6.Run the fixrootpath.pl perl script to correct the root paths.The fixrootpath.pl
perl script is located in the main ERS home directory.For example:
prompt$ cd/opt/ers
prompt$ perl fixrootpath.pl
Note:It is assumed in the preceding command that Perl is in your PATH;if it is not,specify
the full pathname.For example,on Windows,if you installed Perl in c:\home\perl5.8:
prompt> c:\home\perl5.8\bin\perl fixrootpath.pl
The fixrootpath.pl perl script transforms each occurance of @(PRODUCT_ROOT)@ in
any script or configuration file in the product tree with the working directory fromwhich it is
launched.You must run this script with at least perl 5.005.You cannot run the script in
multibyte character encoding such as UTF8.Unset the LANG or LC_*** environment
variables to remove any UTF8 or other encodings before invoking fixrootpath.pl.
7.If you are installing only ERS Tomcat and are using the systemPerl,you must update the
ers-server.pl file by changing the first line so that it correctly points to your system
Perl location (or whatever is appropriate for your environment).For example,if you are using
Perl located at/usr/bin/perl,then change the first line of ers-sever.pl to the
following:
#!/bin/sh/usr/bin/perl
The next steps after installing ERS Tomcat are as follows:
 Create a new ERS Tomcat instance.The default installation does not provide one for you.See
Creating
or
Migrating
ERS
Instances,which is a section that provides general information
about the ers-server.pl Perl script.Both components of ERS (ERS httpd and ERS
Tomcat) include the exact same script,which is why the documentation of the script covers
both components.
 Understand the directory structure of ERS Tomcat.See
Description
of
the
ERS
Tomcat
Directory
Structure.
 Start the new ERS Tomcat instance and test that it is running correctly.See
Starting
and
Stopping
ERS
Tomcat
Instances.
Installing and Using ERS
Tomcat
23
4.0 23
4.3 Description of the ERS Tomcat Directory Structure
The ERS Tomcat directory structure differs slightly fromthe standard Apache Tomcat directory
layout in that ERS separates the runtime binaries fromthe configuration data.To do this,you
create an ERS Tomcat instance that lives in a child-directory of the servers sub-directory of
the main ERS Tomcat home directory.The name of the instance is the name of the new directory
in servers.You then configure this instance as you want,using the standard Apache Tomcat
files in the servers/server-name/conf directory,such as server.xml.You should
performall configuration work inside this server instance directory.You should never modify
any files under the binary directory ( ERS-HOME/tomcat6.0 ).
Keeping the runtime binary files apart fromthe files that are configured by administrators or
end-users makes it easier to upgrade or apply patches to the code without running the risk of
overwriting or corrupting user data.It also enables administrators to run multiple server instances
independently.
Directly after you install ERS Tomcat,you will see the following files and directory in the ERS
home directory:
 tomcat6.0:Directory that contains the Tomcat 6.0 runtime binaries.
 ers-server.pl:Perl script for creating a new instance of ERS Tomcat.
 fixrootpath.pl:Perl script for correcting the root paths.You run this script only once,
after installing the product.
A new installation of ERS Tomcat does not include a default instance;you must create one to
begin using ERS Tomcat,as described in
Creating
or
Migrating
ERS
Instances.After you create
your first instance,you will have a new directory under ERS-HOME called servers which will
contain all ERS Tomcat instances that you subsequently create.
Each of these sub-directories of servers contains a separately configurable instance of ERS
Tomcat.An"instance"is a complete,discrete server configuration.You can create many
instances under the servers directory.You can run multiple instances at the same time if you
are careful not to use the same ports in two different instances.For example,the default HTTP
listening port is 8080,and only one instance on any computer is allowed to communicate on port
8080 at any one time.So if you wanted to have two ERS Tomcat instances running at the same
time,you would configure one instance to use a port other than 8080.
Each instance directory contains subdirectories that contain all the data required to run a given
ERS Tomcat instance.This includes configuration data as well as all other data that is associated
with that instance's configuration.For example,assume you have already created an ERS
Tomcat instance called myserver:
prompt$ cd/opt/ers/servers/myserver
prompt$ ls
bin conf logs ssl temp var webapps work
The conf directory contains the ERS Tomcat configuration files.The bin directory contains
24 Getting Started With ERS
24
Installing and Using ERS
Tomcat
the startup scripts used to start and stop the myserver instance of ERS Tomcat,and so on.
Each of these directories is specific to the myserver instance.Each instance you create will
have a similar set of directories.
4.4 Starting and Stopping ERS Tomcat Instances
This section is divided into two topics based on platform:

Unix

Windows
Unix
You start,stop,or restart an ERS Tomcat instance on Unix using the tomcat_startup.sh
script in the bin directory of the instance.
Warning:You always use the start script in the bin of the instance directory under
ERS-HOME/servers.Do not use the start script in the ERS-HOME/tomcat6.0/bin
directory.
For example,to start an ERS Tomcat instance called myserver,in which the ERS-HOME
directory is/opt/ers,follow these steps after starting a Unix terminal:
prompt$ cd/opt/ers/servers/myserver/bin
prompt$./tomcat_startup.sh start
You should see a message as follows:
Starting Tomcat:
Server started OK
To test that the ERS Tomcat instance actually started,navigate to the http://host:port
URL in your browser,where host refers to the host computer (you can use localhost if
your browser is on the same computer) and port refers to the HTTP port number you provided
when you created the instance.The default value is 8080
For example,if you are using the default ports on your local computer,use this URL:
http://localhost:8080
If the ERS Tomcat instance started successfully,you should see the welcome page.
To stop the instance:
prompt$ cd/opt/ers/servers/myserver/bin
prompt$./tomcat_startup.sh stop
To restart a currently running instance:
Installing and Using ERS
Tomcat
25
4.0 25
prompt$ cd/opt/ers/servers/myserver/bin
prompt$./tomcat_startup.sh restart
Windows
You start,stop,or restart an ERS Tomcat instance on Windows by first installing it as Windows
service using the tomcat_startup.bat script in the bin directory of the instance directory,
and subsequently using the Windows Services console to start or stop it.
Warning:Use the scripts only in the ERS-HOME/servers/server-name/bin directory,
do not use the scripts in the ERS-HOME/tomcat6.0/bin directory.
For example,to install an ERS Tomcat instance called myserver,in which the ERS-HOME
directory is c:\ers\,follow these steps after starting a Windows command prompt:
prompt> cd c:\ers\servers\myserver\bin
prompt> tomcat_startup.bat install
Subsequently use the Windows Services console to start,stop,and restart the ERS Tomcat
instance.The name of the instance in the Windows Services console is ERS myserver
tomcat.Also use the Windows Services control panel to configure whether the ERS Tomcat
service starts automatically when Windows starts,and so on.
To test that the ERS Tomcat instance actually started,navigate to the http://host:port
URL in your browser,where host refers to the host computer (you can use localhost if
your browser is on the same computer) and port refers to the HTTP port number you provided
when you created the instance.The default value is 8080
For example,if you are using the default ports on your local computer,use this URL:
http://localhost:8080
If the ERS Tomcat instance started successfully,you should see the welcome page.
To uninstall the ERS Tomcat instance as a Windows service,use the following command:
prompt> cd c:\ers\servers\myserver\bin
prompt> tomcat_startup.bat uninstall
26 Getting Started With ERS
26
Installing and Using ERS
Tomcat
5.Creating or Migrating ERS Instances
You use the ers-server.pl Perl script to create new instances of both ERS Tomcat and ERS
httpd and to migrate existing ERS httpd instances.
Note that the exact same script is included in the two ERS component packages (ERS httpd and
ERS Tomcat).For this reason,this section applies to both ERS components.If,for example,you
have installed only ERS Tomcat,then you can ignore the option of the script that applies only to
ERS httpd ( --apachever ).This section provides examples for both ERS Tomcat and ERS
httpd.
The ers-server.pl script creates new ERS Tomcat or ERS httpd instances in the
ERS-HOME/servers directory.
The following output fromthe script shows all the available options:
ers-server.pl - install an ERS 4.0 server instance
from the default (_instance/trees) template
Syntax:
--ersdir=/path/to/ers-root default is current dir
--server=servername hostname and default path to create
--serverdir=/path/to/instance override servers/{servername} destdir
--overlay overlay existing {serverdir} files
--apachever=[1.3|2.0|2.2[-64]] deploy new server using Apache httd
--tomcatver=[5.0|5.5|6.0] deploy new server using Apache Tomcat
--javapath=[j5sdk[64]|j6sdk[64]] abs or rel path to jdk/jre for Tomcat
--erssrc=/path/to/old-root migrate ers;default is current dir
--migrate=oldname existing servers/{oldname} instance
--migratedir=/path/to/instance override servers/{oldname} source dir
--quiet bypass all interactive prompts
5.1 Creating New ERS httpd or ERS Tomcat Instances
New server instances do not have examples enabled,have no preconfigured content other than a
default welcome page,and are intended for production usage.
You specify on the command-line which type of instance you want to create (ERS httpd or ERS
Tomcat) using the --apachever and --tomcatver options,respectively.You specify the
name of the server using the --server option.Finally,when creating an ERS Tomcat instance,
you must also use the --javapath option to specify the full pathname of your JDK or JRE.
When you use ers-server.pl to create a new instance you will be asked a series of
questions which will control the configuration of the instance you create.For example,if you
create an ERS Tomcat instance,you will be asked for the various listen ports,such as shutdown,
HTTP,and AJP.When you create a new ERS httpd instance,you will be asked whether you
want to enable certain modules (such as mod_perl or mod_php5) as well as values for various
listen ports,server host and email information,and security information such as whether to
enable SSL,and if so,you will be asked to provide an initial user account and password and
optionally create a temporary SSL certificate,signing request,and key as part of the installation.
Creating or Migrating ERS
Instances
27
4.0 27
For clarity,it is assumed in the examples of this section that you installed ERS in/opt/ers.
The following example shows how to create a new ERS httpd instance:
prompt$ cd/opt/ers
prompt$ perl ers-server.pl --server=myHttpServer --apachever=2.2
Note:It is assumed in the preceding command that Perl is in your PATH;if it is not,specify the
full pathname.For example,on Windows,if you installed Perl in c:\home\perl5.8:
prompt> c:\home\perl5.8\bin\perl ers-server.pl --server=myHttpServer --apachever=2.2
The preceding example shows how to create a new ERS httpd server called myHttpServer
that uses version 2.2 of Apache HTTP.
The following example shows how to create a new ERS Tomcat instance:
prompt$ cd/opt/ers
prompt$ perl ers-server.pl --server=myTomcatServer --tomcatver=6.0 --javapath=/opt/java/jdk1.6.0_18
The preceding example shows how to create a new ERS Tomcat server called
myTomcatServer that uses version 6.0 of Apache Tomcat and the JDK installed in
/opt/java/jdk1.6.0_18.
5.2 Migrating Existing ERS httpd Instances
The ERS httpd package includes two test instances that are already created called
test-apache2.2 and test-apache2.2-64.These preconfigured server instances
include PERL and PHP examples enabled.If you want to create a new instance with these
examples enabled,use the --migrate option of the ers-server.pl script to copy one of
the test-apacheX.X instances to a new location.
Important:Although you do not need a JDK to create a new"blank"ERS httpd instance,you do
need to specify a JDK using the --javapath option if you want to clone an existing instance.
You can download the JDK fromthe
SpringSource
ERS
Download page or fromthe Sun Web
site (see
Sun
JDK
and
JRE
Downloads.)
The following example shows how to create a new ERS httpd instance called newserver using
the existing test-apache2.2 as a template.The new server is,in essence,of copy of
test-apache2.2 but with a new name.
prompt$ cd/opt/ers
prompt$ perl ers-server.pl --server=newserver --migrate=test-apache2.2 --javapath=/opt/java/jdk1.6.0_18
Note:It is assumed in the preceding command that Perl is in your PATH;if it is not,specify the
full pathname.For example,on Windows,if you installed Perl in c:\home\perl5.8:
prompt> c:\home\perl5.8\bin\perl ers-server.pl --server=newserver --migrate=test-apache2.2 --javapath=c:\java\jdk1.6.0_18
If you plan to use both ERS httpd instances on the same computer,remember to ensure that the
28 Getting Started With ERS
28
Creating or Migrating ERS
Instances
listen ports are unique for each instance and configure security appropriately.
Creating or Migrating ERS
Instances
29
4.0 29
30 Getting Started With ERS
30
Creating or Migrating ERS
Instances
6.Configuring Load Balancing Using ERS
httpd
This section describes how to configure simple load balancing between two or more ERS
Tomcat instances using the ERS httpd Server.
In this scenario,you configure an Enterprise Ready Server (ERS) httpd Server to run in front of
the ERS Tomcat instances;this ERS httpd Server receives all requests fromusers,and it then
passes themback to the ERS Tomcat instances using a specified load balancing algorithm.
Responses fromthe ERS Tomcat instances are then routed back through this same ERS httpd
Server.For this reason,the ERS httpd Server acts like a proxy (both reverse and forward) so that
the users never know the URLs of the backend ERS Tomcat instance that are actually doing all
the work.Additionally,the ERS httpd Server ensures that the load on each ERS Tomcat instance
is balanced.You can specify that each ERS Tomcat instance take on an equal work load,or you
can specify that one instance work twice as hard as the others.
For clarity,the following scenario is assumed in the procedure.Note that these assumptions are
not requirements;your environment might be very different.The assumptions are listed only to
make the procedure easier to understand.
 You have two ERS Tomcat instances running at the following two hosts and port numbers:
 http://192.168.0.203:8081
 http://192.168.0.203:8082
Additionally,the two ERS Tomcat instances are running on the same computer and their
respective CATALINA_BASE variables are as follows:
/opt/ers/servers/instanceOne
/opt/ers/servers/instanceTwo
 Each ERS Tomcat instance is configured exactly the same (other than the value of the various
ports).
 You have deployed the same application to both ERS Tomcat instances and the URL context
is the same in both instances:/my-app.
Further,you want all users that use the application to first go through the front-end ERS httpd
Server,and any evidence of the backend ERS Tomcat instances upon which the application is
actually deployed should be hidden fromthe user.
 ERS httpd Server is installed on a different computer than ERS Tomcat.The name of the
particular ERS httpd instance is lb-server and its home directory is
/home/ers/servers/lb-server.
Configuring Load Balancing
Using ERS httpd
31
4.0 31
 You want to configure sticky sessions,which means that the ERS httpd Server always routes
the requests for a particular session to the same ERS Tomcat instance that serviced the first
request for that session.
 You want to use the HTTP protocol for all communication between the ERS httpd Server and
the ERS Tomcat instances.
The load balancing described in this procedure is very simple,although you have many options
available to further customize it.At appropriate locations in the procedure,links to the Apache
HTTP Server documentation are provided for additional configuration options not covered by
this specific scenario.Adapt the procedure for your particular environment.
As part of the procedure,you will update the configuration files of both the ERS httpd Server
and the two ERS Tomcat instances.
To configure load balancing for this scenario,follow these steps:
1.On the computer on which ERS httpd is installed,stop the instance,if it is currently running.
Following our example and assumptions:
prompt$ cd/home/ers/servers/lb-server
prompt$ bin/apache_startup.sh stop
2.Update the httpsd.conf configuration file of the ERS httpd instance by adding the
following LoadModule directive which loads the ERS httpd proxy_balancer_module
module:
LoadModule proxy_balancer_module"ERS-INSTALL/apache2.2/modules/standard/mod_proxy_balancer.so"
where ERS-INSTALL refers to the directory in which you installed ERS httpd.Following
our example,the directive would be:
LoadModule proxy_balancer_module"/home/ers/apache2.2/modules/standard/mod_proxy_balancer.so"
The ERS configuration file is located in the conf directory of your ERS httpd instance
(/home/ers/servers/lb-server/conf in our example.) Add the LoadModule
directive in the same section as the other directives.
Also be sure that the other two required modules,mod_proxy and mod_proxy_http,are
enabled (in other words,are not commented out:)
LoadModule proxy_module"/home/ers/apache2.2/modules/standard/mod_proxy.so"
LoadModule proxy_http_module"/home/ers/apache2.2/modules/standard/mod_proxy_http.so"
3.In the same httpsd.conf file,add the proxy configuration.Use the <Proxy> element to
specify the list of ERS Tomcat instances and the method of load balancing you want to use.
Then use the ProxyPass and ProxyPassReverse directives to specify the URLs that
will use this proxy and load-balancing (both for requests and responses.) For example:
<Proxy balancer://my-balancer>
BalancerMember http://192.168.0.203:8081 route=instanceOne loadfactor=1
BalancerMember http://192.168.0.203:8082 route=instanceTwo loadfactor=1
ProxySet lbmethod=byrequests
32 Getting Started With ERS
32
Configuring Load Balancing
Using ERS httpd
</Proxy>
ProxyPass/my-app balancer://my-balancer/my-app
ProxyPassReverse/my-app http://192.168.0.203:8081/my-app
ProxyPassReverse/my-app http://192.168.0.203:8082/my-app
The balancer parameter of the <Proxy> element specifies a unique identifier for this load
balancer configuration.Each ERS Tomcat instance that will be serviced by this load balancer
must have its own BalancerMember;the first parameter of this directive specifies the full
IP address (including port number) of the ERS Tomcat instance.The route parameter
contains session ID information;you will later use the value of this parameter in the ERS
Tomcat configuration file to configuring sticky sessions;for now,just ensure that the values
are unique for each BalancerMember.
The loadfactor parameter specifies how much of a load a particular member carries.If
you want each member to carry the same load,set the numbers equal to each other (as in the
example above.) If,however,you want one member to work three times harder than the other,
set the loadfactors to 3 and 1.
Use the lbmethod parameter of the ProxySet directive to specify the load balancing
algorithm.The possible values are as follows:
 byrequests which performs weighted request counting.This is the default value.
 bytraffic which performs weighted traffic byte count balancing
 bybusyness which performs pending request balancing.
Finally,use the ProxyPass and ProxyPassReverse to specify the context URLs of the
application that will be routed to the ERS Tomcat instances that you have configured in the
load balancing scheme.ProxyPass specifies that when the ERS httpd server receives a
request at the/my-app URL,it will route it to the load balancer which will in turn route it to
the ERS Tomcat instance.ProxyPassReverse does the reverse:when the ERS Tomcat
instance sends a response to a user who is using/my-app,the response appears to come
fromthe ERS httpd server,and not the ERS Tomcat instance.Thus the details of the ERS
Tomcat instance are hidden fromthe user.
See
Apache
Module
mod_proxy on the Apache Software Foundation Web site for the full
reference documentation on the directives described in this step,along with additional
parameters you can use.
4.Optional.If you want to enable the balancer manager Web application to watch the load
balancing activity and control the behavior,add the following to the httpsd.conf
configuration file of your ERS httpd instance:
<Location/balancer-manager>
SetHandler balancer-manager
Order Deny,Allow
Deny from all
#BE VERY RESTRICTIVE with YOUR ALLOW STATEMENT
Allow from 127.0.0.1
</Location>
Configuring Load Balancing
Using ERS httpd
33
4.0 33
After restarting the ERS httpd instance,you can access the balancer manager application by
navigating to the http://localhost:port/balancer-manager URL in your
browser,where port is the port number of the ERS httpd instance ( 8080 by default.) For
security,the preceding balancer manager configuration allows access only to users who
navigate to the application using a browser installed on the same computer on which the ERS
httpd Server is actually running.
5.Optional.If you want to enable sticky sessions,follow these steps:
a.In the httpsd.conf file of the ERS httpd instance,update the ProxySet directive of
the <Proxy> element you configured in a preceding
step by adding the
stickysession=JSESSIONID|jsessionid parameter.This parameter configures
the cookie/path that will be used for stickiness.For example (update shown in bold):
<Proxy balancer://my-balancer>
BalancerMember http://192.168.0.203:8081 route=instanceOne loadfactor=1
BalancerMember http://192.168.0.203:8082 route=instanceTwo loadfactor=1
ProxySet lbmethod=byrequests stickysession=JSESSIONID|jsessionid
</Proxy>
b.Go to the computer on which ERS Tomcat is running and update the server.xml
configuration file of both ERS Tomcat instances by adding the jvmRoute= value
attribute to the Catalina <Engine> element.Set the value of this attribute equal to the
value you specified (in a preceding
step ) for the route parameter of the
BalancerMember directive in the ERS httpd httpsd.conf file that describes the
ERS Tomcat instance.
Following our example,the updated <Engine> entry for the instanceOne ERS
Tomcat instance (that uses port 8081) would be as follows (new attribute in bold):
<Engine name="Catalina"defaultHost="localhost"jvmRoute="instanceOne">
If you configure sticky sessions,SpringSource recommends that you also configure session
replication for the ERS Tomcat instances.
6.Start the ERS httpd instance.Following our example:
prompt$ cd/home/ers/servers/lb-server
prompt$ bin/apache_startup.sh startssl
7.Start (or restart) the two ERS Tomcat instances for the configuration changes to take effect.
Following our example:
prompt$ cd/opt/ers/servers/instanceOne
prompt$ bin/tomcat_startup.sh stop
prompt$ bin/tomcat_startup.sh start
prompt$ cd/opt/ers/servers/instanceTwo
prompt$ bin/tomcat_startup.sh stop
prompt$ bin/tomcat_startup.sh start
You have now configured load balancing for the two ERS Tomcat instance using the front-end
ERS httpd server.If,for example,the URL to access the ERS httpd server is
http://www.myhost.com,and a user invokes the following URL in their browser:
34 Getting Started With ERS
34
Configuring Load Balancing
Using ERS httpd
http://www.myhost.com/my-app
the ERS httpd server will route the request to one of the two ERS Tomcat instances,balancing
the load between the two instances.
Configuring Load Balancing
Using ERS httpd
35
4.0 35
36 Getting Started With ERS
36
Configuring Load Balancing
Using ERS httpd
7.Upgrading FromERS 3.1 to ERS 4.0
This section describes how to upgrade an existing ERS installation fromversion 3.1 to version
4.0.The procedure first describes how to upgrade the 3.1 installation itself with the new 4.0
binaries,new versions of the Perl scripts,and so on.The procedure then describes how to
migrate a 3.1 ERS server instance to one that uses the versions of Apache HTTP and Tomcat in
ERS 4.0 (namely,Apache 2.2 and Tomcat 6.0).
7.1 Overview of Upgrade
As noted in earlier sections of this guide,ERS 4.0 is now distributed as a collection of separate
packages that correspond to the main components of ERS (such as ERS httpd and ERS Tomcat.)
This differs fromhow ERS 3.1 was packaged,in which all components were distributed
together.For this reason,it is assumed in this procedure that you will continue to have a single
directory for the entire ERS installation;this single directory will hold both the ERS httpd and
ERS Tomcat components.If you want to"split up"your existing 3.1 ERS installation,then
adjust the procedure in this section accordingly.
The procedure will use the default20 sample server instance (included in the 3.1 ERS
installation) as an example of migrating an existing server so it uses the latest versions of Apache
HTTP and Tomcat.Use this example as a guide when you migrate your own server instances.
Important:Before starting the upgrade,make a backup of your existing 3.1 ERS installation so
that you can roll back if needed.SpringSource also recommends that you first upgrade your
non-production ERS installations and servers as a practice before upgrading your production
installations and servers.
The procedure below describes how to do an in-place upgrade.This means you simply install
ERS 4.0 on top of your existing ERS 3.1 installation.ERS 4.0 is designed to support this type of
upgrade,with a few caveats that are explicitly called out in the procedure.
Unpacking ERS 4.0 on top of your ERS 3.1 installation overwrites the perl5.8 directory,the
two Perl scripts ( fixrootpath.pl and ers-server.pl ) and the licenses.Everything else
in 4.0 is new,such as the new version of Apache HTTP ( apache2.2 ),Tomcat ( tomcat6.0 ),
and so on.
ERS 4.0 includes two sample servers in the ERS-HOME/servers directory,but their names
have changed since 3.1;the new names are test_apache2.2 and test-apache2.2-64.
This means that when you performan in-place upgrade,the old default13 and default20
sample servers are not overwritten.Nor,of course,are any server instances that you created in
3.1.
The other main caveat with the in-place upgrade is that the PHPINI directory changes fromERS
3.1 to ERS 4.0.You will have to replace all pointers to php4.4/with php5.2.This is made
easier because the fixrootpath.pl script can do it for you,as described in a step in the
following procedure.
Upgrading FromERS 3.1 to
ERS 4.0
37
4.0 37
7.2 Upgrading:Typical Steps
The following procedure describes the steps needed to execute an in-place upgrade,using sample
commands.
In the procedure,it is assumed that you installed ERS in/opt/ers31;adjust the procedure for
your particular environment accordingly:
1.Read
Before
You
Install
and
Use
ERS
4.0.2:
Warnings.
2.Stop all running ERS 3.1 Apache HTTP and Tomcat servers.For example,to stop the two
default20 servers:
prompt$ cd/opt/ers31/servers/default20/bin
prompt$./apache_startup.sh stop
prompt$./tomcat_startup.sh stop
3.Make a complete backup of your existing ERS 3.1 installation.For example:
prompt$ cd/opt
prompt$ cp -r ers31 ers31-backup
4.Install ERS 4.0 (both components:ERS httpd and ERS Tomcat) into the same location as
ERS 3.1,following the instructions
Installing
and
Using
ERS
httpd and
Installing
and
Using
ERS
Tomcat.For example,after downloading the two distributions for the two components
into the/opt/ers31 directory:
prompt$ cd/opt/ers31
prompt$ java -jar ers-4.0.0-tomcat-6.0.26-unix-2010-03-19.sfx.jar
prompt$ chmod u+x ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx
prompt$./ers-4.0.2-apache-2.2.15-x86-linux-glibc2-20100326.zip.sfx
At the prompt,"Replace ERS_LICENSE.txt?[y]es,[n]o,[A]ll,
[N]one,[r]ename",select All.
5.Run the fixrootpath.pl Perl script,first without any parameters:
prompt$ perl fixrootpath.pl
6.Then run fixrootpath.pl a second time with the following arguments to change pointers
from php4.4 to php5.2:
Make sure you substitute your actual installation path in place of the one used in the example.
prompt$ perl fixrootpath.pl servers --srcdir=/opt/ers31/php4.4 --dstdir=/opt/ers31/php5.2
7.Optionally remove the php4.4 and snmp2.0 directories (the latter is now part of tools ):
prompt$ rm -rf/opt/ers31/php4.4
prompt$ rm -rf/opt/ers31/snmp2.2
8.For each ERS 3.1 instance in which you want to upgrade Apache HTTP and Tomcat,use the
ers-server.pl Perl script to create a new instance that is configured the same as the old
38 Getting Started With ERS
38
Upgrading FromERS 3.1 to
ERS 4.0
one and has all the same applications deployed,but uses the 2.2 version of Apache HTTP and
the 6.0 version of Tomcat,rather than the older versions of Apache HTTP and Tomcat
included in ERS 3.1.
You use the --migrate option of ers-server.pl to do this,as well as the
--tomcatver and --apachever options as needed for your particular server instance.
The --migrate option requires that you also specify the --javapath option,which
means you must have a JDK installed.You can download a JDK fromthe
SpringSource
ERS
Download page or fromthe Sun Web site (see
Sun
JDK
and
JRE
Downloads.)
For example,the 3.1 sample instance called default20 has both Apache HTTP and
Tomcat configured for it.To create a new instance called new40 that looks just like
default20 but uses the latest versions of Apache HTTP and Tomcat,run the following Perl
script:
prompt$ perl ers-server.pl --server=new40 --migrate=default20 --apachever=2.2 --tomcatver=6.0 --javapath=/opt/java/jdk_1.6.0_18
Note that this command does not change the configuration of the server instance,such as the
Tomcat connectors in conf/server.xml,the deprecated 2.0 Apache HTTP directives,or
any of the security.You must performthis step manually.For information,see:

Upgrading
to
Apache
2.2
from
2.0

Apache
Tomcat
Migration
Guide
Also,the various listen ports are the same in the new instance as in the old one,so you cannot
have both instances running at the same time without manually changing the listen ports in
one of the instances to something different.
9.If you have any Perl or PHP applications deployed in the new server,recompile themin the
new 4.0 environment,because the versions of PHP and Perl have changed.
10.Test the new server by starting the Apache HTTP and Tomcat components.For example:
prompt$ cd/opt/ers31/servers/new40/bin
prompt$./apache_startup.sh start
prompt$./tomcat_startup.sh start
Ensure that you can access the new HTTP and Tomcat servers by navigating in your browser
to the appropriate URL.By default,this is:
http://localhost:8080
Then try out your applications to make sure they are working correctly.
Upgrading FromERS 3.1 to
ERS 4.0
39
4.0 39
40 Getting Started With ERS
40
Upgrading FromERS 3.1 to
ERS 4.0
8.Additional Documentation
This documentation provides basic information about what is contained in ERS 4.0,how to
install ERS http and ERS Tomcat,and how to create new instances and start and stop them.The
documentation does not,however,provide details about configuring and using the core Apache
HTTP and Apache Tomcat components;for that you must go elsewhere,such as the Apache
documentation.
See the following links:
 Apache HTTP Server 2.2 -
http://httpd.apache.org/docs/2.2/
 Apache Tomcat 6.0 -
http://tomcat.apache.org/tomcat-6.0-doc/
 OpenSSL -
http://www.openssl.org/docs/
 PERL -
http://www.perl.com/pub/q/documentation
 Mod_perl -
http://perl.apache.org/
 PHP -
http://www.php.net/docs.php
 Mod_SSL (for Apache HTTP Server 1.3) -
http://www.modssl.org/docs/2.8/
 ASF Buzilla page (search for known bugs in Apache HTTP Server and Apache Tomcat) -
http://issues.apache.org/bugzilla/
 Searchable archive of Apache HTTP Users mail list -
http://marc.theaimsgroup.com/?l=apache-httpd-users&r=1&w=2
 Searchable archive of the Apache Tomcat Users mail list -
http://marc.theaimsgroup.com/?l=tomcat-user&r=1&w=4
Additional Documentation 41
4.0 41
42 Getting Started With ERS
42 Additional Documentation