Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 5 Update 1 Upgrade Guide for UNIX 

Chapter 7
Web Server

This chapter describes how to upgrade Web Server to Java ES 5 Update 1 (Release 5U1): Sun Java System Web Server 7.0 Update 1. It covers both feature upgrades from previous Java ES release families and maintenance upgrades from Java ES 5.

The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5U1. The chapter covers upgrades on both the Solaris and Linux operating systems:

Overview of Web Server Upgrades

This section describes the following general aspects of Web Server that impact upgrading to Java ES 5 Update 1 (Release 5U1):

About Release 5U1 Web Server

Release 5U1 Web Server is a maintenance release that fixes bugs in Release 5 Web Server. Release 5 Web Server was a feature release with respect to Release 4. It had a number of new features and interface enhancements.

Release 5 Web Server introduced a new administrative infrastructure with new administrative tools. The administrative infrastructure includes an Administration Server instance which hosts configuration information for any number of Web Server instances. A new command line interface (wadm) and new graphical user interface are used to create Web Server instances, either locally or on remote computers, and to configure and manage these instances. The new administrative tools require an administrator user name and password.

For more information on the new administrative infrastructure introduced in Release 5 Web Server, see the Web Server 7.0 Administrator's Guide, http://docs.sun.com/doc/819-2629.

These changes in the Web Server administrative interface have a significant impact on upgrade.

Web Server Upgrade Roadmap

Table 7-2 shows the supported Web Server upgrade paths to Java ES Release 5U1. The table applies to both Solaris and Linux operating systems.

Table 7-2 Upgrade Paths to Java ES 5 Update 1 (Release 5U1): Web Server 7.0 Update 1

Java ES Release

Web Server Version

General Approach

Reconfiguration
Required

Release 5

Sun Java System Web Server 7.0

Maintenance upgrade. Apply patches.

None

Release 4

Sun Java System Web Server 6.1 SP5 2005Q4

Feature upgrade. Direct upgrade through a fresh install followed by data migration.

Migration of instance configuration to new instances.

Release 3

Sun Java System Web Server 6 2005Q1 Update 1 SP 4

Feature upgrade. Direct upgrade through a fresh install followed by data migration.

Migration of instance configuration to new instances.

Release 2

Sun Java System Web Server 6 2004Q2 Update 1 SP 2
Platform and Enterprise Editions

Feature upgrade. Direct upgrade through a fresh install followed by data migration.

Migration of instance configuration to new instances.

Release 1

Sun ONE Web Server 6.1 (2003Q4)

Feature upgrade. Direct upgrade not certified, but achieved by performing fresh install followed by data migration.

Migration of instance configuration to new instances.

Pre-dates Java ES releases

 

Feature upgrade. No direct upgrade.

 

Web Server Data

The following table shows the type of data that could be impacted by an upgrade of Web Server software.

Table 7-3 Web Server Data Usage

Type of Data

Location

Usage

Configuration data

Web Server 6.x (Java ES Release 2, 3, and 4): WebServer6-base/https-instanceName/config/

Configuration of Web Server instances

Web Server 7.0 (Java ES Release 5 and 5U1):

Instance Configuration
WebServer7Config-base/https-configName/config1/

Central Configuration Store
Accessed through Web Server Console and through wadm command line interface.

 

1Note that the WebServer7Config-base path is substantially different from the WebServer6-base path.

Web Server Upgrade Strategy

Your strategy for upgrading Web Server generally depends on the many considerations discussed in Chapter 1, "Planning for Upgrades": upgrade path, dependencies between Java ES components, selective upgrade versus upgrade all, multi-instance deployments, and so forth.

This section is to particularize that general discussion to Web Server by presenting issues that might influence your Web Server upgrade plan.

Compatibility Issues

Java ES Release 5U1 Web Server does not introduce any changes in public interfaces and is therefore backwardly compatible with earlier versions in this respect.

Note

If you upgrade Web Server to Release 5U1 and Portal Server is deployed in a Web Server instance, you also have to upgrade Portal Server to Release 5U1.

For more information, see the Web Server 7.0 Update 1 Release Notes, http://docs.sun.com/doc/820-1069/6ncp1ddaa?a=view:

However, the new administrative interfaces introduced in Release 5 Web Server are not backwardly compatible with earlier administrative interfaces. This impacts the upgrade and re-deployment of web applications (including, for example, Java ES components).

