Instructions for customizing WebSphere Application Server for z/OS for a Deployment Manager node.

WebSphere Application Server for z/OS V8.5 customization instructions:

Deployment manager ${zServerShortName} (cell ${zCellShortName}, node ${zNodeShortName}) Job manager ${zServerShortName} (cell ${zCellShortName}, node ${zNodeShortName}) Administrative agent ${zServerShortName} (cell ${zCellShortName}, node ${zNodeShortName})
Tailored on ${ZDATE} at ${ZTIMEL} by ${ZUSER}
WCT version ${wctVersion} build ${wctBuild}

The management node will be configured with:

${productName}

The Profile Management Tool has created a response file based on the information you provided. These instructions tell you how to convert this response file into a set of customization jobs and how to run the jobs to customize WebSphere Application Server for z/OS. When you upload the customization jobs to the target system, a text version of these instructions will be written to:

 
    ${zTargetHLQ}.CNTL(BBOCCINS)

Guidelines

Create the customization jobs and upload them to the following data sets on the target system:
```
    ${zTargetHLQ}.CNTL
    ${zTargetHLQ}.DATA
```
Use the Process action to create the customization jobs and upload them to the target z/OS system.
You need to use these instructions on your target system.

Manual configuration updates

The Profile Management Tool does not attempt to update configuration data for your base operating system or existing subsystems. You need to perform the following manual steps prior to running the WebSphere for z/OS configuration jobs.

Update BLSCUSER. To use the IPCS support provided by the product, append the following contents to the BLSCUSER member in your IPCSPARM or system PARMLIB dataset.
Alternatively, once the customization jobs are uploaded to the target z/OS system, you may append the contents of the following partitioned data set member to the BLSCUSER member:
```
    ${zTargetHLQ}.CNTL(BBOIPCSP)
```
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.
Update SMFPRMxx. To collect the SMF120 records created by the run-time servers, update SMFPRMxx to include record type 120, as in the following example:
```
       SUBSYS(STC,EXITS(IEFU29,IEFACTRT),INTERVAL(SMF,SYNC),TYPE(0,30,70:79,88,89,120,245))
```
For details on the SMF records, see related topics in the WebSphere for z/OS Information Center.
Update your active BPXPRMxx member to have the following WebSphere Application Server for z/OS configuration file system:
${zConfigHfsName} mounted at: ${zConfigMountPoint} in read/write mode.

Example:
 MOUNT FILESYSTEM('${zConfigHfsName}') MOUNTPOINT('${zConfigMountPoint}') TYPE(${zFilesystemType}) MODE(RDWR) NOAUTOMOVE   MOUNT FILESYSTEM('${zConfigHfsName}') MOUNTPOINT('${zConfigMountPoint}') TYPE(${zFilesystemType}) MODE(RDWR) PARM('AGGRGROW') NOAUTOMOVE  Note: The NOAUTOMOVE parameter 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.

If you have specified "aggrgrow=on" in your IOEFSPRM parmlib member, you can omit the AGGRGROW parm shown in the above examples

Update TCP/IP by reserving the following ports for WebSphere Application Server for z/OS:

Type	Number
SOAP JMX Connector port	`${zSoapPort}`
Cell Discovery Address port	`${zCellDiscoveryPort}`
ORB port	`${zOrbListenerPort}`
ORB SSL port	`${zOrbListenerSslPort}`
Administrative console port	`${zAdminConsolePort}`
Administrative console secure port	`${zAdminConsoleSecurePort}`
Admin local port	`${zAdminLocalPort}`
High Availability Manager Communication port	`${zHighAvailManagerPort}`
Middleware Agent RPC port	`${zMiddlewareAgentPort}`
Administration Overlay UDP port	`${zAdminOverlayUDPPort}`
Administration Overlay TCP port	`${zAdminOverlayTCPPort}`
Status update listener port	`${zStatusListenerPort}`
Daemon IP port	`${zDaemonPort}`
Daemon SSL port	`${zDaemonSslPort}`

Add the following contents to the PORT section of the TCP/IP profile that is used by the TCP/IP start procedure.

Alternatively, once the customization jobs are uploaded to the target z/OS system, you may append the contents of the following partitioned data set member to the PORT section of the TCP/IP profile:

    ${zTargetHLQ}.CNTL(BBOTCPID)

