Understanding the Linux, VTAM and TCPIP linkage with ADCD and z/OS

This follows on from Getting TCPIP on my Linux machine to talk to z/OS ADCD running on ZPDT on my Linux machine. It shows the moving parts.

There are lot of bits of configuration which have to be mutually consistent, and some bits do not work as I expected.

There are several sections in this blog post

The different parts

The Linux devmap

In Linux the devmap has

[manager]  # tap0 define network adapter (OSA) for communication with Linux
name awsosa 0022 --path=A0 --pathtype=OSD --tunnel_intf=y --tunnel_ip=172.26.1.1 
device 400 osa osa 
device 401 osa osa 
device 402 osa osa 

The key information is

  • It uses z/OS path A0.
  • It is an OSA with QDIO (OSD).
  • It uses the tunnelling interface.
  • The IP address is 172.26.1.1. This is the IP address of the Linux end of the tunnel.
  • There are 3 z/OS devices with address 0400, 0401, 0402.
  • The devices are OSAs.
  • The control unit they are connected to is an OSA. ( A 3279 colour display would have device 3279, control unit 3274).

In ADCD.Z25A.VTAMLST(OSATRL2) is

OSATRL1 VBUILD TYPE=TRL                                                 
OSATRL1E TRLE LNCTL=MPC,READ=(0400),WRITE=(0401),DATAPATH=(0402),      X
               PORTNAME=PORTA,                                         X
               MPCLEVEL=QDIO                                            
OSATRL2E TRLE LNCTL=MPC,READ=(0404),WRITE=(0405),DATAPATH=(0406),      X
               PORTNAME=PORTB,                                         X
               MPCLEVEL=QDIO 

This defines a Transport Resource List(TRL)

  • OSATRL1E is a name which can be used in commands.
  • TRLE is a Transport Resource List Entry
  • It uses MultiPathChannel links(MPC) (more than one device)
  • It uses multiple device addresses 0400,0401,0402
  • The Open Systems Adapter(OSA) port name is PORTA
  • MPCLEVEL=QDIO Indicates that the Queued Direct I/O interface is used for an OSA-Express feature.

You can use commands like

  • D NET,TRL
  • D NET,ID=OSATRL1
  • D NET,ID=OSATRL2E,E

Example output from D NET,IDA=OSATRL1E

DISPLAY ACCEPTED                                                   
NAME = OSATRL1E, TYPE = TRLE 558                                   
STATUS= ACTIV, DESIRED STATE= ACTIV                                
TYPE = LEASED             , CONTROL = MPC , HPDT = YES             
TRL MAJOR NODE = OSATRL2                                          
MPCLEVEL = QDIO       MPCUSAGE = SHARE                            
PORTNAME = PORTA      LINKNUM =   0   OSA CODE LEVEL = 7617       
CHPID TYPE = OSD      CHPID = A0  PNETID = **NA** 
WRITE DEV = 0401 STATUS = ACTIVE     STATE = ONLINE      
READ  DEV = 0400 STATUS = ACTIVE     STATE = ONLINE 
DATA  DEV = 0402 STATUS = ACTIVE     STATE = N/A         

Key information is

  • TYPE = TRLE
  • STATUS= ACTIV
  • PORTNAME = PORTA
  • CHPID = A0
  • There are three devices 0401, 0400, 0402

As this matches the Linux configuration, it has all connected up and become active. It is known to VTAM and TCPIP as PORTA.

Within TCPIP there is a member ADCD.Z25A.TCPPARMS(ZPDTDEV1) with

DEVICE PORTA MPCIPA 
 LINK ETH1 IPAQENET PORTA 
HOME &HOMEIPADDRESS1 ETH1 
BEGINRoutes 
; Destination        SubnetMask    FirstHop       LinkName    Size 
ROUTE 9.114.209.0    255.255.255.0    =            ETH1   MTU 1492 
; Destination                      First Hop      LinkName    Size 
ROUTE DEFAULT             &DEFAULTROUTEADDR        ETH1   MTU 1492 
ENDRoutes 
START PORTA 

The key information is

  • Device PORTA – matches the VTAM TLRE definition.
  • There is a link ETH1 associated with PORTA.
  • When anyone uses this device-> link, use the Home address &HOMEIPADDRESS1. The z/OS symbol &HOMEIPADDRESS1 is “172.26.1.2”, so this value is used.
  • If TCPIP does not know where to send a packet, it sends it to &DEFAULTROUTEADDR down ETH1 link. (&DEFAULTROUTEADDR. = “172.26.1.1”)
  • The “172.26.1.1” matches the –tunnel_ip=172.26.1.1 in the Linux definition.

Background information

A link has two ends, each end defines its IP address. For example

  • for the Linux for the DEVMAP file –tunnel_ip=172.26.1.6 defines the Linux as having IP address 172.26.1.6.
  • for z/OS the HOME 172.26.1.9 ETH2 defines the z/OS as being 172.26.1.9

If you “FTP 172.26.1.9”, and use NETSTAT CONN, it gives a connection 172.26.1.9..21 and 172.26.1.6..53526 , so you can see the IP addresses (and ports) of the two ends of the connection. Note: Port 21 is the well known port for FTP.

The definitions

Devmap

The devmap definitions below, create a two connections between Linux and z/OS.

[manager]  # tap0 define network adapter (OSA) for communication with Linux QDIO
#defaults to  10.1.1.1
name awsosa 0022 --path=A0 --pathtype=OSD --tunnel_intf=y mode
device 400 osa osa 
device 401 osa osa 
device 402 osa osa 

