Migrating Enterprise Ready Server to Pivotal Web Server

This section has information about migrating Enterprise Ready Server (ERS) to to Pivotal Web Server. For information about migrating ERS to Pivotal tc Server, see Migrate an ERS Tomcat Instance to tc Server.

Pivotal currently provides two supported distributions of the open-source Apache HTTPD Server: Pivotal Enterprise Ready Server (ERS) and Pivotal Web Server. Pivotal Web Server is fully supported by Pivotal on common platforms such as Red Hat Enterprise Linux and Microsoft Windows, and support is available for additional, less-common platforms. See Supported Configurations and System Requirements. Contact Pivotal support if your platform is not listed on the Pivotal Web Server product download page.

Pivotal Enterprise Ready Server is deprecated. Pivotal will no longer provide support for HTTPD version 2.0 as of November 30, 2013 and HTTPD version 2.2 as of November 30, 2014. For more information, see VMware Support Policies. Please contact your account manager to learn about converting your existing active ERS licenses to Pivotal Web Server licenses.

This document describes how to migrate Enterprise Ready Server instances to use Pivotal Web Server. Although each product is based on the standard, open-source Apache HTTP Server, there are differences in Pivotal’s implementations. See Differences Between Pivotal Web Server and Pivotal ERS.

Note: This document describes the migration procedure for Enterprise Ready Server based on Apache version 2.4 . You can use the same procedures to migrate from Apache version 2.0, but be aware of additional changes. See Upgrading to 2.4 from 2.2.See Upgrading to 2.2 from 2.0.

Subtopics

Preparing to Migrate

Migration Procedure

Preparing to Migrate

Before you migrate, read the information in this section. You may also want to review Differences Between Pivotal Web Server and Pivotal ERS.

Audit your Configurations

Migration from ERS to Pivotal Web Server is an opportune time for you to examine your Pivotal Web Server configurations for best practices and to update them where necessary. Note the following recommendations:

  • Pivotal recommends that your deployment use the latest security modules and procedures.
  • Pivotal recommends that you use the latest version of plug-in modules.

    Pivotal does not guarantee compatibility of third-party plug-in modules between ERS and Pivotal Web Server. Pivotal recommends that you recompile third-party modules using the Developer build of Pivotal Web Server. You may need to contact your vendor to obtain the latest versions of the modules.

  • Pivotal recommends that you use up-to-date SSL libraries and that you review your SSL cipher configurations and protocol directives. .

  • Pivotal recommends that you use modular configuration files.

    Pivotal recommends that you use the Include directive to add external configurations to your httpd.conf file. When you use the Include directive to reference external configuration files, the httpd.conf file is more readable and your configurations are easier to manage. For example, the following directive references an external configuration file:

    Include conf/extra/httpd-languages.conf 
    

    The default httpd.conf file that is created when you create a new Pivotal Web Server instance contains examples of including external configuration files. The external files are located in the <instance>/conf/extra directory) and are referenced with Include directives in the main httpd.conf file.

For more information, see the Apache HTTPD documentation.

Directory Structure Changes

The directory structure of a Pivotal Web Server installation closely matches a standard Apache 2.4 installation, whereas Pivotal ERS uses a more proprietary file-naming and directory convention.  Migrating to Pivotal Web Server requires that you change configuration files and other scripts in your environment to reflect the new naming conventions. These changes make it easier to integrate third-party extensions with Pivotal Web Server.

Directory Structure and File Name Changes describes the changes in directory structure, configuration file names, and script file names.

Table 1. Directory Structure and File Name Changes

Purpose

Enterprise Ready Server

Pivotal Web Server 6.2

Apache modules

<install_dir>/httpd- .<version>/modules/standard

<install_dir>/httpd- .<version>/modules/covalent

<install_dir>/httpd- .<version>/modules/jakarta

<install_dir>/httpd- .<version>/modules/perl

<install_dir>/httpd- .<version>/modules/php

<install_dir>/httpd- <version>/modules

All modules reside in this single directory. Note that the mod_perl and mod_php modules are not included with Pivotal Web Server.

See Apache Module Changes.

Configuration file

<web_server_instance>/conf/httpsd.conf

<web_server_instance>/conf/httpd.conf

Additional configuration files for various Apache modules are located in the <web_server_instance>/conf/extras subdirectory.

Script for creating new Apache HTTPD server instances