Attention: If another application has already reserved any of these ports for its own use, you must resolve the resulting conflict before you continue. If you use the Profile Management Tool to update the port specifications, be sure to upload the updated customization jobs.

Note: It is recommended that the IPCONFIG, UDPCONFIG, and TCPCONFIG RESTRICTLOWPORTS be defined in your TCP/IP profile to only allow super users or APF-authorized user applications to bind to privileged ports (1-1024), unless the SAF keyword is specified and the user ID binding to the port is permitted to the SAF resource. It is left up to the users' discretion to determine whether this is viable course of action given the users' specific application/port requirements. For more information please consult: z/OS Communication Server IP Configuration Guide.

WebSphere Application Server for z/OS customization assumes that the following system data sets are in the system link list: Language Environment SCEERUN SCEERUN2 System SSL SIEALNKE Support for 64-bit SCLBDLL2
See the Language Environment Customization manual and the System SSL Programming manual for your z/OS release for advice on placing members from the libraries into the system link pack area.

Placing these data sets in the link list insulates your WebSphere Application Server for z/OS configuration from changes in data set names (for example, when migrating to newer releases of z/OS).

If the Language Environment or System SSL load module libraries are not in your system link list, you need to perform the following steps before starting any WebSphere Application Server for z/OS servers:
- Check 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 script(s).
If you regenerate server cataloged procedures at any point, make sure the data sets are added to the new cataloged procedures.

Running the customized jobs

The Profile Management Tool built a number of batch jobs with the variables you supplied. You need to run the jobs in the order listed below, using user IDs with the appropriate authority.

Before you begin: Complete the section above entitled "Manual configuration updates".

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

By default, the customization jobs below are all generated with REGION=0M. If this is not an allowable value on your target system, you may need to modify this value for your environment. Your system must allow a private region of sufficient size to allow the running of a Java Virtual Machine Region with a maximum heap specification of 256 Megabytes (i.e., -Xmx256m). Installation constraints that limit the region size or system exits that restrict the region a job is running in, may cause the customization jobs to fail due to a JVM error. In the event of an Out Of Memory (OOM) failure due to inadequate native storage, you must remove this constraint in order to successfully install WebSphere for z/OS.

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

The BBOSBRAK and BBOSBRAM jobs do not need to be run if the indicated groups, user IDs and directories already exist with the correct gid, uid and ownership permission values, as given below.

In order for RACF to automatically select an unused UID or GID value for WebSphere Application Server user IDs and groups:

- The RACF profile SHARED.IDS must be defined.
- The RACF profile BPX.NEXT.USER must be define and use to indicate the ranges from which UID and GID values are to be selected.

See the article "Preparing the Security Server (RACF)" in the WebSphere Application Server for z/OS online information center. For more information, consult Chapter 20, "RACF and z/OS Unix", in the z/OS Security Server RACF Security Administrator's Guide (SA22-7683).

Some of the customization jobs write temporary files to the /tmp directory. For each of these jobs, the customization process provides an alternate job that will write temporary files to the directory specified by the TMPDIR environment variable. If the TMPDIR environment variable is not defined, then the /tmp directory is used. These alternate jobs require a minimum WebSphere Application Server for z/OS service level of 8.5.5.0 on the target system. Refer to Customizing your .profile in z/OS UNIX System Services User's Guide (SA22-7801-14) for information on defining environment variables.

Run job BBOSBRAK

User ID requirement: RACF special authority.

This job excutes the RACF commands to create common WebSphere Application Server for z/OS groups and user IDs. These commands are located in
${zTargetHLQ}.DATA(BBOSBRAC)

Type	Group/userid	GID/UID
Administrator user ID	`${zAdminUserid}`	`${zAdminUid}`
Control user ID	`${zControlUserid}`	`${zControlUid}`
Servant user ID	`${zServantUserid}`	`${zServantUid}`
Configuration group	`${zConfigurationGroup}`	`${zConfigurationGroupGID}`
Servant group	`${zServantGroup}`	`${zServantGroupGID}`
Local user group	`${zLocalUserGroup}`	`${zLocalUserGroupGID}`

"*" denotes that the system will assign a GID/UID.

Carefully review these definitions with your security administrator.

If the group and user IDs named above have already been created during a previous WebSphere Application Server for z/OS configuration and are in all target system RACF databases, you do not need to rerun this job.

