Getting Started With vFabric Enterprise Ready Server (ERS)

vFabric Enterprise Ready Server

4.0

Copyright © 2012 VMware Inc. All rights reserved.


Table of Contents

1. Copyright Notice
2. Overview of vFabric ERS
2.1. ERS 4.0.3 SP2 Patch: Description and Installation Instructions
2.2. ERS 4.0.3 SP1 Patch: Description and Installation Instructions
2.3. ERS 4.0.3
2.4. Changes to ERS Packaging and Deployment
2.5. Complete Packages for ERS 4.0.3 - Version Contents
2.6. What's New in ERS 4.0.x?
2.7. Alternative Packages for ERS 4.0
3. Installing and Using ERS httpd
3.1. Who Should Install ERS 4.0.x?
3.2. Supported Platforms
3.3. Before You Install and Use ERS 4.0.3: Warnings
3.4. Installing ERS 4.0
3.5. Moving the tools/ Tree
3.6. Manifest of ers-4.0.3-apache-2.2.17 Packages
3.7. Example: Installation Walkthrough on Linux
3.8. Description of the ERS httpd Directory Structure
3.9. Starting and Stopping ERS httpd Instances
4. Installing and Using ERS Tomcat
4.1. Platform Prerequisites
4.2. Installing ERS Tomcat
4.3. Description of the ERS Tomcat Directory Structure
4.4. Starting and Stopping ERS Tomcat Instances
5. Creating or Migrating ERS Instances
5.1. Creating New ERS httpd or ERS Tomcat Instances
5.2. Migrating Existing ERS httpd Instances
6. Configuring Load Balancing Using ERS httpd
7. Upgrading From ERS 3.1 to ERS 4.0
7.1. Overview of Upgrade
7.2. Upgrading: Typical Steps
8. Additional Documentation

1. Copyright Notice

Copyright © 2011 VMware Inc. All rights reserved.

VMware Web Site Legal Notice

2. Overview of vFabric ERS

vFabric 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.3 SP2 Patch: Description and Installation Instructions

This section is for users who have already installed ERS 4.0.3 but now want to apply the SP2 patch, which updates some components and fixes a number of security vulnerabilities.

Important: The SP2 patch includes all changes originally published in the SP1 patch. This means that it is not necessary to apply SP1 first.

ERS 4.0.3 SP2 updates the following component:

  • All: OpenSSL 0.9.8t

  • All: libapr 1.4.5 and libaprutil 1.3.12 for httpd-2.2.17

  • Unix: httpsd.worker and httpsd.prefork for apache-2.2.17

  • Unix: mod_proxy_ajp.so for apache-2.2.17

  • Windows: httpsd.exe for apache-2.2.17

  • Windows: mod_proxy_ajp.so, mod_info.so, mod_unique_id.so, and mod_ftp.so for apache-2.2.17

The preceding information applies to httpd 2.2. Because httpd 1.3 and 2.0 are at their end of life, and the fixed issues in 2.2 were of low priority, 1.3 and 2.0 were not updated. If you are using httpd 1.3 or 2.0, VMware recommends that you migrate to httpd 2.2 to mitigate these issues.

Note about Windows: Apache 2.2.17 in ERS 4.0.3 originally shipped with only IPv4 enabled. All other platforms correctly supported IPv6. For Windows, 4.0.3 SP2 updates libapr-1.dll, libhttpd.dll and several other modules to support IPv6 as designed. Any third party module sensitive to the specific level of TCP support may require recompilation, although most modules do not need to be updated. The affected modules which are updated on Windows only include mod_info.so, mod_unique_id.so and mod_ftp.so.

How to Apply the 4.0.3 SP2 Patch

Important: The SP2 patch includes all changes originally published in the SP1 patch. This means that it is not necessary to apply SP1 first. Do not overwrite an installation patched with SP2 with either the original or SP1 product, doing so will revert the fixes from the SP2 package.

