Getting Started With vfabric Enterprise Ready Server (ERS) 4.0

Transcription

2

3 Table of Contents 1. Copyright Notice Overview of vfabric ERS ERS SP2 Patch: Description and Installation Instructions ERS SP1 Patch: Description and Installation Instructions ERS Changes to ERS Packaging and Deployment Complete Packages for ERS Version Contents What's New in ERS 4.0.x? Alternative Packages for ERS Installing and Using ERS httpd Who Should Install ERS 4.0.x? Supported Platforms Before You Install and Use ERS 4.0.3: Warnings Installing ERS Moving the tools/ Tree Manifest of ers apache Packages Example: Installation Walkthrough on Linux Description of the ERS httpd Directory Structure Starting and Stopping ERS httpd Instances Installing and Using ERS Tomcat Platform Prerequisites Installing ERS Tomcat Description of the ERS Tomcat Directory Structure Starting and Stopping ERS Tomcat Instances Creating or Migrating ERS Instances Creating New ERS httpd or ERS Tomcat Instances Migrating Existing ERS httpd Instances Configuring Load Balancing Using ERS httpd Upgrading From ERS 3.1 to ERS Overview of Upgrade Upgrading: Typical Steps Additional Documentation iii

4 iv Getting Started With vfabric ERS

6 2 Getting Started With vfabric ERS 2 Copyright Notice

7 Overview of vfabric ERS 3 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 ERS SP2 Patch: Description and Installation Instructions This section is for users who have already installed ERS 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 SP2 updates the following component: All: OpenSSL 0.9.8t All: libapr and libaprutil for httpd Unix: httpsd.worker and httpsd.prefork for apache Unix: mod_proxy_ajp.so for apache Windows: httpsd.exe for apache Windows: mod_proxy_ajp.so, mod_info.so, mod_unique_id.so, and mod_ftp.so for apache The preceding information applies to httpd 2.2. Because httpd 1.3 and 2.0 are at their end of life, 4.0 3

8 4 Getting Started With vfabric ERS 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 in ERS originally shipped with only IPv4 enabled. All other platforms correctly supported IPv6. For Windows, 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 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 SP2 patch to an existing installation, follow these steps: 1. Download the ERS SP2 patch from the VMware Download Center. The ERS SP2 package name on Unix is ers patch-apache sp2-platform.zip.sfx, where platform refers to a particular Unix platform. On Windows it is ers patch-apache 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 apache apache original 4. Copy the SP2 package to the ERS root directory. For example, if you downloaded the file in your home directory on Linux: prompt$ cp ~/ers patch-apache sp2-platform.zip.sfx. 5. If necessary, change the file mode to make it executable.: prompt$ chmod u+x ers patch-apache sp2-platform.zip.sfx 6. Invoke the file to self-extract the contents: prompt$./ers patch-apache sp2-platform.zip.sfx The archive unpacks all patch files into the current directory. 4 Overview of vfabric ERS

9 Overview of vfabric ERS 5 7. Start your existing ERS httpd instances. See Starting and Stopping ERS httpd Instances. Security Vulnerabilities Fixed in SP2 The following table describes the security vulnerabilities fixed in the SP2 patch release. Table 2.1. Security Fixes in SP2 Security Fix Severity Description mod_setenvif.htaccess privilege escalation (CVE ) 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. mod_proxy reverse proxy exposure (CVE ) Uninitialized SSL 3.0 Padding (CVE ) Moderate Low Resolved with 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 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 4.0 5

10 6 Getting Started With vfabric ERS Security Fix Severity Description 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. mod_log_config crash (CVE ) Scoreboard parent DoS (CVE ) Low Low Fixed in OpenSSL 0.9.8s. 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 A flaw was found in the handling of the scoreboard. An unprivileged child process could cause the parent process 6 Overview of vfabric ERS

11 Overview of vfabric ERS 7 Security Fix Severity Description to crash at shutdown rather than terminate cleanly. Error responses can expose cookies (CVE ) Insecure LD_LIBRARY_PATH handling (CVE ) Moderate Low Resolved with 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 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 ERS SP1 Patch: Description and Installation Instructions This section is for users who have already installed ERS but now want to apply the SP1 patch, which updates some components and fixes a number of security vulnerabilities. ERS SP1 updates the following components: libapr and libaprutil for httpd libapr and libaprutil for httpd