Note: This job creates the WebSphere administrator ID ${zAdminUserid} without a password (or password phrase). You must assign this user ID a password (or password phrase) that complies with your institution standards. This is also the password (or password phrase) that will be used when logging on to the WebSphere Application Server administrative console.

Enter the following RACF command to assign a password:

	ALTUSER ${zAdminUserid} PASSWORD(password) NOEXPIRED

Enter the following RACF command to assign a password phrase:

	ALTUSER ${zAdminUserid} PHRASE('password phrase') NOEXPIRED

If you are using a different security system, make sure that the ${zAdminUserid} has a password or password phrase.

To use RACF password phrase support, your target system must be at z/OS Version 1.9 or above

Result: You may receive errors, such as INVALID USER messages, from this job because a user ID, group or profile is already defined. Make sure the existing user ID, group, or profile has the same characteristics as the user ID, group, or profile being created by BBOSBRAK. If not, then change the values in the Profile Management Tool, which are causing the conflict. Then upload the updated customization jobs and restart the process.

When this step is complete, all groups and user IDs listed above for job BBOSBRAK should be defined in the RACF database on each target system for the cell.

Note: The WebSphere Application Server administrator user ID ${zAdminUserid} must have the WebSphere Application Server configuration group ${zConfigurationGroup} as its default OMVS group.

Run job BBOSBRAM
- User ID requirement: File system update authority (see above).
  
  This job creates home directories for WebSphere Application Server for z/OS user IDS. These home directories will be subdirectories of ${zUserIDHomeDirectory}
  This job will create the following directories:
```
 
    ${zUserIDHomeDirectory} 
                                               
         ownership:       (any)                                         
         permission bits: 755                                     
                                                                    
    ${zUserIDHomeDirectory}/${zConfigurationGroup} 
                                     
         ownership:       ${zControlUserid}:${zConfigurationGroup}                             
         permission bits: 770                                     
                                                                 
    ${zUserIDHomeDirectory}/${zServantGroup}
                                      
         ownership:       ${zControlUserid}:${zServantGroup}                                    
         permission bits: 770                                     
                                                                     
    ${zUserIDHomeDirectory}/${zLocalUserGroup} 
            
         ownership:       ${zControlUserid}:${zLocalUserGroup}                             
         permission bits: 770
```
  This job should be run on each z/OS system that will host WebSphere Application Server nodes using these WebSphere Application Server for z/OS common groups and owner user ID. After execution, verify that the directories have been created with the correct permissions on each system.
  
  If these directories already exist with the specified ownership and permission on a target system, then this job does not need to be run on that system.
  
  Attention: If the directory ${zUserIDHomeDirectory} is used by applications other than WebSphere Application Server, make sure that the permissions set by BBOSBRAM (755) are appropriate, or change them manually. This directory must be world-readable for Websphere Application Server to run correctly.
Run job BBODBRAK

User ID requirement: RACF special authority.

This job executes the RACF commands to create RACF users and profiles required by this WebSphere for z/OS node. These commands are located in

Type Userid UID

Type Userid UID

Unauthenticated user ID ${zAdminUnauthenticatedUserid} ${zAdminUnauthenticatedUid}

Daemon user ID ${zDaemonUserid} ${zDaemonUid}

"*" denotes that the system will assign a UID.
"*" denotes that the system will assign a UID.
Carefully review these definitions with your security administrator.

Result: You may receive errors, such as INVALID USER messages, from this job because a user ID, group or profile is already defined. Make sure the existing user ID, group or profile has the same characteristics as the user ID, group or profile being created by BBODBRAK. If not, then change the values in the Profile Management Tool which are causing the conflict, upload the updated customization jobs, and restart the process.
Check user ID authorization
- Make sure the ${zConfigurationGroup} group has read access to all WebSphere product data sets, as well as to any other data sets which will be placed in WebSphere Application Server for z/OS cataloged procedure STEPLIB concatenations.
- Make sure the following user IDs have read access to the resolver configuration file in use on your system. Depending on your IP setup, this file may be /etc/resolv.conf, SYS1.TCPPARMS(TCPDATA), or another data set. ${zControlUserid} ${zServantUserid}
  See the z/OS eNetwork Communication Server IP Configuration manual for the resolver search order.
  Ensure the following user ID has read access to the data sets in your system parmlib concatenation:
```
                                                                  
    ${zControlUserid}                                                


    ${zDaemonUserid}                                                
```
- Attention: If operator commands are protected by the z/OS security server at your installation, you must ensure that sufficient authority is given to WebSphere tasks to control operations.
  The deployment manager The job manager The administrative agent controller user ID (${zControlUserid}) needs the ability to perform operations on started tasks belonging to WebSphere Application Server for z/OS.
  The asynchronous administrator user ID, and any user ID used to run the federation job when the node agent is started automatically, need the authority to issue the MVS START command.
  If you are currently controlling MVS console command authority with SAF OPERCMDS profiles, grant the following authorities as indicated, substituting your own profile names:
  PERMIT START_profile_name CLASS(OPERCMDS) ID (${zControlUserid}) ACCESS(UPDATE) PERMIT STOP_profile_name CLASS(OPERCMDS) ID (${zControlUserid}) ACCESS(UPDATE) PERMIT MODIFY_profile_name CLASS(OPERCMDS) ID (${zControlUserid}) ACCESS(UPDATE) PERMIT CANCEL_profile_name CLASS(OPERCMDS) ID (${zControlUserid}) ACCESS(UPDATE) PERMIT FORCE_profile_name CLASS(OPERCMDS) ID (${zControlUserid}) ACCESS(UPDATE)
  You must also grant the appropriate console command authority to any user ID that executes the startServer.sh or stopServer.sh script.
Run job BBODCFS
- User ID requirement:
  File system update authority (see above), and the authority to allocate
  ${zConfigHfsName}
- Attention: Skip this step if the mount point is already created, such as for the stand-alone Application Server.
- This job does two tasks:
  1. Creates a mount point directory
    ${zConfigMountPoint}
  2. Allocates the configuration file system
    ${zConfigHfsName} and mounts it at the above mount point.
  Note: You can run job BBO855CM instead of BBODCFS if the target WebSphere Application Server for z/OS installation image is at least at the 8.5.5.0 service level. The BBO855CM job will use the directory specified by the TMPDIR environment variable, if defined, for temporary files. The user ID requirements for the BBO855CM and BBODCFS jobs are the same.
  
  Do not run this job if:
  1. The configuration file system already exists and is mounted at the desired mountpoint, or if
  2. 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 commands, which will also cause automount to mount the file system chmod 775 ${zConfigMountPoint} chown ${zAdminUserid}:${zConfigurationGroup} ${zConfigMountPoint}
  Before you begin:
  The BBODCFS job assumes your root file system is mounted in read/write mode. If the root file system is not mounted in read/write mode, manually create the directory
  ${zConfigMountPoint}
  and any needed higher directories. Set file permissions to 775 and set the owning user ID and group to ${zAdminUserid} and ${zConfigurationGroup} before running BBODCFS.
  
  Example: If you plan to use /wasv8config as your directory, issue the following commands from within the OMVS shell: mkdir -p -m 775 /wasv8config chown -R ${zAdminUserid}:${zConfigurationGroup} /wasv8config
Run the BBODHFSA job
- User ID requirement:
  File system update authority (see above).
  This job populates the previously-created configuration file system and prepares it for profile creation.
  Note: You can run job BBO855HM instead of BBODHFSA if the target WebSphere Application Server for z/OS installation image is at least at the 8.5.5.0 service level. The BBO855HM job will use the directory specified by the TMPDIR environment variable, if defined, for temporary files. The user ID requirements for the BBO855HM and BBODHFSA jobs are the same.
- Note: If the SCEERUN data set is not in the system link list, add that data set to STEPLIB for the CHECKV step in BBODHFSA.
- Upon completion, examine the job output. Success is indicated with a RC=0 in the job output.

Type	Userid	UID
Unauthenticated user ID	`${zAdminUnauthenticatedUserid}`	`${zAdminUnauthenticatedUid}`
Daemon user ID	`${zDaemonUserid}`	`${zDaemonUid}`

Verify the IBM SDK for Java selection

By default the WebSphere Application Server node will be configured to use the IBM SDK for Java 6 with 64-bit addressing. To configure with a different SDK enter the following commands:

            
         cd ${zConfigMountPoint}/${zWasServerDir}/bin
         
         ./managesdk.sh -setNewProfileDefault -sdkName XXXXXX

