WAS v8.5 > Reference > Command-line utilities
WASPostUpgrade command
The WASPostUpgrade command for WebSphere Application Server retrieves the saved configuration that was created by the WASPreUpgrade command from the backupDirectory that you specified. The WASPostUpgrade script for WAS reads the configuration from this directory to migrate to WAS v8.5 and adds all migrated applications into the directory...
- app_server_root/installedApps
for the v8.5 installation.
Location
This article is about configuration migration, such as migrating deployment managers and federated nodes in a network deployment environment. The Application Migration Toolkit for WAS provides support for migrating applications from previous versions of WAS to the latest product version. For information about migrating applications, read more about the Application Migration Toolkit. sptcfg
The command file is located in and must be run from the app_server_root/bin directory.
Syntax
WASPostUpgrade.sh backupDirectory
[-username userID]
[-password password]
[-oldProfile profile_name]
[-profileName profile_name]
[-scriptCompatibility true | false]
[-portBlock port_starting_number]
[-backupConfig true | false]
[-replacePorts true | false]
[-includeApps true | false | script]
[-requestTimeout seconds]
[-javaoption -Xms...m -javaoption -Xmx...m]
[[-appInstallDirectory user_specified_directory] | [-keepAppDirectory true | false]]
[-traceString trace_spec [-traceFile file_name]]
WASPostUpgrade.bat backupDirectory
[-username userID]
[-password password]
[-oldProfile profile_name]
[-profileName profile_name]
[-scriptCompatibility true | false]
[-portBlock port_starting_number]
[-backupConfig true | false]
[-replacePorts true | false]
[-includeApps true | false | script]
[-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:
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 ]
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 ]
Parameters
The command has the following parameters:
- 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.
- This is an optional parameter. The value userID specifies the administrative user name of the current WAS v6.x or 7.x installation.
- This is an optional parameter. The value password specifies the password for the administrative user name of the current WAS v6.x or 7.x installation.
When specify a password in the Migration wizard or when we use WASPostUpgrade 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 the previous configuration, including the soap.client.props, ssl.client.props, and security.xml files.
When we use WASPostUpgrade 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 the previous configuration, including the soap.client.props, ssl.client.props, and security.xml files.
- This is an optional parameter 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. You 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 the client wants in the new v8.5 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.
- This is an optional parameter for migrating to specific profiles
in WAS v8.5. The value profile_name specifies the name of the v8.5 profile to which the script migrates your configuration. You must have already created this profile before calling WASPostUpgrade.
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. You 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 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 v8.5, we can choose a stand-alone application server node that has already been registered with an administrative agent as the target of the migration.
- This is an optional parameter used to specify whether or not migration should create the following v6.x or 7.x configuration definitions:
- Transport
- ProcessDef
- v6.x SSL
instead of the following v8.5 configuration definitions:
- Channels
- ProcessDefs
- v8.5 SSL
Default is true.
Specify true for this parameter in order to minimize impacts to existing administration scripts. If we have existing wsadmin scripts or programs that use third-party configuration APIs to create or modify the v6.x or 7.x configuration definitions, for example, you might want to specify true for this option during migration.
To use a cell containing v6.x or 7.x nodes, specify true for this variable.
This is meant to provide a temporary transition until all of the nodes in the environment are at the v8.5 level. When they are all at the v8.5 level, you should perform the following actions:
- Modify your administration scripts to use all of the v8.5 settings.
- Use the convertScriptCompatability command to convert your configurations to match all of the v8.5 settings.
- This is an optional parameter used to specify whether the existing WAS v8.5 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_name/temp directory.
Use the restoreConfig command to restore that configuration as required. Read the "restoreConfig command" article in the information center for more information.
- This is an optional parameter. The port_starting_number value specifies the starting value of a block of consecutive port numbers to assign when creating new ports.
By default, this parameter is not set.
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.
- This optional parameter is used to specify how to map port values.
- True
Use all port values from the old configuration in the new configuration. All ports from the old configuration supersede the settings for the same ports in the new configuration.
- If the -portBlock parameter is not set, a conflicting port is renumbered incrementally from its original value until a nonconflicting port is identified.
- If the -portBlock parameter is set, a conflicting port is renumbered incrementally from the port block number until a nonconflicting port is identified.
This value is the default.
- False
Do not replace the default port definitions in the new profile with the values from the old configuration during migration. All ports values from the new configuration supersede the settings for the same ports in the old configuration
- If the -portBlock parameter is not set, a conflicting port is renumbered incrementally from its original value until a nonconflicting port is identified.
- If the -portBlock parameter is set, a conflicting port is renumbered incrementally from the port block number until a nonconflicting port is identified.
- True
- 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 WASPostUpgrade.
This is an optional parameter 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 v8.5 installableApps directory without installing them during WASPostUpgrade processing.
Scripts that can be 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 WASPostUpgrade 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.
- Enterprise applications
WAS system applications migrate regardless of the value set by this parameter.
- True
- This is an optional parameter 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 we specify this parameter, we cannot specify the -appInstallDirectory parameter.
Restrictions: If this parameter is specified as true, the location is shared by the existing WAS v6.x or 7.x installation and the v8.5 installation. If you keep the migrated applications in the same locations as those of the previous version, the following restrictions apply:
- The WAS v8.5 mixed-node support limitations must be followed. This means the following support cannot be used when evoking wsadmin:
- Precompile JSP
- Use Binary Configuration
- Deploy EJB
- Precompile JSP
- You risk losing the migrated applications unintentionally if you later delete applications from these locations when administering (uninstalling for example) your v6.x or 7.x installation.
- The WAS v8.5 mixed-node support limitations must be followed. This means the following support cannot be used when evoking wsadmin:
- This is an optional parameter used to pass the directory name to use when installing all applications during migration. The default of profile_name\installedApps is used if this parameter is not specified.
If we specify this parameter, 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, you receive the following warning message that tells you the tools changed your specified value and what that contracted value is:
- MIGR0341W: Application install directory has been updated to {0}.
- MIGR0341W: Application install directory has been updated to ${USER_INSTALL_ROOT}\customAppDirectory.
MIGR0341W: Application install directory has been updated to ${APP_INSTALL_ROOT}\ cellName\customAppDirectory\. - This is an optional parameter. 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.
- This is an optional parameter. 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.
- This is an optional parameter. 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.
- This is an optional parameter. 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.
- This is an optional parameter. 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.
- This is an optional parameter. 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".
This parameter is required only if the application server being migrated is managed by an administrative agent.
- This is an optional parameter. The value login username
for old admin agent refers to the username for the original administrative agent.
This parameter is required only if the application server being migrated is managed by an administrative agent that has administrative security enabled.
- This is an optional parameter. 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.
- This is an optional parameter. The value soap port of old admin agent refers to the SOAP port used by the newly
migrated Administrative Agent for administrative connections.
This parameter is required only if the application server being migrated is managed by an administrative agent.
- This is an optional parameter. 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".
This parameter is required only if the application server being migrated is managed by an administrative agent.
- This is an optional parameter. The value login username
for old admin agent refers to the username for the new Administrative Agent.
This parameter is required only if the application server being migrated is managed by an administrative agent that has administrative security enabled.
- This is an optional parameter. The value login password for old admin agent refers to the username for the new Administrative Agent.
This parameter is required only if the application server being migrated is managed by an administrative agent that has administrative security enabled.
- This is an optional parameter. 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 that you need. 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 that you need. For example, if the maximum heap size is to be 1024 MB, specify the parameter as: -javaoption -Xmx1024m
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 you migrate from a source configuration that has security enabled, WASPostUpgrade automatically enables security for the v8.5 target configuration during the migration.
java.security file
During WASPostUpgrade, a copy of the java.security file is made in the target WAS installation before migrating the file. The presence of this copy, named java.security.premigration, indicates to future migrations the file has already been migrated. Also, the copy gives you a chance to reference the default v8.0 settings and determine to make changes to the migrated java.security file.
The following properties are migrated in the java.security file, all other properties and comments are not migrated:
?security.provider.* - prepend the source provider list before the target provider list and renumber the target provider list, removing duplicates. Also ensure the com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl security provider is placed before the com.ibm.crypto.provider.IBMJCE security provider in preference order if both are present in the migrated file. ?networkaddress.cache.ttl ?networkaddress.cache.negative.ttl ?ocsp.enable ?ocsp.responderURL ?ocsp.responderCertSubjectName ?ocsp.responderCertIssuerName ?ocsp.responderCertSerialNumber
The following situations might cause the migration of the java.security file to fail. If use any of the following settings, then manually migrate the java.security file.
- If the WASPreUpgrade command is run with the machineChange=true option, the source and target operating systems will be checked before migrating the java.security file. If the source operating system iss HP or Sun, and the target operating system is not the same, the file will not be migrated. If the target operating system is HP or Sun, and the source operating system is not the same, the file will not be migrated. This is because the contents of the java.security file are not compatible between the different operating systems.
- If the copy of the java.security file to java.security.premigration cannot be made, the file will not be migrated.
- If the java.security file is not writeable, the file will not be migrated.
- If the java.security file is not found in the backup directory, the file will not be migrated. If we use an old backup directory, or if something there is a problem with the old installation, then this problem might occur.
Reference:
WASPreUpgrade command