In particular, Release 5 and Release 5U1 Web Server use defaults for instance directories and virtual server names different from earlier releases, as shown in the following table.

Table 7-4 Web Server Default Names

Item

Java ES Release 2, 3, and 4
Web Server 6.x Default

Java ES Release 5 and 5U1
Web Server 7.0 Default

Configuration name

 

hostName.domainName

Instance directory path

WebServer6-base/
https-hostName.domainName

WebServer7Config-base
https-hostName.domainName

Virtual server name

https-hostName.domainName

hostName.domainName

Web Server Dependencies

Web Server has dependencies on the following Java ES components:

Dual Upgrade

Dual upgrades, in which both Web Server and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Software) can be performed using the in-place operating system upgrade approach:

  1. Back up existing Web Server data.

    2. See Web Server Data for the location of essential data.

  2. Upgrade the operating system.

    3. The upgrade leaves the existing file system in place.

  3. Upgrade to Release 5U1 Web Server.

    4. See the appropriate section of this chapter, depending on upgrade path.

Upgrading Web Server from Java ES 5

This section includes information about upgrading Web Server from Java ES 5 (Release 5) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:

Introduction

When upgrading Release 5 Web Server to Release 5U1, consider the following aspects of the upgrade process:

Release 5 Web Server Upgrade

This section describes how to perform an upgrade of Web Server from Java ES Release 5 to Release 5U1 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:

Pre-Upgrade Tasks

Before you upgrade Web Server software you should perform the following tasks:

Verify Current Version Information

You can verify the current version of Web Server using the following command:

WebServer7-base/bin/wadm --version

Table 7-5 Web Server Version Verification Outputs

Java ES Release

Web Server Version Number

Release 2

6.1SP2

Release 3

6.1SP4

Release 4

6.1SP5

Release 5

7.0

Release 5U1

7.0U1

Upgrade Web Server Dependencies

It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Release 5U1 Web Server has no hard upgrade dependencies, but upgrade is only certified when shared components have also been upgraded.

Back Up Web Server Data

The Web Server upgrade to Release 5U1 does not modify Release 5 configuration data. There is no need to back up current data.

Obtain Required Configuration Information and Passwords

You will have to log in as superuser to perform the upgrade and the user account performing migration should have permission to access the existing Web Server installation directories.

Upgrading Release 5 Web Server (Solaris)

This section discusses considerations that impact the upgrade procedure for Web Server, followed by a description of the procedure itself.

Upgrade Considerations (Solaris)

The upgrade of Web Server software to Java ES Release 5U1 takes into account the following considerations:

Upgrade Procedure (Solaris)

The procedure documented below applies to Web Server instances residing locally on the computer where the upgrade is taking place.

  1. Log in as root or become superuser.

    2. su -

  2. Shut down the Release 5 Web Server instances.

    3. WebServer7Config-base/https-configName/bin/stopserv

    If the server was stopped properly then you will see a message "server has been shutdown".

  3. Make sure you have upgraded any Java ES components upon which Web Server has hard upgrade dependencies (see Upgrade Web Server Dependencies).
  4. Obtain the latest Web Server upgrade patches, based on Table 7-6.

    5. To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.

  5. Apply the appropriate Web Server core and, if needed, localization patches in Table 7-6, in that order.

    6. patchadd /workingDirectory/patch_ID

    Be sure to consult the README.patch_ID file for additional patch installation instructions.

  6. Confirm that the patch upgrades were successful:

    7. showrev -p | grep patch_ID

    The output should return the versions of patch IDs applied in Step 5.

  7. Restart the Web Server instances

    8. WebServer7Config-base/https-configName/bin/startserv

Upgrading Release 5 Web Server (Linux)

This section discusses considerations that impact the upgrade procedure for Web Server, followed by a description of the procedure itself.

Upgrade Considerations (Linux)

The upgrade of Web Server software to Java ES Release 5U1 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that the Linux Release 5U1 upgrade patches differ from the Solaris patches.

The Release 5U1 Web Server upgrade patches for Linux OS are shown in the following table:

Table 7-7 Patches1 to Upgrade Web Server on Linux 

Description

Patch ID and RPM names

Web Server core

