Instructions for migrating a WebSphere Application Server for z/OS standalone application server node

If your back-level version of WebSphere Application Server is using the unrestricted jurisdiction policy files, you must perform the following special step to migrate these files to your new version of WebSphere Application Server. If you are not using the unrestricted jurisdiction policy files, you do not need to take the following step.

Before migrating, copy the modified local_policy.jar file to a temporary location.

The z/OS Migration Management Tool has created jobs based on the information that you provided. These instructions tell you how to modify the operating system and run the jobs to migrate WebSphere Application Server for z/OS. When you upload the migration definition to the target system, a text version of these instructions will be written to:

  ${zTargetHLQ}.CNTL(BBOMBINS)

Guidelines

Upload the migration definitions to the following data sets on the target system:
```
  ${zTargetHLQ}.CNTL
  ${zTargetHLQ}.DATA
```
Before proceeding to execute any jobs, ensure the above datasets have been defined with the correct characteristics.

The ${zTargetHLQ}.CNTL datasets should be defined with the following characterists: PRIMARY=15 SECONDARY=15 TRACKS LRECL=80 BLKSIZE=8000 DIRECTORY=30 RECFM=FB

Also ensure that the ${zTargetHLQ}.DATA datasets have been defined with the following characteristics: PRIMARY=5 SECONDARY=5 TRACKS LRECL=255 BLKSIZE=0 DIRECTORY=30 RECFM=VB
You must use these instructions on your target system.

Performing manual configuration updates

The z/OS Migration Management Tool for WebSphere Application Server for z/OS does not attempt to update configuration data for your base operating system or existing subsystems. You must take the following manual steps before running the WebSphere Application Server for z/OS migration jobs. Because you are migrating an existing system, some of these steps might have already been taken in your previous installation.

Update your active BPXPRMxx member to have the following WebSphere Application Server for z/OS configuration file system:
```
  ${zConfigHfsName}
```
mounted at:
```
  ${zmbToConfigRoot}
```
in read and write mode.
For example:
```
  MOUNT FILESYSTEM('${zConfigHfsName}')
  MOUNTPOINT('${zmbToConfigRoot}')
  TYPE(${zFilesystemType})
  MODE(RDWR)
```
If you are configuring in a sysplex environment, you might want to add the NOAUTOMOVE parameter as follows:
```
  MOUNT FILESYSTEM('${zConfigHfsName}')
  MOUNTPOINT('${zmbToConfigRoot}')
  TYPE(${zFilesystemType})
  MODE(RDWR) SYSNAME(<system_name>) NOAUTOMOVE
```
The NOAUTOMOVE parameter in this example prevents the configuration file system from being mounted on a different z/OS system in a shared file system configuration, which could cause performance problems. Replace <system_name> with the applicable system name for your installation.
Update SCHEDxx. To set the correct program properties for the WebSphere for z/OS run-time executables, append the following contents to the SCHEDxx member in your system PARMLIB concatenation.
Alternatively, once the customization jobs are uploaded to the target z/OS system, you may append the contents of the following paritioned data set member to the SCHEDxx member:
```
    ${zTargetHLQ}.CNTL(BBOSCHED)
```
Note: When you are finished updating SCHEDxx, issue the command SET SCH=xx to activate SCHEDxx and load a new program properties table. This action does not need to be performed if the target z/OS system is at z/OS 1.9 or above, as the BPXBATA2 entry that the BBOSCHED member contains already exists in the IBM-supplied PPT table at those z/OS levels.
WebSphere Application Server for z/OS customization assumes that the following system data sets are in the system link list or link pack area:
```
  Language Environment     SCEERUN
                           SCEERUN2

  System SSL               SIEALNKE (z/OS 1.6 and above)
  64-bit Support Code      SCLBDLL2 
```
Placing these data sets in the link list or link pack area improves performance and insulates your WebSphere Application Server for z/OS configuration from changes in data set names (for example, when migrating to z/OS 1.6).

