Search Tips   |   Advanced Search

WebSphere Portal v7 to v8 migration

  1. Overview
  2. Apply WAS fix packs to source host
  3. Apply Portal fix packs to source host
  4. Prep source portal
  5. Create /opt/IBM and /media mounts on target host
  6. Install Installation Manager on target host
  7. Install WAS v8.5.5 on target host
  8. Install Portal v8 on target host
  9. Make tarball backup
  10. Migrate deployment manager
  11. Migrate application server nodes
  12. Set up unique multicast ports
  13. Upgrade ConfigEngine
  14. Migrate databases
  15. Upgrade node profile
  16. Upgrade default admin theme
  17. Install Welcome Portlet
  18. Update portlet URLs
  19. Rebuild search indexes
  20. Enable JCR text search indexing
  21. Custom JSP files
  22. Update authoring portlet theme
  23. Configure web server plugin


This document discusses a WebSphere Portal v7 to v8 migration scenario.

Before starting...

  1. Review system requirements
  2. Confirm DB2 configuration
  3. Confirm versions
  4. Review what's changed
  5. Review what is migrated?

Confirm database configuration

DB2 v9.7 FP 6...

Env DB Host Port User Pass Portal DBs


Target hosts:

What is migrated?

WebSphere Portal automatically migrates the following applications and configuration data...