125439-10

  • sun-webserver7-7.0-113.i386
  • sun-webserver7-cli-7.0-113.i386
  • sun-webserver7-dev-7.0-113.i386

Web Server localization

126333-02

  • sun-webserver7-l10n-7.0-12.i386.rpm
  • sun-webserver7-cli-l10n-7.0-12.i386.rpm

1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.

Upgrade Procedure (Linux)

The procedure documented below applies to Web Server instances residing locally on the computer where the upgrade is taking place.

Caution

An upgrade from Release 5 to Release 5U1 on Linux cannot easily be rolled back.

  1. Log in as root or become superuser.

    2. su -

  2. Shut down the Release 5 Web Server instances.

    3. WebServer7Config-base/https-configName/bin/stopserv

    If the server was stopped properly then you will see a message "server has been shutdown".

  3. Make sure you have upgraded any Java ES components upon which Web Server has hard upgrade dependencies (see Upgrade Web Server Dependencies).
  4. Obtain the latest Web Server upgrade patches, based on Table 7-7.

    5. To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.

  5. Apply the core patch for Web Server in Table 7-7.

    6. cd /workingDirectory/patch_ID
    ./installpatch

    If installpatch reports any errors, you will need to resolve the reported errors and run installpatch again.

    Be sure to consult the README.patch_ID file for additional patch installation instructions.

  6. Apply the localization patch for Web Server in Table 7-7.

    7. rpm -Fvh *.rpm

    Be sure to consult the README.patch_ID file for additional patch installation instructions.

  7. Confirm that the patch upgrades were successful.

    8. rpm -qa | grep sun-webserver7

    The new version numbers of the RPMs should be returned.

  8. Restart the Web Server instances that were stopped in Step 2.

    9. WebServer7Config-base/https-configName/bin/startserv

Verifying the Upgrade

You can verify successful upgrade of Web Server by starting the Web Server instance as follows:

WebServer7-base/bin/wadm --version

See Table 7-5 for output values.

Post-Upgrade Tasks

There are no post-upgrade tasks beyond the steps described in Upgrade Procedure (Solaris) and Upgrade Considerations (Linux).

Rolling Back the Upgrade (Solaris)

This section describes the Release 5U1 upgrade rollback procedure for Web Server on the Solaris platform.

  1. Log in as root or become superuser.

    2. su -

  2. Stop all running instances of Web Server.

    3. WebServer7Config-base/https-configName/bin/stopserv

  3. Remove the patches in Table 7-6.

    4. patchrm patch_ID

  4. Restart the Web Server instances that were stopped in Step 2.

    5. WebServer7Config-base/https-configName/bin/startserv

Rolling Back the Upgrade (Linux)

This section describes the Release 5U1 upgrade rollback procedure for Web Server on the Linux platform. There is no automated rollback procedure for Linux patches, so the recommended approach is to manually overwrite the Release 5U1 RPMs with the Release 5 RPMs, as described below.

  1. Log in as root or become superuser.

    2. su -

  2. Stop all running instances of Web Server.

    3. WebServer7Config-base/https-configName/bin/stopserv

  3. Check the revision numbers of Web Server RPMs.

    4. rpm -qa | grep sun-webserver7

    The updated RPMs should be those listed in Table 7-7.

  4. Check to see if the RPMs have been relocated from their default location.

    5. rpm -q --queryformat '%{INSTALLPREFIX}' rpmName

    where rpmName is the unique name of the RPM (for example, the values sun-ebserver7-* shown in Table 7-7). The command returns a prefixValue as a path to the installed RPM.

  5. Reinstall Release 5 RPMs from the Java ES 5 distribution.

    6. (If you are rolling back to a post-Release 5 sustaining patch, rather than to Release 5, reinstall the RPMs from that patch.)

    rpm -Uvh --force [--prefix prefixValue] *.rpm

    The --force option will allow the command to overwrite later packages of the same name. The --prefix option is not required unless the RPMs have been relocated. (If only a subset of the RPMs had been relocated, use individual file names as command arguments rather than *.rpm.)

  6. Start the Web Server instances that were stopped in Step 2.

    7. WebServer7Config-base/https-configName/bin/startserv

Upgrading Web Server from Java ES Release 4

This section includes information about upgrading Web Server from Java ES 2005Q4 (Release 4) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:

Introduction

When upgrading Java ES Release 4 Web Server to Release 5U1, consider the following aspects of the upgrade process:

Release 4 Web Server Upgrade

This section describes how to perform an upgrade of Web Server from Java ES Release 4 to Release 5U1 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:

Pre-Upgrade Tasks

Before you upgrade Web Server software you should perform the following tasks:

Verify Current Version Information

You can verify the current version of Web Server by running the Web Server instance server with the -version option:

WebServer6-base/https-hostName.domainName/start -version

See Table 7-5 for version output values.

Upgrade Web Server Dependencies

It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. However, all shared components required by Web Server (see Table 1-10) are upgraded automatically by the Java ES installer when you perform an upgrade of Web Server to Release 5U1.

Back Up Web Server Data

The Web Server upgrade from Release 4 to Release 5U1 does not modify the existing configuration data; it is left intact. There is no need to back up current data.

Obtain Required Configuration Information and Passwords

You will have to log in as superuser to perform the upgrade and the user account performing migration should have permission to access the existing Web Server installation directories.

Upgrading Release 4 Web Server

This section discusses considerations that impact the upgrade procedure for Web Server followed by a description of the procedure itself.

Upgrade Considerations

When upgrading Release 4 Web Server software to Release 5U1 you should take into account the following considerations:

Upgrade Procedure

The procedure documented below applies to all Web Server instances corresponding to the same installed Web Server image on the computer where the upgrade is taking place.

  1. Log in as root or become superuser.

    2. su -

  2. Stop all running instances of Web Server and the Administration Server.

    3. WebServer6-base/https-instanceName/stop
    WebServer6-base/https-admserv/stop

  3. Perform a fresh install of Release 5U1 Web Server.

    4. Perform the following steps:

    1. Launch the Java ES installer.

      2. cd Java ES Release 5U1 distribution/os_arch
      ./installer

      where os_arch matches your platform, such as Solaris_sparc. (Use the installer -nodisplay option for the command line interface.)

      After the Welcome and License Agreement pages are displayed, you will be presented with a component selection page. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of "upgradable.")

    2. Select Web Server in the component selection page.
    3. Specify an installation path different from that of Release 4 Web Server.
    4. Choose to Configure Now or Configure Later.
      • If you choose Configure Now, go to Step e.
      • If you choose Configure Later, go to Step f.
    5. If you choose to Configure Now, the Java ES installer offers two choices:
      • Configure Administration Instance as Administration Server
        Use this choice on the computer that will host the Administration Server that, among other administrative tasks, is required to perform migration of Release 4 instances to Release 5U1.
      • Configure Administration Instance as Administration Node
        Use this choice on a computer that will host a Web Server instance remote from the Administration Server. The administration instance is configured as a node agent that interacts with the Administration Server.
      • Specify the configuration values requested.

        • You are asked for the host name, HTTP port, admin user name and admin password.

      • Confirm your installation choices.

        • Web Server packages will be installed and an install summary displayed.

        The Java ES installer will create a default configuration named hostName.domainName and a corresponding Web Server instance.

      • Exit the Java ES installer and go to Step 5.
    6. If you choose to Configure Later, the Java ES installer will create a configureServer script that you run in Step IV.
      1. Confirm your installation choices.

        2. Web Server packages will be installed and an install summary displayed.

      2. Exit the Java ES installer.
      3. Set values in the WebServer7-base/setup/WSInstall.properties file.

        4. Provide values to all the required (non-optional) properties in the following table.

        Table 7-8 WSInstall.properties Values  

        Property

        Description

        WS_DOCROOT

        (Optional) Document location which can host web content files

        WS_SERVER_NAME

        Host name which can be used to serve HTTP requests

        WS_SERVER_USER

        Runtime unix user. Valid values can be root, any valid UNIX user, or webservd (default).

        WS_HTTP_PORT

        Instance port which can be used to listen for HTTP requests

        WS_ADMIN_SSL_PORT

        Admin SSL port

        WS_ADMIN_HOST

        Admin host name for admin server tasks

        WS_CONFIG_NAME

        Config name for this host. This value can be the same value as provided in WS_SERVER_NAME

        WS_ADMIN_SERVER_USER

        Admin server runtime UNIX user. Valid values: 'root' or the same user as WS_SERVER_USER

        WS_ADMIN_LOGIN_USER

        Admin server login user name

        WS_ADMIN_LOGIN_PASSWORD

        Admin server login password

        WS_ADMIN_HTTP_PORT

        (Optional) Admin Non SSL port. Default: 8800

        WS_START_ON_BOOT

        (Optional) Start on boot feature (true/false). True will allow server instance and its admin server to auto start after system reboot. Default: false

        WS_64BIT_INSTALL

        (Optional) Server runtime mode (true/false). True will configure the server in 64 bit mode. (Only for Solaris). False will configure the server in 32 bit mode. (Only for Solaris) Default: false

        WS_ADMIN_IS_SERVER_MODE

        (Optional) Admin configuration mode. (true/false). True will configure server in admin server mode. False will configure server in admin agent mode. Default: true

        WS_REGISTER_ADMIN_AGENT

        (Optional) Remote agent registration. (true/false). This is required only if WS_ADMIN_IS_SERVER_MODE is set to false. True will require you to provide the remote admin server host for registration. Default: true

        WS_AGENT_SSL_PORT

        (Optional) Admin agent SSL port. This is required only if WS_ADMIN_IS_SERVER_MODE is set to false

        WS_AGENT_HOST=

        (Optional) Admin agent host name. This is required only if WS_ADMIN_IS_SERVER_MODE is set to false

      4. Run the configureServer script.

        5. WebServer7-base/setup/configureServer
        -inputfile         WebServer7-base/setup/WSInstall.properties
        -logfile         WebServer7-base/setup/WSInstall.log
        -verbose

        The configureServer script will create a default configuration named hostName.domainName and a corresponding Web Server instance.

  4. Apply the latest Web Server maintenance patches, if any.
    1. Check if there have been any Web Server point fixes subsequent to Release 5U1.

      2. Periodically obtain the latest patches as described in Accessing Java ES Patches and compare them to the Release 5U1 patch revision numbers shown in Table 7-6 (Solaris) or Table 7-7 (Linux).

      If you are using Sun Connection on the Solaris platform, you are automatically notified of new patches for Java ES components installed on your computer.

    2. Apply the appropriate Web Server core and, if needed, localization patches in that order.

      3. On Solaris:
      patchadd /workingDirectory/patch_ID

      If you are using the accumulated patch cluster on the Solaris platform, the install_cluster script will apply any Java ES patches needed on your computer.

      On Linux:
      cd /workingDirectory/patch_ID
      ./installpatch

      Be sure to consult the README.patch_ID file for additional patch installation instructions.

    3. Confirm that the patch upgrades were successful:

      4. On Solaris:
      showrev -p | grep patch_ID

      On Linux:
      rpm -qa | grep sun-webserver7

      The output should return the appropriate patch IDs or version numbers.

  5. Start the Web Server Administration Server service.

    6. WebServer7Config-base/admin-server/bin/startserv

  6. Migrate Release 4 Web Server instance configurations to Release 5U1 configurations.

    7. Note

    When performing the migration of a default Release 4 instance configuration to Release 5U1, there are three approaches you can take, each of which results in a different configuration name. See Migration of a default Release 4 instance configuration.

    You can use either the command-line (wadm) or graphical user interface administration tools (log in to the Web Server Admin Server GUI). The steps that follow are based on the wadm command-line interface.

    For example, to migrate an instance named myinstance to a new configuration:

    WebServer7-base/bin/wadm migrate-server --user=admin
    --host=localhost --server-root=/opt/SUNWwbsvr --instance=https-myinstance --config=newconfigname

    The full command syntax is as follows:

    WebServer7-base/bin/wadm migrate-server

    --user=    admin-user [--password-file=admin-pswd-file] [--host=admin-host]
    [--echo] [--rcfile=rcfile] [--no-prompt] [--verbose]

    [--search-collection-copy-path=    searchCollectionPath]
    [--log-dir=    directory] --serverroot=path
    ([--all] | [--instance=https-instanceName] [--config=newconfigName])

    The first set of command options, above, are common to all wadm commands, and are documented in Table 7-9, below. The second set of command options are specific to the migrate-server command and are documented in Table 7-10.

    Invoking wadm with only the first set of command options places you within the wadm command shell. Invoking commands within this shell does not require that you specify the common options again.

    If you invoke the full wadm commands from outside the shell, you have to specify, at minimum, the --user and --host options. (If you omit the --password-file option, you will be prompted for a password, and if you omit other options, the default value will be assumed.) However, for commands used to illustrate procedures in this chapter, the --user and --host options are not included for the sake of simplicity.

    By default, wadm uses the SSL protocol at port 8989.

    For full information on wadm commands and options, see the Web Server 7.0 CLI Reference Manual, http://docs.sun.com/doc/819-3283.

    Table 7-9 wadm Common Command Options 

    Option

    Description

    user

    Authorized Web Server administrative user ID.

    password-file

    File containing the password to authenticate the administrative user to the Administration Server. The password file must contain a line WADM_PASSWORD=password. If this option is not specified in the command, you will be prompted for the password.

    host

    Name of the computer where the Administration Server is running. Default: localhost.

    echo

    Setting this option to true will echo the command line on standard output before executing the command. Default: false

    interactive

    If this option set to true, the required password options are prompted. Default: true.

    rcfile

    Startup file to be used to load at the start of wadm. Default: ~/.wadmrc.

    no-prompt

    If this option set to true, the command will never ask for any user input under any circumstances. For example, the command will simply error out if invoked with missing parameters rather than asking for and waiting for user input.You might want to set to true when using wadm commands with a shell script so that the command always returns rather than wait for user input. Default: false.

    verbose

    If set to true, verbose listing is displayed. Default: false.

    Table 7-10 wadm migrate-server Command Options and Operands 

    Option/Operand

    Description

    search-collection-
    copy-path

    Specifies the path to which search collection index files will be copied when migrating search collections. The following migration scenarios are possible:

    If the Web Server 6.x search collection path is outside the Web Server 6.x instance, then the migrated search collection path will point to the Web Server 6.x search collection path, and this option will be disregarded.

    If the Web Server 6.x search collection path is within the Web Server 6.x instance, and a valid path is specified for this option, then the search collection index files will be copied to the following directory: searchCollectionPath/configName/virtualServerName/collectionName. If the specified path is not valid, an error message will be logged.

    If the Web Server 6.x search collection path is within the Web Server 6.x instance but no path is specified for this option, then the search collection index files will not be copied. A message will be written to the migration log asking the user to manually copy the search collection index files using the wadm add-documents command. In this case, the migrated search collection path will be the following: WebServer7Config-base/https-configName/config/collections/ virtualServerName/collectionName.

    log-dir

    The location of the migration log.
    Default: WebServer7Config-base/admin-serv/logs

    serverroot

    Installation location (directory) where Web Server 6.x version is installed: same as WebServer6-base.

    all

    If set to true, all Web Server 6.x instance configurations are migrated to Web Server 7.0 configurations of the same names as the instances. If a configuration of that name already exists, instanceName-1 is used as the configuration name. Default: false.

    instance

    If instance configurations are to be individually migrated (all=false), Name of the Web Server 6.x instance configuration to be migrated (in the form:https-instanceName). The default Web Server 6.x instance name is hostName.domainName

    config

    Name of the configuration to which the specified Web Server 6.x instance configuration is to be migrated. The default is to use the instanceName of the Web Server 6.x instance configuration. However, if a configuration of that name already exists, the command will append an integer to the name. This is a likely scenario if the default Web Server 6.x instance configuration is being migrated.

    In using the migrate-server command, please keep in mind the following considerations:

    • If you want to migrate multiple Release 4 instance configurations, you can either run the migrate-server command multiple times with different --instance values and corresponding --config arguments, or use the --all option to migrate them all at once.
    • For every invocation of the migrate-server command, the migration will create a log file of the following name in a directory specified by the --log-dir option (or in the default WebServer7Config-base/admin-server/logs directory):

      MIGRATION_yyyymmddhhmmss.log

      If you select the --all option, then the log file will store migration information for all migrated instances.

  7. Create Release 5U1 Web Server instances.

    8. You must create a new Release 5U1 instance for each Release 4 instance configuration migrated in Step 6.

    1. Before creating a new instance, verify the migration log and fix any issues in the migrated configuration.
    2. Run the create-instance command.

      3. WebServer7-base/bin/wadm create-instance
      --config=      configName nodehost1 [nodehost2 ...nodehostN]

      Common command options are documented in Table 7-9. Options specific to the create-instance command are documented in the following table.

      Table 7-11 wadm create-instance Command Options and Operands

      Option/Operand

      Description

      config

      The name of the Release 5U1 configuration that the instance should point to.

      nodehost

      Name of the computer on which the instance is being created. You can specify multiple computers as a space-separated list of hostName.domainName, thereby creating multiple identical instances.

      The create-instance command creates an instance directory at WebServer7Config-base/https-configName
      on the specified nodes and deploys the configuration to the corresponding instance directories.

  8. Start each Release 5U1 instance.

    9. WebServer7Config-base/https-configName/bin/startserv

    The startserv script is created when the instance is created. If the instance starts without any problem, then you see a message saying "successful server startup." The default URL for the instance will be displayed.