If the Language Environment or System SSL load module libraries are not in your system link list or link pack area, take the following steps before starting any WebSphere Application Server for z/OS servers:
- Make sure that the data sets are APF-authorized.
- Complete the optional step below to add the data sets to STEPLIB in the server JCL and setupCmdLine.sh scripts.
If you regenerate server cataloged procedures at any point, make sure that the data sets are added to the new cataloged procedures.
Set up security system rules to run the Version 8.5 daemon and application server controller under the same user IDs as used for your previous version.
If you use RACF for your security system, use the following instructions. If you use another SAF-compliant security system, contact the security system vendor for appropriate information.

Check your MVS system log or use the TSO RLIST STARTED command to determine the user ID and group under which your previous daemon runs. (The previous default daemon user ID and group are WSDMNCR1 and WSCFG1). Then, issue the following RACF command to create a corresponding STARTED profile for the Version 8.5 daemon cataloged procedure:
```
  RDEFINE STARTED ${zmbDaemonProcName}.*
          STDATA(USER(user) GROUP(group) TRACE(YES))
  SETROPTS RACLIST(STARTED) GENERIC(STARTED) REFRESH
```
Check your MVS system log or use the TSO RLIST STARTED command to determine the user ID and group under which your previous application server controller runs. (The previous default application server controller user ID and group are ASCR1 and WSCFG1.) Then, issue the following RACF command to create a corresponding STARTED profile for the Version 8.5 application server controller cataloged procedure:
```
  RDEFINE STARTED ${zmbControllerProcName}.*
          STDATA(USER(user) GROUP(group) TRACE(YES))
  SETROPTS RACLIST(STARTED) GENERIC(STARTED) REFRESH
```
Because the STARTED profile for the application server servant is based only on the job name, no additional STARTED profile should be needed for the application server servant, which has the same job name before and after migration.
Add the security profiles that were first required in Version 6.1.
If you use RACF for your security system, use the following instructions. If you use another SAF-compliant security system, contact the security system vendor for appropriate information.

Check your MVS system log or use the administrative console to determine if Enable Trusted Applications is set for your server. (Look for control_region_security_enable_trusted_applications in the startup log; if it is set to 1, then Enable Trusted Applications is set.) If it is set, create the following SAF profile and grant READ access to the application server control region user ID:
```
  BBO.TRUSTEDAPPS.<cell_shortname>.<cluster_transition_name>
```
Use the following RACF commands to accomplish this:
```
  RDEFINE FACILITY
          BBO.TRUSTEDAPPS.<cell_shortname>.**
          UACC(NONE)
  PERMIT  BBO.TRUSTEDAPPS.<cell_shortname>.**
          CLASS(FACILITY)  ID(<config_group>)  ACCESS(READ)
          SETROPTS RACLIST(FACILITY) REFRESH
```
Check your MVS system log or use the administrative console to determine if Sync to OS Thread Allowed is set for your server. If it is set, then create the following SAF profile and grant either READ or CONTROL access to the application server control region user ID:
```
  BBO.SYNC.<cell_shortname>.<cluster_transition_name>
```
Granting CONTROL access to the application server control region user ID allows the thread identity to be switched to any user ID that requests Sync to OS Thread:
```
  RDEFINE FACILITY
          BBO.SYNC.<cell_shortname>.**
          UACC(NONE)
  PERMIT  BBO.SYNC.<cell_shortname>.**
          CLASS(FACILITY)  ID(<config_group>)  ACCESS(CONTROL)
  SETROPTS RACLIST(FACILITY) REFRESH
```
As an alternative, you can grant the control region READ access to this profile, which restricts the user IDs to which the thread identity can be changed based on SAF SURROGAT profiles. See the Version 8.5 information center for more information.

Note that Enable Trusted Applications must be set if the LocalOS registry or SAF authorization is used. If needed, the new SAF profiles must be created before servers are started at Version 8.5.

