WASPostUpgrade command

The WASPostUpgrade command is a migration tool for adding the configuration and applications of a previous version or release to a Version 5.1 WebSphere Application Server node. The configuration includes migrated applications. The tool adds all migrated applications into the $WAS_HOME/installedApps directory for the Version 5.1 installation. The tool locates the saved configuration that the WASPreUpgrade tool saves through a parameter you use to specify the backup directory.

 

Location of command file

The command file is located in the $WAS_HOME/bin directory. The command file is a script named WASPostUpgrade.sh for Linux and UNIX-based platforms or WASPostUpgrade.bat for Windows platforms.

 

WASPostUpgrade.sh command syntax for Linux and UNIX-based platforms

The command syntax is as follows

WASPostUpgrade.sh backupDirectory
                     [-import xmi_data_file]
                     [-cellName cell]
                     [-nodeName node]
                     [-serverName server]
                     [-webModuleAdditionalClasspath classpath]
                     [-documentRootLimit number]
                     [-substitute "key1=value1[;key2=value2;[...]]"]
                     [-portBlock port_starting_number] 
                     [-backupConfig true | false]
                     [-replacePorts true | false]
                    [[-traceString trace_spec [-traceFile file_name]]
The first argument is required.

 

WASPostUpgrade.bat command syntax for Windows platforms

WASPostUpgrade backupDirectory
                  [-import xmi_data_file]
                  [-cellName cell]
                  [-nodeName node]
                  [-serverName server]
                  [-webModuleAdditionalClasspath classpath]
                  [-documentRootLimit number]
                  [-substitute "key1=value1[;key2=value2;[...]]"]
                  [-portBlock port_starting_number] 
                  [-backupConfig true | false]
                  [-replacePorts true | false]
                 [[-traceString trace_spec [-traceFile file_name]]

The first argument is required.

 

Parameters

Supported arguments include...

-backupConfig true | false An optional parameter used to back up the existing configuration of the Version 5.1 instance before adding the saved configuration from the earlier release to the Version 5.1 instance. The default is true, to use the backupConfig command to save a copy of the Version 5.1 configuration into the $WAS_HOME/temp directory. Use the restoreConfig command to restore that configuration as required.

No equivalent parameter is available in the silent installation options response file.

backupDirectory Required name of the directory in which the WASPreUpgrade tool stores the saved configuration and files. The WASPostUpgrade tool reads the configuration and files stored in this directory. The WASPreUpgrade tool creates this directory if it does not already exist.

This parameter is equivalent to the -W migrationInformationPanelBean.migrationBackupDir= "/tmp/migrationbackup" parameter in the silent installation options response file.

-cellName cell An optional parameter to specify the cell name for the program to update. If not specified, the program inspects the configuration for cell names. When one cell name exists, the program uses it. Otherwise, the program returns an error.

This parameter is equivalent to the -W nodeNameBean.cellName= "nodenameNetwork" parameter in the silent installation options response file for the Network Deployment product. No equivalent parameter is available in the silent installation options response file for the base product.

-documentRootLimit number An optional parameter to specify the number of files that the program copies from the document-root field of Web-application. It is only applicable to Version 3.5.x upgrades. If not specified, the default is 300.

No equivalent parameter is available in the silent installation options response file.

-import xmi_data_file The name of the WAS Advanced Single Server Edition, Version 4.0 XML Metadata Interchange (XMI) configuration file to process. This parameter is optional because the program uses the config\server-cfg.xml file by default.

This parameter is ignored when migrating from V5.0.x, including WAS- Express, V5.

When migrating a configuration that uses anything other than the default server-cfg.xml file name, use the -import option along with the path to the non-default XMI configuration file in the directory created by the WASPreUpgrade tool.

This parameter is equivalent to the -W previousVersionPanelBean.selectedVersionConfigFile= "/opt/WebSphere/AppServer/config/server-cfg.xml" parameter in the silent installation options response file.

-nodeName node An optional parameter to specify the node name for the program to update. If not specified, the program inspects the configuration for node names. When one node name exists, the program uses it. Otherwise, the program returns an error.

This parameter is equivalent to the -W nodeNameBean.nodeName= "nodenameManager" parameter in the silent installation options response file for the Network Deployment product. No equivalent parameter is available in the silent installation options response file for the base product.

-portBlock port_starting_number An optional parameter used to specify the starting value to use when creating ports.

No equivalent parameter is available in the silent installation options response file.

-replacePorts true | false An optional parameter used to define how to migrate virtual host and server transport ports. The default is false, to not replace default port definitions. By default the migration adds configuration data from the previous version to the existing data in the V5.1.x configuration. In some cases existing port definitions from the earlier release were carefully set to avoid port conflicts with other products. In such cases, it is likely that you would want to migrate the settings into V5.1.x. Use the -replacePorts parameter to totally replace settings in the V5.1.x environment with the settings from the previous version. Select true to replace all virtual host alias port settings during migration. If migrating from V5.0.x or later, transport settings in existing servers are replaced by the settings from the previous version.

-serverName server An optional parameter to specify the server name for the program to update. If not specified, the program inspects the configuration for server names. When one server name exists, with an Application Server name that matches, the program uses it. Otherwise, the program creates a new server.

-substitute key1=value1;key2=value2;... Optional argument passed to the XMLConfig tool. Specify values for security variables to substitute (for example, -substitute "NODE_NAME=admin_node;APP_SERVER=default_server").

In the input XML data file, each key appears as $key$ for substitution. This argument substitutes any occurrence of $NODE_NAME$ with admin_node and $APP_SERVER$ with default_server in the input XML file.

If the substitution string contains semicolons, use $semiColon$ to distinguish the string from the ";" delimiter. On Linux and UNIX-based platforms, add an escape character to each dollar sign ($) within the substitution string (for example, \$semiColon\$).

This parameter is applicable for configurations saved from Advanced Edition, Versions 3.5.x and 4.0.x.

No equivalent parameter is available in the silent installation options response file.

-traceString trace_spec -traceFile file_name An optional parameters to gather trace information for IBM Service personnel. Specify a trace specification of "*=all=enabled" (with quotation marks) to gather all trace information.

No equivalent parameter is available in the silent installation options response file.

-webModuleAdditionalClasspath classpath An optional parameter to specify the path or the path and file names of specific directories or files that you do not want copied into the Web archive (WAR) file. Instead, the program adds the paths and the files to the Web Module extension (ibm-web-ext.xmi) additionalClassPath attribute. This parameter is applicable only when migrating a Version 3.5.x installation.

No equivalent parameter is available in the silent installation options response file.

 

Logging

The WASPostUpgrade tool displays status to the screen while running. This tool also saves a more extensive set of logging information in the logs directory. You can view the WASPostUpgrade.log file with a text editor.

 Migrating from V3.5.x Standard Edition or Advanced Edition, or from V4.0.x Advanced Edition

The following example specifies a backup directory named backupDirectory, and identifies the root of the existing installation as d:\WebSphere\AppServer

WASPreUpgrade backupDirectory d:\WebSphere\AppServer yourNodeName

 Migrating from V4.0.x Advanced Single Server Edition with multiple backup directories

This example shows how to migrate separate configuration files incrementally from a single node with a single installation of WAS Advanced Single Server Edition. To migrate more than one configuration file, run the WASPreUpgrade tool multiple times to multiple backup directories because not all of the applications are in the same installedApps directory. For this reason, using a single backup directory for all the runs of the WASPreUpgrade tool is not recommended. Use a separate backup directory for each run. The intent of this example is to show how to migrate a single node with multiple configuration files.

  1. Run the following WASPreUpgrade commands to migrate applications A, B, C, D, and E, which reside in three separate application directories. Server assumptions include...

    • The Application Server uses the server-cfg.xml default configuration file, as well as the servername1-cfg.xml and the OldServer-cfg.xml files.

    > WASPreUpgrade "C:\WAS4ABBACKUP"  G:\WebSphere\AppServer
    > WASPreUpgrade "C:\WAS4CDBACKUP"  G:\WebSphere\AppServer
          -import  G:\WebSphere\AppServer\config\servername1-cfg.xml
    > WASPreUpgrade "C:\WAS4EBACKUP"  G:\WebSphere\AppServer
          -import G:\WebSphere\AppServer\config\OldServer-cfg.xml
    
    

  2. Run the following WASPostUpgrade commands to restore the applications and configurations to the Version 5.1 Application Server

    > WASPostUpgrade  C:\WAS4ABBACKUP
    > WASPostUpgrade "C:\WAS4CDBACKUP" -import "C:\WAS4CDBACKUP\servername1-cfg.xml"
    > WASPostUpgrade "C:\WAS4EBACKUP"  -import "C:\WAS4EBACKUP\OldServer-cfg.xml"
    
    

 Migrating from V5.0.0 or V5.0.1 with the embedded messaging feature

This example shows how to migrate a single instance of base WAS, V5.0.0. Verify that you have stopped all Java processes related to the WAS product that you are migrating. Run the WASPreUpgrade tool against the installedApps directory.

  1. Run the following WASPreUpgrade.bat command to migrate all applications in the installedApps directory of the V5.0.0 Application Server, which has an installation root of C:\Program Files\WebSphere\AppServer

    > WASPreUpgrade "C:\WAS500BACKUP"  C:\Program Files\WebSphere\AppServer
    
    

  2. Run the following WASPostUpgrade commands to restore the applications and configurations to the Version 5 Application Server

    > WASPostUpgrade  "C:\WAS500BACKUP"