Verifying the Upgrade

You can verify the upgrade of Web Server to Release 5U1 by performing the following steps:

  1. Check the newly created migration log file for any ERROR messages.

    2. If needed, make manual changes (see Post-Upgrade Tasks).

  2. Verify the Release 5U1 Web Server instances.

    3. From a web browser access the following URL and make sure you get the welcome page:

    http://hostName.domainName:port

    where the fully-qualified host name and port correspond to each instance.

  3. Run the Web Server instance with the -version option:

    4. WebServer7Config-base/https-configName/bin/startserv -version

    See Table 7-5 for version output values.

Post-Upgrade Tasks

The main post-upgrade task concerns performing manual migration, if needed, of certain Release 4 data. This is data normally associated with one or more virtual servers configured for Release 4 and specified in the server.xml configuration file.

Please note the post-upgrade procedures to address the following situations:

Migrating Web Server 6.1 docroot content
  1. Copy the Web Server 6.1 docroot content to wherever you want.
  2. Update the new document root path using the following command:

    3. WebServer7-base/bin/wadm set-virtual-server-prop
    --config=    configName --vs=virtualServerName
    document-root=    new docroot path

    Common command options are documented in Table 7-9. Options specific to the set-virtual-server-prop command are documented in the following table.

    Table 7-12 wadm set-virtual-server-prop Command Options and Operands

    Option/Operand

    Description

    config

    Name of the Release 5U1 configuration for which the new document root path is being set.

    vs

    The name of the virtual server to which the migrated document root corresponds.

    document-root

    The path to the new document root directory.

  3. Redeploy the configuration to the relevant Web Server instances.

    4. WebServer7-base/bin/wadm deploy-config
    [--force] [--restart] [--no-reconfig]
    configName

    Common command options are documented in Table 7-9. Options specific to the deploy-config command are documented in the following table.

    Table 7-13 wadm deploy-config Command Options and Operands

    Option/Operand

    Description

    force

    If true, forces the overwriting of an instance configuration that has been manually modified since the previous configuration deployment. Default: false

    restart

    If true, running instances will be restarted to pick up configuration settings in the deployed configuration. Default: false

    no-reconfig

    if true, running instances will not pick up configuration settings in the deployed configuration until the instance is restarted. Default: false

    configName

    Name of the Release 5U1 configuration that is being deployed to a Web Server instance whose instance name corresponds to the configuration name.