[manager]  # tap1 define network adapter (OSA) for communication with Linux QDIO
name awsosa 0009 --path=A1 --pathtype=OSD --tunnel_intf=y --tunnel_ip=172.26.1.6 
device 404 osa osa 
device 405 osa osa 
device 406 osa osa 

The VTAM TRL definition

OSATRL1 VBUILD TYPE=TRL                                                 
OSATRL1E TRLE LNCTL=MPC,READ=(0400),WRITE=(0401),DATAPATH=(0402),      X
               PORTNAME=PORTA,                                         X
               MPCLEVEL=QDIO                                            
OSATRL2E TRLE LNCTL=MPC,READ=(0404),WRITE=(0405),DATAPATH=(0406),      X
               PORTNAME=PORTB,                                         X
               MPCLEVEL=QDIO                                            

The TCPIP definition in USER.Z25A.TCPPARMS(ZPDTDEV1)

DEVICE PORTB MPCIPA 
 LINK ETH2 IPAQENET PORTB 
HOME 172.26.1.9      ETH2 
                                                                        
DEVICE PORTA MPCIPA 
 LINK ETH1 IPAQENET PORTA 
HOME 10.1.1.2        ETH1 
                                                                        
BEGINRoutes 
; Destination        SubnetMask    FirstHop   LinkName    Size 
ROUTE 10.1.1.0       255.255.255.0    =            ETH1   MTU 1500 
ROUTE 172.26.1.0     255.255.255.0    =            ETH2   MTU 1492 
ROUTE DEFAULT                      10.1.1.1        ETH1   MTU 1492 
ENDRoutes 


START PORTA 
START PORTB 

I found that sometimes TCPIP does not 100% accept an update, and the device continues to point to old definitions.

I used the operator commands

v tcpip,,STOP,PORTA
v tcpip,,STOP,PORTB
v tcpip,,obey,USER.Z25A.TCPPARMS(ZPDTDEV1)

to activate the change.

With this I could ping and FTP to 10.1.1.2 and 127.26.1.9 (the values in the HOME)

TSO netstat home gave

MVS TCP/IP NETSTAT CS V2R5       TCPIP Name: TCPIP 
Home address list:
Address          Link             Flg
-------          ----             ---
172.26.1.9       ETH2             P
10.1.1.2         ETH1
172.26.1.20      EZASAMEMVS
127.0.0.1        LOOPBACK

Address          Interface        Flg
-------          ---------        ---
172.26.1.20      EZAZCX

and TSO NETSTAT ROUTE gave

Destination    Gateway  Flags Refcnt     Interface
-----------    -------  ----- ------     ---------
Default        10.1.1.1 UGS   0000000000 ETH1
10.1.1.0/24    0.0.0.0  US    0000000000 ETH1
10.1.1.2/32    0.0.0.0  UH    0000000000 ETH1
127.0.0.1/32   0.0.0.0  UH    0000000000 LOOPBACK
172.26.1.0/24  0.0.0.0  US    0000000000 ETH2
172.26.1.9/32  0.0.0.0  UH    0000000000 ETH2
172.26.1.20/32 0.0.0.0  H     0000000000 EZAZCX
172.26.1.20/32 0.0.0.0  H     0000000000 EZASAMEMVS

Where the flags are

  • UGS – The route is Up, uses a Gateway, is a Static route
  • US -The route is Up, is a Static route
  • US
  • UH – The route is Up, is a route to a Host (rather than a gateway)
  • H – is a route to a Host (rather than a gateway) It does not have “U” so is not up.

More complex example – Using an Interface statement

The definitions above used

DEVICE PORTB MPCIPA 
 LINK ETH2 IPAQENET PORTB 
HOME 172.26.1.9      ETH2 

You can also use the newer interface definitions which combine these

INTERFACE IFPORTCP  DELETE 
INTERFACE IFPORTCP 
  DEFINE IPAQENET 
  CHPIDTYPE OSD 
  PORTNAME PORTCP 
  IPADDR 172.25.1.1 

START IFPORTCP                                      

I activated this by V TCPIP,,OBEYFILE,USER.Z25A.TCPPARMS(IFACE)

This still needs a TRLE, such as

OSATRL3 VBUILD TYPE=TRL                                                 
OSATRL3E TRLE LNCTL=MPC,READ=(0408),WRITE=(0409),DATAPATH=(040A),      X
               PORTNAME=PORTCP,                                        X
               MPCLEVEL=QDIO                                            

Connected by the PORTNAME=PORTCP

More complex example – Using an Interface statement and different IP address ranges

I change the address of the interface

INTERFACE IFPORTCP  DELETE 
INTERFACE IFPORTCP 
  DEFINE IPAQENET 
  CHPIDTYPE OSD 
  PORTNAME PORTCP 
  IPADDR 172.27.1.1 

START IFPORTCP                                      

I activated this by

  • v tcpip,,stop,IFPORTCP
  • V TCPIP,,OBEYFILE,USER.Z25A.TCPPARMS(IFACE)
  • v tcpip,,start,IFPORTCP

TSO NETSTAT HOME now says

IntfName:   IFPORTCP
  Address:  172.27.1.1
    Flags:

Tell Linux of the new address

To use the new IP address, you need to tell Linux where to send the requests to.

sudo ip route add 172.27.1.0/24 via 172.25.1.6

This says that to get to the 172.27… you need to go via 172.25.1.6, which has been defined as