To apply the 4.0.3 SP2 patch to an existing 4.0.3 installation, follow these steps:

  1. Download the ERS 4.0.3 SP2 patch from the VMware Download Center.

    The ERS 4.0.3 SP2 package name on Unix is ers-4.0.3-patch-apache-2.2.17-sp2-platform.zip.sfx, where platform refers to a particular Unix platform. On Windows it is ers-4.0.3-patch-apache-2.2.17-sp2-x86-winnt.zip.exe.

  2. Open a command prompt or terminal window and stop any running ERS httpd instances. See Starting and Stopping ERS httpd Instances.

  3. Optionally backup the existing ERS-ROOT/apache2.X directories. For example, on Linux, if the ERS root is /opt/ers:

    prompt$ cd /opt/ers
    prompt$ cp -r apache2.2 apache2.2.original
    prompt$ cp -r apache2.2-64 apache2.2-64.original
  4. Copy the 4.0.3 SP2 package to the ERS root directory. For example, if you downloaded the file in your home directory on Linux:

    prompt$ cp ~/ers-4.0.3-patch-apache-2.2.17-sp2-platform.zip.sfx .
  5. If necessary, change the file mode to make it executable.:

    prompt$ chmod u+x ers-4.0.3-patch-apache-2.2.17-sp2-platform.zip.sfx
  6. Invoke the file to self-extract the contents:

    prompt$ ./ers-4.0.3-patch-apache-2.2.17-sp2-platform.zip.sfx

    The archive unpacks all patch files into the current directory.

  7. Start your existing ERS httpd instances. See Starting and Stopping ERS httpd Instances.

Security Vulnerabilities Fixed in 4.0.3 SP2

The following table describes the security vulnerabilities fixed in the 4.0.3 SP2 patch release.

Table 2.1. Security Fixes in 4.0.3 SP2

Security FixSeverityDescription
mod_setenvif.htaccess privilege escalation (CVE-2011-3607)Low

An integer overflow flaw was found which, when the mod_setenvif module is enabled, could allow local users to gain privileges via a .htaccess file.

Resolved with 2.2.22

mod_proxy reverse proxy exposure (CVE-2011-4317)Moderate

An additional exposure was found when using mod_proxy in reverse proxy mode. In certain configurations using RewriteRule with proxy flag or ProxyPassMatch, a remote attacker could cause the reverse proxy to connect to an arbitrary server, possibly disclosing sensitive information from internal Web servers not directly accessible to the attacker.

Resolved with 2.2.22.

Uninitialized SSL 3.0 Padding (CVE-2011-4576)Low

OpenSSL (prior to version 0.9.8s) failed to clear the bytes used as block cipher padding in SSL 3.0 records. This affects both clients and servers (httpd proxy connections to a backend, and connections from a client) that accept SSL 3.0 handshakes: those that call SSL_CTX_new with SSLv3_{server|client}method or SSLv23{server|client}_method. It does not affect TLS. As a result, in each record, up to 15 bytes of uninitialized memory may be sent, encrypted, to the SSL peer. This could include sensitive contents of previously freed memory.

The httpd server does not use SSL_MODE_RELEASE_BUFFERS and therefore has only a single write buffer per connection. That write buffer is partially filled with non-sensitive, handshake data at the beginning of the connection and, thereafter, only records which are longer any any previously sent record leak any non-encrypted data. This, combined with the small number of bytes leaked per record, serves to limit to severity of this issue.

Fixed in OpenSSL 0.9.8s.

mod_log_config crash (CVE-2012-0021)Low

A flaw was found in mod_log_config. If the '%{cookiename}C' log format string is in use, a remote attacker could send a specific cookie causing a crash. This crash would only be a denial of service if using a threaded MPM.

Resolved with 2.2.22.

Scoreboard parent DoS (CVE-2012-0031)Low

A flaw was found in the handling of the scoreboard. An unprivileged child process could cause the parent process to crash at shutdown rather than terminate cleanly.

Resolved with 2.2.22.

Error responses can expose cookies (CVE-2012-0053)Moderate

A flaw was found in the default error response for status code 400. This flaw could be used by an attacker to expose "httpOnly" cookies when no custom ErrorDocument is specified.

Resolved with 2.2.22.

Insecure LD_LIBRARY_PATH handling (CVE-2012-0883)Low

When merging the apache-2.2/lib product path to an empty LD_LIBRARY_PATH, the administrator could inadvertently cause the current working directory to be searched for DSOs. This could lead to executing user code as root, if an administrator runs apache-startup.sh from an untrusted directory.

