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

The Profile Management tool or Customization Dialog 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(BBOANINS)

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 TCP/IP by reserving the following ports for WebSphere Application Server for z/OS:

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

    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}
    High Availability Manager Communication port ${zFederateHamCommPort}
    Node Agent's ORB SSL port ${zFederateOrbSslPortName}
    Application Server's ORB Port ${zFederateAppServerOrbPort}

    Add the contents of the cntl/bbotcpia 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.


    Note: The addNode process introduces a special utility server to the node. This utility server is called a nodeagent and exists to support administrative functions on the node.

    By default the nodeagent takes over ORB port 2809. Be aware that on WebSphere z/OS the ORB port doubles as the INS CosNaming bootstrap port. By default, this port (2809) was assigned to the Application Server. Usually you want the nodeagent to be the INS CosNaming bootstrap point for the entire node, so that RMI/IIOP clients that do not override the INS CosNaming bootstrap defaults can locate within the namespace, EJBs installed on any server on that node.

    In order for the nodeagent to take over port 2809, the Application Server must be assigned a new ORB port. The default new ORB port for the Application Server is 9810. The nodeagent will take over an Application Server's ORB port if and only if the nodeagent's ORB port is equal to an Application Server's ORB port. You can specify the nodeagent's ORB port in the 'ORB port' field. You can specify the new ORB port for the Application Server in the 'Appplication Server's ORB Port' field.

    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 update the WebSphere for z/OS Customization Dialog or Profile Management tool with new port specifications, be sure to regenerate the customization jobs, data, and instuctions.


    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.



  1. Run Job BBOWADDN

    User ID requirement: File system update 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

    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.

    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.

    If SSL certificates are stored in the SAF keyrings, then the user ID used to run this job must have a SAF keyring whose name matches the value of com.ibm.ssl.keyStore in the application server's WAS_HOME/profiles/default/properties/ssl.client.props file, and this keyring must contain the Network Deployment cell's CA certificate.


    Add the application server or servers associated with the stand- alone application server node to the deployment manager's cell.

    For security enablement on the Deployment Manager:



    If your application server is using z/OS log streams for transaction XA partner logs, delete and recreate the log streams before federation.

    Note: 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.

    If you choose to start the node agent automatically, the user ID used to run BBOWADDN will also need the authority to issue the MVS START command.


    Attention: Before you run the BBOWADDN job to federate the stand-alone Application Server node, you must have started the stand-alone Application server that you are federating at least once so the applyPTF step runs. Otherwise, the BBOWADDN job will fail with an error such as:
    java.lang.NullPointerException at com.ibm.ws.management.tools.NodeFederationUtility.createNDProductFile(NodeFederationUtility.java:1929)
    Note: Run this job only once for each node that you federate, regardless of how many application servers the node contains.

    Result: Upon successful completion of this job, you will see the following message in SYSPRINT:
    ADMU0003I: Node <nodename> has been successfully federated.
    Status of task Date
         




  2. Start the node agent server


    Note: If your server is already running, this step is not necessary.

    Example: If your Application Server proc name is XXXXXXXX, and your Application Server node name (short) is YYYYYYYY, and your Deployment Manager cell name (short) is ZZZZZZZZ, issue the MVS command:
    START XXXXXXXX,JOBNAME=${zFederateServerShortName}, ENV=ZZZZZZZZ.YYYYYYYY.${zFederateServerShortName}
    This command starts the node agent server.

    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}.
    Status of task Date
         




  3. Start the Application Server (optional)

    Note: You must start the node agent before you start the Application Server, if the node agent has not already been started.

    Example: If your Application Server proc name is XXXXXXXX, and your Application Server node name (short) is YYYYYYYY, and your server short name is BBOS001, and your Deployment Manager cell name (short) is ZZZZZZZZ, the MVS command you would issue would be similar to the following:
    START XXXXXXXX,JOBNAME=BBOS001, ENV=ZZZZZZZZ.YYYYYYYY.BBOS001
    This command starts the Application Server.

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