12 8 Getting Started With vfabric ERS httpsd.worker and httpsd.prefork for unix apache and apache httpsd.exe for windows apache and apache mod_proxy_ajp.so for apache Note about Windows: Apache in ERS originally shipped with only IPv4 enabled. All other platforms correctly supported IPv6. For Windows, 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 SP1 Patch To apply the SP1 patch to an existing installation, follow these steps: 1. Download the ERS SP1 patch from the VMware Download Center. The ERS SP1 package name on Unix is ers patch-apache sp1-platform.zip.sfx, where platform refers to a particular Unix platform. On Windows it is ers patch-apache 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 apache apache original 4. Copy the SP1 package to the ERS root directory. For example, if you downloaded the file in your home directory on Linux: prompt$ cp ~/ers patch-apache sp1-platform.zip.sfx. 5. If necessary, change the file mode to make it executable.: prompt$ chmod u+x ers patch-apache sp1-platform.zip.sfx 6. Invoke the file to self-extract the contents: prompt$./ers patch-apache 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. 8 Overview of vfabric ERS

13 Overview of vfabric ERS 9 Security Vulnerabilities Fixed in SP1 The following table describes the security vulnerabilities fixed in the SP1 patch release. Table 2.2. Security Fixes in SP1 Security Fix Severity Description mod_proxy reverse proxy exposure (CVE ) 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.* the remote request may be made which injects a different servername or port. Workaround: Use only well-formed patterns such as RewriteRule ^/(.*) in which the trailing URI slash '/' delimiter following the target machine name is explicit. mod_proxy_ajp remote DoS (CVE ) Moderate 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. 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 4.0 9

14 10 Getting Started With vfabric ERS Security Fix Severity Description 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. Range header remote DoS (CVE ) apr_fnmatch flaw leads to mod_autoindex remote DoS (CVE ) (CVE ) Important Moderate Affected: ERS Apache , ERS Apache , ERS Apache 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 Affected: ALL ERS Apache 2.0 and Apache 2.2 packages. 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 10 Overview of vfabric ERS

15 Overview of vfabric ERS 11 Security Fix Severity Description 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 ERS ERS consists of Apache HTTP Server (and related components) and Apache Tomcat Server 6.0.X. ERS updates the Apache HTTP Server component, with the ers apache package 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 Complete Packages for ERS Version Contents This section lists the complete contents of ERS What's New in ERS calls out components that are new in ERS 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.)

16 12 Getting Started With vfabric ERS Package 1: Apache HTTP Server 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 Apache mod_ftp (derived from and improves upon Covalent mod_ftp) Apache mod_fcgid (a FastCGI invoker) PHP OpenSSL 0.9.8r OpenLDAP mod_jk mod_snmp (enables vhost-level metrics in Hyperic HQ, not included in original 4.0 release) libexpat libapr libaprutil zlib Perl mod_perl 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. 12 Overview of vfabric ERS

