Getting Started With vFabric Enterprise Ready Server (ERS)

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:

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

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

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

4.0.3 adds the following new components:

ERS 4.0.3 updates ERS 3.x components as follows:

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.

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.

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.

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

	Note
	See Conflict Between mod_snmp and SNMPCONFPATH Variable.

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 .

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.

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.

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

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.

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.

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.

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

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

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