Migrating webdav collection information

No extra manual migration needed. Just updating the docroot path is enough.

Migrating Log files

Copy these files to a known location if you want to save them (otherwise they will be deleted should you remove the Release 4 installation).

Migrating 3rd party NSAPI plug-ins
  1. Copy the library files from their Release 4 location as follows:
    1. Create a new plug-in directory:

      2. WebServer7-base/plugins/plug-inName

    2. Copy the 3rd party library files to the new directory.
  2. Export the magnus.conf and obj.conf configuration files to a temporary working directory.

    3. WebServer7-base/bin/wadm get-config-file --config=configName
    magnus.conf > /    workingDirectory/magnus.conf

    WebServer7-base/bin/wadm get-config-file --config=configName
    obj.conf > /    workingDirectory/obj.conf

    Common command options are documented in Table 7-9.

  3. Modify magnus.conf and obj.conf files as specified in 3rd party NSAPI plugin documentation.
  4. Import the magnus.conf and obj.conf configuration files from the temporary directory.

    5. WebServer7-base/bin/wadm set-config-file --config=configName
    --upload-file=/    workingDirectory/magnus.conf magnus.conf

    WebServer7-base/bin/wadm set-config-file --config=configName
    --upload-file=/    workingDirectory/obj.conf obj.conf

    Common command options are documented in Table 7-9.

  5. Redeploy the modified configuration to the relevant Web Server instances.

    6. WebServer7-base/bin/wadm deploy-config
    [--force] [--restart] [--no-reconfig]
    configName

    Command options are documented in Table 7-13.