[manager]  # tap2 define network adapter (OSA) for communication with Linux
name awsosa 0019 --path=A2 --pathtype=OSD --tunnel_intf=y --tunnel_ip=172.25.1.6 
  # QDIO mode
device 408 osa osa 
device 409 osa osa 
device 40a osa osa 

z/OS needs to know how to get back from z/OS. In the routes you need

BEGINRoutes 
; Destination        SubnetMask    FirstHop   LinkName    Size 
ROUTE 172.25.1.0     255.255.255.0    =       IFPORTCP    MTU 1492 
ROUTE DEFAULT        172.25.1.6               IFPORTCP    MTU 1492 
ENDRoutesd

Which says anything for 172.25.1.* send down link/interface IFPORTCP.

If no routes match – send it to 172.25.1.6.

Lessons learned

Below are some of the lessons I learned in writing this blog post. I hope they will be useful to other people. They will be useful to me when I come to use this topic and find it does not work!

Defining Linux tunnels

On Linux the tunnels are defined by the zPDT code, you do not have to define them. If you have defined a tunnel, the zPDT will override the definitions.

Activating resources on z/OS

I created my z/OS TCP, and activated them, but they did not work.

If you define a resource which already exists, and is active, parts of the old definition is still used. I had to stop the PORT using V TCPIP,,STOP,PORTA before I could successfully activate the resource.

When I did not stop the PORT I got

PROCESSING COMMAND: VARY TCPIP,,OBEY,USER.Z25A.TCPPARMS(ZPDTDEV1)          
OPENED OBEYFILE FILE 'USER.Z25A.TCPPARMS(ZPDTDEV1)'                        
PROFILE PROCESSING BEGINNING FOR 'USER.Z25A.TCPPARMS(ZPDTDEV1)'            
DEVICE NAME PORTA ON LINE 5 IS ALREADY DEFINED                             
LINK NAME ETH1 ON LINE 6 IS ALREADY DEFINED                                
DEVICE PORTA ON LINE 15 IS ALREADY STARTED                                 
PROFILE PROCESSING COMPLETE FOR FILE 'USER.Z25A.TCPPARMS(ZPDTDEV1)'        
COMMAND VARY OBEY COMPLETED SUCCESSFULLY                                   
INITIALIZATION COMPLETE FOR DEVICE PORTB                                   

When I put a STOP PORTA in the OBEY file, I got

EZZ4308I ERROR: CODE=8010302D DURING ACTIVATION OF DEVICE PORTB. DIAGNOSTIC CODE: 02    
EZD2028I DEVICE PORTB ACTIVATION FAILED - NO DATAPATH DEVICE ADDRESSES ARE AVAILABLE    

When I repeated it – it worked. It looks like a timing issue. So you have to do it in two steps. The meaning of 302D is A ULP cannot use a QDIO device because there are no datapath channel addresses available.

VTAMTRL

When the system was IPLED the VTAM command D NET,TRL gave

DISPLAY TYPE = TRL             
---------------------------------------------------------
 TRL MAJOR NODE = OSATRL2                                
 TRLE = OSATRL1E  STATUS = ACTIV       CONTROL = MPC     
 TRLE = OSATRL2E  STATUS = NEVAC       CONTROL = MPC     
 2 TRLE(S) DISPLAYED                                     

The TRLE entry will only become active when the port is active. Defining it and starting it gave me TRLE = OSATRL2E STATUS = ACTIV CONTROL = MPC

Getting TCPIP to talk to an ADCD system.

I had a new (z/OS 2.5) ADCD system, and wanted to get FTP working. Once I had unzipped the files, and started z/OS, I could not ping or connect to the z/OS via TCPIP.

When I wanted to use z/OS on a different machine I needed to configure my laptop to give the route to the machine using

sudo ip route add 10.1.1.0/24 via 10.1.0.3 
# open a session to it
ssh -X colin@10.1.0.3 

The problem

I had ZD&T running on my laptop; My definitions on Linux used an IP address of 10.1.1.2, but the the shipped ADCD system has been configured for a HOME entry of 172.26.1.2.

You can either change z/OS, or you can change your Linux setup.

Changing z/OS

I wanted to get the address 10.1.1.2 on my Linux to talk to z/OS, but z/OS was not configured for this address. Using the TCPIP command NETSTAT HOME showed it was configured for a 172.26.1.2 .

In ADCD.Z25A.TCPPARMS(ZPDTDEV1) is

DEVICE PORTA MPCIPA 
 LINK ETH1 IPAQENET PORTA 
HOME &HOMEIPADDRESS1 ETH1 
BEGINRoutes 
; Destination        SubnetMask    FirstHop       LinkName    Size 
ROUTE 9.114.209.0    255.255.255.0    =            ETH1   MTU 1492 
; Destination                      First Hop      LinkName    Size 
ROUTE DEFAULT             &DEFAULTROUTEADDR        ETH1   MTU 1492 
ENDRoutes 
START PORTA 
                                                                       

The z/OS command D SYMBOLS gave

&DEFAULTROUTEADDR. = "172.26.1.1"         
&DYNXCFIPADDRESS.  = "172.26.1.20"        
&EPHEMERALPORTS.   = "10000 65534"        
&GBLRESL.          = "GBLRESOL"           
&HOMEIPADDRESS1.   = "172.26.1.2" 
&TCPPROF.          = "PROF2"                            f

Updating the address