Linux Perl script: <install_directory>/ers-server.pl

Linux symlink to Perl script: <install_directory>/newserver

 

Windows Perl script: <install_directory>\ers-server.pl

Windows PowerShell script: <install_directory>\newserver.ps1

Start-up script

Linux: <web_server_instance>/bin/apache-startup.sh

Linux: <web_server_instance>/bin/httpdctl

 

Windows: <web_server_instance>\bin\apache-startup.bat

Windows PowerShell script: <web_server_instance>\bin\httpdctl.ps1

Tools

<install_directory>/tools/*

<install_directory>/httpd-<version>/bin/*

Apache HTTPD binaries

HTTPD binaries are written to the installation directory. When the server is upgraded, the binaries are overwritten.

HTTPD binaries are written to a directory in the following format:

pivotal-web-server/httpd.- .xx.x-bb.(Where xx.x is the minor version number and bb is either 32 or 64 (for 32-bit or 64-bit versions). When the server is upgraded, the binaries are not overwritten.

Windows service names

ERS <instance name> httpsd

Pivotal httpd <instance name>

Apache Module Changes

The compiled Apache modules for Pivotal Web Server differ from those that are compiled and provided with Enterprise Ready Server. Pivotal recommends you substitute the modules described in Apache Modules. If necessary, you can compile and implement the modules yourself using the Developer build of Pivotal Web Server. To ensure compatibility, Pivotal recommends that you recompile all third-party modules. See Complete Packages and Modules in Pivotal Web Server 6.2 .

Table 2. Apache Modules

Module

Changes in Pivotal Web Server

mod_perl

Pivotal recommends that you use the mod_fcgid module to serve Perl-based applications.

For more information, see: FastCGI rocks mod_perl and FCGID.

mod_php (ERS)

The mod_php module is not included with Pivotal Web Server. Pivotal recommends that you use the mod_fcgid module to serve PHP-based applications.

For more information on the benefits of using mod_fcgid, see Apache with fcgid: acceptable performance and better resource utilization.

mod_snmp (ERS)

Pivotal recommends that you use the Apache BMX framework to provide internal runtime information about your Pivotal Web Server instances to monitoring systems such as [Pivotal Hyperic](http://pubs.vmware.com/vfabric52/topic/com.vmware.vfabric.hyperic.4.6/Pivotal_Hyperic_4.6.html). The following modules are included and are enabled by default:

  • mod_bmx
  • mod_bmx_status
  • mod_bmx_vhost

You can disable this functionality by commenting out the LoadModule directives for the BMX modules in the httpd.conf file.

For more information, see Configure BMX for Monitoring Pivotal Web Server Instances.

mod_bmx (Pivotal Web Server)

mod_bmx is a module in Pivotal Web Server. For a sample configuration, see the following directory in a newly created Pivotal Web Server instance:

<instance>/conf/extras/conf/extra/httpd-info.conf

mod_jk

Although mod_jk is still included with Apache version 2.4 , it has limitations on header fields sizes, cannot be secured with SSL cryptography, and requires separate configuration of proxy worker pools.

Pivotal recommends that you use mod_proxy_balancer, which supports both the ajp protocol used by mod_jk, and also the http and https protocol to legibly decipher the back-end connection stream and secure the back-end connections to Tomcat and tc Server. mod_proxy_balancer is configured using the httpd.conf file syntax.

For mod_proxy configuration options, see http://httpd.apache.org/docs//mod/mod_proxy.html .

For configuration instructions, see Configure Load Balancing Between Two or More tc Runtime Instances.

mod_version

The mod_version module is compiled into Pivotal Web Server. If your ERS httpdsd.conf file contains a LoadModule line, delete the line. The functionality of mod_version is still available in your migrated Pivotal Web Server instances.

For example, delete the following line:

LoadModule version_module <path>

mod_ssl

In ERS instances, you conditionally configure SSL in the httpdsd.conf file by wrapping the LoadModule mod_ssl directive within an <IfDefine SSL> directive. When you start the server with the startssl command, SSL is enabled.

In Pivotal Web Server, you configure SSL in the httpd.conf file by adding the LoadModule ssl_module <path> line without a conditional <IfDefine SSL> directive. When you start the server instance using the start command, the server starts using SSL.

See Startup Script Changes.

Pivotal Web Server now uses Open SSL 1.01 and supports Transport Layer Security (TLS) 1.1 and 1.2.

Startup Script Changes

The name of the script that you use to start Pivotal Web Server instances has changed, and has some new options. In addition, configuration of the multi-process module (MPM) has changed. The startup scripts are located in the bin subdirectory of a server instance.

Table 3. Startup Script Changes

Item

Enterprise Ready Server

Pivotal Web Server 6.2

Startup (control) script name

Linux: <web_server_instance>/bin/apache_startup.sh

Linux: <web_server_instance>/bin/httpdctl

 

Windows: <web_server_instance>\bin\apache_startup.bat

Windows: <web_server_instance>\bin\httpdctl.ps1

Startup (control) script parameters

The following commands are available with the apache_startup script:

  • start
  • startssl
  • stop
  • restart
  • graceful
  • configtest
  • configtestssl

The following commands are available with the httpdctl script:

  • start
  • stop
  • restart
  • gracefulstop
  • graceful
  • status
  • install
  • uninstall
  • configtest

See httpdctl Reference.

Startup script command with SSL enabled

To use SSL in an ERS instance you configure and load an SSL module in the httpsd.conf file, and you use the startssl option when you run the apache_startup script.

To use SSL in a Pivotal Web Server instance, you configure a SSL module in the httpd.conf file and use the regular start option when you run the httpdctl script.

Multi-process module (MPM) configuration

You configure MPM in the startup.properties file.

You configure MPM when you create a Pivotal Web Server instance. Use the following option of the newserver command:

--mpm=worker|prefork|event (The default value is worker.)

See newserver Prompts and Command Reference.

If you need to modify MPM after creating a server, change the value of the default_mpm variable to worker, prefork, or event by changing the following line in the httpdctl script:

default_mpm="worker"

Migration Procedure

To migrate an Enterprise Ready Server installation to a Pivotal Web Server installation:

  1. Install Pivotal Web Server on each host where you will run a Pivotal Web Server instance. See Installing Pivotal Web Server.
  2. Create a new Pivotal Web server instance. See Creating and Using Pivotal Web Server Instances.

    Note: If you specified mpm options in the Enterprise Ready Server startup.properties file, you must specify the --mpm=worker|prefork|event option when creating the new Web server instance. See Startup Scripts and newserver Prompts and Command Reference.

  3. Make a backup copy of the default configuration file from the new Pivotal Web Server instance. The file is in the following location:

    <Web Server instance>/conf/httpd.conf .

  4. Copy the following file from the Enterprise Ready Server instance directory:

    servers/<Web server instance>/conf/httpsd.conf

    into the conf directory of your new Pivotal Web Server instance and rename the file to httpd.conf.

  5. Open the newly-copied httpd.conf configuration file in a text editor and modify all of the paths to point to the new Web server instance. Make sure to change the following paths:

    • ServerRoot property.
    • Apache modules—modify the appropriate LoadModule directives.
    • DocumentRoot property.
    • <Directory> statements.
    • Include directives.
    • Paths to any scripts referenced in the configuration.
    • Paths to any log files referenced in the configuration.
  6. If your Pivotal Web server instance uses any of the Apache modules that have changed, change the LoadModule directives to point to the new modules. Review the changes listed in Apache Modules Changes for any changes that apply to your deployment.

  7. Move static content from the previous Document Root directory to the new Document Root (or change DocumentRoot to point to the correct location. )

  8. Make sure that the user and group name used to run Pivotal Web Server instances exist on the host system. Use the host operating system commands to create the required user and group as indicated in the following table.

    The default user and group names used to run the httpd server have changed.

    Table 4. User and group name changes
    Default Name

    Enterprise Ready Server

    Pivotal Web Server

    Default group name

    nobody

    pwshttpd

    Default user name

    nobody

    pwshttpd

  9. Review the configuration file for any modules that you are not using in your deployment, and remove any LoadModule directives for these modules.

  10. If you are using SSL, move the certificates and key file to your new Pivotal Web Server instance directory. Make sure the permissions allow access to these files. (The root user should have read-only access.)

  11. If a previous instance of Enterprise Ready Server was running on the host computer, make sure you uninstall the obsolete service and install the new Pivotal Web Server instance as a service. See Windows: Start and Stop Pivotal Web Server Instances or Installing Pivotal Web Server Instances as Unix Services.

  12. Start the Pivotal Web Server instance, using the httpdctl script. See Startup Script Changes.

  13. Test the server using a Web browser.