+

Search Tips   |   Advanced Search

WASPostUpgrade command

The WASPostUpgrade command for WebSphere Application Server retrieves the saved configuration created by the WASPreUpgrade command from the backupDirectory specified. The WASPostUpgrade script for WAS reads the configuration from this directory to migrate to WAS v9.0 and adds all migrated applications into the app_server_root/installedApps directory for the v9.0 installation.

The command file is located in and must be run from the app_server_root/bin directory.


(iSeries) Authority

To run this command script, your user profile must have *ALLOBJ authority.


Syntax

(UNIX) 

WASPostUpgrade.sh backupDirectory
                     [-properties properties_file_name]
                     [-username userID]
                     [-password password]
                     [-oldProfile profile]
                     [-profileName profile]
                     [-setPorts useOld | generateNew | port_starting_number]
                     [-resolvePortConflicts incrementCurrent | port_starting_number]
                     [-backupConfig true | false]
                     [-includeApps true | false | script]
                     [-clone true | false]
                      [-newDmgrHostname host_name]
                      [[-newDmgrSoapPort port_number] | [-newDmgrRmiPort port_number]]
                     [-keepDmgrEnabled true | false]
                     [-requestTimeout seconds]
                     [-javaoption -Xms...m -javaoption -Xmx...m]
                     [[-appInstallDirectory user_specified_directory] | 
                      [-keepAppDirectory true | false]]
                     [-traceString trace_spec [-traceFile file_name]]
(Windows) 
WASPostUpgrade.bat backupDirectory
                     [-properties properties_file_name]
                     [-username userID]
                     [-password password]
                     [-oldProfile profile]
                     [-profileName profile]
                     [-setPorts useOld | generateNew | port_starting_number]
                     [-resolvePortConflicts incrementCurrent | port_starting_number]
                     [-backupConfig true | false]
                     [-includeApps true | false | script]
                     [-clone true | false]
                      [-newDmgrHostname host_name]
                      [[-newDmgrSoapPort port_number] | [-newDmgrRmiPort port_number]]
                     [-keepDmgrEnabled true | false]
                     [-requestTimeout seconds]
                     [-javaoption -Xms...m -javaoption -Xmx...m]
                     [[-appInstallDirectory user_specified_directory] | 
                      [-keepAppDirectory true | false]]
                     [-traceString trace_spec [-traceFile file_name]]
(iSeries) 
WASPostUpgrade backupDirectory
                     [-properties properties_file_name]
                     [-username userID]
                     [-password password]
                     [-oldProfile profile]
                     [-profileName profile]
                     [-setPorts useOld | generateNew | port_starting_number]
                     [-resolvePortConflicts incrementCurrent | port_starting_number]
                     [-backupConfig true | false]
                     [-includeApps true | false | script]
                     [-keepDmgrEnabled true | false]
                     [-requestTimeout seconds]
                     [-javaoption -Xms...m -javaoption -Xmx...m]
                     [[-appInstallDirectory user_specified_directory] | 
                      [-keepAppDirectory true | false]]
                     [-traceString trace_spec [-traceFile file_name]]

Use these parameters when migrating a registered application server with security enabled for both the target and source administrative agent:(UNIX) 

WASPostUpgrade.sh backupDirectory
[-oldAdminAgentProfilePath path to old admin agent]
[-oldAdminAgentSoapPort soap port of old admin agent]
[-oldAdminAgentHostname hostname of old admin agent, defaults to localhost ]
[-oldAdminAgentUsername login username for old admin agent, if admin security is enabled ]
[-oldAdminAgentPassword login password for old admin agent, if admin security is enabled ]
[-newAdminAgentProfilePath path to new admin agent ]
[-newAdminAgentSoapPort soap port of new admin agent ]
[-newAdminAgentHostname hostname of new admin agent, defaults to localhost ]
[-newAdminAgentUsername login username for new admin agent, if admin security is enabled ]
[-newAdminAgentPassword login password for new admin agent, if admin security is enabled ]
(Windows) 
WASPostUpgrade.bat backupDirectory
[-oldAdminAgentProfilePath path to old admin agent]
[-oldAdminAgentSoapPort soap port of old admin agent]
[-oldAdminAgentHostname hostname of old admin agent, defaults to localhost ]
[-oldAdminAgentUsername login username for old admin agent, if admin security is enabled ]
[-oldAdminAgentPassword login password for old admin agent, if admin security is enabled ]
[-newAdminAgentProfilePath path to new admin agent ]
[-newAdminAgentSoapPort soap port of new admin agent ]
[-newAdminAgentHostname hostname of new admin agent, defaults to localhost ]
[-newAdminAgentUsername login username for new admin agent, if admin security is enabled ]
[-newAdminAgentPassword login password for new admin agent, if admin security is enabled ]
(iSeries) 
WASPostUpgrade backupDirectory
[-oldAdminAgentProfilePath path to old admin agent]
[-oldAdminAgentSoapPort soap port of old admin agent]
[-oldAdminAgentHostname hostname of old admin agent, defaults to localhost ]
[-oldAdminAgentUsername login username for old admin agent, if admin security is enabled ]
[-oldAdminAgentPassword login password for old admin agent, if admin security is enabled ]
[-newAdminAgentProfilePath path to new admin agent ]
[-newAdminAgentSoapPort soap port of new admin agent ]
[-newAdminAgentHostname hostname of new admin agent, defaults to localhost ]
[-newAdminAgentUsername login username for new admin agent, if admin security is enabled ]
[-newAdminAgentPassword login password for new admin agent, if admin security is enabled ]