You have several approaches.

  • Update the system symbols and re-ipl or restart TCPIP
  • Replace the symbols with the hard coded definitions and re-ipl or restart TCPIP
  • Use system symbols and restart just the relevant bits of TCPIP
  • Update the TCPIP definitions and restart just the relevant bits of TCPIP

Update the system symbols and re-ipl

See Changing z/OS system symbols is – easy – ish.

My IEASYM definition included member IEASYMAU.

I created member USER.Z25A.PARMLIB(IEASYMAU), copied member FEU.Z25A.PARMLIB(IEASYMAU) into it, and changed the definitions.

SYSDEF  SYSNAME(S0W1) 
        SYSCLONE(1A) 
        SYMDEF(&HOMEIPADDRESS1.='10.1.1.2') 
        SYMDEF(&DEFAULTROUTEADDR.='10.1.1.1') 
        SYMDEF(&DYNXCFIPADDRESS.='10.1.1.31') 
        SYMDEF(&ZCXDVIPAADDRESS.='10.1.1.32') 
        SYMDEF(&EPHEMERALPORTS.='10000 65534') 
        SYMDEF(&GBLRESL.='GBLRESAU') 
        SYMDEF(&TCPPROF='PROF2') 

I shutdown z/OS and restarted it – and then I could use PING and, once I had started FTPD, I could FTP to 10.1.1.2. If you do not want to restart z/OS see below for the long story. in Changing z/OS system symbols is – easy – ish, or “Refreshing TCP/IP definitions“, below.

Update the TCPIP definitions and restart TCPIP or re-ipl

I backed up ADCD.Z25A.TCPPARMS(ZPDTDEV1), then changed ADCD.Z25A.TCPPARMS(ZPDTDEV1) to use the hardcoded address and default router address.

Restarting TCPIP or a REIPL activated these changes – but doing this is disruptive to users.

Refreshing TCP/IP definitions.

It is not easy to refresh the TCPIP definitions. See here.

Once I had made the changes, and activated the updated definitions, I could ping to z/OS and use FTPD.

Changing Linux

I changed my devmap to have

[manager] # tap0 define network adapter (OSA) for communication with Linux
name awsosa 0022 –path=A0 –pathtype=OSD –tunnel_intf=y –tunnel_ip=172.26.1.1
device 400 osa osa –unitadd=0
device 401 osa osa –unitadd=1
device 402 osa osa –unitadd=2

The “ip route” command gave

default via 192.168.1.254 dev wlp4s0 proto dhcp metric 600
169.254.0.0/16 dev wlp4s0 scope link metric 1000
172.26.1.0/24 dev tap0 proto kernel scope link src 172.26.1.1
192.168.1.0/24 dev wlp4s0 proto kernel scope link src 192.168.1.223 metric 600

The find_io command gave

         Interface         Current          MAC     IPv4       IPv6           
 Path    Name              State            Address Address    Address        
------   ----------------  ---------------- ------- -------    --------- 
  F0     enp0s31f6         UP, NOT-RUNNING  8c:...  *          *               
  F1     wlp4s0            UP, RUNNING      d4....  192....    2a00:...  
  F2     wwan0             DOWN             a2....  *          *               
. 
  A0     tap0              UP, RUNNING      22....  172.26.1.1 fe80...
  A1     tap1              DOWN             02....  *         *               
  ...

I could ping and FTP to 172.26.1.2.

Using eclipse based tools to z/OS

Eclipse based tools like z/OS Explorer and IBM Developer for z/OS, use a server on the z/OS system called RSED.

This is available on the ZD&T (ZPDT) system, but is hidden away.

You need to mount the file system

mount filesystem(‘FEK320.HALG320.ZFS’) mountpoint(‘/usr/lpp/IBM/zexpl/’)
mode(read)type(ZFS)

Then start the server

s rsed

It’s easy when you know how.

Getting z/OS running on my Ubuntu laptop with zD&T and zPDT

Having downloaded and installed the zD&T, ZPDT and z/OS products on my laptop.  I was keen to start using it.   Here are part of my journey.

The  IBM ZPDT Guide and Reference redbook is excellent.

I used zD&T to install the products,  but it is missing a few things.

Check the environment

I used /usr/z1090/bin/z1090instcheck in section 4.1.84 of the red book to check the configuration.

I had

 UBUNTU kernel.core_pattern is |/usr/share/apport/apport which is BAD

I left it as it was, it is about what happens if there is a coredump.

Section 4.1.11 talks about checking /etc/sysctl.conf. You can use

sudo  /usr/z1090/bin/aws_sysctl

to set all of the parameters to value values.   It prompts before it changes any value, so is safe.

Creating the devmap

I used the perl script to create my devmap file.

Number of processors

You may want to set the number if processors less than the number of cores in your machine, so you can continue to run if zPDT is 100% busy.
Use the top command.  At the top it shows “load average: 5.3 3.7 4.1” this shows 3 numbers – this is 3 cores.

Set the number of cores using the

processors 1 # number of processors

statement.  Event with 1 processor, sometimes the laptop locked up, the cursor did not move,  or was about 5 seconds behind moving the mouse.

Storage usage

z/OS requires a minimum of 2GB to start (otherwise you get a message at IPL)

IAR057D LESS THAN 2GB OF REAL STORAGE IMPACTS SYSTEM AVAILABILITY

Using the top command gave

 

Use the free -g command to display the storage in your machine, so you do not over allocate the storage.

      total used free shared buff/cache available
Mem:     7     3    0      3          3         0
Swap:    0     0    0