Resolved after 2.2.22.


2.2. ERS 4.0.3 SP1 Patch: Description and Installation Instructions

This section is for users who have already installed ERS 4.0.3 but now want to apply the SP1 patch, which updates some components and fixes a number of security vulnerabilities.

ERS 4.0.3 SP1 updates the following components:

  • libapr 1.4.5 and libaprutil 1.3.12 for httpd-2.2.17

  • libapr 0.9.19 and libaprutil 0.9.19 for httpd-2.0.64

  • httpsd.worker and httpsd.prefork for unix apache-2.2.17 and apache-2.0.64

  • httpsd.exe for windows apache-2.2.17 and apache-2.0.64.

  • mod_proxy_ajp.so for apache-2.2.17

Note about Windows: Apache 2.2.17 in ERS 4.0.3 originally shipped with only IPv4 enabled. All other platforms correctly supported IPv6. For Windows, 4.0.3 SP1 updates libapr-1.dll, libhttpd.dll and several other modules to support IPv6 as designed. Any third party module sensitive to the specific level of TCP support may require recompilation, although most modules do not need to be updated. The affected modules which are updated on Windows only include mod_info.so, mod_unique_id.so and mod_ftp.so.

How to Apply the 4.0.3 SP1 Patch

To apply the 4.0.3 SP1 patch to an existing 4.0.3 installation, follow these steps:

  1. Download the ERS 4.0.3 SP1 patch from the VMware Download Center.

    The ERS 4.0.3 SP1 package name on Unix is ers-4.0.3-patch-apache-2.2.17-sp1-platform.zip.sfx, where platform refers to a particular Unix platform. On Windows it is ers-4.0.3-patch-apache-2.2.17-sp1-x86-winnt.zip.exe.

  2. Open a command prompt or terminal window and stop any running ERS httpd instances. See Starting and Stopping ERS httpd Instances.

  3. Optionally backup the existing ERS-ROOT/apache2.X directories. For example, on Linux, if the ERS root is /opt/ers:

    prompt$ cd /opt/ers
    prompt$ cp -r apache2.2 apache2.2.original
    prompt$ cp -r apache2.2-64 apache2.2-64.original
  4. Copy the 4.0.3 SP1 package to the ERS root directory. For example, if you downloaded the file in your home directory on Linux:

    prompt$ cp ~/ers-4.0.3-patch-apache-2.2.17-sp1-platform.zip.sfx .
  5. If necessary, change the file mode to make it executable.:

    prompt$ chmod u+x ers-4.0.3-patch-apache-2.2.17-sp1-platform.zip.sfx
  6. Invoke the file to self-extract the contents:

    prompt$ ./ers-4.0.3-patch-apache-2.2.17-sp1-platform.zip.sfx

    The archive unpacks all patch files into the current directory.

  7. Start your existing ERS httpd instances. See Starting and Stopping ERS httpd Instances.

Security Vulnerabilities Fixed in 4.0.3 SP1

The following table describes the security vulnerabilities fixed in the 4.0.3 SP1 patch release.

Table 2.2. Security Fixes in 4.0.3 SP1

Security FixSeverityDescription
mod_proxy reverse proxy exposure (CVE-2011-3368)Moderate

An exposure was found when using mod_proxy in reverse proxy mode. In certain configurations that specify RewriteRule with the proxy flag with an insecure pattern, such as RewriteRule .* http://server$1, the remote request may be made which injects a different servername or port.

Workaround: Use only well-formed patterns such as

RewriteRule ^/(.*) http://server/$1

in which the trailing URI slash '/' delimiter following the target machine name is explicit.

Affected: Fixed on both 2.0 and 2.2. No fix for 1.3 is planned; customers are encouraged to apply the workaround above or to update to the 2.0 or 2.2 package if this remains a concern.

mod_proxy_ajp remote DoS (CVE-2011-3348)Moderate

A flaw was found when mod_proxy_ajp is used together with mod_proxy_balancer. Given a specific configuration, a remote attacker could send certain malformed HTTP requests, putting a backend server into an error state until the retry timeout expired. This could lead to a temporary denial of service.

Workaround: Use http (mod_proxy_http) balancer members.

