Setting up networking for on-premises z/OS environment

In IBM® Wazi Image Builder, when you initiate the process to deploy a custom image to a target environment, you are asked to specify the PARMLIB and IEASYM suffix for the member that contains the TCP/IP symbol configuration.

Some of these symbols are modified in the IBM Wazi as a Service deployment process so that the IP address that is dynamically assigned by IBM Cloud® is injected into this member and is used by your z/OS® TCP/IP profile when it runs in IBM Cloud.

You have two options to set up the networking for your on-premises z/OS environment.

Option 1: Using the zOS-cloud-prepare tool to automatically create z/OS configuration

You can automatically create a z/OS configuration (PARMLIB, PROCLIB, TCPPARMS, IPLPARM) by using the IBM-provided zOS-cloud-prepare tool. This tool runs in a running z/OS UNIX System Services environment and creates a new load suffix that contains a templates configuration so that the z/OS can run in a Wazi as a Service environment successfully.

Before you begin, check the installation directory of your web server. For example, /opt/ibm/wib is the default installation directory, but you can specify your own installation directory during the installation process.

The zOS-cloud-prepare tool is packaged with Wazi Image Builder at <installation_directory>/zSystem/zOS-cloud-prepare.s390x. Complete the following steps before you run this tool:
  1. Copy the zOS-cloud-prepare file to the z/OS UNIX folder /usr/lpp/IBM/zdt in the source z/OS environment. You can use one of the following ways:
    • Use the Secure Copy Protocol (SCP) to transfer the file.
    • Use the Securing File Transfer Protocol (SFTP) to transfer the file with binary mode.
  2. Add execution permission to the file with the following command:
    chmod 755 zOS-cloud-prepare.s390x
  3. Execute the file on your source environment.
This tool creates a new load suffix that you defined (default value is K2) and creates three new data sets based on the new suffix.
  • K2.PARMLIB

    Based on copies of an existing load suffix, where XX is either a discovered or a provided value:

    • IEASYMXX: Symbols that are used and can be updated during deployment.
    • MSTJCLXX: Adds a prefix to the XX.PROCLIB to the proclib search list.
  • K2.PROCLIB

    Based on copies of existing proclibs from an existing load suffix:

    • JES2: Adds a prefix to the XX.PROCLIB to the proclib search list (static or dynamic).
    • RESOLVER: Sets the XX.TCPPARMS(RESSETUP) and adds execution step for XX.PROCLIB(UPDRESOL).
    • TCPIP: Sets the XX.TCPPARMS(PROFILE) and XX.TCPPARMS(TCPDATA).
    • UPDRESOL: REXX that updates symbols within the XX.TCPPARMS(INODES).
  • K2.TCPPARMS

    TCPIP templates are created based on the new load suffix (K2):

    • INODES: Host/domain resolution
    • PROFILE: z/OS network configuration
    • RESSETUP: Resolver configuration that points to XX.TCPPARMS(INODES) and XX.TCPPARMS(TCPDATA)
    • TCPDATA: z/OS hostname and domain configuration
  • K2.MSGPARMS
    • DEVICES: Buffer for device notifications during attachment and detachment
Tip: To see the syntax of the tool, issue zOS-cloud-prepare --help.
Following is a list of commands in the zOS-cloud-prepare tool:
  1. -config="": Path to the config file.
  2. -dbs=100: Devices buffer size.
  3. -debug=false: Enable verbose logging.
  4. -destloadsuffix="K2": Destination IPL parm load suffix to be created.
  5. -dryrun=true (optional): Skip committing changes to the system.
  6. -osaportname="": Specify the OSA port name if zoautil is unavailable for discovery.
  7. -srcloadsuffix="A0": Source IPL parm load suffix to be copied.
  8. -sysdsn="SYS0": System data set name that contains the load parameters (IPLPARM).
  9. -tmpdir="/tmp": Temporary directory to store artifacts. It is cleaned up if debug is not enabled.
  10. -zosutil="/usr/lpp/IBM/zoautil": Location of zoautil (used as OSA port name when not specified).
  11. -ttls=true: Activate Application Transparent TLS (AT-TLS) in destination TCPIP config.
  12. -version=false: Display the version information for the tool used.
Note:

The default value of the High Level Qualifier (HLQ) is K2. You can specify an HLQ other than K2 with the "-destloadsuffix" command line parameter.

The load parm member (LOADK2 in the example) is created from the existing load suffix that you specified with the "-srcloadsuffix" command line parameter.

The load parm member (LOADK2 in the example) is created under the DSN (SYS0.IPLPARM in the example) that you specified with the "-sysdsn" command line parameter.

To run the zOS-cloud-prepare tool, complete the following steps.
  1. Run the tool in -dryrun=true mode, and save the output to a file. When this value is provided, no changes are committed to your system, but it prints to the console what happens if you run -dryrun=false. For example:
    ./zOS-cloud-prepare.s390x -dryrun=true -destloadsuffix=K2 -osaportname=CU331660 -srcloadsuffix=ZL -sysdsn=SYS0 > cloud-prepare.out 2>&1
  2. Remove the translation tag from output file.
    chtag -r ./cloud-prepare.out
  3. View the output file contents. If you see "Done" at the end, then it means that the process is completed. Otherwise, an error might have occurred and caused the tool to exit early. If this happens, then investigate and resolve the error, and run the tool in dryrun mode again, until you see the "Done" message. For example:
    ./zOS-cloud-prepare.s390x -dryrun=true -debug=true -destloadsuffix=K2 -osaportname=CU331660 -srcloadsuffix=ZL -sysdsn=SYS0 > cloud-prepare.out 2>&1
    Tip: When you debug errors, use the "-debug=true" command line parameter to get the tool to output more details.
  4. When the tool runs to completion without error, then review the output file to see what data sets and data set members (and contents) the tool intends to create.
  5. If everything looks good, run the tool again with the same parameters in step 1, and specify "-dryrun=false" this time. The tool will attempt to create the data sets and data set members. For example:
    ./zOS-cloud-prepare.s390x -dryrun=false -destloadsuffix=K2 -osaportname=CU331660 -srcloadsuffix=ZL -sysdsn=SYS0 > cloud-prepare.out 2>&1
    Note: Make sure that you are given the appropriate permissions to create the data sets (see the Prerequisites section). If you do not want the tool to make the updates, then use the data from the output file to manually create the data sets and data set members on the source z/OS system.
  6. From ISPF, review the data set members that the tool creates, and make any adjustments that might be unique to the source z/OS system and necessary for the custom image to IPL successfully in the z/OS virtual server instance.
Also, review the following known limitations with the zOS-cloud-prepare tool, and make changes accordingly.
  • The tool might not create the output data sets and/or data set members when the target (output) data set is in use (even with DISP=SHR). For example, if ISPF is already open and browsing SYS0.IPLPARM, the tool will not create the new load parm member that it intends to create, and an error will not be raised. It is always a best practice to review the data set and data set members that the tool creates before you proceed.
  • The tool does not currently handle source z/OS environments where symbols are only loaded for specific HWNAME and LPARNAME values. As these values cannot be set properly in the Wazi as a Service environment in IBM Cloud, it means that these symbols will not get loaded and might cause IPL problems because the configuration is expecting values for them. The workaround is to either temporarily remove the HWNAME/LPARNAME filtering for needed symbols, or to copy the needed symbols that are protected by the filters to the K2.PARMLIB(IEASYMK2) member.
  • The tool does not currently copy or modify the CONSOLEXX member. Debugging IPL issues on Wazi as a Service could be more difficult if the CONSOLE statement for DEVNUM(SYSCON) does not specify ROUTCODE(ALL) and ALLOWCMD(Y). If the parameters for the SYSCON CONSOLE statement are not set on the source z/OS system as described here, then the suggested workaround is to manually copy the CONSOLEXX member to the K2.PARMLIB data set that the tool creates, and edit it accordingly.

After you run the zOS-cloud-prepare tool, you can start the extraction in Wazi Image Builder by creating the components that you want, and then create an image from the components.

Option 2: Using your existing z/OS configuration

You can also use your existing z/OS configuration with the following modifications.
  • The TCP/IP profile is set up so that it relies on the following symbols that are defined in your system PARMLIB (IEASYMxx).
    • IP address: HOMEIPADDRESS1
    • Default route: DEFAULTROUTEADDR
  • The resolver configuration is defined in a PDS (not a PDSE) and is set up so that it relies on the following symbols that are defined in your system PARMLIB (IEASYMxx).
    • Name server: NAMESERVERADDR1

If a new load parm is produced from these configuration changes, you can create the components that you want, and then create an image from the components.

Configuring image properties

After you created an image, you need to edit the image to match the configuration by completing the following steps:
  1. In the Images (from source environment) table, find the image that you created.
  2. Click the Edit icon , and then select Edit advanced image properties.
  3. Under IPL properties, change the LOADxx suffix to the suffix that you produced.
  4. Validate that the SYSRES device number and IODF device number are correct. The numbers are used by Wazi as a Service to build the IPL statement.
  5. Click Next to check the networking settings, and then click Save.

For more information, see Monitoring and managing the created images.