The devmap had

memory 5984m  # define storage size for virtual host

When I stared zD&T  I got

AWSSTA146I Starting independent 1090 instance 'ibmsys1'
AWSEMI001T Insufficient Memory for 1090 to start.

I changed the memory to

memory 2G  # define storage size for virtual host

And I got into the IPL.

First IPL

I did a cold start, as per instructions.

I saw a message “waiting for vtam”.  So I reipled.

I used the command k s,del=n to prevent messages rolling off the top of the screen, and saw

CSV028I ABEND306-0C ISTCFCR2 and VTAM won’t start

I issued the commands

  • SETPROG APF,ADD,DSNAME=NET621.SCNMLNK1,VOLUME=A4PRD3
  • S VTAM

and the system started.

Edit ADCD.Z24A.PARMLIB(PROGAB)  and add  NET621.SCNMLNK1  A4PRD3, and do the same the the same data set on SARES1

Basic checks

The system worked as expected.

I could use x3270 localhost:3270 to get into z/OS using a 3274 “hardware controller” or x3270 10.1.1.2 via TCPIP.  This showed my IP network was basically working.

To get FTP working

Use the MVS command S  FTPD this takes a short time to start.

I installed vsftp on Ubuntu and started it

  • sudo apt install vsftpd
  • sudo service vsftpd start

I could FTP 10.1.1.2 and enter the userid and password.  When I issued any command such as ls, it hung.

I used this article on the Ubuntu firewall. The command  sudo ufw status verbose gave

Status: active

I disabled the firewall in linux

sudo ufw disable

and ftp worked.

The log showed me the activity sudo grep -i ufw /var/log/syslog |grep 10.1.1

Either of the commands give access through the firewall

  • sudo ufw allow from 10.1.1.2
  • sudo iptables -A INPUT -p tcp -s 10.1.1.2 -j ACCEPT

TCP error messages

I got

11.45.32 *EZZ9308E UNRESPONSIVE NAME SERVER DETECTED AT IP ADDRESS 9.26.4.6
11.45.32 EZZ9310I NAME SERVER 9.26.4.6
TOTAL NUMBER OF QUERIES SENT 2
TOTAL NUMBER OF FAILURES 2
PERCENTAGE 100%

This is because it is trying to use the DNS server .  The default is to use DNS then local. To fix this edit  ADCD.Z24A.TCPPARMS(TCPDATA)  insert the bold line

; LOOKUP statement 
; ================ 
; LOOKUP indicates the order of name and address resolution. DNS means 
; use the DNSs listed on the NSINTERADDR and NAMESERVER statements. 
; LOCAL means use the local host tables as appropriate for the 
; environment being used (UNIX System Services or Native MVS). 
; 
; LOOKUP DNS LOCAL  the default
LOOKUP LOCAL

Specifying LOCAL uses /etc/hosts which has

10.1.1.2 S0W1.CANLAB.IBM.COM S0W1 
127.0.0.1__ localhost localhost.localdomain localhost4 
___________ localhost4.localdomain4__________________ 
::1________ localhost localhost.localdomain localhost6 
___________ localhost6.localdomain6________________

Where the _ is really hex ’41’ !

I went into OMVS and issued

mv /etc/resolv.conf /etc/resolv.conf.old
touch /etc/resolv.conf
chmod 755 /etc/resolv.conf

ISPF primary menu

The initial ISPF menu is in

ADCD.Z24A.ISPPLIB(ISR@PRIM)

You can copy it to USER.Z24A.ISPPLIB and tailor it.  If you create a new member name – COLIN, use the command at logon ispf panel(COLIN)

The supplied ISR@PRIM has options which are not listed on the display RACF, ISMF, SMPE, WLM S (for SDSF).  This allows you to issue =S or =ISMF.

When you logon to TSO there is an ISPFLITE procedure with no optional products in the list, in case you have problems.

Unexpected messages

I got the following message many times at IPL  once for each disk.

IEC816I xxx VARY ONLINE – CU AUTHORIZATION FAILED SER=IBM-01024

A VARY ONLINE command attempted to validate the use of advanced features for the device.
The authorization failed.

I think this can be ignored.

RACF set up.

RACMAP command gets Abend System 684 rc 004

Copy ADCD.Z24A.PARMLIB(IKJTSO00) to USER.Z24A.PARMLIB(IKJTSO00)

Add RACMAP

 

Getting z/OS installed on my Ubuntu laptop

Some people retire and buy an open top sports car or big motorbike.  Up here in Orkney  the weather can change every day, so instead of buying a fast car with an open top, when I retired, I got z/OS running on my laptop for the similar sort of price!   This means I can continue “playing” with z/OS and MQ, and helping the next generation to use z/OS.  At the end of this process I had the software installed on my laptop, many unwanted DVDs, and a lot of unnecessary cardboard.

I’ll cover my journey in getting the product and installing it, so anyone following in my footsteps will know what to expect and the time frame.  The process works, but could be slicker.

What options are there?

There are two emulators

HerculesHercules is an open source software implementation of the mainframe System/370 and ESA/390 architectures, in addition to the new 64-bit z/Architecture. Hercules runs under Linux, Windows (98, NT, 2000, and XP), Solaris, FreeBSD, and Mac OS X (10.3 and later).

zPDT from IBM.  IBM System z® Personal Development Tool (IBM zPDT®), which produces a small System z environment suitable for application development. zPDT is a PC Linux application. When zPDT is installed (on Linux), normal System z operating systems (such as IBM z/OS®) can be run on it. zPDT provides the basic System z architecture and emulated IBM 3390 disk drives, 3270 interfaces, OSA interfaces, and so on.  It needs a USB dongle or a license server to run.