Affected: ERS 4.0.3 Apache 2.2.17, ERS 4.0.2 Apache 2.2.15, ERS 4.0.1 Apache 2.2.14

Range header remote DoS (CVE-2011-3192)Important

A flaw was found in the way the Apache HTTP Server handled Range HTTP headers. A remote attacker could use this flaw to cause httpd to use an excessive amount of memory and CPU time via HTTP requests with a specially-crafted Range header. This could be used in a denial of service attack.

Workaround: See http://httpd.apache.org/security/CVE-2011-3192

Affected: ALL ERS Apache 2.0 and Apache 2.2 packages.

apr_fnmatch flaw leads to mod_autoindex remote DoS

(CVE-2011-0419)

(CVE-2011-1928)

Moderate

A flaw was found in the apr_fnmatch() function of the bundled APR library. Where mod_autoindex is enabled, and a directory indexed by mod_autoindex contained files with sufficiently long names, a remote attacker could send a carefully crafted request which would cause excessive CPU usage. This could be used in a denial of service attack.

Workaround: Setting the 'IgnoreClient' option to the 'IndexOptions' directive disables processing of the client-supplied request query arguments, preventing this attack.

Affected: All ERS Apache 2.0 and Apache 2.2 packages.


2.3. ERS 4.0.3

ERS 4.0.3 consists of Apache HTTP Server 2.2.17 (and related components) and Apache Tomcat Server 6.0.X. ERS 4.0.3 updates the Apache HTTP Server component, with the ers-4.0.3-apache-2.2.17 package.

2.4. 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 and Apache Tomcat. 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.5. Complete Packages for ERS 4.0.3 - Version Contents

This section lists the complete contents of ERS 4.0.3. What's New in ERS 4.0.3 calls out components that are new in ERS 4.0.3 and components that are updated from ERS 3.x.

For a standalone Apache HTTP environment, download Package 1. For a standalone Apache Tomcat environment, download package 2. Apache Tomcat is dependent on Java, so you also need to download a Java JDK, such as from the Oracle Sun Web site. (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.17

[Note]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.17

  • Apache mod_ftp 0.9.6 (derived from and improves upon Covalent mod_ftp)

  • Apache mod_fcgid 2.3.6 (a FastCGI invoker)

  • PHP 5.2.17

  • OpenSSL 0.9.8r

  • OpenLDAP 2.3.43

  • mod_jk 1.2.31

  • mod_snmp (enables vhost-level metrics in Hyperic HQ, not included in original 4.0 release)

  • libexpat 2.0.1

  • libapr 1.4.2

  • libaprutil 1.3.10

  • zlib 1.2.3

  • Perl 5.8.8

  • mod_perl 2.0.4

  • 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

Package 2: Apache Tomcat Server 6.0.X

2.6. 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.3

4.0.3 adds the following new components:

  • Apache HTTP Server 2.2.17

  • PHP 5.2.17, 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 from and improving upon Covalent mod_ftp).

  • Apache mod_fcgid 2.3.6 (a FastCGI invoker).

  • mod_snmp (enables vhost-level metrics in Hyperic HQ).

Updates to ERS 3.x Components

ERS 4.0.3 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.8r, libexpat is updated to 2.0.1, libapr to 1.4.2, and libaprutil to 1.3.10.

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.3 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 from third parties, running out-of-process from the 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 from modperl 1.99 RC4 to modperl release 2.0.4, which renamed all modperl symbols from Apache 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.

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.3; they were omitted from the ERS 4.0.0 packages. The tools/ tree includes a set of ucd-snmp command line tools.

Open SSL 0.9.8r 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.8r 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.7. Alternative Packages for ERS 4.0

Apache Alternative Add-Ons

  • Apache 2.0.64 Package, including FTP (can stand alone): Apache HTTP 2.0.64, mod_jk 1.2.31, Perl 5.8.8, PHP 4.4.9, OpenSSL 0.9.8r, OpenLDAP 2.3.39. Note: SNMP/mod_snmp not included in initial release.

  • Apache 1.3.42 Package (can stand alone): Apache HTTP 1.3.42, mod_jk 1.2.31, Perl 5.8.8, PHP 4.4.9, OpenSSL 0.9.8r, 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.33

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.3 updates the Apache HTTP component with the ers-4.0.3-apache-2.2.17 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.17 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]Note

