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.
- 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.
- Add execution permission to the file with the following
command:
chmod 755 zOS-cloud-prepare.s390x
- Execute the file on your source environment.
- 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
zOS-cloud-prepare
--help
.-config=""
: Path to the config file.-dbs=100
: Devices buffer size.-debug=false
: Enable verbose logging.-destloadsuffix="K2"
: Destination IPL parm load suffix to be created.-dryrun=true
(optional): Skip committing changes to the system.-osaportname=""
: Specify the OSA port name ifzoautil
is unavailable for discovery.-srcloadsuffix="A0"
: Source IPL parm load suffix to be copied.-sysdsn="SYS0"
: System data set name that contains the load parameters (IPLPARM).-tmpdir="/tmp"
: Temporary directory to store artifacts. It is cleaned up if debug is not enabled.-zosutil="/usr/lpp/IBM/zoautil"
: Location ofzoautil
(used as OSA port name when not specified).-ttls=true
: Activate Application Transparent TLS (AT-TLS) in destinationTCPIP config
.-version=false
: Display the version information for the tool used.
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.
- 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
- Remove the translation tag from output
file.
chtag -r ./cloud-prepare.out
- 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. - 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.
- 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. - 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.
- 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 browsingSYS0.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
andLPARNAME
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 theHWNAME/LPARNAME
filtering for needed symbols, or to copy the needed symbols that are protected by the filters to theK2.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 forDEVNUM(SYSCON)
does not specifyROUTCODE(ALL)
andALLOWCMD(Y)
. If the parameters for theSYSCON CONSOLE
statement are not set on the source z/OS system as described here, then the suggested workaround is to manually copy theCONSOLEXX
member to theK2.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
- 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
- In the Images (from source environment) table, find the image that you created.
- Click the Edit icon , and then select Edit advanced image properties.
- Under IPL properties, change the LOADxx suffix to the suffix that you produced.
- 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.
- Click Next to check the networking settings, and then click Save.
For more information, see Monitoring and managing the created images.