What software can be used?

  • Products like z/OS, z/VM and z/VSE are licensed to run on only zPDT software.
  • Using z/VM to provide a coupling facility allows z/OS sysplex functions to be run.  Your USB dongle needs to have the support for this.
  • Public domain or “copyrighted software provided without charge”  software like OS/360DOS/VS, MVS, VM/370 were in the field a long time ago and can be installed on Hercules without a license.     You can also get MTS (which I used when I was at University).

What software is available to me?

I will not cover Hercules, as it is not licensed, and will only cover the IBM solution.

  1. For (big) business partners who are developing software to run on z/OS, you need to get approval to become a z ISV.  You can then  get the hardware dongles and the software from one part of IBM
  2. For other people (like me) who want to use z/OS running on a laptop for non production work there is zDevelopment and Test (zD&T). This comes in 3 flavours.
    1. ZD&T Personal Edition enables a single user to run an IBM® Z distribution on a personal computer. For more information about Personal Edition, see Personal Edition.
      • See here for the price.  You can pay for a 1 year subscription, get support from IBM,  download the code and any updates, and a hardware dongle which has the license to use/decrypt the code
      • You can pay for a perpetual license where you get the 1 year subscription as above, but can use it for ever (no support or updates after 1 year).  You can renew the license for the dongle at no charge.
    2. ZD&T Enterprise Edition enables enterprises to host an IBM Z distribution on low-cost Intel-based x86 machines. Enterprise Edition provides a web-based interface. You can extract, deploy, and manage the application images from an existing Z or ADCD packages. For more information about ZD&T Enterprise Edition, see Enterprise Edition.
      • I could not find the price for this. The license set-up looks very complex.  It looks like you need multiple machines to implement it  With a flexible licensing method, ZD&T Enterprise Edition can be used on cloud, VMs, or in-housed physical 8086 hardware. The Enterprise Edition also comes with a single user license that is known as Authorized User (AU) license, or with a multi-user license that is known as the Resource value Unit (RVU) license.
    3. ZD&T Parallel Sysplex can be used to enable a Sysplex environment that is running within z/VM®. For more information about ZD&TParallel Sysplex, see Parallel Sysplex.
      • I could not find the price for this. It looks like you have to use  a separate machine running as a license server.  The Software-based License Server and ZD&T Parallel Sysplex cannot be installed on the same machine.   I got confused between hardware dongle, software License Server and Rational tokens (which look like they need a different machine).

How do I purchase it?

See the IBM website.  That is the for the UK.    Or use

  • HTTP://IBM.COM
  • sign on
  • search for Development test environment
  • Select IBM Z Development and Test Environment in the right hand side of the window.

I’ve paid my money – now what?

This page says Software available for immediate download after online purchase.  This was not true for me.

  • You need an IBM id – this takes seconds to obtain.
  • To be able to download software and get the hardware key, you need access to Passport Advantage.
  • To get access to Passport Advantage you need a site number
  • To download software you need an IBM customer number, and an entry in a database saying what you are entitled to download.
  • To get a customer number takes a few days.

You should plan on two weeks from ordering the package to be able to run it.

The sequence of events before I could download the software and order the USB key…

  • I paid my money on the day 1
  • I quickly received an an email from IBM saying “thank you for your order”.   I was expecting a slick process like Amazon, saying “Your dongle has been dispatched – expect it in 3 days, you can download the software now” – but no.
  • I quickly received an email from IBM saying “Welcome to IBM Rational License Key Center.  Here is your License Key Center account ID:123456789.  Here are the instructions for downloading your license key”.  Great – the first question it asks  is “what is the serial number of your hardware key”.  I had not received it yet, so could not download the license.
  • I created a Passport Advantage account using the “License Key Center account ID” as my “site”.  This worked, and I got an email saying “IBM Welcomes you to Passport Advantage Online”
  • I logged on and tried downloading software – there was non available to me.  I could not order a hardware dongle as I needed a customer number.
  • I had an email from IBM Philippines asking “please confirm if this is for personal or commercial use”.  I said this was for me using as part of my company.    As a result it was flagged as “personal use”.
  • Day 2. I got an electronic PDF invoice, which told me my site number was as above.
  • I received my “Proof of entitlement” giving me my customer number and site number.
  • Later that night I got an email “IBM Electronic Support: Welcome to IBM Electronic Support
  • Day 3. I could order my hardware dongle and there was software for me to download!
  • The money was taken from my account
  • The hardware USB key arrived on day 11 – but the courier notified my it was coming on day 15.

So overall allow for a couple of days before you can access the software, and 2 weeks for the box of dongles.

Downloading the software

If you use the DownloadDirector, check that directory is empty before you start the download – you can move files to a sub directory, or select a different directory for the downloads.  The default directory is ~/DownloadDirector.

You need about 46GB just to download the files,and 270 GB when the files are unpacked.  There are 31 unpacked files of 8GB and one file of 15 GB for z/OS and its disks.  If you are going to allocate additional disks, plan for 8GB for each.