Changing the search collection document root

The migrate-server command has an option for migrating search collection information, however you might want to change the search collection document root, as follows:

  1. If the document root for the search collection is different from that used for Release 4, use the following command to set the document root for the search collection:

    2. WebServer7-base/bin/wadm set-search-collection-prop --config=configName --vs=virtualServerName --collection-name=searchCollectionName document-root=new docroot path for the search collection

    Common command options are documented in Table 7-9. Options specific to the set-search-collection-prop command are documented in the following table.

    Table 7-14 wadm set-search-collection-prop Command Options and Operands

    Option/Operand

    Description

    config

    Name of the Release 5U1 configuration for which the document root of the search collection is being set.

    vs

    The name of the virtual server to which the search collection corresponds.

    collection-name

    The name of the search collection for which a new document root path is being set.

    document-root

    The path to the new document root directory for the search collection.

  2. Redeploy the configuration to the relevant Web Server instances.

    3. WebServer7-base/bin/wadm deploy-config
    [--force] [--restart] [--no-reconfig]
    configName

    Command options are documented in Table 7-13.

Customizing command-line scripts

If scripts such as startsvr, startsvr.bat, stopsvr, stopsvr.bat, restart, reconfig, and reconfig.bat have been customized, then you will have to perform the same customizations on the Release 5U1 default scripts, located in the following directory: WebServer7-base/bin.