Parameters

The command has the following parameters:

backupDirectory

This is a required parameter. The value backupDirectory specifies the name of the directory in which the WASPreUpgrade tool stores the saved configuration and files and from which the WASPostUpgrade tool reads the configuration and files.

-properties

Optional. The value properties_file_name specifies the path to a properties file containing parameter properties that define how migration tools such as WASPostUpgrade operate.

We can define parameter properties in the migration properties file rather than specifying most optional parameters on the command line. If parameters are both defined in the properties file and specified on the command line, the parameters specified on the command line take precedence.

Certain parameters cannot be specified in the properties file, such as the -properties parameter itself and -username and -password. For a list of parameters that cannot be defined as a property, see the template migration.properties file in the app_server_root/bin directory.

-username

Optional. The value userID specifies the administrative user name of the current WAS v7.0 or later installation.

This is a required parameter if the following conditions are true:

  • We are migrating a deployment manager or a federated node.
  • Administrative or global security is enabled in the source installation.

  • The administrative or global security user ID is not defined in the security.xml file.

-password

Optional. The value password specifies the password for the administrative user name of the current WAS v7.0 or later installation.

This is a required parameter if the following conditions are true:

  • We are migrating a deployment manager or a federated node.
  • Administrative or global security is enabled in the source installation.

  • The administrative or global security password is not defined in the security.xml file.

(Dist) Tip: When we need to specify a password in the Migration wizard or when using the WASPostUpgrade command with the -password parameter on the command line, we can type the password in plain text or use the xor-ciphered value. To use the xor-ciphered value, type the entire cipher including the {xor} prefix as the value for the parameter. This xor-ciphered value can be specified in any one of several WAS configuration files for our previous configuration, including the soap.client.props, ssl.client.props, and security.xmlfiles.

(Dist) Tip: When we use the WASPostUpgrade command with the -password parameter on the command line, we can type the password in plain text or use the xor-ciphered value. To use the xor-ciphered value, type the entire cipher including the {xor} prefix as the value for the parameter. This xor-ciphered value can be specified in any one of several WAS configuration files for our previous configuration, including the soap.client.props, ssl.client.props, and security.xmlfiles.

-oldProfile

Optional.for migrating instances or profiles from previous WAS versions. The instance or profile must already exist in the migration backup directory before running this command.

If the -oldProfile parameter is not specified, the default profile is used. If no default profile is found, the system reports an error.

If we do not specify the specific profile name on -oldProfile, then whatever is the designated "default" profile will be migrated. We might have to migrate each profile in the backup taken on pre-migration, using the WASPostUpgrade post-migration command specifying the -oldProfile and -profileName parameters for each and every profile that the client wants in the new v9.0 environment. If the old profile contains installed applications (installedApps) in addition to the sample application and system applications, then the migration process automatically migrates those applications.

-profileName

Optional.for migrating to specific profiles in WAS v9.0. The value profile specifies the name of the v9.0 profile to which the script migrates the configuration. We must have already created this profile before calling the WASPostUpgrade command.

If the -profileName parameter is not specified, the default profile is used. If no default profile is found, the system reports an error.

If we do not specify the specific profile name on -profileName, then whatever is the designated "default" profile will be migrated. We might have to migrate each profile in the backup taken on pre-migration, using the WASPostUpgrade post-migration command specifying the -oldProfile and -profileName parameters for each and every profile that the client wants in the new environment. If the old profile contains installed applications (installedApps) in addition to the sample application and system applications, then the migration process automatically migrates those applications.