If the server being migrated uses SAF authorization for EJB roles, you might need to create EJBROLE profiles for the deployer and adminsecuritymanager roles that were added in Version 6.1. Use the following RACF commands to create the profiles:
```
  RDEFINE  EJBROLE (optionalSAFProfilePrefix.)deployer
           UACC(NONE)
  RDEFINE  EJBROLE (optionalSAFProfilePrefix.)adminsecuritymanager
           UACC(NONE)
  SETROPTS RACLIST(EJBROLE) REFRESH
```
The adminsecuritymanager role must be granted to any administrator who needs to update WebSphere Application Server console users and groups (for example, in preparation for an LDAP or custom user registry with non-SAF authorization). The administrator user ID created during configuration should usually be granted this role:
```
  PERMIT   (optionalSAFProfilePrefix.)adminsecuritymanager
           CLASS(EJBROLE)  ID(WSADMIN)  ACCESS(READ)
  SETROPTS RACLIST(EJBROLE) REFRESH
```
Add the security profile that was first required in Version 7.0.
If the server being migrated uses SAF authorization for EJB roles, you might need to create an EJBROLE profile for the auditor role that was added in Version 7.0. Use the following RACF commands to create the profile:
```
  RDEFINE  EJBROLE (optionalSAFProfilePrefix.)auditor
           UACC(NONE)
  SETROPTS RACLIST(EJBROLE) REFRESH
```
The auditor role should be granted to users who need to view and modify the configuration settings for the security auditing subsystem. The administrator user ID created during configuration should usually be granted this role:
```
  PERMIT   (optionalSAFProfilePrefix.)auditor
           CLASS(EJBROLE)  ID(WSADMIN)  ACCESS(READ)
  SETROPTS RACLIST(EJBROLE) REFRESH
```

Running the migration jobs

The z/OS Migration Management Tool built a number of batch jobs with the variables that you supplied. You must run the jobs in the order listed below using user IDs with the appropriate authority.

Note: Whenever "file system update authority" is indicated, the user ID used to run the configuration job must have either uid = 0 or the following UNIXPRIV class profile privileges:

  CONTROL access to SUPERUSER.FILESYS
  UPDATE  access to SUPERUSER.FILESYS.MOUNT
  READ    access to SUPERUSER.FILESYS.CHOWN
  READ    access to SUPERUSER.FILESYS.CHANGEPERMS
  READ    access to SUPERUSER.FILESYS.PFSCTL

If the UNIXPRIV profile CHOWN.UNRESTRICTED is defined, then the SUPERUSER.FILESYS.CHOWN is not required. For information about the UNIXPRIV class, see the z/OS Unix System Services Planning book.

Before you begin, complete the section above that is titled "Performing manual configuration updates."

Follow the steps in the section below, which lists in order the jobs that you must submit and the commands that you must enter. Special handling notes are included in the section. All jobs are members of ${zTargetHLQ}.CNTL.

Attention: After submitting each job, carefully check the output. Errors might exist even when all return codes are zero.

Unless otherwise indicated, these jobs must be submitted by a user ID that has authority to alter file permissions, change file ownership, and change group membership of all files. Please read the instructions for each job carefully before submitting it.

Managed Base Node Migrations

The previous and the new administrative agents cannot be running at the same time. To migrate managed application servers, only start the previous administrative agent. After the managed application server is migrated, it will be unregistered from the old administrative agent as part of the migration process. After migration re-register this base application server to the new administrative agent.

Note: If the managed base node is also registered to a job manager, the managed base node must be unregistered from the job manager before migration. After migration is completed, you will need to register the application server to any job manager that it was registered to before migration and recreate the jobs.

It is recommended that you migrate the managed application servers by following these steps:

Migrate the previous administrative agent to Version 8.5.
Start the previous administrative agent if it is not already running.
If registered to a job manager, unregister the the managed base application servers from job manager.
Migrate all the managed base application servers that are registered to the previous administrative agent, one at a time.
Stop the previous administrative agent.
Start the Version 8.5 administrative agent.
Register the migrated application servers one at a time to the Version 8.5 administrative agent.
Register the migrated application servers to any job managers that it was registered to before migration.
Recreate jobs that were being executed by the managed application servers.

Run job BBOMBHFS.
User ID requirement:

The user ID that submits this job must have file system update authority (see above) and the authority to allocate ${zConfigHfsName}.