Apply WAS fix packs to source host

  1. Log on to source host as user root and run: "slibclean"

  2. sudo su - wpsadmin

  3. mkdir /opt/IBM/UpdateInstaller/was70029fix

  4. From client, upload fixes...

      scp -r fixes wpsadmin@source_host:/opt/IBM/UpdateInstaller/was70029fix

  5. From host, copy WAS fixes into place

  6. cp /opt/IBM/UpdateInstaller/was70029fix/WAS/*.pak /opt/IBM/UpdateInstaller/maintenance
    wpsadmin@v7host  /opt/IBM/UpdateInstaller/maintenance$ ls -l
    total 1781424
    -rw-------    1 wpsadmin staff      25337900 Dec 12 17:56 7.0.0-WS-IHS-AixPPC64-FP0000029.pak
    -rw-------    1 wpsadmin staff      39938326 Dec 12 17:56 7.0.0-WS-PLG-AixPPC64-FP0000029.pak
    -rw-------    1 wpsadmin staff     742962010 Dec 12 17:56 7.0.0-WS-WAS-AixPPC64-FP0000029.pak
    -rw-------    1 wpsadmin staff     103839334 Dec 12 17:56 7.0.0-WS-WASSDK-AixPPC64-FP0000029.pak

  7. Stop all WebSphere Java processes

      cd /opt/IBM/WebSphere1/wp_profile/bin
      ./stopServer.sh WebSphere_Portal -username wpsadmin -password ***
      cd /opt/IBM/WebSphere1/appserver/bin
      ./stopNode.sh -username wpsadmin -password ***
      cd /opt/IBM/WebSphere/appserver/bin
      ./stopManager.sh -username wpsadmin -password ***

  8. Install WAS fixes...

  9. Verify version:

  10. If it fails right away, check logs in...


Apply portal fix packs to source host

For our scenarios, we fixpack up to v7.0.0.2 CF26.

  1. Review: IBM WebSphere Portal Combined Cumulative Fix Readme - cluster

  2. On v7 portal host, extract 7.0-WP-UpdateInstaller-AIX.tar.gz to...


  3. Run HealthChecker

    You should get output similar to...

      Total time: 14 minutes 44 seconds

  4. Unzip fix archive...


  5. Copy PM99534.jar to fixes directory


  6. Verify information in wkplc.properties, wkplc_dbtype.properties, wkplc_dbdomain.properties, and wkplc_comp.properties...

    • PortalAdminPwd and WasPassword parameters in wkplc.properties
    • DbUser and DbPassword in wkplc_dbdomain.properties

  7. Disable automatic synchronization

      System administration | Node agents | nodeagent | File Synchronization Service | Automatic Synchronization (uncheck) | OK | Save

  8. Synchronize nodes

      System administration | Nodes | Synchronize

  9. Restart primary node agent

      System administration \ Node agents | nodeagent | Restart

  10. Set up command-line

      cd /opt/IBM/WebSphere1/appserver/bin
      . ./setupCmdLine.sh

  11. Stop WebSphere_Portal

      cd /opt/IBM/WebSphere1/wp_profile/bin
      ./stopServer.sh WebSphere_Portal -username wpsadmin -password ***

  12. Install portal fixes
    cd /opt/IBM/WebSphere1/update
    ./updatePortal.sh -install  \
                      -installDir "/opt/IBM/WebSphere1/PortalServer"  \
                      -fix  \
                      -fixDir "/opt/IBM/WebSphere1/update/fixes"  \
                      -fixes PM99534
                      <!-- -fixes CF026 -->

  13. Run WPVersionInfo to verify

      cd /opt/IBM/WebSphere1/PortalServer/bin
      ./WPVersionInfo.sh > /tmp/WPVersionInfo.txt

  14. Redeploy any customized WCM portlets

    To update the deployed remote rendering portlet:

    1. Backup any files (e.g. custom JSPs) which have been copied to the deployed remote rendering portlet WAR directory

    2. Log in to Portal as the Portal Administrator

    3. Navigate to:

        Administration | Portlet Management | Web Modules

      Find and select the remote rendering portlet web module

      Click the Update Portlet Icon to the right of the selected portlet

      Select the updated portlet WAR file located in:


    4. Click Next and Finish

We cannot upgrade the source portal with a fixpack after migration if you intend to re-migrate the JCR. For example, if the source portal is running V6.1.0.4 and you migrate the portal to v8.0, we cannot then upgrade the source portal to V6.1.0.5 and migrate the JCR again. This is not supported.

Prep source portal

  1. Remove JCR search collections

  2. Remove old WCM versions

  3. Disable JCR Text Search

  4. Enable the clear versions tool and clean up WCM Versions...


  5. Remove obsolete portlets from virtual portal scripts

  6. Disable automatic synchronization

  7. Verify property files

  8. Remove locked WCM content

  9. Create directories for src and tgt...

    • mkdir /opt/IBM/supp_dir
    • mkdir /opt/IBM/backup_dir

  10. Verify WCM library names and virtual portal contexts

    In v8.0, if the name of a web content library is the same as the URL context of a virtual portal, we can experience incorrect rendering behavior. To prevent this issue, rename the library to a different name before you perform the migration. For each web content library with a name that matches the URL context of a virtual portal on the source server, go to...

      Administration | Portal Content | Web Content Libraries | Edit Library icon

    ...enter a new name for the library that is distinct from the URL context of the virtual portal.

Create /opt/IBM and /media mounts on target host

wpsadmin@v8DevHost /home/wpsadmin ->hostname
wpsadmin@v8DevHost /home/wpsadmin ->df -g
Filesystem    GB blocks      Free %Used    Iused %Iused Mounted on
/dev/hd4           3.00      2.81    7%    11397     2% /
/dev/hd2          11.00      7.32   34%    59609     4% /usr
/dev/hd9var        4.00      3.66    9%     8940     2% /var
/dev/hd3           4.00      3.94    2%      101     1% /tmp
/dev/hd1           3.00      2.96    2%       72     1% /home
/dev/hd11admin      3.00      3.00    1%        9     1% /admin
/proc                 -         -    -         -     -  /proc
/dev/hd10opt       4.00      3.80    6%     7187     1% /opt
/dev/livedump      0.25      0.25    1%        4     1% /var/adm/ras/livedump
/dev/lvapp        50.00     49.80    1%        4     1% /opt/IBM

Dmgr directory: /opt/IBM/WebSphere
Portal directory: /opt/IBM/WebSphere1
Verify /tmp > 3 GB free

wpsadmin@v8TstHost /home/wpsadmin ->df -g
Filesystem    GB blocks      Free %Used    Iused %Iused Mounted on
/dev/hd4           3.00      2.81    7%    11409     2% /
/dev/hd2          11.00      7.32   34%    59730     4% /usr
/dev/hd9var        4.00      3.62   10%     8988     2% /var
/dev/hd3           4.00      3.94    2%       96     1% /tmp
/dev/hd1           3.00      2.96    2%       79     1% /home
/dev/hd11admin      3.00      3.00    1%        9     1% /admin
/proc                 -         -    -         -     -  /proc
/dev/hd10opt       4.00      3.73    7%     8177     1% /opt
/dev/livedump      0.25      0.25    1%        4     1% /var/adm/ras/livedump
/dev/lvportalwps     90.00     89.63    1%        4     1% /opt/IBM
/dev/lvrafrepo     20.00     19.92    1%        4     1% /rafrepo
/dev/lvmedia      50.00     14.17   72%    33264     1% /media

Install Installation Manager

  1. On your notebook computer, download, install, and run XMing X server

  2. In putty, enable X11 forwarding

  3. On target host, install Installation Manager 1.6.2...

      username@v8DevHost /home/username ->xauth list
      v8DevHost/unix:11 MIT-MAGIC-COOKIE-1 0c723ae2ccd7660271b1bafc01b5d55f
      v8DevHost/unix:10 MIT-MAGIC-COOKIE-1 d15b40a439806573a57f10099fa9cfaf
      username@v8DevHost /home/username ->sudo su -
      root@v8DevHost / ->xauth add v8DevHost/unix:10 MIT-MAGIC-COOKIE-1 d15b40a439806573a57f10099fa9cfaf
      root@v8DevHost / ->DISPLAY=localhost:10.0
      root@v8DevHost / ->export DISPLAY
      root@v8DevHost / ->xclock
      root@v8DevHost /cd /media/installmgr
      root@v8DevHost / ./installc -acceptLicense
      root@v8DevHost / cd /opt/IBM/InstallationManager/eclipse
      root@v8DevHost / ./IBMIM

  4. If it does not work, we might need to enable X11 in sshd

    1. vi cd /etc/ssh/sshd_config
    2. Set X11Forwarding yes
    3. stopsrc -s sshd
    4. root@v8DevHost /etc/ssh ->startsrc -s sshd

Install WAS v8.5.5

By default, Portal v8 is installed with WAS v8.0. We can configure Portal v8 with WAS v8.5.5 if you install WAS first, then install Portal v8 specifying "Using existing WAS installation".

The following procedure installs WAS ND v8.5.5 twice, once for a dmgr, once for portal

  1. Download WAS v8.5.5 FP1

  2. On your notebook computer, download, install, and run XMing X server

  3. Log on to target host

  4. Set ulimit for number of files and file blocks

      ulimit -n 20480
      ulimit -f unlimited

  5. Set umask 022 in .profile

  6. Install WAS v8.5.5 binaries for use by dmgr profile

    1. Start Installation Manager


      ...and go to...

        File | Preferences | Repositories | Add Respository

    2. Add WAS v8.5.5 repository...


      ..and then click Apply

    3. On IIM main page, click Install, select the WAS ND package, then click Next...

    4. Accept the license terms, then click Next

    5. Set location of Shared Resources Directory


    6. Set WAS home


    7. Select default features

    8. Accept summary information

    9. On last screen, Select None and Finish

  7. Install WAS v8.5.5 binaries for use by portal profile

    1. Select Install, then select Continue in pop-up panel.

    2. On the Install Packages screen, select...

        Create a new package group

      ...and for Installation Directory select...


    3. Select defaults for remainder of panels, then on summary page, select Install

    4. On last screen, select None, then Finish

  8. Install Fixes

    1. Add repository for WAS 8.5.5 FP 1


      Uncheck: "Search service repositories during installation and updates"

    2. On the main IIM page, select Update

    3. On the "Select a package group to find updates for", select first package group

    4. On the panel, "Select updates to install", verify V8.5.5.1 is selected

    5. On the panel, "Select the features to install", keep defaults, then select Next

    6. On the Summary panel, select Update

    7. After it finishes, do the same for the second package group

Install Portal v8

  1. Add repository...


  2. On Install Packages panel, select IBM WebSphere Portal Server

  3. Select "Create a new package group" and set Installation Directory to...


  4. For migration target host, for features, select only...

    • Config Engine
    • Portal Server Binary

    For non-migration host, for features, select...

    • Config Engine
    • Portal Server Binary
    • Portal Server Profile

  5. On the next screen, select "Existing WebSphere Application Server Root Directory"


    For a non-migration host, we would set node and cell name...

    Cell PortalCell1
    Node PortalNode1

    The dmgr cell and node names MUST be different than the portal cell and node names for the federation step, which we will execute later, to work successfully.

  6. On the Summary page, click install...

    Migration target summary...

    Non-migration target summary...

Upgrade Portal v8 with FP1

  1. Review: Update Portal v8 with FP1

  2. Add FP1 to Installation Manager repository


  3. From Installation Manager select "Update"

  4. If you have more than one fix in your repository, it will try to install them all. To install just FP1, de-select "Show recommended only", then select only "v8.0.0.1"

Update portal with Portal Cumulative Fix 09

After upgrading portal v8 with Cumulative Fix 9 we should be able to syndicate between the v7 and v8 portals, which means we do not have to use the update WCM data after migration procedure to refresh WCM data.

  1. Download CF09

  2. Add CF09 to Installation Manager repository

  3. Change class loader from parent first to parent last.

  4. Stop all WebSphere processes

  5. Update wps.properties to include profile name and location

  6. Install CF09 with Installation Manager GUI

      cd /opt/IBM/InstallationManager/eclipse

    To install from command-line...

    1. Determine offering ID...

        $ cd /opt/IBM/InstallationManager/eclipse/tools
        $ ./imcl listAvailablePackages -repositories /media/CF09/repository.config

    2. Install

      ./imcl install \
             com.ibm.websphere.PORTAL.SERVER.v80_8.0.1.20131217_0755 \
             -repositories /media/CF09/repository.config \
             -installationDirectory /opt/IBM/WebSphere1/PortalServer \
             -sharedResourcesDirectory /opt/IBM/IMShared \
             -log /tmp/imcl.log  \

  7. Start all WebSphere processes

  8. Synchronize nodes

  9. Perform post-upgrade steps

  10. Copy over any custom shared libraries jar files

Migrate v7 dmgr to remote v8 dmgr

  1. From target host, copy filesForDmgr.zip to the source dmgr host...

      scp filesForDmgr.zip wpsadmin@v7host.myco.com:/opt/IBM/WebSphere/AppServer

  2. On source host, stop the dmgr, and unarchive file...

      cd /opt/IBM/WebSphere/Appserver/bin
      cd /opt/IBM/WebSphere/Appserver
      unzip filesForDmgr.zip

    Failure to copy the migration plug-in files to the dmgr can result in the following error when you try to upgrade the ConfigEngine tool:

      com.ibm.websphere.management.exception.InvalidConfigDataTypeException: ADMG0007E: The configuration data type CellCompRegistryCollection is not valid

    If the dmgr profile location is not set to the default location...


    ...copy metadata_wkplc.xml in the compressed file to the actual dmgr profile directory...

      cp ./Appserver/profiles/Dmgr01/config/.repository/metadata_wkplc.xml $MY_DMGR_PROFILE/config/.repository

  3. On the target host, create WAS_V85_aix.ppc64_RemoteMigrSupport.jar...

      cd /opt/IBM/WebSphere/AppServer/bin/migration/bin/
      ./createRemoteMigrJar.sh -targetDir /tmp

  4. Copy file to v7 source environment...

      scp /tmp/WAS_V85_aix.ppc64_RemoteMigrSupport.jar wpsadmin@v7host.myco.com:/tmp
      rm /tmp/WAS_V85_aix.ppc64_RemoteMigrSupport.jar

  5. On source host, extract, set perms, and run WASPreUpgrade...

    mkdir /opt/IBM/WebSphere/AppServer/supp_dir
    mv /tmp/WAS_V85_aix.ppc64_RemoteMigrSupport.jar  /opt/IBM/WebSphere/AppServer/supp_dir
    cd /opt/IBM/WebSphere/AppServer/supp_dir
    jar xvf WAS_V85_aix.ppc64_RemoteMigrSupport.jar
    chmod -R 755 /opt/IBM/WebSphere/AppServer/supp_dir 
    cd /opt/IBM/WebSphere/AppServer/supp_dir/bin/
    ./WASPreUpgrade.sh /opt/IBM/backup_dir  \
                       /opt/IBM/WebSphere/AppServer/  \
                       -oldProfile Dmgr01 \
                       -machineChange true  \
                       -javaoption -Xmx2048m

    If you get an error, we can re-run with trace...

    ./WASPreUpgrade.sh /opt/IBM/backup_dir  \
                       /opt/IBM/WebSphere/AppServer/  \
                       -traceString trace_spec  \
                       -traceFile trace_file  \
                       -oldProfile wp_profile_name  \
                       -machineChange true  \
                       -javaoption  -Xmx2048m

  6. On target host, copy backup_dir to /opt/IBM...

      scp -r wpsadmin@v7host.myco.com:/opt/IBM/backup_dir /opt/IBM

  7. Log on to v7 dmgr console and make a note of dmgr cell and node name.

  8. On target host, create dmgr profile...

    cd /opt/IBM/WebSphere/AppServer/bin/
    ./manageprofiles.sh -create   \
                        -profileName Dmgr01   \
                        -templatePath /opt/IBM/WebSphere/AppServer/profileTemplates/management   \
                        -serverType DEPLOYMENT_MANAGER   \
                        -nodeName v7hostCellManager01  \
                        -cellName v7hostCell01  \
                        -hostName v8host

  9. On target host, run WASPostUpgrade...

    cd /opt/IBM/WebSphere/AppServer/bin/
    ./WASPostUpgrade.sh /opt/IBM/backup_dir  \
                        -profileName Dmgr01 \
                        -oldProfile Dmgr01 \
                        -username wpsadmin \
                        -password foo!  \
                        -replacePorts TRUE  \
                        -backupConfig TRUE  \
                        -scriptCompatibility TRUE \
                        -keepDmgrEnabled TRUE

Migrate appserver nodes

  1. On the portal v8.0 host, run...

      cd /opt/IBM/WebSphere1/PortalServer/bin
      ./genRemMigPkg.sh /tmp

    This creates file...


  2. On source host, create directory to hold files we will extract...

      mkdir /opt/IBM/supp_dir

  3. Copy jar file from target host to supp_dir directory on source host...

      scp /tmp/PORTAL_V8.0.0.1_WAS_V85_aix.ppc64_RemoteMigrSupport.jar wpsadmin@v7srcportal.myco.com:/opt/IBM/supp_dir

  4. On source, extract and set perms...

      cd /opt/IBM/supp_dir
      jar xvf PORTAL_V8.0.0.1_WAS_V85_aix.ppc64_RemoteMigrSupport.jar
      chmod -R 755 /opt/IBM/supp_dir

  5. Set...

      ulimit -n 20000

  6. Clean log directories...

    1. Stop servers

        cd /opt/IBM/WebSphere1/wp_profile/bin
        ./stopServer.sh WebSphere_Portal -username wpsadmin -password ***
        cd /opt/IBM/WebSphere1/AppServer/bin
        ./stopNode.sh -username wpsadmin -password ***
        cd /opt/IBM/WebSphere/AppServer/bin
        ./stopManager.sh -username wpsadmin -password ***

    2. Compress archive logs...

      cd /opt/IBM/WebSphere1/wp_profile/logs/WebSphere_Portal
      for i in `ls verbosegc.* trace_* SystemOut_* SystemErr_*`
          echo $i
          gzip $i

    3. Restart Source portal

        cd /opt/IBM/WebSphere/AppServer/bin
        cd /opt/IBM/WebSphere1/AppServer/bin
        cd /opt/IBM/WebSphere1/wp_profile/bin
        ./startServer.sh WebSphere_Portal

  7. Stop dmgr on target...

      cd /opt/IBM/WebSphere/AppServer/bin

  8. Archive then remove dmgr files in backup_dir...

      cd /opt/IBM
      tar cvf backup_dir.tar backup_dir; gzip backup_dir.tar
      rm -rf backupdir/*

  9. On the source host run WASPreUpgrade...

    cd /opt/IBM/supp_dir/bin/
    ./WASPreUpgrade.sh /opt/IBM/backup_dir \
                       /opt/IBM/WebSphere1/AppServer \
                       -oldProfile wp_profile\
                       -machineChange true \
                       -javaoption -Xmx3096m


    old profile path          = /opt/IBM/WebSphere1/wp_profile/
    old cell                  = v7srcportalCell01
    old node                  = v7srcportal
    old server name           = WebSphere_Portal
    new profile path          = /opt/IBM/backup_dir/profiles/wp_profile/
    new cell                  = v7srcportalCell01
    new node                  = v7srcportal
    isWAS60Release            = false
    isVMMDBRepositoryUsed     = false
    MIGR0303I: The existing Application Server environment is saved.
    MIGR0420I: The first step of migration completed successfully.

  10. On target host, tarball existing backup_dir then remove contents.

      cd /opt/IBM
      tar cvf backup_dir_dmgr.tar backup_dir
      gzip backup_dir_dmgr.tar
      rm -rf backup_dir/*

  11. From target host, copy extracted files from source host...

      scp -r wpsadmin@v7srcportal.myco.com:/opt/IBM/backup_dir/* /opt/IBM/backup_dir

  12. On target, ff there is enough disk space, make another tarball backup. Stop all WebSphere java processes before running

      df -g
      cd /opt/IBM
      tar cvf WebSpherePreProfile.tar WebSphere
      tar cvf WebSphere1PreProfile.tar WebSphere1
      gzip WebSpherePreProfile.tar; gzip WebSphere1PreProfile.tar

  13. Create a profile on the target node:

    cd /opt/IBM/WebSphere1/AppServer/bin
    ./manageprofiles.sh -create  \
                        -defaultPorts  \
                        -enableAdminSecurity false  \
                        -profileName wp_profile  \
                        -profilePath /opt/IBM/WebSphere1/wp_profile  \
                        -templatePath /opt/IBM/WebSphere1/AppServer/profileTemplates/default \
                        -nodeName v7srcportal  \
                        -cellName v7srcportalCell01  \
                        -hostName v8host  \
                        -isDefault  \
                        -omitAction samplesInstallAndConfig defaultAppDeployAndConfig  

  14. On target, update the backup files created when running WASPreUpgrade to point to the new environment. Replace the source deployment manager host name with the target deployment manager host name.


  15. On target host, verify dmgr is started

      cd /opt/IBM/WebSphere/AppServer/bin

  16. On source host, verify dmgr is stopped

  17. Run WASPostUpgrade...

    cd /opt/IBM/WebSphere1/AppServer/bin
    ./WASPostUpgrade.sh /opt/IBM/backup_dir  \
                        -profileName wp_profile  \
                        -oldProfile wp_profile  \
                        -username wpsadmin  \
                        -password foo!  \
                        -includeApps true  \
                        -backupConfig false  \
                        -javaoption -Xmx3096m

    MyCo ProdlineA output...

        old profile path          = /opt/IBM/WebSphere1/wp_profile/
        old cell                  = v7srcportalCell01
        old node                  = v7srcportal
        old server name           = WebSphere_Portal
        new profile path          = /opt/IBM/WebSphere1/wp_profile/
        new cell                  = v7srcportalCell01
        new node                  = v7srcportal
        isWAS60Release            = false
        isVMMDBRepositoryUsed     = false

  18. In the target environment, edit...


    ...and set WasSoapPort and WasRemoteHostName to the target deployment manager.

More info

Set up unique multicast ports

Set unique broadcast ports on target host...

  1. Start node agent

      cd /opt/IBM/WebSphere1/AppServer/bin

  2. Open the WAS admin console and select...

      System administration | Deployment manager | Ports

  3. Update the following ports:

    Source Target

  4. Click...

      System administration | Node agents | node_agent | Ports

    1. Update the following ports:


    2. Repeat this step on all node agents

    Source Target

  5. Click...

      Servers | Server types | WebSphere application servers | application_servers | Ports

    The default value for application_servers is WebSphere_Portal however you may have more servers defined. You need to update the ports on all application servers listed.

  6. Update the following ports:


    Source Target

  7. Fully resynchronize the primary node:

    1. Click...

        System administration | Nodes

    2. Select the check box for the primary node.

    3. Click on Full Resynchronize.

  8. Restart the dmgr and node agent.

      cd /opt/IBM/WebSphere1/AppServer/bin
      ./stopNode.sh -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere/AppServer/bin
      ./stopManager.sh -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere/AppServer/bin
      cd /opt/IBM/WebSphere1/AppServer/bin

Upgrade the ConfigEngine tool

To upgrade the ConfigEngine tool, from the target v8 host, run...

Trace information is stored in the UpgradeConfigEngineTrace.log file in the WP_PROFILE/ConfigEngine/log directory.

Migrate databases

The process of connecting to the domain copies must be done after you upgrade the ConfigEngine tool but before you upgrade the Portal profile. For more information on this process, see the Wiki article: Connecting to database domains

  1. In source environment, in the JCR domain, execute reorgchk and runstats.

    Run the statistics on all the columns in all tables and indexes. Gather at least a minimum level of sampling and distribution.

  2. Restore v7 copies of RELDB, JCRDB, FDBKDB, COMDB, LMDB, and CUSDB to v8 databases, then set all DbUrls in wkplc_dbdomain.properties to point to v8 databases

  3. Verify connectivity from portal v8 host to DB2 host...

      telnet v8DevDb 60004

  4. Optional: Use DB2 client to validate db configuration

  5. Verify values of the following...

      Parameter Recommended Actual
      lock list size 10000  
      package cache size 24000 AUTOMATIC(3214)
      statistics heap size 16384 AUTOMATIC(4384)

  6. On the database copies, verify the Statement Heap size is set to at least 32k.

    1. List the database manager configuration parameters...

        db2 get db cfg for dbname

    2. If the Statement Heap size is smaller than 32k, increase it by running

        UPDATE DB CFG FOR dbname USING stmtheap 32768

  7. Disable all automatic maintenance on the database, including health monitoring.

    DBAs run a full reorg and runstats of all tables once a week (sat 4 am).

  8. Start the dmgr and the node

  9. On the target portal, edit...

    ...and set DB properties...

    • DbUrl


    • DbUser


    • DbPassword


  10. From target portal host, set up DB2 Client jar files...

      mkdir /opt/IBM/WebSphere1/PortalServer/db2drivers
      cd /opt/IBM/WebSphere1/PortalServer/db2drivers
      scp wpsadmin@v7host.myco.com:/opt/IBM/WebSphere1/PortalServer/db2drivers/*.jar .

    Note that it is not uncommon for obsolete DB2 Client jar files are installed on source portal. This can happen, for example, if DB2 Server was upgraded, and nobody remembered to copy latest client jars to portal environment. If this is the case, copy the jar files from the DB2 server host.

  11. Verify paths to Type 4 database drivers, db2jcc4.jar and db2jcc_license_cu.jar, in properties file...

  12. Validate from command-line...

      cd /opt/IBM/WebSphere1/wp_profile/ConfigEngine
      nohup ./ConfigEngine.sh validate-database > validate-database.log

    OK to run with nohup, but do not run as a background process

  13. Increase space in the transaction log...

      db2 update db cfg for jcrdb using logprimary double_current_value
      db2 update db cfg for jcrdb using logsecond double_current_value

  14. Connect to the database domains:

      cd /opt/IBM/WebSphere1/wp_profile/ConfigEngine
      nohup ./ConfigEngine.sh connect-database > connect-database.log

  15. Log on to dmgr console and synchronize nodes...

      System Administrations | Nodes | Synchronize

Property extension database

If we are using a property extension database, on the dmgr, set up access to the database drivers...

  1. In wkplc.properties, set la.DbType

  2. Add library paths to VMM_JDBC_CLASSPATH variable. From the console, got to...

      Environment | WebSphere Variables | Scope: Cell

    ...and set VMM_JDBC_CLASSPATH variable, for example...


    If this variable does not exist, click New to create the variable.

    We can confirm this value by clicking...

    Enter the complete paths to the library files in Value. These files must be JDBC Version 4 compliant, for example...


  3. Stop and restart the appropriate servers to propagate the changes.

  4. Create the local dmgr WebSphere variable used to access the database drivers:
    ./ConfigEngine.sh wp-prep-vmm-db-secured-environment  \
                      -DWasPassword=foo \
                      -DDbDomain=la|federated.db  \
                      -Ddb_type.NodeDbLibrary=/path/to/dmgr/jars  \

  5. Create the variable used to access the VMM database drivers:
    cd /opt/IBM/WebSphere1/wp_profile/ConfigEngine
    ./ConfigEngine.sh wp-node-prep-vmm-db-secured-environment \
                    -DWasPassword=dmgr_password \
                    -DDbDomain=la|federated.db \
                    -DVmmNodeName=node_name \

    VmmNodeName is a list of one or more nodes names in the cell which share the same database driver paths. The db_type in db_type.NodeDbLibrary should be set to the type of database we are using, for example db2.

Retain custom table spaces

If a database domain in the earlier portal server uses assigned custom table spaces to retain for use on the new portal server (instead of using the default table spaces), update the table space property file and the index space property file for the database table. Complete these updates only after you have upgraded the ConfigEngine tool.

To retain assigned custom table spaces, update these files on the target portal server:

Make tarball backup

Tarball backups allow us to restore portal filesystems without having to contact infrastructure backup team. We back up dmgr, portal, and Installation Manager directories.

  1. Log on as root and verify there is enough space...

      cd /opt/IBM
      du -gs WebSphere
      du -gs WebSphere1
      df -k

  2. If enough space, make tarball...

      cd /opt/IBM/WebSphere1/wp_profile/bin
      ./stopServer.sh WebSphere_Portal -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere1/appserver/bin
      ./stopNode.sh -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere/appserver/bin
      ./stopManager.sh -username wpsadmin -password foo!
      cd /opt/IBM
      tar cvf WebSphereD.tar WebSphere
      gzip WebSphereD.tar
      tar cvf WebSphere1D.tar WebSphere1
      gzip WebSphere1D.tar
      tar cvf InstallationManager.tar /var/ibm/InstallationManager
      gzip InstallationManager.tar
      tar cvf IMShared.tar /opt/IBM/IMShared
      gzip IMShared.tar
      cd /opt/IBM/WebSphere/appserver/bin
      cd /opt/IBM/WebSphere1/appserver/bin
      cd /opt/IBM/WebSphere1/wp_profile/bin
      ./startServer.sh WebSphere_Portal

Upgrade wp_profile

We run the upgrade-profile task to upgrade the v7 profile, wp_profile, from v7 to v8.

The longest running part of this long running script (2+ hrs) is the modification of the JCR schema from JCR7.0.0.2 to JCR8.0.0.1

After running any ConfigEngine tasks, IBM recommends to review...

  1. Start dmgr and node agents

  2. In dmgr console, synchronize all nodes.

  3. On the primary node.

    cd /opt/IBM/WebSphere1/wp_profile/ConfigEngine 
    ./ConfigEngine.sh upgrade-profile  \
                      -DWasPassword=foo!  \
                      -DPortalAdminPwd=foo!   \

    If upgrade-profile fails, we can restart using:

    For example:


    To get resume_point, we can review the ConfigEngine logs in...


    If upgrade-profile files with error...

      Fri Dec 27 15:56:16 CST 2013 Target started: import-nodes import-nodes: --- Exception Thrown --- /opt/IBM/WebSphere1/PortalServer/jcr/wp.content.repository.install/config/includes/jcr.install_cfg.xml:826: com.ibm.icm.jcr.task.TaskException: TASK001X: Remote task execution failed with response code 404 due to exception : Not Found

    ...and WebSphere_Portal/SystemOut.log has:

      [12/27/13 15:56:16:601 CST] 00000128 filter E com.ibm.ws.webcontainer.filter.FilterInstanceWrapper doFilter SRVE 8109W: Uncaught exception thrown by filter Extensible Filter: java.io.FileNotFoundException: SRVE0190E: File not found: /jcr/remotetask

    The portal wiki has a fix...

    ./ConfigEngine.sh action-create-ear-wp.content.repository.install \
                      -DWasPassword=foo!  \
    ./ConfigEngine.sh action-modify-servlet-path-wp.content.repository.install \
                      -DWasPassword=foo!  \
    ./ConfigEngine.sh action-connect-database-edit-ear-wp.content.repository.install \
                      -DWasPassword=foo!  \

    Synchronize nodes and restart all processes...

      cd /opt/IBM/WebSphere1/wp_profile/bin
      ./stopServer.sh WebSphere_Portal -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere1/AppServer/bin
      ./stopNode.sh -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere/AppServer/bin
      ./stopManager.sh -username wpsadmin -password foo!
      cd /opt/IBM/WebSphere1/AppServer/bin
      cd /opt/IBM/WebSphere1/wp_profile/bin
      ./startServer.sh WebSphere_Portal

    Then retry...

    ./ConfigEngine.sh upgrade-profile  \
                      -DWasPassword=foo!  \
                      -DPortalAdminPwd=foo!   \

  4. Start the portal server

    cd /opt/IBM/WebSphere1/wp_profile/bin
    ./startServer.sh WebSphere_Portal

  5. To verify, open portal in web browser...

Upgrade default administration theme

The portal migration process uses v7 administration themes. After successful migration, to use v8 administration themes, run the following ConfigEngine tasks.

If the migrated v7 theme does not render correct, we can set the Portal v8 theme as default.

Install Welcome Portlet

Log on to portal and go to admin page...

...and install...

See also: Deploying portlets common across clusters

Update portlet urls

After migrating, verify and update as needed the portlets URLs. In some cases, portlets have the incorrect URL after migration.

Perform the following steps in the newly migrated environment....

  1. Export the portlet configuration for both base and virtual portals...

    cd /opt/IBM/WebSphere1/PortalServer/bin
    ./xmlaccess.sh -in /opt/IBM/WebSphere1/PortalServer/doc/xml-samples/ExportAllPortlets.xml \
                   -user wpsadmin \
                   -password foo! \
                   -url http://v8host.myco.com:10039/wps/config \
                   -out /tmp/Server_config.xml
    ./xmlaccess.sh -in /opt/IBM/WebSphere1/PortalServer/doc/xml-samples/ExportAllPortlets.xml \
                   -user wpsadmin \
                   -password foo! \
                   -url http://v8host.myco.com:10039/wps/config/URL_mapping_context_of_the_VP \
                   -out /tmp/Server_configVP.xml

    The exported configuration is stored in Server_config.xml

  2. Verify output XML file and update URLs as needed.

    Edit Server_config.xml and verify that all URLs are valid. All the files listed in the XML file must be present and accessible in the specified locations. For example..

      $ grep "<url>" /tmp/Server_config.xml | grep sitemap.war
      $ find /opt/IBM/WebSphere1/wp_profile -name sitemap.war | grep installedApps

    If the URLs do not match the actual location in your environment, update those entries according to the actual location of the files.

    If the files specified in the URL field do not exist in the migrated environment or are no longer needed in the configuration, remove those entries.

  3. Modify the XML file to remove the global-settings and services-settings entries

  4. Import the updated configuration using the Server_config.xml file you updated:

    cd PortalServer_root/bin
    ./xmlaccess.sh -in Server_config.xml \
                   -user wpsadmin \
                   -password foo! \
                   -url http://v8host.myco.com:port/wps/config

    After the request has been processed, make sure that the import process has given the following return message:

      <status element="all" result="ok">

  5. Resync the cluster from the Deployment Manager console.

  6. Restart the Enterprise Applications from the Deployment Manager console.

  7. Activate the deployed portlets:

      ./ConfigEngine.sh activate-portlets -DWasPassword=password

  8. Restart the portal.

Rebuild search indexes

Before you migrated the search components, you exported the search collections as XML files and deleted the search collections from the Manage Search portlet. After migrating to the current version of WebSphere Portal, we can rebuild your search indexes.

  1. Create the new search collections.

  2. Import the backed up configuration information for each of the search collections.

  3. Check if the URLs for the crawlers are still valid.

  4. Stop the WebSphere Portal server.

  5. If the schedules have not been set, start the crawlers manually.

    Ignore this step if schedules have been set. When schedules are set, the crawlers update the search collections.

JSP files and Web content plug-ins

Any JSP files used on the old system will need to be manually copied to the new system. Any Web content plug-ins used on the old system, such as custom workflows, will need to be manually copied to the new system and enabled.

Update authoring portlet theme

You must change the theme of the hidden Web Content Manager authoring portlet to Portal 8.0 theme, otherwise Web Content Manager related portlets do not work properly.

  1. Log in to Portal as an administrator and go to...

  2. In the Search by menu select...

      Unique name contains

    ...and search for...


  3. Select...

      Web Content Manager page | Edit Page Properties | Theme field | Portal 8.0 | OK

Configure Web Server Plug-in

  1. Review v7 source properties

    Web server properties...

    Web server name webserver1
    Port 80
    Web server installation location /opt/IBM/HTTPServer
    Configuration file name /opt/IBM/HTTPServer/conf/httpd.conf

    Plug-in properties...

    Web server copy of Web server plug-in files /opt/IBM/Plugins/config/webserver1/plugin-cfg.xml
    Plug-in key store directory and file name /opt/IBM/Plugins/config/webserver1/plugin-key.kdb
    Plug-in logging /opt/IBM/Plugins/logs/webserver1/http_plugin.log

  2. Use Installation Manager to install WebSphere Customization Toolbox

    Install into /opt/IBM/Websphere/WebSphere/Toolbox

    root@v8host /opt/IBM/WebSphere/Toolbox ->ls -l
    total 24
    drwxr-xr-x    5 root     system          256 Jan 07 16:22 WCT
    drwxr-xr-x    3 root     system          256 Jan 07 16:22 bin
    drwxr-xr-x    8 root     system         4096 Jan 07 16:22 java
    drwxr-xr-x    2 root     system         4096 Jan 07 16:22 lafiles
    drwxr-xr-x    3 root     system         4096 Jan 07 16:22 lib
    drwxr-xr-x    2 root     system          256 Jan 07 16:22 plugins
    drwxr-xr-x    6 root     system          256 Jan 07 16:22 properties
    drwxr-xr-x    2 root     system          256 Jan 07 16:22 uninstall
    drwxr-xr-x    2 root     system          256 Jan 07 16:22 util

  3. In IHS httpd.conf file, set...

      Listen 80

  4. Start web server and admin server

      cd /opt/IBM/HTTPServer/bin
      ./apachectl start
      ./adminctl start

  5. Run the WCT GUI...

      cd /opt/IBM/WebSphere/Toolbox/WCT

  6. Specify port 80.

  7. Choose "local" install

  8. Review summary info then click Configure.

  9. Create web server definition

      cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
      . ./setupCmdLine.sh
      cp /opt/IBM/Plugins/bin/configurewebserver1.sh .

  10. Log on to dmgr and verify web server definition was created.

  11. Synchronize nodes

  12. Add rewrite rules at end of httpd.conf, right before plug-in directives.

  13. Configure LoadModule
    # LoadModule foo_module modules/mod_foo.so
    LoadModule authz_host_module modules/mod_authz_host.so
    LoadModule auth_basic_module modules/mod_auth_basic.so
    LoadModule authn_file_module modules/mod_authn_file.so
    LoadModule authz_user_module modules/mod_authz_user.so
    #LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
    LoadModule include_module modules/mod_include.so
    LoadModule log_config_module modules/mod_log_config.so
    LoadModule env_module modules/mod_env.so
    #LoadModule mime_magic_module modules/mod_mime_magic.so
    LoadModule expires_module modules/mod_expires.so
    LoadModule headers_module modules/mod_headers.so
    LoadModule unique_id_module modules/mod_unique_id.so
    LoadModule setenvif_module modules/mod_setenvif.so
    #LoadModule proxy_module modules/mod_proxy.so
    #LoadModule proxy_connect_module modules/mod_proxy_connect.so
    #LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
    #LoadModule proxy_http_module modules/mod_proxy_http.so
    LoadModule mime_module modules/mod_mime.so
    #LoadModule dav_module modules/mod_dav.so
    #LoadModule dav_fs_module modules/mod_dav_fs.so
    LoadModule autoindex_module modules/mod_autoindex.so
    #LoadModule asis_module modules/mod_asis.so
    #LoadModule info_module modules/mod_info.so
    LoadModule cgid_module modules/mod_cgid.so
    LoadModule dir_module modules/mod_dir.so
    LoadModule actions_module modules/mod_actions.so
    #LoadModule speling_module modules/mod_speling.so
    #LoadModule userdir_module modules/mod_userdir.so
    LoadModule alias_module modules/mod_alias.so
    LoadModule rewrite_module modules/mod_rewrite.so
    LoadModule deflate_module modules/mod_deflate.so
    LoadModule cache_module modules/mod_cache.so

  14. Restart web server

      cd /opt/IBM/HTTPServer/bin
      ./apachectl restart

    Add myhost.myvirtualportal.com to...


  15. Pull up virtual portal

SSL test:

../bin/gskcmd -keydb \
              -create \
              -db ihsserverkey.kdb \
              -pw password \
              -type cms \
              -expire 360 \
../bin/gskcmd -cert \
              -create \
              -db ihsserverkey.kdb \
              -pw password \
              -size 1024 \
              -dn "CN=v8host.myco.com,O=clientd,OU=IBM HTTP Server,ST=FL,C=US" \
              -label HTTPCert \
              -default_cert yes \
              -expire 360

Create web server definition and plug-in configuration from command-line

Example of the content of a response file for an IHS local plug-in configuration.


The following is an example of the content of a response file for an IHS remote plug-in configuration.


Delete a definition...

./wctcmd.sh -tool pct 
            -defLocPathname /data/IBM/WebSphere/Plugins 
            -defLocName DefinitionLocationName 
            -deleteDefinition DefinitionName 

Remove a definition location...
./wctcmd.sh -tool pct 
            -defLocPathname /data/IBM/WebSphere/Plugins


./wctcmd.sh -tool pct 
            -defLocName someDefinitionLocationName

Enable JCR text search indexing

Before beginning with migration, we disabled JCR text search indexing in the v7 environment. Now that the migration is complete, we need to re-enable JCR text search indexing.



...and set...

    key = jcr.textsearch.enabled
    value = true

Restart portal for the changes to take effect.

Create JCR search collection

To create the default JCRCollection1 search collection, log on to Portal as an administrator and go to...

    Applications | Content | Web Content Management

Edit the portlet and save it. You do not have to actually change anything, saving the configuration triggers the indexing. A new JCRCollection1 JCR search collection is generated automatically.