At first glance, the download looked pretty simple. It is, unless you want to put the files on a different drive to the default.

  • From the IBM Passport Advantage site click on Download software.
  • It had IBM Z Development and Test Environment Personal Edition displayed.  I clicked on it.
  • It popped up a window saying
    • IBM Z Development and Test Environment Personal Edition
    • Please do not select an operating system and language for all Engineering and Rational software.   I don’t know what this means.  I ignored it
    • Operating system had a pull down list 1) All operating systems 2) Redhat.   I use Ubuntu so I chose 1) All operating systems.
    • Language had a pull down list of languages.  I selected English and clicked Go.
  • The download page said Required: 38 files (45319MB)  which was the first time I had been told about the amount of space needed.
  • I could select all files or individual files.   This page  gives a list of packages to volids.  A package may have more than one file in it – despite what the description is.
  • I clicked on Estimate download time for selected files.   it gave me T1 Download Director 951 minutes, HTTP 4758 minutes.
  • I clicked on  Download, which displayed a terms and conditions page.  Click “HTTP” or “Download Director”, click “I agree” and click “download now” .
  • It displayed “Your browser might ask to open/save a JNLP file in order to launch Download Director. Open the JNLP file with Java WebStart (javaws).”  Click OK
  • It popped up a window “Opening IBM_DownloadDirector.jnlp” Select “Open with “Oracle Java 8 Web Start (default)”   click OK
  • There is a pop up ” Do you want to run this application?  IBM Download Director?” Click on Run
    • The first time I ran it, it tried to put all of the downloads in ~/DownloadDirector.  I clicked cancel, and Setup, and specified the download location to my external hard drive, and clicked “Always ask for Download location”. When I reran it, I think it ignored the location and  put the files in the ~/DownloadDirector path.   The second time I came through this process, it prompted me for the Download Location as expected.  It would be nice if the first time through it prompted for download location rather than take the default.
  • Check where the files are being downloaded to, and restart the download if they are going to the wrong place.
  • The documentation says Verify the integrity of downloaded ADCD packages by using the MD5SUM that is in the adcd.md5 and pe.md5 files.   You can use the command  md5sum -c nov2019_adcd_md5.txt  to do a checksum on the downloads.

Ordering the hardware dongle.

In Passport Advantage, select “Software download & media access“.  Then select “Request Media”.   It should have the hardware dongle items you need.  I can’t remember what I ordered, but I overachieved and ordered stuff I didn’t want.   I cannot remember what the request page looked like, but once the order had been fulfilled it I could see I had ordered

  • IBM Z Development and Test Environment Version 9.1 Hardware Key Multiplatform Multilingual DVD Media Pack (BT0MIML)
  • IBM Z Development and Test Environment Version 9.1 Multiplatform Multilingual DVD Media Pack (BT0MJML)
  • IBM Z Development and Test Environment Hardware Key Version 9.5 Multiplatform Multilingual DVD Media Pack (BT0NUML)
  • IBM Z Development and Test Environment Personal Edition Version 10.0 Multilingual Hardware Key Media Pack (BT0P6ML)
  • IBM Z Development and Test Environment Personal Edition V12.0 Multilingual Hardware Key Media Pack (BT0PFML)

I do not know which of these I should have ordered, the names all look similar.   I was reminded of the phrase from the original game of Adventure “you are in a maze of twisty little passages , packages all alike

What came in the dongle box?

I  was notified that the package would be delivered on day 15, but it arrived on day 11.  I was expecting a small jiffy bag. I got a box 30 cm * 24 cm * 20 cm, with lots of Russian Doll type boxes – it was like Christmas!

In the box I had

  • A box labelled RD&T for System z V9.1 Hardware key media pack containing
    • a box containing
      • a bag containing
        • a plastic wallet containing
          • the USB
    • a CD labelled  IBM Rational Developer and test environment for system z V9.1
    • some instructions
    • other paper work
  • A box labelled RD&T for System z V9.5 Hardware key media pack containing
    • a box containing a bag,containing a plastic wallet, containing the USB
    • a CD labelled  IBM Rational Developer and test environment for system z V9.5
    • some instructions
    • other paper work
  • A box labelled IBM z Systems Development and Test Environment Personal Edition  V10 containing
    • a box containing a bag, containing a plastic wallet, containing the USB
    • a CD labelled IBM z Systems Development and Test Environment Personal Edition  V10
    • some instructions
    • other paper work
  • A box labelled IBM z Systems Development and Test Environment Personal Edition  V12 containing
    • a box containing a bag, containing a plastic wallet, containing the USB
    • a CD labelled IBM z Systems Development and Test Environment Personal Edition  V12
    • some instructions
    • other paper work
  • A bigger box containing CDs
    • IBM Rational Integration Tester Platform Pack 1 CD
    • IBM Rational License Key Server 1 CD
    • IBM Rational Developer and test environment  for System z v9.1 Software distribution for z/OS 1.1.3 12 CDs
    • IBM Rational Developer and test environment  for System z v9.1 Software distribution for z/OS 2.1 15 CDs

Overall I got 4 USB keys (It  could be a challenge to use all 4 ,as my laptop has only one spare USB slot), lots of software and a lot of cardboard.  As I have already downloaded the images, I have two lots of software CDs I do not need. I think the provisions system needs to be looked at, so I get just what I need (one dongle) instead of a lot of waste cardboard and plastic.

Getting the license for the keys