Before running this job, do the following:
Verify that the DD statement that defines the data set is valid for the storage rules defined on the target system.
This job is not required if you already have a suitable mount point. If you are required to manually create the directory structure, this job performs the following tasks:
- Creates a mount point directory
```
  ${zmbToConfigRoot}
```
- Allocates the configuration file system using the hierarchical file system (HFS)
```
  ${zConfigHfsName}
```
- Mounts the file system at the mount point
Do not run this job if any of the following are true:
- The configuration file system already exists and is mounted at the desired mount point.
- The mount point directory is controlled by automount.
  Either disable the automount rule for the configuration mount point while running this job, or perform the following steps manually:
  1. Allocate the configuration file system data set.
  2. Issue the following shell command, which will also cause automount to mount the file system:
    chmod 775 ${zmbToConfigRoot}
Before you begin:

The BBOMBHFS job assumes that your root file system is mounted in read and write mode. If the root file system is not mounted in read and write mode, manually create the directory ${zmbToConfigRoot}.

For example:
If you plan to use /WebSphere/V8R5 as your directory, issue the following command from within the OMVS shell:
```
  mkdir -p -m 775 /WebSphere/V8R5
```
Attention:
The migration procedure will set the file ownership and permissions to match your previous configuration. Verify that the mount point directory is owned by your WebSphere Application Server administrator and that the group is assigned to the Administrators group. If it is not, then determine the user ID and group ID values that are designated as owners of the previous WebSphere Application Server configuration. Either the numeric ID values or the user name and group name can be used. Issue the following command within the OMVS shell, replacing <owner> and <group> with the user and group determined previously. Also replace <mount_point> with ${zmbToConfigRoot}:
```
  chown <user>:<group>  <mount_point>
```
Status of task Date
Run job BBOMBZFS.
User ID requirement:

The user ID that submits this job must have file system update authority (see above) and the authority to allocate ${zConfigHfsName}.

Before running this job, do the following:
Verify that the DD statement that defines the data set is valid for the storage rules defined on the target system.
This job is not required if you already have a suitable mount point. If you are required to manually create the directory structure, this job performs the following tasks:
- Creates a mount point directory
```
  ${zmbToConfigRoot}
```
- Allocates the configuration file system using the z/OS Distributed File Service zSeries File System (zFS)
```
  ${zConfigHfsName}
```
- Mounts the file system at the mount point
Do not run this job if any of the following are true:
- The configuration file system already exists and is mounted at the desired mount point.
- The mount point directory is controlled by automount.
  Either disable the automount rule for the configuration mount point while running this job, or perform the following steps manually:
  1. Allocate the configuration file system data set.
  2. Issue the following shell command, which will also cause automount to mount the file system:
    chmod 775 ${zmbToConfigRoot}
Before you begin:

The BBOMBZFS job assumes that your root file system is mounted in read and write mode. If the root file system is not mounted in read and write mode, manually create the directory ${zmbToConfigRoot}.

For example:
If you plan to use /WebSphere/V8R5 as your directory, issue the following command from within the OMVS shell:
```
  mkdir -p -m 775 /WebSphere/V8R5
```
Attention:
The migration procedure will set the file ownership and permissions to match your previous configuration. Verify that the mount point directory is owned by your WebSphere Application Server administrator and that the group is assigned to the Administrators group. If it is not, then determine the user ID and group ID values that are designated as owners of the previous WebSphere Application Server configuration. Either the numeric ID values or the user name and group name can be used. Issue the following command within the OMVS shell, replacing <owner> and <group> with the user and group determined previously. Also replace <mount_point> with ${zmbToConfigRoot}:
```
  chown <user>:<group>  <mount_point>
```
Status of task Date
Run job BBOMBCP.
```
  ${zmbProclibName}
```
Attention:

WebSphere Application Server Version 8.5 requires the new STARTED procedures that you provided when you created your migration definition. Depending on what these are, you might be required to create additional RACF STARTED profiles.

It is recommended that you use the same user ID and group memberships that you you used in your previous version.

This job copies the tailored start procedures, parameters, and EXECs to the runtime libraries.
Be aware that you might overlay existing members in the above data set.