Rolling Back the Upgrade

Release 4 Web Server was left intact by the fresh installation of Release 5U1 and subsequent migration of Web Server instance configurations. Hence, the rollback of Release 5U1 Web Server consists of the following steps for reverting back to Release 4.

  1. Log in as root or become superuser.

    2. su -

  2. Stop all running Web Server instance one by one.

    3. WebServer7Config-base/https-configName/bin/stopserv

    If the server was stopped properly then you will see a message "server has been shutdown".

  3. Remove the Release 5U1 Web Server installation.

    4. You have to remove all Release 5U1 instances and migrated configurations:

    1. Delete all Release 5U1 instances.

      2. WebServer7-base/bin/wadm delete-instance --user ...     --config=configName hostName.domainName

    2. Delete all Release 5U1 configurations.

      3. WebServer7-base/bin/wadm delete-config --user ... configName

  4. Restart the Web Server instances that were stopped when upgrading Web Server, as described in Upgrade Procedure.

Upgrading Web Server from Java ES Release 3

The procedure for upgrading Java ES 2005Q1 (Release 3) Web Server to Release 5U1 is the same as that for upgrading Release 4 Web Server to Release 5U1.

To upgrade Release 3 Web Server to Release 5U1, use the instructions in Upgrading Web Server from Java ES Release 4, except substitute Release 3 wherever Release 4 is referenced.

Upgrading Web Server from Java ES Release 2

Java ES certifies indirect upgrade from Java ES 2004Q2 (Release 2) Web Server by first upgrading to Release 5 Web Server (as documented in the Java Enterprise System 5 Update 1 Upgrade Guide for UNIX, http://docs.sun.com/doc/819-6553:) and then upgrading from Release 5 Web Server to Release 5U1Web Server (as documented in Upgrading Web Server from Java ES 5).

However, direct upgrade is also supported. The procedure for directly upgrading Release 2 Web Server to Release 5U1 is the same as that for upgrading Release 4 Web Server to Release 5U1, with the exception that the pre-upgrade tasks should include the upgrading to Release 5U1 of all shared components (see Table 1-10).

To directly upgrade Release 2 Web Server to Release 5U1, use the instructions in Upgrading Web Server from Java ES Release 4, except substitute Release 2 wherever Release 4 is referenced.

Note

If you are upgrading from Release 2 Web Server on the Linux platform, then you will have to perform a dual upgrade, in which both Web Server and the operating system are upgraded (Release 5U1 Web Server is not supported on RHEL 2.1). See Dual Upgrade for more information.



Previous      Contents      Index      Next     

Part No: 820-2510-10
November 2007.   Copyright 2004 Sun Microsystems, Inc. All rights reserved.