17 Overview of vfabric ERS 13 New Components in ERS adds the following new components: Apache HTTP Server PHP , which introduces object oriented development to PHP. modperl 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-apache Caution: Use these server examples for testing and validation only. Apache mod_ftp (derived from and improving upon Covalent mod_ftp). Apache mod_fcgid (a FastCGI invoker). mod_snmp (enables vhost-level metrics in Hyperic HQ). Updates to ERS 3.x Components ERS updates ERS 3.x components as follows: Perl (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 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

18 14 Getting Started With vfabric ERS zts threading for worker MPM. mod_fcgid Implementation of Connector to FastCGI The mod_fcgid distributed with ERS 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 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 packages. The tools/ tree includes a set of ucd-snmp command line tools. 14 Overview of vfabric ERS

19 Overview of vfabric ERS 15 Note See Conflict Between mod_snmp and SNMPCONFPATH Variable. 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 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 Alternative Packages for ERS 4.0 Apache Alternative Add-Ons Apache Package, including FTP (can stand alone): Apache HTTP , mod_jk , Perl 5.8.8, PHP 4.4.9, OpenSSL 0.9.8r, OpenLDAP Note: SNMP/mod_snmp not included in initial release. Apache Package (can stand alone): Apache HTTP , mod_jk , Perl 5.8.8, PHP 4.4.9, OpenSSL 0.9.8r, OpenLDAP Note: SNMP/mod_snmp not included in initial release. Apache Tomcat Alternative Add-Ons (require a JAVA package, or a pre-existing

20 16 Getting Started With vfabric ERS JVM/JDK) Apache Tomcat Overview of vfabric ERS

21 Installing and Using ERS httpd 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 updates the Apache HTTP component with the ers apache 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 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 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 to an ERS 2.x installation 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 System Processor Version Requirements Linux x86 and x86_64 Minimum kernel , equivalent to RHEL 5 or later Important Notes Linux PowerPC Minimum kernel Patch Linux to

22 18 Getting Started With vfabric ERS Operating System Processor Version Requirements , equivalent to RHEL 5 or later Important Notes support IBM's Java 5 release. IBM AIX Power or later Patch AIX to support IBM's Java 5 Solaris Sparc Solaris 10 Solaris x86 and x86_64 Solaris 10 Windows Server (see Important Notes) x86 and x64 Windows Server 2008 Apache 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 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 Do Not Overwrite Updated ers-servers.pl Script ERS 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 component in the same tree as the 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 18 Installing and Using ERS httpd

23 Installing and Using ERS httpd 19 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 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

24 20 Getting Started With vfabric ERS 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 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 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 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 apache x86-linux-glibc2.zip.sfx Invoke the file name at the command line to extract the corresponding platforms: 20 Installing and Using ERS httpd

25 Installing and Using ERS httpd 21 prompt$./ers apache 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 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 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 Manifest of ers apache Packages The immediately available package files included in this release are: ers apache powerpc-ibm-aix-5.3.zip.sfx ers apache ppc-linux-glibc2.zip.sfx ers apache x86-linux-glibc2.zip.sfx ers apache x86-solaris-10.x.zip.sfx

26 22 Getting Started With vfabric ERS ers apache x86-winnt.zip.exe ers apache powerpc-ibm-aix-5.3.zip.sfx ers apache ppc-linux-glibc2.zip.sfx ers apache x86-linux-glibc2.zip.sfx ers apache x86-solaris-10.x.zip.sfx ers apache x86-winnt.zip.exe ers apache powerpc-ibm-aix-5.3.zip.sfx ers apache ppc-linux-glibc2.zip.sfx ers apache x86-linux-glibc2.zip.sfx ers apache 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 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 Example: Installation Walkthrough on Linux To install ERS 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 apache x86-linux-glibc2.zip.sfx. 22 Installing and Using ERS httpd

27 Installing and Using ERS httpd Change file mode to make it executable: prompt$ chmod u+x ers apache x86-linux-glibc2.zip.sfx 7. Invoke the file to self-extract the contents: prompt$./ers apache 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 apache x86-linux-glibc2.zip.sfx ers-server.pl licenses perl php tools apache 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-apache 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 or You will see a certificate warning from https. 12.Enter username spring, with password spring to authenticate to the ERS httpd instance home page

28 24 Getting Started With vfabric ERS 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 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/ apache2.2-64/ php5.2/ php5.2-64/ tools/ perl5.8/ perl5.8-64/ servers/ ERS_LICENSE.txt ers-server.pl fixrootpath.pl (Apache 2.2 binary runtime files only) (64-bit Apache 2.2 binary runtime files only) (PHP binaries for use with Apache mod_php) (64-bit PHP binaries for use with Apache mod_php) (misc tools) (PERL for use with Apache mod_perl) (64-bit PERL for use with Apache mod_perl) (Servers directory contains all deployed data - configs, logs, content, etc) (ERS license file) (Perl script for creating or migrating ERS httpd instances) (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-apache 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 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: 24 Installing and Using ERS httpd

29 Installing and Using ERS httpd 25 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 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 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:

30 26 Getting Started With vfabric ERS 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 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: 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: 26 Installing and Using ERS httpd

31 Installing and Using ERS httpd 27 prompt> cd c:\ers\servers\myserver\bin prompt> apache_startup.bat uninstall

32 28 Getting Started With vfabric ERS 28 Installing and Using ERS httpd

33 Installing and Using ERS Tomcat 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 tomcat 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 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

34 30 Getting Started With vfabric ERS have Perl installed you have two choices: Install a system Perl. Windows users can install ActiveState ActivePerl. 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 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 30 Installing and Using ERS Tomcat

35 Installing and Using ERS Tomcat 31 for both Unix and Windows, where X refers to a specific version, such as ers tomcat 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 tomcat 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 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 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: 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