where XXXXXX is set to one of the following values:

         1.6_31   (IBM SDK for Java 6 with 31-bit addressing)
         1.6_64   (IBM SDK for Java 6 with 64-bit addressing)
         1.7_31   (IBM SDK for Java 7 with 31-bit addressing)
         1.7_64   (IBM SDK for Java 7 with 64-bit addressing)
         1.7.1_31 (IBM SDK for Java 7.1 with 31-bit addressing)
         1.7.1_64 (IBM SDK for Java 7.1 with 64-bit addressing)

Note that you must have the IBM WebSphere SDK for Java(TM) Technology Edition Version 7.0 or 7.1 installed to specify one of the Java 7 or 7.1 SDKs. Use the following commands to determine which SDKs are available:

            
         cd ${zConfigMountPoint}/${zWasServerDir}/bin
         
         ./managesdk.sh -listAvailable

Run the BBOWWPFD job
- User ID requirement:
- File system update authority (see above).
- This job creates a profile (set of configuration files for a node) in the configuration file system.
  Note: You can run job BBO855PM instead of BBOWWPFD if the target WebSphere Application Server for z/OS installation image is at least at the 8.5.5.0 service level. The BBO855PM job will use the directory specified by the TMPDIR environment variable, if defined, for temporary files. The user ID requirements for the BBO855PM and BBOWWPFD jobs are the same.
  
  Note: If the SCEERUN2 data set is not in the system link list, add that data set to STEPLIB for the LIBVSCRP and WPROFILE steps in BBOWWPFD.
  Upon completion, examine the job output. Success is indicated by rc=0.
  Note: If the BBOWWPFD (profile creation) job fails, you must perform the following steps to clean up the partially-built profiles:
```
            
         cd ${zConfigMountPoint}/${zWasServerDir}
         
         ./bin/manageprofiles.sh -deleteAll
         
         rm -R profiles
```
  Then correct the problem that caused BBOWWPFD to fail and re-run the job.
Run the BBODPROC job
- User ID requirement: Authority to update the cataloged procedure library ${zProclibName}
  This job creates the tailored cataloged procedures and copies them to your procedure library.
  Note: You can run job BBO855RM instead of BBODPROC if the target WebSphere Application Server for z/OS installation image is at least at the 8.5.5.0 service level. The BBO855RM job will use the directory specified by the TMPDIR environment variable, if defined, for temporary files. The user ID requirements for the BBO855RM and BBODPROC jobs are the same.
- Attention: Be aware that you may overlay existing members in the above data set.
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, add them to the STEPLIB DD concatenation in each of the following cataloged procedures in ${zProclibName}: ${zControlProcName} ${zServantProcName} ${zDaemonProcName} and also add the full data set names, separated by colons (:), to the STEPLIB variable in the shell script
```
${zConfigMountPoint}/${zWasServerDir}/profiles/default/bin/setupCmdLine.sh               
```
When modifying the setupCmdLine.sh script, do not remove lines or comment them out, as this may cause problems with automated updates to the script.
Add only those data sets which are NOT in the link list.
Make sure Resource Recovery Services (RRS) is active. (See the online information center for setup instructions if necessary.) Look for the following console message to verify that RRS was successfully started:
ASA2011I RRS INITIALIZATION COMPLETE. COMPONENT ID=SCRRS
Update WLM policy. If your system is busy, you may want to include a rule in your WLM policy that OMVS work for job ${zServerShortName} (such as the postinstaller step) is to run in a service class with a high service objective.
Start the Deployment Manager Start the Job Manager Start the Administrative Agent
- Result: The following message appears on the console and in the job log of ${zServerShortName}
  BBOO0019I INITIALIZATION COMPLETE FOR WEBSPHERE FOR z/OS CONTROL PROCESS ${zServerShortName}
The deployment manager The job manager The administrative agent is now configured

To run this server in a reusable address space, add ",REUSASID=YES" to the end of the START command. See the article "Reusable address space" in the WebSphere Application Server for z/OS Information Center for more information, and important restrictions.

To access the administrative console, point a Web browser at:

http://${hostName}:${zAdminConsolePort}/ibm/console

To stop the location service daemon and all servers associated with it on this MVS system, enter the MVS command:
STOP ${zDaemonJobName}