The documentation has a topic Obtaining an update file from Rational License Key Center  which worked.

  • Follow the link and logon
  • It showed me IBM Rational Developer for System z Unit Test.
  • The serial number of one of my USBs was like 02-00222.
  • Number of Server Instances:1
  • Number of Licenses:1
  • Click generate, wait for 10 second and a window is displayed
  • Click download – and save it
  • Follow the instructions in the documentation.  I cannot use “su” so I used sudo ./Z1091_token_update…  which worked.  note the upper case Z in Z1091
  • The status command “sudo ./Z1091_token_update -status” gave me
    • Info: Processing Status request.
    • Info: Found both ADCD-1 License and ADCD-2 License.
    • Info: Command completed with 0 error(s).

As I was only entitled to one license – I had 3 spare dongles but with no license for them.

Installing zD&T.

The instructions are here.

  1. Check the instructions are for the level of zD&T you are using.   Google found me the version for 12.04; I was using 12.05
  2. The license is displayed.
    1. The license is displayed using the more command, so you can use ‘f’ and ‘b’ to go forward and back.  (Until you get to the last page when you cannot go back,  you have to decline license, and go through the install again.
    2. I found the license was not clear.   It looks like big chunks are repeated with only minor variations, which were too subtle for me.
    3. Some software you are allowed to install but not use: Fault Analyzer for z/OS and File Manager for z/OS.  (File manager:  IBM® File Manager for z/OS® (base component) provides comprehensive, user-friendly tools for working with Websphere MQ data, HFS files and QSAM, VSAM and IAM data sets. These tools include the familiar view, edit, copy and print utilities found in ISPF, enhanced to meet the needs of application developers)
    4. I think the words about Authorized User Single Session apply to zD&T personal Edition, and the words about  Resource Value Unit (RVU) apply to the enterprise edition.
    5. I don’t understand When determining the number of entitlements required for Licensee’s installation or use of the Program, Licensee is allowed to define up to two log-in identifiers for use by system programmers (i.e. system administrators or database administrators) to support Licensee development and test activities, which are not used to determine the number of entitlements required for the Program.  I do not understand this (what entitlements?, what is not used ?).  At least two userids are defined, for example IBMUSER, so additional  system programming userids may not be needed.  I do not know if I am allowed to define more userids for doing MQ application development, and defining MQ resources.
    6. The license refers to “Program”.   The text has Program Name : IBM Z Development and Test Environment Enterprise Edition Version 12.0.5, so I think the term “Program” to mean the whole package, so CICS, MQ and z/OS are individual Programs.
      1. This sounds a bit recursive, The license Programs, have programs (load modules) which have programs (compilable source code), the compiled programs have z architecture  instructions which deep down have programs in zPDT, which have instructions which have microcode programs which run on the chip.
    7. I could not find how to get a copy of the license, so I cancelled the installation and found the license in ~/DownloadDirector/zdtpefolder/license/Lic_en.txt
    8. Text like L/N: L-JWOG-BKVNF6 are the license number.  I think it is IBM internal use only as I googled it but could not find it.
    9. So overall written by lawyers and hard to understand.

Optional questions.

It asked Do you want to install Network Configuration for IBM® ZD&T Personal Edition ?(y/N):

I don’t think it installs anything.   I think it configures the network. See installation  and network.  The configuration scripts for example in /opt/ConfigGuideSample/zdt_config_network10.sh enables packet forwarding,  uses iptables to set up routing, Network Address Translation(NAT) with destination of 10.1.1.2.

I could IPL and logon without doing this optional step.  To get FTP working, I had to make one network configuration action.

It uses iptables-save  to make a copy of the IP configuration.  You may want to issue sudo iptables-save > myipconfig.txt  to save your current configuration before using this install to change it.

It makes changes to the running system, then saves them, and changes /etc/rc.local so the commands are executed at Linux boot time.

It asked Optional: Enter y to install all needed dependencies or enter n to decline.

I thought I had checked these, so I replied n.  I don’t know if it checks them and warns of any missing ones.

The installation complete message is not as documented.   The documentation says “If the package is installed successfully, the following output is displayed”

z1091-1-10.55.04.x86_64

I got

ii z1091 1.10.55.04 amd64 z1091, version 1.10.55.04, build date - 02/19/20 for Linux on Ubuntu 64bit

which is close enough.

Unzipping the files

Files  ending in .gz can be unzipped with gunzip.  The other files have to be decrypted and you need the dongle to do that.

The command

gunzip file.gz

takes the file, unzips it to file and deletes file.gz.  The option -k says do not delete the input file.

You can use the command

gunzip -c file.gz > /directory/file

the -c option says write to sysout and do not delete the input file.

To unzip all the files (this took a couple of hours to execute).

  • you could issue gunzip *.gz  . You may want to check that the directory has only the zP&T files in it before executing the command.  Remember it will delete the .gz file afterwards.  (This helps save space).
  • if you want to have the unzipped files on a different drive you could copy the .gz files to the drive then issue  gunzip *.gz in the directory.

Unzip and decrypting the RES files.

When I tried to unzip the *RES files using my colinpaice userid I got.  /usr/z1090/bin/Z1091_ADCD_install: error while loading shared libraries: libawsDiskItf.so: cannot open shared object file: No such file or directory.

I logged switched to the ibmsys1 userid, and followed the instruction in the documentation. I got

  • /usr/z1090/bin/Z1091_ADCD_install ./A4RES1.ZPD ./A4RES1
  • LIC hasp: * Communication error between API and local Sentinel License Manager : code=33

It took just over 4 minutes to unzip the SARES1 disk

Overall all

The overall process worked.  It took longer than I expected to get entitlement, and the hardware dongles.  I also have 3 dongles I cannot use, a large pile of cardboard, and two piles of CDs I don’t think I need.