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

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

Managed application server node ${zNodeShortName}
Deployment manager ${zFederateDmaNodeHostName}, port ${zFederateDmaPort}
Tailored on ${ZDATE} at ${ZTIMEL} by ${ZUSER}
WCT version ${wctVersion} build ${wctBuild}

The managed 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(BBOMNINS)

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.
These will be used during the federation process of your managed node.

Type	Number
SOAP JMX Connector port	`${zFederateJmxSoapConnectorPort}`
Node Discovery port	`${zFederateNodeDiscoveryPort}`
Node Multicast Discovery Port	`${zFederateNodeMulticastDiscoveryPort}`
Node IPv6 multicast discovery port	`${zFederateNodeIPv6MulticastDiscoveryPort}`
Node Agent's ORB port	`${zFederateOrbPortName}`
Admin local port	`${zFederateAdminLocalPort}`
High Availability Manager Communication port	`${zFederateHamCommPort}`
Node Agent's ORB SSL port	`${zFederateOrbSslPortName}`

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(BBOTCPIM)

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.

Attention: Skip this step if the ports are already defined in the TCP/IP profile.

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.

For more information, consult the WebSphere Application Server for z/OS Information Center and Chapter 20, RACF and z/OS Unix, in the z/OS Security Server RACF Security Administrator's Guide (SA22-7683).

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 BBOMBRAK

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
```
    ${zTargetHLQ}.DATA(BBOMBRAC)  
```
Type Userid UID

Asynch admin user ID ${zAdminAsynchTaskUserid} ${zAdminAsynchTaskUid}

Daemon user ID ${zDaemonUserid} ${zDaemonUid}

Adjunct user ID ${zAdjunctUserid} ${zAdjunctUid}

"*" 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 BBOMBRAK. 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.

Type	Userid	UID
Asynch admin user ID	`${zAdminAsynchTaskUserid}`	`${zAdminAsynchTaskUid}`
Daemon user ID	`${zDaemonUserid}`	`${zDaemonUid}`
Adjunct user ID	`${zAdjunctUserid}`	`${zAdjunctUid}`

Check WebSphere Application Server home directories.

Verify that the following directories exist on your target z/OS system and that the ownership and permission bits are correct:

 
    ${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

If the these directories do not exist, create them with the above ownership and permission bits.

The security domain configuration job BBOSBRAM can be used to create these directories if necessary.

Run job BBOMSGC
User ID requirement: Update authority for data set SYS1.MSGENU and/or SYS1.MSGJPN.

Attention: This is optional unless you require message translation.

This job sets up MMS to translate messages for WebSphere Application Server for z/OS.

Before running this job, update the INPUT DD statements to point to the SBBOMSG dataset for your installation.
There are two steps to update: One that performs a copy to SYS1.MSGENU and one that performs a copy to SYS1.MSGJPN. Remove the unneeded step and if necessary, change the target libraries.
Check user ID authorizations

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.

Check 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 Application Server 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} ${zAdminAsynchTaskUserid}) 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 the BBOMCFS job
- User ID requirement: File system update authority (see above), and the authority to allocate ${zConfigHfsName}
- This job completes two tasks:
  - Creates a mount point directory ${zConfigMountPoint}
  - Allocates the configuration file system ${zConfigHfsName} and mounts it at the above mount point.
  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:
    - Allocate the configuration file system data set.
    - 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 BBOMCFS 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 BBOMCFS.
  
  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 BBOMHFSA 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: If the SCEERUN data set is not in the system link list, add that data set to STEPLIB for the CHECKV step in BBOMHFSA.
  
  After you completed this step, check the job output. Success is indicated with a RC=0 in the job output.
Run the BBOWWPFM 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: If the SCEERUN2 data set is not in the system link list, add that data set to STEPLIB for the LIBVSCRP step in BBOWWPFM.
  
  After you have completed this step, examine the job output. Success is indicated by rc=0.
  
  Note: If the BBOWWPFM (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 BBOWWPFM to fail and re-run the job.
Run the BBOMPROC job
- User ID requirement: File system update authority, and the authority to update the cataloged procedure library ${zProclibName}
  
  This job creates the tailored cataloged procedures and copies them to your procedure library.
  
  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} ${zAdjunctProcName} ${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 you modify the setupCmdLine.sh script, do not remove lines or comment them out, this may cause problems with automated updates to the script.

Add only those data sets that 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
WebSphere-managed security update. If both your target Network Deployment cell and the cell containing the node you are federating use WebSphere-managed security, and both cells are using file-based keystores, run the retrieveSigners.sh script from the home directory of the node being federated:

${zConfigMountPoint}/${zWasServerDir}/bin/retrieveSigners.sh CellDefaultTrustStore ClientDefaultTrustStore -port ${zFederateDmaPort} -conntype ${zFederateDmaPortType} -user ${zFederateDmaSecurityUserID} -password ${zFederateDmaSecurityPassword} -autoAcceptBootstrapSigner
Check administrative security. You need to verify that your target Network Deployment cell is running without administrative security. You should enable administrative security after you have federated to prevent unauthorized access to the Network Deployment cell.
Run the BBOWMNAN job
- User ID requirement:
  1. File system update authority (see above).
  2. If the Network Deployment cell uses a z/OS LocalOS (SAF) registry, then the user ID used to run this job must be connected to the Network Deployment cell's configuration group.
  3. If SSL certificates are stored in SAF keyrings, then the user ID used to run this job must have a SAF keyring named ${zDefaultSAFKeyringName} and this keyring must contain the Network Deployment cell's CA certificate.
  If you choose the start the node agent automatically, the user ID used to run BBOWMNAN will also need the authority to issue the MVS START command.
  
  This job will federate your node into the specified Network Deployment cell. Ensure that the cell's Deployment Manager is running before submitting this job.
  
  After you complete this step, check the job output. Success is indicated with a RC=0 in the job output.
Update WLM policy. If your system is busy, you may want to include a rule in your WLM policy that OMVS work for job ${zFederateServerShortName} (such as the postinstaller step) is to run in a service class with a high service objective.
Start the node agent server

Issue the following MVS command to start your node agent server, replacing <dmgr_cell_short_name> with the cell short name of the target Deployment Manager cell:

START ${zControlProcName},JOBNAME=${zFederateServerShortName},ENV=<dmgr_cell_short_name>.${zNodeShortName}.${zFederateServerShortName}

Result: The following message appears on the console and in the job log of ${zFederateServerShortName}.

BBOO0019I INITIALIZATION COMPLETE FOR WEBSPHERE FOR z/OS CONTROL PROCESS ${zFederateServerShortName}

Note: The node agent will already be started if you chose to start the node agent after federation. Use this command to start the node agent at other times.
The product is now configured.

You may create and manage application servers in the node using the administrative console or scripting.

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