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
• More complex example – Using Link and Device statements
• More complex example – Using an Interface statement
• More complex example – Using an Interface statement and different IP address ranges
• Lessons learned

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.

More complex example – using Link and Device statements

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