Instructions for customizing WebSphere Application Server for z/OS for a stand-alone Application Server node.

The stand-alone application server will be configured with:

${zAugmentingProductData}

The Profile Management Tool has created jobs based on the information you provided. These instructions tell you how to modify the operating system and 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(BBOSSINS)

Guidelines


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.



  1. Update BLSCUSER. To use the IPCS support provided by the product, append the contents of the cntl/bboipcsp file within this customization definition to the BLSCUSER member in your IPCSPARM or system PARMLIB dataset.

    Status of task Date
         



  2. Update SCHEDxx.
    Refer to the cntl/bbosched file within this customization definition.

    In order to set the correct program properties for the WebSphere for z/OS run-time executables, append the contents of this member to the SCHEDxx member in your system PARMLIB concatenation.

    Note: When you are finished, issue the command SET SCH=xx to activate SCHEDxx and load a new program properties table.

    Status of task Date
         



  3. Check that the following data sets are APF-authorized: ${zBbolpaName} ${zBboloadName} ${zBbgloadName} ${zBbolod2Name} ${zAppServerBbolpaName} ${zAppServerBboloadName} ${zAppServerBbgloadName} ${zAppServerBbolod2Name}

    Add these datasets to your PROGxx or IEAAPFxx parmlib members, as appropriate, ensuring you specify the correct volsers.
    Note: You must add the actual data set names to your parmlib members and not any aliases you may have specified.


    Status of task Date
         


  4. 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.

    Status of task Date
         


  5. 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) PARM('AGGRGROW') MOUNT FILESYSTEM('${zConfigHfsName}') MOUNTPOINT('${zConfigMountPoint}') TYPE(${zFilesystemType}) MODE(RDWR) If you are configuring in a sysplex environment, you may wish to use the NOAUTOMOVE parameter as follows:
    MOUNT FILESYSTEM('${zConfigHfsName}') MOUNTPOINT('${zConfigMountPoint}') TYPE(${zFilesystemType}) MODE(RDWR) PARM('AGGRGROW') SYSNAME(${zSystemName}) NOAUTOMOVE MOUNT FILESYSTEM('${zConfigHfsName}') MOUNTPOINT('${zConfigMountPoint}') TYPE(${zFilesystemType}) MODE(RDWR) SYSNAME(${zSystemName}) 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

    Status of task Date
         


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

    Type Number
    SOAP JMX Connector port ${zSoapPort}
    ORB port ${zOrbListenerPort}
    ORB SSL port ${zOrbListenerSslPort}
    Administrative console port ${zAdminConsolePort}
    Administrative console secure port ${zAdminConsoleSecurePort}
    HTTP Transport port ${zHttpTransportPort}
    HTTPS Transport port ${zHttpTransportSslPort}
    High Availability Manager Communication port ${zHighAvailManagerPort}
    Service Integration port ${zServiceIntegrationPort}
    Service Integration Secure port ${zServiceIntegrationSecurePort}
    Service Integration MQ Interoperability port ${zServiceIntegrationMqPort}
    Service Integration MQ Interoperability Secure port ${zServiceIntegrationSecureMqPort}
    Session Initiation Protocol (SIP) port ${zSessionInitiationPort}
    Session Initiation Protocol (SIP) port ${zSessionInitiationPort}
    Session Initiation Protocol (SIP) secure port ${zSessionInitiationSecurePort}
    Daemon IP port ${zDaemonPort}
    Daemon SSL port ${zDaemonSslPort}

    Add the contents of the cntl/bbotcpip file within this customization definition to the PORT section of the file referenced by the DD statement for the TCP/IP profile in the TCP/IP start procedure. Copy and paste from this file into the data set used by your installation.

    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.


    Status of task Date
         


  7. The WebSphere product libraries will be placed in the system link pack area (LPA) and system link list.

    Check that no other copies of WebSphere Application server, from any release, reside in the link pack area or the system link list. Also, check that the target MVS system has at least 40MB of free storage in the extended CSA if SBBOLOAD is placed in the link pack area, or 8MB of free storage in extended CSA for the daemon and for each node (deployment manager node or application server node), if SBBOLOAD is placed in the link list.


    SBBOLOAD

    You can either load the SBBOLOAD modules into the dynamic link pack area, which we recommend, or place SBBLOAD in the system link list.


    SBBGLOAD

    If your servers will be running in 64-bit mode, the SBBGLOAD data set must be added to the system link list or link pack area following the same procedure as for the SBBOLOAD data set.

    SBBOLD2

    Place the SBBOLD2 data set into the system link list. This data set must NOT be placed in the system link pack area; separate copies of the SBBOLD2 modules need to be loaded into each WebSphere Application Server address space.

    Status of task Date
         


  8. The WebSphere product libraries are placed in STEPLIB as needed, rather than in the system link pack area and system link list.
    Make sure that the target MVS system has at least 8MB of free storage in extended CSA for the daemon and for EACH node (deployment manager node or application server node).

    SBBOLOAD, SBBGLOAD and SBBOLD2

    The following data sets will be placed in the STEPLIB concatenation for the location service daemon, controller and servant regions, and in the setupCmdLine.sh script in the WebSphere Configuration file system. You must not remove these STEPLIB statements.
    ${zBboloadName} ${zBbgloadName} ${zBbolod2Name}
    The following data sets will be placed in the STEPLIB concatenation for the location service daemon, deployment manager controller and servant regions, and in the setupCmdLine.sh script in the WebSphere Configuration file system for the deployment manager. You must not remove these STEPLIB statements.
                                                                                   
        ${zBboloadName}
        ${zBbgloadName}                                                                       
        ${zBbolod2Name}
    
    The following data sets will be placed in the STEPLIB concatenation for the application server controller, controller adjunct and servant regions, and in the setupCmdLine.sh script in the WebSphere Configuration file system for the application server. You must not remove these STEPLIB statements.
                                                                                   
        ${zAppServerBboloadName}
        ${zAppServerBbgloadName}                                                                       
        ${zAppServerBbolod2Name}
    

    BBORTS61

    The BBORTS61 module is used by WebSphere Application Server for component trace support. A copy of this module (any maintenance level) must be in the system link pack area in order for CTRACE to work correctly.

    If a copy of BBORTS61 is currently loaded into LPA, no further action is required.

    Otherwise, issue the following MVS console command to load BBORTS61 into dynamic LPA:

    SETPROG LPA,ADD,MODNAME=BBORTS61,DSNAME=${zBbolpaName}

    Alternatively, you can place the following statement in a parmlib PROGxx member, which is activated with the SET PROG=xx command after system IPL is complete:

    LPA ADD MODNAME(BBORTS61) DSNAME(${zBbolpaName})

    Check that the BBORTS61 module is loaded into LPA after each system IPL.

    Status of task Date
         


  9. 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 (z/OS 1.6 and above)

    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 z/OS 1.6).

    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:


    If you regenerate server cataloged procedures at any point, make sure the data sets are added to the new cataloged procedures.

    Status of task Date
         


  10. If the error logstream ${zErrorLogstreamName} does not already exist on your target system, make a copy of the appropriate job in the SBBOJCL data set, customize it according to the comments in the job, and run: BBOERRLC Create an error logstream in a coupling facility BBOERRLD Create a DASD-only error logstream
    Status of task Date
         


  11. WebSphere Application Server for z/OS regions open a large number of files (more than 1024). Make sure your BPXPRMxx parmlib member(s) specify a value of MAXFILEPROC that is greater than or equal to 2000. Use the following MVS console command to see your current MAXFILEPROC setting: D OMVS,OPTIONS

    Status of task Date
         







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.


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

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

The next three jobs (BBOSBRAJ, BBOSBRAK, BBOSBRAM) 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 InfoCenter. For more information, consult Chapter 20, "RACF and z/OS Unix", in the z/OS Security Server RACF Security Administrator's Guide (SA22-7683).

  1. Run job BBOSBRAJ
    The commands are placed into member BBOSBRAK of data set
    ${zTargetHLQ}.DATA
    Carefully review these definitions with your security administrator.

    Status of task Date
         


  2. Run job BBOSBRAK

    User ID requirement: RACF special authority.

    This job executes the RACF commands created by the previous job. 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.

    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 BBOSBRAJ should be defined in the RACF database on each target system for the cell.

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


    Status of task Date
         


  3. Run job BBOSBRAM

    Status of task Date
         


  4. 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.

    There are two steps to update SYS1.MSGENU and SYS1.MSGJPN. Remove the unneeded step and change the target libraries, if necessary.



    Status of task Date
         


  5. Run job BBOCBRAJ

    User ID requirement: Authority to update data set

    ${zTargetHLQ}.DATA
    This job builds (but does not execute) the RACF commands for the WebSphere for z/OS run-time clusters and places them into member BBOWBRAK of data set
    ${zTargetHLQ}.DATA
    Carefully review these definitions with your security administrator.

    Status of task Date
         


  6. Run job BBOCBRAK

    User ID requirement: RACF special authority.



    This job executes the RACF commands set up in the previous job.

    This job creates the WebSphere administrator ID ${zAdminUserid} without a password. You must assign this user ID a password that complies with your institution standards. This is also the password 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
    If you are using a different security system, make sure that the ${zAdminUserid} user ID has a password.

    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 BBOCBRAK. 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.

    Status of task Date
         


  7. 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.
    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:
    ${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 Application Server 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 need to also grant the appropriate console command authority to any user ID that executes the startServer.sh or stopServer.sh script.

    Status of task Date
         


  8. Run job BBOWCHFS

    User ID requirement: File system update authority (see above), and the authority to allocate

    ${zConfigHfsName} This job:

    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 ${zHFSOwnerUserID}:${zConfigurationGroup} ${zConfigMountPoint}

    Before you begin: The BBOWCHFS 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 ${zHFSOwnerUserID} and ${zConfigurationGroup} before running BBOWCHFS.

    Example: If you plan to use /WebSphere/V6R1 as your directory, issue the following commands from within the OMVS shell:
    mkdir -p -m 775 /WebSphere/V6R1 chown -R ${zHFSOwnerUserID}:${zConfigurationGroup} /WebSphere

    Status of task Date
         


  9. Run job BBOWCZFS

    User ID requirement: File system update authority (see above), and the authority to allocate


    ${zConfigHfsName}

    This job:
    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 ${zHFSOwnerUserID}:${zConfigurationGroup} ${zConfigMountPoint}
    Before you begin: The BBOWCZFS 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 ${zHFSOwnerUserID} and ${zConfigurationGroup} before running BBOWCZFS.

    Example: If you plan to use /WebSphere/V6R1 as your directory, issue the following commands from within the OMVS shell:
    mkdir -p -m 775 /WebSphere/V6R1 chown -R ${zHFSOwnerUserID}:${zConfigurationGroup} /WebSphere


    Status of task Date
         


  10. Run job BBOWHFSA

    User ID requirement: File system update authority (see above).


    This job populates the previously-created file system.

    Note: If the SCEERUN data set is not in the system link list, add that data set to STEPLIB for the CHECKV step in BBOWHFSA.
    When the job completes, examine the job output. Success is indicated with a RC=0 in the job output.

    Status of task Date
         


  11. Run job BBOWCPY1

    User ID requirement: File system update authority (see above), and the authority to update the cataloged procedure library ${zProclibName} .

    This job copies the tailored start procedures, parameters, and EXECs to the run-time libraries.

    Attention: Be aware that you may overlay existing members in the above data sets.

    Status of task Date
         


  12. Run job BBOWWPFA

    User ID requirement: File system update authority (see above).


    This job sets up the runtime file system.

    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 BBOWWPFA.
    Upon completion, examine the job output. Success is indicated by rc=0.

    Note: If the BBOWWPFA (profile creation) job fails, you must perform the following steps to clean up the partially-built profiles:
                
             cd ${zConfigMountPoint}/${zWasServerDir}
             ./bin/bbowprof.sh -deleteAll
             rm profileRegistry.xml
             rm -R profiles
    
    Then correct the problem that caused BBOWWPFA to fail and re-run the job.

    Status of task Date
         


  13. Run job BBOWHFSB

    User ID requirement: File system update authority (see above).


    This job will complete the file system initialization.
    When the job completes, examine the job output. Success is indicated with a RC=0 in the job output.

    Status of task Date
         


  14. 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}Z ${zServantProcName}Z ${zAdjunctProcName}Z ${zDaemonProcName}Z
    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.

    Status of task Date
         


  15. Make sure Resource Recovery Services (RRS) is active. (See the InfoCenter 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
  16. 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.



    Status of task Date
         


  17. Start the Application Server

    Issue the MVS command:
    START ${zControlProcName},JOBNAME=${zServerShortName},ENV=${zCellShortName}.${zNodeShortName}.${zServerShortName}
    This command starts the Application Server. Wait until the server is finished initializing before proceeding.

    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}.

    Status of task Date
         


  18. Run job BBOWIVT

    User ID requirement: Any user ID defined to Unix System Services.

    This job runs the IVT application. See related topics in the WebSphere for z/OS Information Center for information about how to run this job.

    Status of task Date
         


  19. The product is now configured and verified.

    To start the application server, issue the MVS command:
    START ${zControlProcName},JOBNAME=${zServerShortName},ENV=${zCellShortName}.${zNodeShortName}.${zServerShortName}

    Note: If you later convert the Application Server to 64-bit mode, you need to add AMODE=64 to the START command.

    START ${zControlProcName},JOBNAME=${zServerShortName},ENV=${zCellShortName}.${zNodeShortName}.${zServerShortName},AMODE=64
    To stop the application server, enter the MVS command:
    STOP ${zDaemonJobName}