When migrating a stand-alone application server from v9.0, we can choose a stand-alone application server node that has already been registered with an administrative agent as the target of the migration.

-backupConfig

Optional. Used to specify whether the existing WAS v9.0 configuration is saved before any changes are made by the WASPostUpgrade tool. The default is true-that is, to use the backupConfig command to save a copy of the current configuration into the profile/temp directory.

Use the restoreConfig command to restore that configuration as required. See restoreConfig command .

-setPorts

Optional.that specifies how to set the ports for the new profile. The parameter takes the following values:

  • useOld (default): Use the same ports that the old profile used. (Dist) This value cannot be used for clone migrations.
  • generateNew: Generate new ports based on the default port assignments.
  • port_starting_number: Generate new ports, incrementing from the specified value.

If a value is specified for this parameter, any new ports assigned are set based on this value. Every time a new port value is required, the port is created based on this value and the seed value is incremented for the next usage. No duplicate ports are assigned.

-resolvePortConflicts

This optional parameter specifies how to map port values. When a port cannot be used, its value is incremented from a starting value until an available port is found.

  • incrementCurrent (default): Increment from the conflicted port value.
  • port_starting_number: Increment from the specified common starting port value.

-includeApps

We can include business level applications, assets, and composition units as part of the migration. We can optionally migrate these items using the -IncludeApps parameter on the WASPostUpgrade command. Optional.that can be specified in the following ways:

  • True

    Include user enterprise applications, business level applications, assets, and composition units as part of the migration.

    This value is the default.

  • False

    Do nothing with user enterprise applications, business level applications, assets, and composition units during WASPostUpgrade processing.

  • Script

    • Enterprise applications

      Prepare user enterprise applications for installation in the WAS v9.0 installableApps directory without installing them during WASPostUpgrade processing.

      Scripts used to install these applications are generated and saved in the backupDirectory directory. We can then run these files at any point and in any combination after the WASPostUpgrade command has completed. We can also reorganize and combine these files to enhance the efficiency of application installation.

    • Business level applications, assets, and composition units

      The install_all_BLAs.jy script is generated and placed in the backup directory. This script can migrate all business level applications, assets, and composition units located in the backup directory to your target profile. The WASPostUpgradeBLAHelper.bat/.sh script, located in the <WAS_PROFILE_ROOT>/bin directory, is used to migrate the business level applications, assets and composition units in the install_all_BLAs.txt file.

      To migrate business level applications, assets, and composition units, first create their dependencies.

WAS system applications migrate regardless of the value set by this parameter.

(Dist) -clone

(Dist) This optional parameter indicates whether to perform a clone migration, which means that we can continue to use the source profile after we migrate it to the v9.0 environment. The default is false.

When the -clone parameter is true, we cannot specify -setPorts useold. The new profile configuration must use unique port numbers so that the now coexisting new and old configurations do not have port conflicts.

If we clone a deployment manager, we must also clone its federated nodes, and we cannot clone federated nodes without cloning the deployment manager. Clone migrations of federated nodes require that we set the new host name and either the node SOAP port or the RMI port on the following parameters.

-newDmgrHostname

The host name of the v9.0 deployment manager

-newDmgrSoapPort

The Simple Object Access Protocol (SOAP) port of the v9.0 deployment manager

-newDmgrRmiPort

The RMI port of the v9.0 deployment manager

-keepDmgrEnabled

Optional. Used to specify whether to disable the existing WAS v7.0 or later deployment manager. (iSeries) The default is false.(Dist) The default is false unless the -clone parameter is true, in which case -keepDmgrEnabled is also set to true.

If this parameter is specified as true, we can use the existing v7.0 or later deployment manager while the migration is completed. It is only valid when we are migrating a deployment manager; it is ignored in all other migrations.

Caution: Use this parameter with care.

  • The reason that WAS v7.0 or later deployment manager configurations normally are stopped and disabled is to prevent multiple deployment managers from managing the same nodes. We must stop the v7.0 or later deployment manager before starting using the v9.0 deployment manager. The most likely error conditions that occur if this is not done are port conflicts when the second instance of the deployment manager is started.

  • Specify true for this parameter means any configuration changes made in the old configuration during migration might not be migrated.

-keepAppDirectory

Optional. Used to specify whether to install all applications to the same directories in which they are currently located. The default is false.

If this parameter is specified as true, each individual application retains its location.

If specified, we cannot specify the -appInstallDirectory parameter.