Do not apply ERS 4.0.3 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 system flaws that affect sockets and multi-threaded services for Java similarly affect ERS httpd and its support libraries.

Note: VMware supports only those operating system versions that are still supported by the OS vendor and that have not been designated end-of-life (EOL). For example, the inclusion of "IBM AIX 6.1 or later" in the following tables means that VMware supports vFabric ERS with AIX 6.1 and later versions that are currently available and supported under IBM's policies.

Table 3.1. ERS 4.0.x Platform Requirements

Operating SystemProcessorVersion RequirementsImportant Notes
Linuxx86 and x86_64Minimum kernel 2.6.18, equivalent to RHEL 5 or later 
LinuxPowerPCMinimum kernel 2.6.18, equivalent to RHEL 5 or laterPatch Linux to support IBM's Java 5 release.
IBM AIXPower 5+6.1 or laterPatch AIX to support IBM's Java 5
SolarisSparcSolaris 10 
Solarisx86 and x86_64Solaris 10 
Windows Server (see Important Notes)x86 and x64Windows Server 2008Apache httpd 2.2 is only supported on 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.

See VMware Lifecycle Product Matrix for the End of General Support and End of Technical Guidance dates for various versions of vFabric Enterprise Ready Server.

3.3. Before You Install and Use ERS 4.0.3: Warnings

Make sure you read the sections that follow before you install and use ERS httpd 4.0.3.

Do Not Overwrite Updated ers-servers.pl Script

ERS 4.0.3 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.3 script. It may be worthwhile to give this script a unique name, such as $ mv ers-servers.pl ers-servers-403.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 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]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

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.3 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 platform supports it, or you can obtain an unzip utility to expand the ZIP with additional options.

[Note]Note

If your operating system is 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 filesystem permissions 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 from another 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. On Microsoft Windows, do not install into a path that contains spaces.

    If this is an upgrade from an 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 from vFabric ERS installed in this directory.

  4. Self-extract the files from this 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.3-apache-2.2.17-x86-linux-glibc2.zip.sfx

    Invoke the file name at the command line to extract the corresponding platforms:

    prompt$ ./ers-4.0.3-apache-2.2.17-sparc-sun-solaris-10.x.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]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 transform each occurrence of PRODUCT_ROOT in any script or configuration file in the product tree with the working directory from which 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 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. Optionally, add tools-env.sh to .profile to make permanent.

3.6. Manifest of ers-4.0.3-apache-2.2.17 Packages

The immediately available package files included in this release are:

ers-4.0.3-apache-2.2.17-powerpc-ibm-aix-5.3.zip.sfx
ers-4.0.3-apache-2.2.17-ppc-linux-glibc2.zip.sfx
ers-4.0.3-apache-2.2.17-x86-linux-glibc2.zip.sfx
ers-4.0.3-apache-2.2.17-x86-solaris-10.x.zip.sfx
ers-4.0.3-apache-2.2.17-x86-winnt.zip.exe

ers-4.0.3-apache-2.0.64-powerpc-ibm-aix-5.3.zip.sfx
ers-4.0.3-apache-2.0.64-ppc-linux-glibc2.zip.sfx
ers-4.0.3-apache-2.0.64-x86-linux-glibc2.zip.sfx
ers-4.0.3-apache-2.0.64-x86-solaris-10.x.zip.sfx
ers-4.0.3-apache-2.0.64-x86-winnt.zip.exe

ers-4.0.3-apache-1.3.42-powerpc-ibm-aix-5.3.zip.sfx
ers-4.0.3-apache-1.3.42-ppc-linux-glibc2.zip.sfx
ers-4.0.3-apache-1.3.42-x86-linux-glibc2.zip.sfx
ers-4.0.3-apache-1.3.42-x86-solaris-10.x.zip.sfx

These packages contain:

drwxr-xr-x   13 root     root         4096 apache2.2/
drwxr-xr-x   13 root     root         4096 apache2.2-64/ 1
-rw-r--r--    1 root     root         8985 ERS_LICENSE.txt
-rwxr-xr-x    1 root     root        23266 ers-server.pl
-rwxr-xr-x    1 root     root         5674 fixrootpath.pl
drwxr-xr-x    2 root     root         4096 licenses/
drwxr-xr-x    5 root     root         4096 perl5.8/
drwxr-xr-x    5 root     root         4096 perl5.8-64/ 1
drwxr-xr-x    8 root     root         4096 php5.2/
drwxr-xr-x    8 root     root         4096 php5.2-64/ 1
drwxr-xr-x    3 root     root         4096 servers/
drwxr-xr-x    8 root     root         4096 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 from the operating system, except for s390x.

3.7. Example: Installation Walkthrough on Linux

To install ERS 4.0.3 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.3-apache-2.2.17-x86-linux-glibc2.zip.sfx .
  6. Change file mode to make it executable:

    prompt$ chmod u+x ers-4.0.3-apache-2.2.17-x86-linux-glibc2.zip.sfx
  7. Invoke the file to self-extract the contents:

    prompt$ ./ers-4.0.3-apache-2.2.17-x86-linux-glibc2.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-4.0.3-apache-2.2.17-x86-linux-glibc2.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
    

    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 from https.

  12. Enter username spring, with password spring to authenticate to the ERS httpd instance home page.

  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 from the standard Apache HTTP directory layout in that ERS separates the runtime binaries from the 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 perform all 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 from the 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:

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

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

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:

prompt> cd c:\ers\servers\myserver\bin
prompt> apache_startup.bat uninstall

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.X-tomcat-X.X.X.sfx.jar

where X refers to a specific version, such as ers-4.0.3-tomcat-6.0.33.sfx.jar.

For a summary of the changes in ERS Tomcat, see the following links:

4.1 Platform Prerequisites

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 VMware 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.

  • JVM implementations from HP, IBM and Sun are supported.

  • The ERS Tomcat package requires Perl version 5.8 or later. If your system does not already have Perl installed you have two choices:

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 from the 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, VMware 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 from the VMware Download Center into the ERS home directory you created in the preceding step (such as /opt/ers.)

    The distribution is a self-extracting file named ers-4.0.X-tomcat-X.X.X.sfx.jar for both Unix and Windows, where X refers to a specific version, such as ers-4.0.3-tomcat-6.0.33.sfx.jar.

  5. Change to the ERS home directory and extract the files from the downloaded distribution by executing the JAR file. For example, on Unix:

    prompt$ cd /opt/ers
    prompt$ java -jar ers-4.0.3-tomcat-6.0.33.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 from which 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. On Unix-like systems, if you are installing only ERS Tomcat and are using the system Perl, you must update the ers-server.pl file, changing the first line so that it correctly points to your system Perl location (or whatever is appropriate for your environment). For example, if Perl is located at /usr/bin/perl, change the first line of ers-sever.pl to:

    #!/usr/bin/perl

    After specifying the location of Perl, you can invoke ers-server.pl using this command form:

    ./ers-server.pl {options}

The next steps after installing ERS Tomcat are as follows:

4.3 Description of the ERS Tomcat Directory Structure

The ERS Tomcat directory structure differs slightly from the standard Apache Tomcat directory layout in that ERS separates the runtime binaries from the 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 perform all 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 from the 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 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

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:

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

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 from the 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.

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 from the 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 listen ports are unique for each instance and configure security appropriately.

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 from users, and it then passes them back to the ERS Tomcat instances using a specified load balancing algorithm. Responses from the 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 from the 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.

  • 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
    </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 from the ERS httpd server, and not the ERS Tomcat instance. Thus the details of the ERS Tomcat instance are hidden from the 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>

    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:

    1. 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>
    2. 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, VMware 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:

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.

7. Upgrading From ERS 3.1 to ERS 4.0

This section describes how to upgrade an existing ERS installation from version 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 from how 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. VMware 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 perform an 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 from ERS 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.

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.3: 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.3-tomcat-6.0.33.sfx.jar
    prompt$ chmod u+x ers-4.0.3-apache-2.2.17-x86-linux-glibc2.zip.sfx
    prompt$ ./ers-4.0.3-apache-2.2.17-x86-linux-glibc2.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 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 from the 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 perform this step manually. For information, see:

    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 them in 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.

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: