Skip to main content

Running zCX in ZD&T

A how-to article on setting up zCX in ZD&T, thereby starting innovation in a small way and subsequently taking it to real infrastructure

Diagonal blue, teal and silver slats.

To have an edge over competition and to provide superior experience to clients, enterprises must try new technologies early, understand their values quickly and innovate faster by making it part of their technology landscape. IBM Z® Development and Test Environment (ZD&T) is a popular IBM offering that provides a true IBM z/OS® instance that runs on Linux® with the real IBM Z instructions set. It can be deployed on demand and gives developers insulation from peak workloads on the mainframe and without any impact to other developers. Testing bottle necks are removed because developers can have their own test environments created/reset/destroyed at will without waiting for Operations or Systems programmers intervention. IBM z/OS Container Extensions (zCX) is a new IBM offering that can run open-source Linux packages and microservices in Docker containers securely within the boundaries of z/OS, thus furthering innovation with total security and widening the scope of the z/OS ecosystem in the hybrid cloud world. The IBM zCX Redbook describes everything you would want to know about zCX.

If developers can get a working zCX instance in ZD&T, they will be able to try out different things and innovate faster. They will also have total insulation from production workloads without worrying about environment challenges. This article will explain how to set up zCX in ZD&T, thereby starting innovation in a small way and subsequently taking it to real infrastructure.

About My Setup

I used the latest ZD&T 12.0.5 that emulates the IBM z15™ instructions set. Every release of ZD&T comes with a special package/bundle called Application Developers Controlled Distribution (ADCD), a ready to run z/OS system with almost all the commonly used IBM software like IBM CICS® TS, IBM Db2® for z/OS, COBOL, etc. ZD&T 12.0.5 comes with z/OS 2.4 version of ADCD.  ZD&T 12.0.5 (which will be referred as just “ZD&T”) together with z/OS 2.4 ADCD (which will be referred as just “ADCD system” or “ADCD”) is a quick way to get access to zCX.

At a high level the I did the following steps to set up a zCX instance:
  • Storage management tasks for smooth creation of VSAM and zFS data sets required for the functioning of a zCX instance
  • TCPIP configuration task for connecting to zCX
  • Getting access to a z/OS Management Facility (z/OSMF) instance
  • RACF planning
  • USS planning
  • Running z/OSMF workflows and starting the instance

Storage Management Tasks 

VSAMs and zFS data sets used by zCX may require Extended Format and Extended Addressability attributes to be set. For this, ADCD system already has a SMS Data Class, CXDC, defined. I wanted ZCX to be the HLQ of all the zCX data sets, to make sure ZCX.** data sets get assigned to CXDC Data Class, I added the following statements to SMS Data Class routine:

FILTLIST ZCX_HLQ INCLUDE(ZCX.**)
 
IF &HLQ = &ZCX_HLQ THEN
      DO                         
             SET &DATACLAS='CXDC'
      END     

ADCD has a Storage Class defined for zCX purposes, CXROOTSC. From Interactive System Management Facility (ISMF) Panels, I had to change the ACCESSIBILITY field/attribute of the Storage Class to NOPREF, so that any disk volume can be accepted even if it does not support Concurrent Copy feature. To make sure ZCX.** data sets gets CXROOTSC Storage Class assigned, I added the following statements to SMS Storage Class routine:

FILTLIST ZCX_HLQ INCLUDE(ZCX.**)
 
SELECT                            
             WHEN (&HLQ = &ZCX_HLQ)            
                        DO                              
                                     SET &STORCLAS='CXROOTSC'  
                         EXIT CODE(0)  
END             

ADCD has a Storage Group, CXROOTSG corresponding to Storage Class, CXROOTSC and DASD volume A4ZCX1 has already been added to this Storage Group. As a single instance of zCX would need about 33 GB of DASD space for its VSAM and zFS data sets, I added additional DASD volumes to the Storage Group, CXROOTSG.

TCPIP Configuration Tasks 

zCX instance requires a DVIPA (Dynamic Virtual IP Address) to talk to the outside world and uses a SAMEHOST interface to talk to other z/OS address spaces. My ADCD system running on ZD&T has only one default emulated network interface, traffic to z/OS flows this interface with the default internal IP 172.26.1.2 and traffic to/from outside world is getting forwarded using Linux iptables. For zCX purposes, I created a DVIPA with an internal IP 172.26.1.3, which can go through the same default emulated network interface, as DVIPA does not require direct access to network interface. For zCX to talk to the outside world, I modified Linux iptables such that certain ports that will be used by zCX (port 8022) and the ones used by my applications running within zCX (ports 8023-8100) will be forwarded to 172.26.1.3.

Pertinent section of my TCPIP profile looked like this:

IPCONFIG DYNAMICXCF 10.1.100.74 255.255.255.0 1     
VIPADYNAMIC                                            
VIPARANGE DEFINE 255.255.255.255 172.26.1.3 ZCX ;      
ENDVIPADYNAMIC
    
I created iptables rules like these to forward certain ports to 172.26.1.3 IP address for zCX purposes:

iptables -A FORWARD -p tcp --dport 8022:8100   -d 172.26.1.3    -j ACCEPT
iptables -t nat -A PREROUTING  -p tcp -m tcp  --dport 8022:8100  -j DNAT --to-destination 172.26.1.3

Getting Access to a z/OSMF Instance 

z/OSMF is required to run the workflows that can provision a zCX instance and to perform tasks like reconfiguring, adding disks and deprovisioning an instance. ADCD system comes with a pre-configured z/OSMF instance that can be started anytime, by starting the started tasks IZUANG1 & IZUSVR1 using console commands. Once started, z/OSMF listens at port 10443 and can be accessed with a browser using the IP address of Linux and port 10443. To optimize my ZD&T resources, as zCX just needs z/OSMF core, I disabled all the plug-ins before starting the z/OSMF instance, by commenting out PLUGINS statement in IZUPRMxx PARMLIB member for z/OSMF:
 
/* Commenting out plugins
 PLUGINS( INCIDENT_LOG,                                  
            COMMSERVER_CFG,                                
            WORKLOAD_MGMT                                  
            RESOURCE_MON,                                  
            CAPACITY_PROV,                                 
            SOFTWARE_MGMT,                                 
            SYSPLEX_MGMT,                                  
            ISPF)       Commenting out  plugins*/

RACF Planning 

As z/OSMF workflows are used to provision a zCX instance and subsequently to perform certain tasks like zCX instance reconfiguration, a user ID with RACF authority to run workflows is required. Similarly, as a zCX instance runs as a started task under the ownership of a user ID, the started task user ID will need certain RACF authority including access to zFS and VSAM data sets of zCX. Each instance of zCX also needs an instance admin user ID, which need not be a real z/OS user ID.
 
For my setup, I followed the approach mentioned in the section 4.2 in the IBM zCX Redbook. Accordingly, I created RACF groups ZCXPRVG, ZCXSTCG and ZCXADMG. I used the existing user ID, IBMUSER for workflow purposes and connected it to RACF group ZCXPRVG. I used existing user ID, ADCDMST for SSH key generation for the zCX instance administrator user ID (say admin) and connected ADCDMST to RACF group, ZCXADMG. I created only the user ID, ZXCSTC1 for started task purpose and connected it to RACF group, ZCXSTCG.

USS Planning 

USS planning is important as zFS and VSAM data sets of a zCX instance at some stage gets mounted to a directory structure to hold zCX appliance image, configuration files, properties file, logs, etc.
 
For my setup, I followed the approach mentioned in the section 4.3 in the IBM zCX Redbook. Accordingly, I created the mentioned directory structure and set the user & group owner for the directories as given in the section in the Redbook.

Running z/OS MF Workflows in z/OSMF and Starting the Instance 

In the ADCD system, zCX related z/OS MF workflows are in the directory path /usr/lpp/zcx_zos/workflows/ and sample properties file for the workflow is in the file, /usr/lpp/zcx_zos/properties/workflow_variables.properties. As described in the section 4.7 in IBM zCX Redbook, I customized the properties file to run with 2 CPUs and 8 GB memory. To insert the SSH key value for the property ZCX_DOCKER_ADMIN_SSH_KEY in the properties file, I followed the approach mentioned in section 4.7.2 of IBM zCX Redbook, but note that in the sed command statement given there, ZCX_DOCKER_ADMIN_SSH_KEYS should be changed to ZCX_DOCKER_ADMIN_SSH_KEY.
 
Pertinent sections of my properties file looked like this:

ZCX_INSTALL_DIR /usr/lpp/zcx_zos                      
ZCX_REGISTRY_DIR /global/zcx/instances                
ZCX_INSTNAME ZCXED01                                     

ZCX_CPUS 2                                             
ZCX_MEMGB 8
ZCX_ZFS_GROUP_NAME ZCXPRVG

ZCX_HOSTNAME S0W1
ZCX_GUESTIPV4 172.26.1.3           
ZCX_TCPIPNAME TCPIP                
ZCX_MTU 1492                       
ZCX_HOSTDNS1 9.x.x.x 
 
I accessed the z/OSMF using the URL https://n.n.n.n:10443/zosmf, where n.n.n.n is the IP address of Linux in which my ZD&T emulator is running and ran the workflow to provision a zCX instance as described in the section 4.8 in the IBM zCX Redbook, except that the system name is S0W1.
 
A started task JCL procedure and a RACF STARTED class profile is required to start the provisioned zCX instance. I created these exactly as described in the section 4.9.1 in IBM zCX Redbook  and started the zCX instance.
 
To log on to the zCX instance from USS, I followed the steps described in the section 4.10 in the IBM zCX Redbook, except that I used ADCDMST user ID and my SSH command looked like this:      
 
ssh admin@172.26.1.3 -p 8022

zCX can be accessed from workstation using an SSH client. For this, I did a binary transfer of the SSH private key file, id_rsa (was created with ADCDMST user ID in the RACF planning step) and issued the below command from the directory containing the private key file:

ssh -i ./id_rsa -p 8022 admin@n.n.n.n
 
Where n.n.n.n is the IP address of Linux running ZD&T. This zCX knowledge center link describes other ways of accessing zCX from workstation.

Bringing zCX Within Reach

This is how I set up a zCX instance in my ZD&T running ADCD system. In this way, we can bring zCX within easy reach of developers. Giving such an option to developers will help them try out different things and come up with innovative ideas faster. These ideas can be made bigger in a real IBM Z infrastructure, thus expanding the z/OS ecosystem in the hybrid cloud world.
IBM Systems Webinar Icon

View upcoming and on-demand (IBM Z, IBM i, AIX, Power Systems) webinars.
Register now →