Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 5 Upgrade Guide for UNIX 

Chapter 7
Web Server

This chapter describes how to upgrade Web Server to Java ES 5 (Release 5): Sun Java System Web Server 7.0.

The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5. 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 (Release 5):

About Java ES Release 5 Web Server

Java ES Release 5 Web Server represents a major release with respect to Release 4. It has a number of new features and interface enhancements.

Release 5 Web Server has 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, 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 5. The table applies to both Solaris and Linux operating systems.

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

Java ES Release

Web Server Version

General Approach

Reconfiguration
Required

Release 4

Sun Java System Web Server 6.1 SP5 2005Q4

Direct upgrade:
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

Direct upgrade:
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

Direct upgrade:
Fresh install followed by data migration

Migration of instance configuration to new instances.

Release 1

Sun ONE Web Server 6.1 (2003Q4)

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

 

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):

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 5 Web Server does not introduce any changes in public interfaces and is therefore backwardly compatible with earlier versions in this respect. However, the new administrative interfaces 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 Web Server uses different defaults for instance directories and virtual server names, 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
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 Softwared) 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 5 Web Server.

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

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 (Release 5). The section covers the following topics:

Introduction

When upgrading Java ES Release 4 Web Server to Release 5, 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 Java ES Release 5 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

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

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 Java ES Release 5. However, all shared components required by Web Server (see Table 1-9) are upgraded automatically by the Java ES installer when you perform an upgrade of Web Server to Release 5.

Back Up Web Server Data

The Web Server upgrade from Release 4 to Release 5 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 Web Server software to Java ES Release 5 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 5 Web Server.

    4. Perform the following steps:

    1. Launch the Java ES installer.

      2. cd Java ES Release 5 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 5.
      • 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 4.
    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-6  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. Start the Web Server Administration Server service.

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

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

    6. 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-7, below. The second set of command options are specific to the migrate-server command and are documented in Table 7-8.

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

  6. Create Release 5 Web Server instances.

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

    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-7. Options specific to the create-instance command are documented in the following table.

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

      Option/Operand

      Description

      config

      The name of the Release 5 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.

  7. Start each Release 5 instance.

    8. 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 5 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 5 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-7. Options specific to the set-virtual-server-prop command are documented in the following table.

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

    Option/Operand

    Description

    config

    Name of the Release 5 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-7. Options specific to the deploy-config command are documented in the following table.

    Table 7-11  wadm deploy-cofig 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 5 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 to the WebServer7-base/lib directory.
  2. Export the magnus.conf and obj.conf configuration files to a temporary directory.

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

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

    Common command options are documented in Table 7-7.

  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=/tmp/magnus.conf magnus.conf

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

    Common command options are documented in Table 7-7.

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

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-7. Options specific to the set-search-collection-prop command are documented in the following table.

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

    Option/Operand

    Description

    config

    Name of the Release 5 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-11.

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 5 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 5 and subsequent migration of Web Server instance configurations. Hence, the rollback of Release 5 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 5 Web Server installation.

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

    1. Delete all Release 5 instances.

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

    2. Delete all Release 5 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 5 is the same as that for upgrading Release 4 Web Server to Release 5.

To upgrade Release 3 Web Server to Release 5, 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

The procedure for upgrading Java ES 2004Q2 (Release 2) Web Server to Release 5 is the same as that for upgrading Release 4 Web Server to Release 5.

To upgrade Release 2 Web Server to Release 5, 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 5 Web Server is not supported on RHEL 2.1). See Dual Upgrade for more information.



Previous      Contents      Index      Next     

Part No: 819-6553-11
June 2007.   Copyright 2007 Sun Microsystems, Inc. All rights reserved.