Status of task Date
Run job BBOWMG1B.
This job must be submitted from a WebSphere Application Server administrator's user ID.
1. Stop the application server.
2. Submit the job, and verify that the return code is 0.
3. Restart the application server, and wait for it to perform PRR processing and terminate.
4. If the server does not terminate after a few minutes, stop the server.
This job is not required if you do not have any XA connectors installed in your previous server. If you have any XA connectors, then submit this job.

Status of task Date
Run job BBOWMG2B.
This job must be submitted from a WebSphere Application Server administrator's user ID.
1. After completing BBOWMG1B, submit this job.
2. Submit the job, and verify that the return code is 0.
This job is not required if you do not have any XA connectors installed in your previous server. If you ran BBOWMG1B, then submit this job.

Status of task Date
Select whether to migrate the profile using a single job OR as a multi-job process.
The steps for migrating a profile include:
1. creating a target profile in the new release.
2. creating a backup of the source profile.
3. migrating the backup profile into the new profile.
All three steps can be done using a single job (BBOWMG3B) OR
they can be individually submitted in this order: BBOWBPRO, BBOWBPRE, BBOWBPOS

The user ID that submits the job(s) must have file system update authority.
Submit the job, and verify that the return code is 0. If using the multi-job option verify the return code is 0 before submitting the next job.
This job performs the main migration procedure. Based on the information that you provided when you created your migration definition and your previous configuration, your previous server will be migrated to Version 8.5.

Note: If you selected to deploy the applications by script, you can use the following generated script to deploy your applications to the new environment. The script also contains further instructions about deploying applications.
```
  ${zmbTempDirectory}/${zmbTimestamp}/base_backup/install_all_apps.jy
```
Status of task Date
All WebSphere Application Server processes require access to the Language Environment and System SSL load modules.
If the SCEERUN, SCEERUN2, and System SSL load module libraries are not in the system link list or link pack area, add them to the STEPLIB DD concatenation in each of the following cataloged procedures in ${zmbProclibName}:
```
  ${zmbControllerProcName}
  ${zmbServantProcName}
  ${zmbDaemonProcName}
```
and also add the full data set names, separated by colons (:), to the STEPLIB variable in the shell script:
```
  ${zmbToConfigRoot}/
  ${zmbToWASHomeDir}/
  profiles/default/bin/setupCmdLine.sh
```
When modifying the setupCmdLine.sh script, do not remove lines or comment them out, as this might cause problems with automated updates to the script.

Add only those data sets that are not in the link list or link pack area.

Status of task Date
Permit the servant's user ID read access to the z/OS Workload Manager (WLM) server profile.
WebSphere Application Server for z/OS Version 8.5 requires that the servant's address space be authorized to interface with the WLM. The following RACF commands must be issued to permit the application server's STARTED task user ID to have READ access to the WLM server profile.:
```
  PE BPX.WLMSERVER CLASS(FACILITY) ID(<servant_user_id>) ACCESS(READ)
  SETROPTS RACLIST(FACILITY) REFRESH
```
Status of task Date
Shut down the application servers and daemon.
The daemon is required to run at the Version 8.5 level of code for all the servers that it manages on the same LPAR. It will be at the Version 8.5 level when the server is started.

Copy unrestricted jurisdiction policy files

If you saved a copy of local_policy.jar in the beginning of the migration process take the following steps:

1)After migration completes successfully, mount the new product hfs read/write.

2)Copy the modified local_policy.jar from the temporary location to the following directory on the new WebSphere Application Server installation: WAS_HOME/java/lib/security

3)Mount the new product HFS as read/only

Status of task Date
Start the application server.
Use the existing commands that you currently use to start your previous server, but replace the STARTED procedure name with the value that you entered when you created your migration definition:
```
  ${zmbControllerProcName}
```
This command starts the application server. Wait until the server has finished initializing before proceeding.

The following message appears on the console and in the job log of BBOS001:
```
  BBOO0019I INITIALIZATION COMPLETE FOR WEBSPHERE FOR z/OS CONTROL PROCESS BBOS001
```
Status of task Date

Migration has now been completed.

Status of task	Date

Status of task	Date

Status of task	Date

Status of task	Date