WASPreUpgrade command
The WASPreUpgrade command for WebSphere® Application Server Version 9.0 saves the configuration of a previously installed version of WebSphere Application Server into a migration-specific backup directory.
Location
The command file is located in and must be run from the Version 9.0 app_server_root/bin directory.
Authority
To run this command script, your user profile must have *ALLOBJ authority.
Syntax
WASPreUpgrade.sh backupDirectory
currentWebSphereDirectory
[-properties properties_file_name]
[-traceString trace_spec [-traceFile file_name ]]
[-machineChange true | false]
[-oldProfile profile_name]
[-workspaceRoot profile1=user_workspace_folder_name_1;profile2=user_workspace_folder_name_2]
[-username < user name >]
[-password < password >]
[-javaoption < -Xms...m > -javaoption < -Xmx...m > ]
[-requireEmbeddedDBMigration true | false]
[-keepDmgrEnabled true | false]
[-allowSameRelease < true | false >]
WASPreUpgrade.bat backupDirectory
currentWebSphereDirectory
[-properties properties_file_name]
[-traceString trace_spec [-traceFile file_name ]]
[-machineChange true | false]
[-oldProfile profile_name]
[-workspaceRoot profile1=user_workspace_folder_name_1;profile2=user_workspace_folder_name_2]
[-username < user name >]
[-password < password >]
[-javaoption < -Xms...m > -javaoption < -Xmx...m > ]
[-requireEmbeddedDBMigration true | false]
[-keepDmgrEnabled true | false]
[-allowSameRelease < true | false >]
WASPreUpgrade backupDirectory
currentWebSphereDirectory
[-properties properties_file_name]
[-traceString trace_spec [-traceFile file_name ]]
[-oldProfile profile_name]
[-workspaceRoot profile1=user_workspace_folder_name_1;profile2=user_workspace_folder_name_2]
[-username < user name >]
[-password < password >]
[-javaoption < -Xms...m > -javaoption < -Xmx...m > ]
[-requireEmbeddedDBMigration true | false]
[-keepDmgrEnabled true | false]
Parameters
The command has the following parameters:
- This is a required parameter and must be the first parameter that you specify. The value
backupDirectory specifies the name of the directory where the command script
stores the saved configuration. Avoid trouble: The WAS_INSTALL and USER_INSTALL root directories are invalid directories for the location of the WebSphere Application Server backup directory.
This is also the directory from which the WASPostUpgrade command reads the configuration.
If the directory does not exist, the WASPreUpgrade command script creates it.
- This is a required parameter and must be the second parameter that you specify. This can be any
edition of WebSphere Application Server
Version 7.0 or later for which migration is supported.
The currentWebSphereDirectory value specifies the name of the installation root directory for the source WebSphere Application Server installation.
For transitioning users: In versions prior to Version 9.0, the currentWebSphereDirectory value specified the name of the source instance or profile root directory rather than the installation directory. Although you can continue to specify the profile root directory as this value, specifying the installation directory as this value and specifying the profile on the -oldProfile parameter allows for greater flexibility. - This is an optional parameter. The value properties_file_name specifies the
path to a properties file containing parameter properties that define how migration tools such as
WASPreUpgrade operate.
You 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.
Note: 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. - This is an optional parameter. The value trace_spec specifies the trace
information that you want to collect.
To gather all trace information, specify "*=all=enabled" (with quotation marks).
If you 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 you 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 used for a migration involving cross operating-system and machine
boundaries. If specified as true, this parameter provides support for changing physical hardware
when migrating by backing up items that are stored outside the WebSphere Application Server installation or profile folder hierarchy. If
specified as false, only files stored under the WebSphere Application Server
installation folder or profile folders are copied to the backup directory during migration.
The default is false.
When this value is false, migration assumes that the new and old WebSphere Application Server installations are on the same physical machine with shared access to the file system. Therefore, any files located outside the WebSphere directories are communal and can be shared. Migration does not copy files outside the WebSphere Application Server tree into the backup directory when -machineChange is false. False is the only option when you use the Migration wizard. If you select -machineChange=false, you must run the WASPostUpgrade command on the same physical hardware.
If you intend to run the WASPostUpgrade command on a different machine or file system, you should run the WASPreUpgrade command with -machineChange=true. If you select -machineChange=true, migration creates an additional subdirectory (/migrated/) in the migration backup directory that contains any files referenced by the WebSphere Application Server configuration that reside outside the product or profile directories. When you run the WASPostUpgrade command, these files are returned to their original paths on the new machine.
Performance considerations:If you migrate with Service Integration Bus (SIB) busses configured with file-system file-store repositories, you might require additional space in your migration heap and migration backup directory. Each bus has three file-store values—a log, a tempspace, and a repository. These three files vary in size, but they can be as much as 100-500 MB each. When migration is running, it backs up any file stores that are in the WebSphere Application Server tree during the pre-upgrade process. There needs to be sufficient space on the file system to permit this. If file stores exist at the destination location already during the post-upgrade process, migration backs up the file stores in memory to support rollback.
If you run the WASPreUpgrade command with -machineChange=true, resulting in a backup directory that contains shared file-store objects, you might find that the post-upgrade process suffers from out-of-memory exceptions because the default maximum heap is too small to contain the file-store backups in support of rollback. To resolve this issue, perform one of the following three tasks: - This is an optional parameter used for migrating a specific instance or profile from a previous
version of WebSphere Application Server. Important: If you specify a profile root as the currentWebSphereDirectory value and you specify a profile on the -oldProfile parameter, the profiles must match.
- This is an optional parameter. The value user_workspace_folder_name_x specifies the location of the administrative console customized "My tasks" settings for one or more profiles.
- This is an optional parameter. The value user name specifies the
administrative user name of the current WebSphere Application Server
installation.This is a required parameter if the following conditions are true:
- You are migrating a deployment manager.
- Administrative or global security is enabled in the source installation.
- The WebSphere Application Server installation you are migrating from is Version 8.0 or later.
- This is an optional parameter. The value password specifies the
administrative password of the current WebSphere Application Server
installation.This is a required parameter if the following conditions are true:
- You are migrating a deployment manager.
- Administrative or global security is enabled in the source installation.
- The WebSphere Application Server installation you are migrating from is Version 8.0 or later.
- This is an optional parameter. Use this parameter to specify memory sizes for the Java™ heap used by the WASPreUpgrade
command.
The value "-Xms...m" is the parameter specified to indicate the starting heap size. Replace the "..." with the size in Megabytes that you intended to use. For example, if the starting heap size is to be 128 MB, specify the parameter as: -javaoption -Xms128m
The value "-Xmx...m" is the parameter specified to indicate the maximum heap size. Replace the "..." with the size in Megabytes that you intend to use. For example, if the maximum heap size is to be 1024 MB, specify the parameter as: -javaoption -Xmx1024m
- This is an optional parameter for migrating embedded databases.
If the value is specified as true, any exception that occurs when you migrate the embedded databases causes the WASPreUpgrade command to fail. If the value is specified as false, any exception that occurs when you migrate the embedded databases is logged in the trace file, and the WASPreUpgrade command continues.
The default value is true.
- This is an optional parameter used for migrating a deployment manager profile.
When WASPreUpgrade runs, the deployment manager profiles are stopped. By default, the deployment manager remains stopped. If the value is specified to true, WASPreUpgrade starts the deployment manager before the command finishes running.
The default value is false.
- This parameter is optional. When this parameter is set to
true
, you can migrate a WebSphere Application Server Version 9.0 profile from one WebSphere Application Server Version 9.0 installation to another one, including to an installation on a different machine. When the -allowSameRelease parameter is set totrue
, the -clone parameter on the WASPostUpgrade command must be set totrue
.
Logging
The WASPreUpgrade tool displays status to the screen while it runs. The tool also saves a more extensive set of logging information in the WASPreUpgrade.time_stamp.log file written to the backupDirectory directory, where backupDirectory is the value specified for the backupDirectory parameter. You can view the WASPreUpgrade.time_stamp.log file with a text editor.
Migrated resources
WASPreUpgrade saves all of your resources, but it does not migrate entities in your classes directory.