Restrictions: If this parameter is specified as true, the location is shared by the existing WAS v7.0 or later installation and the v9.0 installation. If we keep the migrated applications in the same locations as those of the previous version, the following restrictions apply:

  • The WAS v9.0 mixed-node support limitations must be followed. This means that the following support cannot be used when evoking the wsadmin command:

    • Precompile JSP

    • Use Binary Configuration
    • Deploy EJB

  • You risk losing the migrated applications unintentionally if you later delete applications from these locations when administering our v7.0 or later installation.

-appInstallDirectory

Optional. Used to pass the directory name to use when installing all applications during migration. The default of profile\installedApps is used if this parameter is not specified.

If specified, we cannot specify the -keepAppDirectory parameter.

Quotes must be used around the directory name if one or more spaces are in the name.

If we use this parameter, the migration tools investigate the node-level variables for the node being migrated both in the backup directory (variables for the old release) and in the destination profile (variables from the new release). If the path is part of any of the following variables in either of these releases, the tools contract the path information to use the related variable:

  • APP_INSTALL_ROOT
  • USER_INSTALL_ROOT
  • WAS_INSTALL_ROOT

When the contraction takes place, we receive the following warning message that tells you that the tools changed your specified value and what that contracted value is: 

MIGR0341W: Application install directory has been updated to {0}.
For example: 
MIGR0341W: Application install directory has been updated to ${USER_INSTALL_ROOT}\customAppDirectory.
or 
MIGR0341W: Application install directory has been updated to ${APP_INSTALL_ROOT}\
cellName\customAppDirectory\.

-traceString

Optional. The value trace_spec specifies the trace information to collect.

To gather all trace information, specify "*=all=enabled" (with quotation marks).

If we do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDirectory/logs directory.

-traceFile

Optional. The value file_name specifies the name of the output file for trace information.

If we do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDirectory/logs directory.

-requestTimeout

Optional. The value seconds refers to the number of seconds that migration will wait before failing attempted wsadmin connections.

This value is also used as the timeout parameter during application migration.

-oldAdminAgentProfilePath

Optional. The value path to old admin agent refers to the file system path of the profile directory for the original administrative agent.

This parameter is only required if the application server being migrated is managed by an administrative agent.

-oldAdminAgentSoapPort

Optional. The value soap port of old admin agent refers to the SOAP port used by the original administrative agent for administrative connections.

This parameter is required only if the application server being migrated is managed by an administrative agent.

-oldAdminAgentHostname

Optional. The value hostname of old admin agent refers to the hostname location of the original administrative agent. If the parameter is not specified, the value is set by default to "localhost".

Required only if the application server being migrated is managed by an administrative agent.

-oldAdminAgentUsername

Optional. The value login username for old admin agent refers to the username for the original administrative agent.

Required only if the application server being migrated is managed by an administrative agent that has administrative security enabled.

-newAdminAgentProfilePath

Optional. The value path to new admin agent refers to the file system path of the profile directory for the newly migrated Administrative Agent.

This parameter is required only if the application server being migrated is managed by an administrative agent.

-newAdminAgentSoapPort

Optional. The value soap port of old admin agent refers to the SOAP port used by the newly migrated Administrative Agent for administrative connections.

Required only if the application server being migrated is managed by an administrative agent.

-newAdminAgentHostname

Optional. The value hostname of old admin agent refers to the hostname location of the new Administrative Agent. If the parameter is not specified, the value is set by default to "localhost".

Required only if the application server being migrated is managed by an administrative agent.

-newAdminAgentUsername

Optional. The value login username for old admin agent refers to the username for the new Administrative Agent.

Required only if the application server being migrated is managed by an administrative agent that has administrative security enabled.

-newAdminAgentPassword

Optional. The value login password for old admin agent refers to the username for the new Administrative Agent.

Required only if the application server being migrated is managed by an administrative agent that has administrative security enabled.

-javaoption < -Xms...m > -javaoption < -Xmx...m >

Optional. Specify memory sizes for the Java heap used by WASPostUpgrade.

The value "-Xms...m" specifies the starting heap size. Replace the "..." with the size in Megabytes needed. For example, if the starting heap size is to be 128 MB, specify the parameter as: -javaoption -Xms128m

The value "-Xmx...m" specifies the maximum heap size. Replace the "..." with the size in Megabytes needed. For example, if the maximum heap size is to be 1024 MB, specify the parameter as: -javaoption -Xmx1024m

(Dist)

Logging

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


Security considerations

The target system must have security disabled before migration. If we migrate from a source configuration that has security enabled, the WASPostUpgrade command automatically enables security for the v9.0 target configuration during the migration.

  • WASPreUpgrade command
  • restoreConfig command