Migrating a WebSphere Portal V9 stand-alone server to WebSphere Application Server V9.0
You can migrate your IBM® WebSphere® Portal profile to IBM WebSphere Application Server Version 9.0.0.2 or higher. Two options exist for this migration process: local or remote. For a local migration only: Install the latest WebSphere Application Server version on the same server where WebSphere Portal V9 is installed. For a remote migration only: Install WebSphere Portal V9 with the latest IBM WebSphere Application Server on a separate server, which will be the target server for the migration. In both scenarios, make a copy of the source database to use on the target server. The remote migration is a better option because it leaves the source migration environment intact. For a local migration, the source migration profile is no longer usable after the migration.
Before you begin
About this task
- v85_wp_profile_name
- This term refers to the original WebSphere Portal profile on the WebSphere Application Server v8.5.5.5 or higher installation.
- v90_wp_profile_name
- This term refers to the new WebSphere Portal profile on the WebSphere Application Server v9.0 installation.
- v85_wp_profile_path
- This term refers to the full path to the v85 profile.
- v90_wp_profile_path
- This term refers to the full path to the v9 profile.
- v85_was_root_path
- This term refers to the full path to the WebSphere Application Server v8.5.5.5 or higher installation.
- v90_was_root_path
- This term refers to the full path to the WebSphere Application Server v9.0.0.2 or higher installation.
Procedure
- For a local migration only: Install WebSphere Application Server v9.0.0.2. For a remote migration only: Install WebSphere Portal 9.0 on the remote target server. Use the same WebSphere Portal installation directory path as the source server.
- Create a base profile on the target WebSphere Application
Server
v9.0.0.2 by using the manageprofiles command line option. Important:
- The WebSphere Application Server v9.0.0.2 migration is different from the standard WebSphere Portal migration in that references in the source environment are updated to point to the target WebSphere Application Server v9.0.0.2 environment.
- Use the exact same cell name, and node name that you used for the WebSphere Portal v8.5 and WebSphere Application Server v8.5.5.5 installation.
- AIX®: ./manageprofiles.sh -create -defaultPorts -enableAdminSecurity false -profileName v90_wp_profile_name -profilePath v90_wp_profile_path -templatePath v90_was_root_path/profileTemplates/default -nodeName source_node_name -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig
- Linux: ./manageprofiles.sh -create -defaultPorts -enableAdminSecurity false -profileName v90_wp_profile_name -profilePath v90_wp_profile_path -templatePath v90_was_root_path/profileTemplates/default -nodeName source_node_name -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig
- Windows: manageprofiles.bat -create -defaultPorts -enableAdminSecurity false -profileName v90_wp_profile_name -profilePath v90_wp_profile_path -templatePath v90_was_root_path/profileTemplates/default -nodeName source_node_name -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig
Where the following values are set:- source_node_name
- The node name on the source installation.
- source_cell_name
- The cell name on the source installation.
- host_name
- The host name of the environment.
- Open a command prompt. Note: If you are instructed to open a properties file, they are ASCII files. Open them with the appropriate tool.
- For a local migration only: Change to the source
v85_wp_profile_path/ConfigEngine directory. Then, run the
install-wp-migration-files task to install WebSphere Portal-specific files into the WebSphere Application
Server v9.0 installation: Note: Ensure that the file folder that contains the source binary files is read/write enabled. If the folder is read only, the install-wp-migration-files task fails.
- AIX: ./ConfigEngine.sh install-wp-migration-files -DNewWasLocation=v90_was_root_path -DWasPassword=password
- Linux: ./ConfigEngine.sh install-wp-migration-files -DNewWasLocation=v90_was_root_path -DWasPassword=password
- Windows: ConfigEngine.bat install-wp-migration-files -DNewWasLocation=v90_was_root_path -DWasPassword=password
Note:- If this step fails, ConfigEngine might not be working. To fix this error,
restore the ConfigEngine.migration.bak file that was created in the
ConfigEngine root directory. Change
ConfigEngine.migration.bak to ConfigEngine.sh or
ConfigEngine.bat, depending on your operating system.Note: If ConfigEngine.migration.bak was not created, the failure occurred before the file was changed. Therefore, ConfigEngine should work.
- Ensure that the OSGi cache was cleared from the new WebSphere Application
Server v9.0 installation by running the following command
from the v90_wp_profile_path/bin directory:
- AIX: ./osgiCfgInit.sh -all
- Linux: ./osgiCfgInit.sh -all
- Windows: osgiCfgInit.bat -all
- For a remote migration only: On the WebSphere Portal
V9.0 server, run the following command to create the
PORTAL_V8.5.0.0_WAS_V90_OS.arch_RemoteMigrSupport.jar
file. For example, the file might be
PORTAL_V8.5.0.0_WAS_V90_windows.x86_RemoteMigrSupport.jar.
- AIX: cd PortalServer_root/bin ./genRemMigPkg.sh remote_zip_dir
- Linux: cd PortalServer_root/bin ./genRemMigPkg.sh remote_zip_dir
- Windows: cd PortalServer_root\bin genRemMigPkg.bat remote_zip_dir
Where remote_zip_dir is an existing directory that is used to contain the generated file. Make sure that you specify the full path to the directory. Copy the PORTAL_V8.5.0.0_WAS_V90_OS.arch_RemoteMigrSupport.jar file from the WebSphere Portal V9 target server to the WebSphere Portal source server. Extract the JAR file into a working directory. For example, extract PORTAL_V8.5.0.0_WAS_V90_linux.amd64_RemoteMigrSupport.jar.
Linux only: Ensure that read and run permissions are set on the extracted files. For example: run chmod -R 755 supp_dir. - On the source WebSphere Portal server, complete the
following steps to prepare the WebSphere Portal profile
for the WASPreUpgrade command.
- Uninstall any unnecessary applications.
- Delete backup and uninstalled applications.
- Delete any old large log files or temp files that are no longer needed, which might require the
WebSphere Portal Server to be stopped. The following
locations are for common temp files:
- v85_wp_profile_path/temp/
- v85_wp_profile_path/wstemp/
- v85_wp_profile_path/config/temp/
- The WASPreUpgrade and WASPostUpgrade commands that are
used in WebSphere Portal migration use much memory and
might result in an OutOfMemoryException. To prevent this error from happening,
complete the following steps:
- Ensure that you are using a large enough heap size. Generally, using 2 GB heap size is sufficient, specified by using the -javaoption -Xmx2048m variable when you run WASPreUpgrade or WASPostUpgrade commands. Increase the heap size by increasing the -Xmx2048m variable. A possible value might be -Xmx4096m.
- Ensure that the size of the WebSphere Portal
profile was minimized by deleting unnecessary files. In most cases, the WebSphere Portal profile (wp_profile) should not be larger
than 2 GB. Search for files larger than 10 MB to find any possible files that can be contributing to
a large profile size. For example:
- In Linux you can use the following command to find files larger than 10 MB: > find . -type f -size +10000k -exec ls -lh {} \; | awk '{ print $9 ": " $5 }'.
- In Windows, you can run the following search in Windows Explorer: *.* size:> 10MB
- Stop WebSphere Portal before you run the WASPreUpgrade command.
- Set the file descriptor limit to at least
20480.
ulimit -n 20480
- Set the stack limit to at least 65536.
ulimit -s 65536
- AIX only: Use the following steps
to increase the maximum length of the command line with environment variables:
- Run the following command to query the system attributes:
lsattr -EH -l sys0 | grep ncargs
The command returns a value similar to the following example:ncargs 256 ARG/ENV list size in 4K byte blocks True
- If the ncargs value is less than
512, run the following command to increase the value:
chdev -l sys0 -a ncargs=1024
- Run the following command to query the system attributes:
- For a local migration only: Run the
WASPreUpgrade command from the v90_was_root_path/bin directory. For a remote migration
only: Run the WASPreUpgrade command from the
working_directory/bin directory that contains the remote migration package that
is copied earlier. For a remote migration only: Add the extra parameter
-machineChange true.
- AIX: ./WASPreUpgrade.sh temp_dir v85_was_root_path -javaoption -Xmx2048m -oldProfile v85_wp_profile_name -username was_admin_user -password was_admin_user_pswrd
- Linux: ./WASPreUpgrade.sh temp_dir v85_was_root_path -javaoption -Xmx2048m -oldProfile v85_wp_profile_name -username was_admin_user -password was_admin_user_pswrd
- Windows: WASPreUpgrade.bat temp_dir v85_was_root_path -javaoption -Xmx2048m -oldProfile v85_wp_profile_name -username was_admin_user -password was_admin_user_pswrd
Where the following values are set:- temp_dir
- Temporary directory where the backup is stored.
Note:- If you are running this command on Windows, the temp_dir cannot have spaces in the path.
For example, your command might look like: ./WASPreUpgrade.sh /opt/IBM/wasMigrateBackup /opt/IBM/WebSphere/AppServer -javaoption -Xmx2048m -oldProfile v85_wp_profile_name -username was_admin_user -password was_admin_user_pswrd
- For a remote migration only: Compress and copy the backup that is created by the WASPreUpgrade command from the source server to the remote target server. Extract the backup into a temporary directory such as temp_dir.
- For a local migration only: Run the
WASPostUpgrade command from the v90_was_root_path/bin directory on the local server. For a remote migration only:
Run the WASPostUpgrade command from the v90_was_root_path/bin directory on the remote target server. The
WasPostUpgrade command migrates the backed-up source profile into the new
profile. Note: If security is enabled on your profile, add the -username was_userid -password was_userid_password parameters to your WASPostUpgrade task.
- AIX: ./WASPostUpgrade.sh temp_dir -profileName v90_wp_profile_name -oldProfile v85_wp_profile_name -javaoption -Xmx2048m
- Linux: ./WASPostUpgrade.sh temp_dir -profileName v90_wp_profile_name -oldProfile v85_wp_profile_name -javaoption -Xmx2048m
- Windows: WASPostUpgrade.bat temp_dir -profileName v90_wp_profile_name -oldProfile v85_wp_profile_name -javaoption -Xmx2048m
If the WASPreUpgrade was successful, but the WASPostUpgrade command results in an error, complete the following steps:
- Check that only one profile exists in the backup profile.
- If necessary, delete the search collection to decrease the data size.
- Move JCR Data during migration. Note: The Java™ Content Repository might store index-related files in subdirectories in the WebSphere profile, such as jcr, that can use much space. This data is not altered by the migration process, so it can be temporarily moved out of the old profile or the backup directory in preparation for migration. Move the directory into the new profile after migration completes.
- Ensure that no paths exist with the ":" character. The character might cause problems for WASPreUpgrade and WASPostUpgrade commands.
- If the source and target profile names are not the same, in the Source ConfigEngine path, run
the action-copy-ce-script-native-encoding task: Note: The source ConfigEngine path should be in the same path as the PortalServer and AppServer paths. Do not run this task from the ConfigEngine path that is located within the source profile.
- AIX: ./ConfigEngine.sh -profileName v90_wp_profile_name action-copy-ce-script-native-encoding -DWasPassword=password -DPortalAdminPwd=password
- Linux: ./ConfigEngine.sh -profileName v90_wp_profile_name action-copy-ce-script-native-encoding -DWasPassword=password -DPortalAdminPwd=password
- Windows: ConfigEngine.bat -profileName v90_wp_profile_name action-copy-ce-script-native-encoding -DWasPassword=password -DPortalAdminPwd=password
- Create a copy of the WebSphere Portal source database. Refer to your database documentation for instructions on how to create the backup. Modify the wkplc_dbdomain.properties file on the WebSphere Portal V9 target server to point to the database copy.
- Modify the following properties files so that the parameters point to the new
v90_was_root_path/ directory locations:
- From the v90_wp_profile_path/ConfigEngine/properties directory:
- Verify that the DbLibrary parameter in the wkplc_dbtype.properties file points to the correct JDBC driver class. The value is either .zip or .jar. For example: /derby/lib/derby.jar.
- Verify that the WpsInstallLocation parameter in the wkplc.properties file points to the installation location of WebSphere Portal. For example: the value might be the /opt/IBM/wp85/PortalServer directory.
- Verify that the administrative passwords in the wkplc_dbdomain.properties file were not deleted by the fix pack.
- Verify that the WasRemoteHostName, WasSoapPort, WpsHostName properties in the wkplc.properties are set to the correct values.
- For a local migration only: From the /PortalServer
directory, modify the following parameters in the wps.properties file:
- WasRootDir=v90_was_root_path/
- ProfileDirectory=v90_wp_profile_path
- From the v90_wp_profile_path/ConfigEngine/properties directory:
- Open a command prompt and change to the v90_wp_profile_path/ConfigEngine directory.
- Run the following command:
- AIX: ./ConfigEngine.sh validate-database -DWasPassword=password -DPortalAdminPwd=password
- Linux: ./ConfigEngine.sh validate-database -DWasPassword=password -DPortalAdminPwd=password
- Windows: ConfigEngine.bat validate-database -DWasPassword=password -DPortalAdminPwd=password
- Run the following command to re-create your data sources:
- AIX: ./ConfigEngine.sh connect-database -DWasPassword=password -DPortalAdminPwd=password
- Linux: ./ConfigEngine.sh connect-database -DWasPassword=password -DPortalAdminPwd=password
- Windows: ConfigEngine.bat connect-database -DWasPassword=password -DPortalAdminPwd=password
- Run the following post-was-migration-update command:
- AIX: ./ConfigEngine.sh post-was-migration-update -DWasPassword=password -DoldProfileLocation=v85_wp_profile_path
- Linux: ./ConfigEngine.sh post-was-migration-update -DWasPassword=password -DoldProfileLocation=v85_wp_profile_path
- Windows: ConfigEngine.bat post-was-migration-update -DWasPassword=password -DoldProfileLocation=v85_wp_profile_path
- Start the WebSphere Portal server. Note: If the WebSphere Application Server migration fails:
- Refer to the job log in the WebSphere Application Server temporary directory to troubleshoot WebSphere Application Server migration errors.
- Rerun the install-wp-migration-files command from step 3.
- After you migrate your profile to WebSphere Application
Server 9.0.0.2,
the Configuration Wizard in the v85_AppServer root/profiles/cw_profile
directory is still usable. If you want to have the wizard also running on WebSphere Application
Server 9.0.0.2, run the following command from the
v90_wp_profile_path/ConfigEngine directory.
- AIX: ./ConfigEngine.sh create-config-wizard -DWizardUserid=userID -DWizardPassword=password -DWasPassword=password
- Linux: ./ConfigEngine.sh create-config-wizard -DWizardUserid=userID -DWizardPassword=password -DWasPassword=password
- Windows: ConfigEngine.bat create-config-wizard -DWizardUserid=userID -DWizardPassword=password -DWasPassword=password