Networking options overview
This chapter provides an overview of networking options that are available for IBM z/VSE.
Hardware options include the features of the latest IBM System z and z Enterprise processors and various types of networking adapters, such as Open Systems Adapter-Express, IBM HiperSockets™, and Intra-Ensemble Data Network (IEDN).
Software options include the different IP stacks that are available for z/VSE, TCP/IP for VSE/ESA, IPv6/VSE, and Fast Path to Linux on System z (Linux Fast Path), and different networking protocols, such as IPv4 and IPv6.
There are applications that are designed for a specific stack. Other applications can be used together with all stacks.
Finally, we describe how you can secure your connections by using Secure Sockets Layer (SSL).
This chapter includes the following topics:
 
1.1 Overview
The following sections provide an overview of the networking options that are available for z/VSE.
In this book, we describe only the hardware options that are based on Open Systems Adapter (OSA) technology. Earlier options, such as Common Link Access to Workstation (CLAW) or Channel to Channel Adapter (CTCA), are no longer relevant for most customers. For more information about CLAW, see Networking with z/OS and Cisco Routers: An Interoperability Guide, SG24-6297.
Software options for z/VSE include IPv4 and IPv6 in different environments and IP stacks.
1.2 Hardware options
This section describes various connectivity options that are based on OSA technology as they are relevant for z/VSE. For a general overview on OSA, see the following resources:
•OSA Express Implementation Guide, SG24-5948, which is available at this website:
•Open Systems Adapter-Express Customer's Guide and Reference, SA22-7935, which is available at this website:
•IBM System z Networking Features:
•Introducing OSA-Express, OSA-Express2, and OSA-Express3:
•IBM System z Connectivity Handbook, SG24-5444, which is available at this website:
1.2.1 OSA-Express
The OSA is a network controller that you can install in a mainframe I/O cage. The adapter integrates several hardware features and supports many networking transport protocols. The OSA card is the strategic communications device for the mainframe architecture. It has several key features that distinguish it from CCW-based communications.
The OSA integrates the control unit and device into the same hardware by placing it on a single card that directly connects to the central processor complex I/O bus.1
The following versions of the OSA are available:
•OSA-Express
•OSA-Express2
•OSA-Express3
•OSA-Express4S
•OSA-Express5S
z/VSE supports OSA-Express adapters in IBM System z environments. OSA-Express in QDIO mode is supported since VSE/ESA 2.6 and IBM HiperSockets since VSE/ESA 2.7.
The OSA-Express family of network adapters (OSA-Express5S, OSA-Express4S, OSA-Express3, and OSA-Express2) supports the following features:
•10-Gigabit Ethernet
•Gigabit Ethernet
•1000BASE-T Ethernet
 
Note: Starting with OSA-Express4S, group addressing is no longer supported.
Table 1-1 shows the channel-path identifier (CHPID) types that are supported by z/VSE.
Table 1-1 OSA adapter CHPID types
CHPID type
Description
SA-Integrated Console Controller (OSC)
OSA-ICC for emulation of TN3270E and non-SNA DFT 3270
OSA-Express in QDIO mode (OSD)
Queued Direct Input/Output (QDIO) architecture
OSA-Express (OSE)
non-QDIO Mode (OSA-2, for SNA/APPN connections)
OSA for NCP support (OSN)
OSA-Express for NCP: Appears to z/VSE as a device that is supporting Channel Data Link Control (CDLC) protocol.
OSA-Express for zBX (OSX)
OSA-Express for zBX. Provides connectivity and access control to the Intra-Ensemble Data Network (IEDN) from z196, z114, zEC12, and zBC12 to Unified Resource Manager functions.
These CHPID types are described next. For each type, there is a sample IOCDS definition, the related statement in the IPL procedure, and how TCP/IP is configured to use this CHPID type.
1.2.2 OSA-Integrated Console Controller
The OSC CHPID type is available on mainframes that are running an OSA-Express2 card or an OSA-Express card with the Gigabit Ethernet feature. The OSC is a special channel type that eliminates the need for an external console controller. The OSC CHPID can also be used to connect TN3270 sessions (with some limitations).
IOCDS definition
The IOCDS definition is shown in the following example:
CHPID PATH=(CSS(0,2,3),0C),SHARED, *
      PARTITION=((CSS(0),(0),(P0E)),(CSS(2),(GRY2LP41,GRY2LP42*
      ,GRY2LP43,GRY2LP44,GRY2LP45),(=))), *
NOTPART=((CSS(3),(GRY2LP60))),PCHID=5D1,TYPE=OSC
CNTLUNIT CUNUMBR=0003,PATH=((CSS(2),0C),(CSS(3),0C)),UNIT=OSC
IODEVICE ADDRESS=(cuu1,num),MODEL=X,UNITADD=00,CUNUMBR=(0003),*
      UNIT=3270
IPL procedure
The IPL procedure is shown in the following example:
ADD cuu1:cuu2,3277
CHPID type OSC does not support TCP/IP traffic.
1.2.3 OSA-Express in QDIO mode
The Queued Direct Input/Output (QDIO) architecture provides increased performance because of minimized I/O interrupts and I/O path-lengths. It dramatically improves data transfer speed and efficiency for TCP/IP traffic.
To access an OSA-Express adapter in QDIO mode, you need the following OSA-Express devices:
•Read device
•Write device
•Data path device
 
Note: Use QDIO mode wherever possible.
IOCDS definition for OSD
The IOCDS definition for OSD is shown in the following example:
CHPID PATH=(CSS(0,1,2),B6),SHARED, **
      PARTITION=((CSS(0),(COH1,VMA,VMCOV),(VMC)),(CSS(2),(LNXT**
      ST1,VMUNI),(=))),PCHID=540,TYPE=OSD
CNTLUNIT CUNUMBR=0003, *
      PATH=((CSS(0),B6),(CSS(1),B6),(CSS(2),B6)),UNIT=OSA
IODEVICE ADDRESS=(cuu1,num),CUNUMBR=(0003),UNIT=OSA
IPL procedure
Add the device addresses in the IPL procedure as device type OSAX, as shown in the following example:
ADD cuu1-cuu3,OSAX
TCP/IP for VSE/ESA
In TCP/IP for VSE/ESA, you define a LINK with type OSAX, as shown in the following example:
DEFINE LINK,ID=...,TYPE=OSAX,DEV=cuu1,DATAPATH=cuu3,IPADDR=addr,...
IPv6/VSE
In IPv6/VSE, you define a DEVICE with type OSAX.
DEVICE device_name OSAX cuu1 portname cuu3
The device numbers in the DEV parameter of the DEFINE LINK statement (TCP/IP for VSE/ESA) or DEVICE statement (IPv6/VSE) must be an even/odd pair for the read and write device.
 
Note: If you are running under z/VM, ensure that the real device numbers as generated in the IOCP are an even/odd pair.
Additionally, the device number of the write device must be the successor (+1) of the device number of the read device.
1.2.4 OSA-Express
The CHPID type OSE emulates former OSA-2 devices.
IOCDS definition for OSE
The IOCDS definition for OSE is shown in the following example:
CHPID PATH=(CSS(0),94), *
      PARTITION=((R35LP01),(R35LP02,R35LP03,R35LP04,R35LP05,R3*
      5LP06,R35LP07,R35LP08,R35LP09,R35LP10,R35LP13,R35LP14,R3*
      5LP15),REC),PCHID=550,TYPE=OSE
CNTLUNIT CUNUMBR=0003,PATH=((CSS(0),94),(CSS(1),94)),UNIT=OSA
IODEVICE ADDRESS=(cuu1,num),CUNUMBR=(0003),UNIT=OSA
IPL procedure
Add the device addresses in the IPL procedure as device type OSA, as shown in the following example:
ADD cuu1-cuu2,OSA
TCP/IP for VSE/ESA
The TCP/IP for VSE/ESA is shown in the following example:
DEFINE LINK,ID=...,TYPE=OSA,DEV=(cuu1,cuu2), .......
IPv6/VSE
When IPv4 is used, you use the following DEVICE command:
DEVICE device_name OSA cuu1 ETHERNET
IPv6 is not supported by CHPID type OSE.
1.2.5 OSA for NCP support
Open Systems Adapter for NCP (OSA for NCP) support provides channel connectivity from the operating systems to the Communication Controller for Linux on System z (CCL) image. Each operating system that supports CDLC can use this connectivity option without changes to the operating system. OSN was available since IBM System z9® and IBM System z10® servers.
CHPID type OSN requires 1000BASE-T Ethernet with two ports per feature.
IOCDS definition
The IOCDS definition is shown in the following example:
CHPID PATH=(CSS(0,1,2,3),0D),SHARED, *
      NOTPART=((CSS(1),(IRD6),(=)),(CSS(2),(TUXMAKER),(=)),(CS*
      S(3),(IRD1,IRD2))),PCHID=370,TYPE=OSN
CNTLUNIT CUNUMBR=0003, *
      PATH=((CSS(0),0D),(CSS(1),0D),(CSS(2),0D),(CSS(3),0D)), *
      UNIT=OSN
IODEVICE ADDRESS=(070,008),UNITADD=00,CUNUMBR=(0003),UNIT=OSN
IODEVICE ADDRESS=(078,003),UNITADD=08,CUNUMBR=(0003),UNIT=3745
IODEVICE ADDRESS=07F,UNITADD=FE,CUNUMBR=(0003),UNIT=OSAD
IPL procedure
Emulates a 3745 adapter and is used like a real 3745 adapter in z/VSE.
There is no TCP/IP support for CHPID type OSN.
1.2.6 Intra-Ensemble Data Network support
The OSA-Express for zBX (CHPID type OSX) provides connectivity and access control to the IEDN from IBM zEnterprise® 196, z114, zEC12, and zBC12 to Unified Resource Manager functions. IEDN is supported by OSA-Express 10 GbE features only.
An IEDN is a private 10-Gigabit Ethernet network for application data communications within an ensemble. Data communications for workloads can flow over the IEDN within and between nodes of an ensemble. All of the physical and logical resources of the IEDN are configured, provisioned, and managed by the Unified Resource Manager.
An OSA-Express adapter that is connected to an IEDN has fast and secure network access to other nodes and systems that also connected to the IEDN.
An IEDN provides connectivity between the following components:
•A zEnterprise Central Electrical Complex (CEC) and IBM zEnterprise BladeCenter Extensions (zBXs)
•Two or more zEnterprise CECs
z/VSE supports the IEDN network of a zEnterprise 196, z114, or zEC12 in the following environments:
•z/VSE V4.2, V4.3 and V5.1: IBM z/VM VSWITCH and OSDSIM mode in a z/VM 6.1 guest environment.
•z/VSE V5.1: OSA-Express for zBX devices in an LPAR or z/VM guest environment with dedicated OSAX devices. This requires VLAN support.
IOCDS definition
The IOCDS definition is shown in the following example:
CHPID PATH=(CSS(0,2),CA),SHARED, *
      PARTITION=((CSS(0),(DWB1,DWB2),(=)),(CSS(2),(LNXTST1),(V*
      MUNI))),PCHID=3F8,TYPE=OSX
CNTLUNIT CUNUMBR=0003,PATH=((CSS(0),CA),(CSS(2),CA)),UNIT=OSX
IODEVICE ADDRESS=(cuu1,num),MODEL=X,CUNUMBR=(0003),UNIT=OSA
IPL procedure
The IPL procedure is shown in the following example:
ADD cuu1-cuu3,OSAX
TCP/IP for VSE/ESA
From a TCP/IP for VSE/ESA perspective, OSX is identical to an OSAX link, as shown in the following example:
DEFINE LINK,ID=...,TYPE=OSAX,DEV=cuu1,DATAPATH=cuu3
IPv6/VSE
The IPv6/VSE product is shown in the following example:
DEVICE device_name OSAX cuu1 portname cuu3
The next sections provide more information about the following OSA-Express features:
•OSA-Express Multi-Port Support
•HiperSockets
•Virtual LAN
1.2.7 OSA-Express multi-port support
OSA-Express3 or later provides two ports per CHPID for selected features. The default port is port 0.
For CHIPID type OSE (non-QDIO mode), you must use OSA/SF to select the OSA port. Because there are multiple ports per CHPID, both of the ports that are associated with the CHPID are the same; that is, OSD, OSE, or OSC. It is not possible, for example, to have one port that is defined as OSC and the other as OSD. However, it is possible to have different CHPID types for the same card where the card does support multiple CHPIDs.
Because the number of CHPIDs is limited, the Multi-Port support increases the number of ports you can use. When OSA-Express3 adapters are used, the port number that is used is specified as the adapter number.
IOCDS definition
IPL procedure
For more information, see the IPL procedure headings in the following sections:
TCP/IP for VSE/ESA
The default port is port 0. To use port 1, you must specify the port number by using the OSAPORT parameter of the DEFINE LINK statement, as shown in the following example for CHPID type OSD:
DEFINE LINK,ID=linkname,TYPE=OSAX,DEV=cuu1,DATAPATH=cuu3,OSAPORT=1,...
DEFINE ROUTE ID=local,LINKID=linkname,IPADDR=subnetaddr
DEFINE ROUTE ID=default,LINKID=linkname,IPADDR=0.0.0.0,GATEWAY=ipaddr
With OSAX QDIO, you do not specify the OSA port in the DEFINE ROUTE statement. The correct adapter is identified by the OSA card. The IP address of the gateway must be a router that is attached to the local subnet.
IPv6/VSE
For IPv6/VSE, you specify the adapter number immediately after the device name in the LINK command, as shown in the following example for CHPID type OSD:
DEVICE device_name OSAX cuu1 portname cuu3
LINK device_name 1 IPv6_addr netmask mtu
1.2.8 Using VTAM (SNA) and TCP/IP (non-QDIO) parallel on the same CHPID
IOCDS definitions needed for IBM VTAM® (SNA) and TCP/IP using OSA (non-QDIO):
CHPID TYPE=OSE
CNTLUNIT UNIT=OSA
IODEVICE UNIT=OSA
Definitions in z/VSE IPL procedure for VTAM (SNA):
ADD cuu,OSA
VTAM definitions for using SNA:
VBUILD TYPE=XCA
       PORT MEDIUM=CSMACD
       ADAPNO=1
       CUADDR=cuu
Definitions in z/VSE IPL procedure for TCP/IP using OSA (non-QDIO):
ADD cuu1:cuu2,OSA
For non-QDIO, you need a cuu even-odd pair, for example ADD 260:261,OSA or ADD 270:271,OSA.
TCP/IP definitions for using OSA (non-QDIO):
SET IPADDR=vseipaddr
SET MASK=subnetmask
DEFINE LINK ID=linkname,TYPE=LCS|OSA|OSA2|3172,DEVICES=cuu1
DEFINE ADAPTER LINKID=linkname,TYPE=ETHERNET,NUMBER=1
DEFINE ROUTE ID=local,LINKID=linkname,ADAPTER=1,IPADDR=subnetaddr
DEFINE ROUTE ID=default,LINKID=linkname,ADAPTER=1,IPADDR=0.0.0.0,GATEWAY=ipaddr
The IP address of the gateway must be a router attached to the local subnet.
1.2.9 HiperSockets (IQD)
The HiperSockets implementation is based on the OSA-Express Queued Direct I/O (QDIO) protocol. HiperSockets is also called internal QDIO (iQDIO).
HiperSockets provide “network within the box” functionality, with which high speed any-to-any connectivity among operating systems is possible without requiring any physical cabling. Because a HiperSockets connection does not leave the box, it is secure. This means that there is no attack possible from outside. The entire communication is done in memory, which results in increased performance.
IOCDS definition
HiperSockets must be defined in the IOCDS as CHPID type IQD, as shown in the following example:
CHPID PATH=(CSS(0,1),E5),SHARED, *
      PARTITION=((CSS(0),(0),(D0E)),(CSS(1),(COH2,COH3,VMCOH),*
      (=))),CHPARM=40,TYPE=IQD
CNTLUNIT CUNUMBR=0003,PATH=((CSS(0),E5),(CSS(1),E5)),UNIT=IQD
IODEVICE ADDRESS=(cuu1,num),CUNUMBR=(0003),UNIT=IQD
The frame size is defined by using CHPARM parameter (formerly OS=nn), as shown in the following example:
CHPARM=00 16K (MTU=8K) (default)
CHPARM=40 24K (MTU=16K)
CHPARM=80 40K (MTU=32K)
CHPARM=C0 64K (MTU=56K)
IPL procedure
You must add HiperSockets devices in the IPL procedure as device type OSAX with mode 01, as shown in the following example:
ADD cuu1-cuu3,OSAX,01
TCP/IP for VSE/ESA
The DEFINE LINK statement for HiperSockets is similar to those that we use for defining CHPIDs, as shown in the following example:
DEFINE LINK,ID=...,TYPE=OSAX,DEV=cuu1,DATAPATH=cuu3
IPv6/VSE
Defining HiperSockets in the IPv6/VSE product is similar to defining OSA CHPIDs, as shown in the following example:
DEVICE OSA HIPR cuu1 TRLHF9 cuu3
1.2.10 Virtual local area network
Virtual local area network (VLAN) requires OSA-Express2, OSA-Express3, or later features that are configured in QDIO mode. By using VLAN, a physical network can be divided administratively into separate logical networks. These logical networks operate as though they are physically independent of each other.
z/VSE provides VLAN support for OSA-Express CHPID types OSD and OSX, and HiperSockets devices since z/VSE 5.1.
 
Note: In a Layer 3 configuration, VLANs can be used transparently by IPv6/VSE and TCP/IP for VSE/ESA.
If you want to configure VLANs for OSA-Express (CHPID type OSD and OSX) devices in a Layer 2 configuration that carries IPv6 traffic, the IPv6/VSE product is required.
You can use one of the following two methods to configure your system to use VLAN:
•Configure one or more VLANs in the TCP/IP stack of IPv6/VSE by using the LINK command. For more information about IPv6/VSE commands, see IPv6/VSE Installation Guide, SC34-2616.
•Generate and catalog phase IJBOCONF that includes the global VLANs that are to be used with your OSAX devices. z/VSE provides skeleton SKOSACFG to generate phase IJBOCONF. The VLANs that are contained in IJBOCONF can be used transparently for Layer 3 links by IPv6/VSE and TCP/IP for VSE/ESA. For more information, see z/VSE Planning, SC34-2635.
Example 1-1 shows a sample configuration setting VLAN ID 200 for Device D00.
Example 1-1 Sample SKOSACFG configuration
* $$ JOB JNM=IJBOCONF,CLASS=A,DISP=D
// JOB IJBOCONF GENERATE IJBOSA MODULE CONFIGURATION PHASE
// LIBDEF *,CATALOG=PRD2.CONFIG
// LIBDEF *,SEARCH=PRD1.BASE
// OPTION ERRS,SXREF,SYM,NODECK,CATAL,LISTX
PHASE IJBOCONF,*
// EXEC ASMA90,SIZE=(ASMA90,64K)
IJBOCONF CSECT
IJBOCONF AMODE ANY
IJBOCONF RMODE ANY
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* GLOBAL VLAN DEFINITION *
* *
* DEFGVLAN DEVNO=<CUU>, VLAN_ID=<ID>, VLAN_PRIO=<PRIO> *
* <CUU> VSE DEVICE NUMBER IN HEX FORMAT *
* <ID> VLAN ID IN DECIMAL FORMAT (1 ... 4095)               *
* <PRIO> VLAN PRIORITY (VALID VALUES 0 ... 7)                 *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
DEFGVLAN DEVNO=0D00,VLAN_ID=200
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* ONLY ONE GLOBAL VLAN CAN BE DEFINED PER SUBCHANNEL. *
* IF GLOBAL VLAN IS DEFINED, NO USUAL VLAN(S) MAY BE DEFINED *
* ON THE SAME SUBCHANNEL. *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
END
/*
// IF $MRC GT 4 THEN
// GOTO NOLINK
// EXEC LNKEDT,PARM='MSHP'
/. NOLINK
/&
* $$ EOJ
The job template SKOSACFG is in ICCF library 59.
The next two sections describe the pros and cons of OSA adapter versus HiperSockets. Details about what is important when HiperSockets are used with Linux on System z also are provided.
1.2.11 Shared OSA adapter versus HiperSockets
You can use one of the following methods to connect a z/VSE system with a Linux on System z guest:
•Using a shared OSA adapter
All traffic is passed through the OSA adapter, which has its own processor. Therefore, processing occurs asynchronously and processing in the OSA adapter does not affect host processors.
•Using HiperSockets
This case performs direct memory copy from one LPAR or z/VM guest to the other. Because memory copy is handled by the host processors, processing occurs synchronously. This is especially important when mixed speed processors (full speed IFLs and throttled CPs) are used because memory copy performed by a throttled CP is slower than memory copy performed by a full speed IFL.
1.2.12 Using HiperSockets to communicate with Linux on System z
When HiperSockets are used to communicate between z/VSE and Linux, you might encounter a Target Buffer Full condition. This condition occurs when z/VSE sends data faster or in higher quantities than Linux can receive.
In the past, Linux had 16 inbound buffers (64 KB per buffer = 1 MB per link). To increase the number of buffers on Linux, use the QETH option buffer_count=128. The maximum of 128 buffers requires 8 MB of storage per link.
The default value of 16 was increased to 128 with RHEL6.2 and SLES11 SP2.
 
Note: When TCP/IP for VSE/ESA encounters this situation (BUSY), it waits 500 msec until it tries again to send the packet. Any other packets that are to be sent are queued up.
IPv6/VSE does not have this timer delay performance problem.
The problem can become dramatic if more than 16 packets are queued up to be sent after a BUSY situation. The resend immediately floods the Linux buffers again, which leads to the next BUSY situation.
You can check for the issue by using QUERY STATS,LINKID=xxxx [,RESET] if you ever encounter the BUSY situation (RESET resets the counters), as shown in the following example:
C1 0065 0004: IPL615I Busy mode............................0
C1 0065 0004: IPL615I Busy mode, longest...................0
In TCP/IP for VSE/ESA, you can configure a shorter BUSY wait time with a DEFINE LINK command, where BUSY=nnn (shortest possible wait time is 100 msec.).
 
Tip: For more information about optimizing HiperSockets with IPv6/VSE, see the Bernard Software, Inc. blog, which is available at this website:
APAR DY47394 with PTF UD53905 provides a configuration option with which you can configure the number of QDIO input buffers (the default is 8). Use macro QDIOBUFF (newly shipped with this APAR) in skeleton SKOSACFG in ICCF library 59. It improves the performance in a Linux on System z and z/VSE HiperSockets environment when the number of queues is unbalanced.
The next section describes how to configure the QDIO buffers in z/VSE.
1.2.13 QDIO buffer configuration
Since z/VSE v5.1 (with PTF UD53905), the number of QDIO input queue buffers can be configured. This ability might be needed by clients who extend z/VSE solutions by using Linux on System z that use a HiperSockets network for high-speed TCP/IP connectivity between z/VSE and Linux on System z. Best performance can be achieved when data is always delivered successfully without the need for resending.
Because HiperSockets transfers data synchronously, successful delivery of data depends on free Queued Direct I/O (QDIO) input buffers of the target system. z/VSE uses a default of eight QDIO input buffers. This might not always be sufficient, especially if clients increased the number of QDIO input buffers on the Linux on System z system.
To configure the number of QDIO input buffers for HiperSockets (CHPID type IQD) and OSA-Express devices (CHPID types OSD and OSX), the configuration skeleton SKOSACFG in ICCF library 59 can be used. More QDIO input buffers might require increasing the size of the TCP/IP partition.
 
Note: z/VSE needs 1 MB of 31-bit partition GETVIS space per link (for eight input queue buffers). For each additional input queue buffer, z/VSE needs 64K (OSA-Express) and up to 64K (HiperSockets, depending on your IOCDS definition) more 31-bit partition GETVIS space. Therefore, when the client increases the count of input queue buffers, they also might increase the partition GETVIS space. Because the input queue buffers are PFIXed, the client also must increase the value of the JCL SETPFIX LIMIT statement in their TCP/IP startup job accordingly.
Example 1-2 shows a sample configuration setting 16 QDIO input buffers for device D00. Skeleton SKOSACFG is provided in ICCF library 59.
Example 1-2 Sample SKOSACFG configuration
* $$ JOB JNM=IJBOCONF,CLASS=A,DISP=D
// JOB IJBOCONF GENERATE IJBOSA MODULE CONFIGURATION PHASE
// LIBDEF *,CATALOG=PRD2.CONFIG
// LIBDEF *,SEARCH=PRD1.BASE
// OPTION ERRS,SXREF,SYM,NODECK,CATAL,LISTX
PHASE IJBOCONF,*
// EXEC ASMA90,SIZE=(ASMA90,64K)
IJBOCONF CSECT
IJBOCONF AMODE ANY
IJBOCONF RMODE ANY
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* GENERAL CONFIGURATION *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* QDIO BUFFER COUNT *
* YOU CAN SPECIFY THE NUMBER OF QDIO INPUT QUEUE BUFFERS BY *
* ADJUSTING THE QDIO BUFFER COUNT. THE NUMBER OF QUEUE BUFFERS *
* IS ALLOWED TO BE 8, 16, 32 or 64. *
* THE DEFAULT IS 8. *
* *
* QDIOBUFF DEVNO=<CUU>,IQBUF=<COUNT> *
* <CUU> VSE DEVICE NUMBER IN HEX FORMAT *
* <COUNT> QDIO BUFFER COUNT *
* (VALID VALUE: 8, 16, 32 or 64) *
* *
QDIOBUFF DEVNO=0D00,IQBUF=16
*
* NOTE: *
* UP TO Z/VSE VERSION 5.1 WE NEED 1MB OF 31-BIT PARTITION GETVIS *
* SPACE PER LINK (FOR 8 INPUT QUEUE BUFFERS). FOR EACH ADDITIONAL *
* INPUT QUEUE BUFFER, WE NEED 64K (OSA-EXPRESS) AND UP TO 64K *
* (HIPERSOCKETS - DEPENDING ON YOUR IOCDS DEFINITION) ADDITIONAL *
* 31-BIT PARTITION GETVIS SPACE. SO IF YOU INCREASES THE COUNT OF *
* INPUT QUEUE BUFFERS, YOU MAY ALSO HAVE TO INCREASE THE PARTITION *
* GETVIS SPACE. SINCE THE INPUT QUEUE BUFFERS ARE PFIXED, YOU ALSO *
* HAVE TO INCREASE THE ABOVE VALUE OF THE JCL SETPFIX LIMIT *
* STATEMENT IN YOUR TCP/IP STARTUP JOB ACCORDINGLY. *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
END
/*
// IF $MRC GT 4 THEN
// GOTO NOLINK
// EXEC LNKEDT,PARM='MSHP'
/. NOLINK
/&
* $$ EOJ
1.2.14 Virtual OSA devices and VMAC
Before the introduction of the virtual MAC (VMAC) function, an OSA interface had only one MAC address. This restriction caused problems when load balancing technologies were used with TCP/IP stacks that share OSA interfaces. The single MAC address of the OSA also causes a problem when TCP/IP stacks are used as a forwarding router for packets that are destined to unregistered IP addresses.
VMAC support enables an OSA interface to have a physical MAC address and many distinct virtual MAC addresses for each device or interface in a stack. That is, each stack can define up to eight VMACs per protocol (IPv4 or IPv6) for each OSA interface. VMAC is supported on z9 and later processors with all OSA types.
For more information, see IBM z/OS V1R11 Communications Server TCP/IP Implementation Volume 1: Base Functions, Connectivity, and Routing, SG24-7798.
VMAC support helps to simplify the infrastructure and provide load balancing when a logical partition is sharing the OSA MAC address with another logical partition. Each operating system instance can now have its own unique virtual MAC (VMAC) address. All IP addresses that are associated with a TCP/IP stack are accessible by using their own VMAC address, instead of sharing the MAC address of an OSA port. This applies to Layer 3 mode and to an OSA port shared among logical partitions.
 
Note: Layer 3 means that the stack sees only the IP packets. The hardware Ethernet frames, MAC addresses, and ARP processing are offloaded from the host TCP/IP stack. This reduces stack processor usage, but limits some types of processing.
Layer 2 means that the stack is responsible for managing the TCP/IP packets at the Ethernet frame level. The stack must perform its own ARP/Neighbor Discovery (IPv6) and track or manage Ethernet MAC addresses.
In z/VSE, the idea of defining a VMAC is a Layer 2 concept. When an OSA-Express adapter is running in Layer 3 mode, all MAC processing (ARP, and so on) is managed by or offloaded to the adapter. However, when the adapter is running in Layer 2 mode, the stack is responsible for managing and tracking the MAC and IP addresses. This allows the stack to inform the adapter that multiple MAC addresses are being used, which allows the stack to respond to multiple IP addresses.
IOCDS definition
There is no change to the OSA-Express definition in the IOCDS.
TCP/IP for VSE/ESA
TCP/IP for VSE/ESA does currently not support VMAC.
IPv6/VSE
IPv6/VSE supports virtual OSA-Express devices in Layer 2 mode. This means you can define virtual OSA-Express Layer 2 devices, each with their own IPv4/IPv6 address and VMAC address.
 
Note: z/VSE VMAC support requires z/VSE 5.1 plus IPv6/VSE at GA Build 254.
When you are running under z/VSE 5.1, the OSA-Express adapter can be started by the stack to run in Layer 2 mode. This is done by using the LAYER 2 literal on the DEVICE statement. Also, multiple MAC addresses (VMAC) can be defined for the adapter.
Example 1-3 shows a setup with two OSA-Express devices defined. The DEVICE that is called VIRTUALx (x=0-9,A-Z) is a virtual device where the portname field is used to reference the real OSA-Express device. Each is on a different subnet and the virtual OSA-Express device is using a manually defined VMAC address.
Example 1-3 Configuring virtual OSA devices in IPv6/VSE
DEVICE VIRTUAL0 OSAX 780 OSAX780 782 LAYER2 020000008001
LINK VIRTUAL0 0 192.168.11.238 255.255.255.0 9000
ROUTE VIRTUAL0 192.168.11.0 255.255.255.0 0.0.0.0 0
*
DEVICE OSAX780 OSAX 780 L2TEST 782 LAYER2
LINK OSAX780 0 192.168.10.238 255.255.255.0 9000
ROUTE OSAX780 192.168.10.0 255.255.255.0 0.0.0.0 0
*
ROUTE OSAX780 0.0.0.0 0.0.0.0 192.168.10.1 1
*
By using this configuration, you can have multiple IP/VMAC addresses for each physical OSA-Express adapter. Each device (real or virtual) also can be on a different VLAN.
Linux Fast Path
Linux Fast Path (LFP) does not access any OSA device directly. Support for VMAC depends on Linux on System z. For more information about network configuration for Linux on System z, see the following resources:
•Chapter 9, “What you should know about the qeth device driver” of Device Drivers, Features, and Commands (kernel 3.10), SC33-8411.
1.2.15 OSAX Hotswap support
IPv6/VSE allows you to define a spare or Hotswap device for each OSA Express adapter. If the primary OSA Express adapter fails, the Hotswap adapter and port take over operations without losing connections. Example 1-4 shows an OSAX Hotswap configuration.
Example 1-4 IPv6/VSE Hotswap support for OSAX
// EXEC BSTTINET,SIZE=BSTTINET,OS390,TASKS=ANY
ID 00 NAME OSAIPV4
INTERVAL 120
*
DEVICE OSAX620 OSAX 620 EXPRESS 622
LINK OSAX620 0 10.1.1.239 255.255.255.0 9000
ROUTE OSAX620 10.1.1.0 255.255.255.0 0.0.0.0 0
*
DEVICE OSAX610 OSAX 610 EXPRESS 612
LINK OSAX610 0 192.168.1.239 255.255.255.0 1500
ROUTE OSAX610 192.168.1.0 255.255.255.0 0.0.0.0 0
*
ROUTE OSAX610 0.0.0.0 0.0.0.0 192.168.1.100 1
*
HOTSWAP OSAX610 0630 0632 0
HOTSWAP OSAX620 0640 0642 0
*
ATTACH TCP/IP
/*
The HOTSWAP command specifies the device name and cuu addresses of the read/write pair and the control cuu address. The port number to use is also specified. The cuu addresses must be specified as four character hexadecimal values.
If your primary DEVICE command is DEVICE OSAX610 OSAX 610 portname 612, you can use this HOTSWAP command:
HOTSWAP OSAX610 0630 0632 0
 
Note: Do not HOTSWAP to the same adapter.
Ideally, if you have a z box with two OSA Express adapters and two z/VSE images, you might use port 0 on each adapter as the primary NIC and use port 1 as the HOTSWAP NIC. For example:
Adapter 0, port 0 VSEPROD
Adapter 0, port 1 VSETEST HOTSWAP
Adapter 1, port 0 VSETEST
Adapter 1, port 1 VSEPROD HOTSWAP
Hotswap support requires IPv6/VSE build 255pre08. Example 1-5 shows the console log from the case where the primary OSAX adapter gets detached and the hotswap device immediately takes over control.
Example 1-5 IPv6/VSE Hotswap example
R1 0495 BSTT613I OSAX610 Interface 1 IP address 192.168.1.239
R1 0495 BSTT600I 13 INITIATED DEVOSAX Build255 05/23/14 11.16
R1 0495 BSTT605I 13 DEVICE 01 OSAX610 TYPE OSAX UNIT 0610
R1 0495 BSTT014I IJBOSA LOADED A=80AB8000 L=00010CE8
R1 0495 BSTT010I IJBOSA DY47264 11318 145512L
R1 0495 BSTT717I IJBOSA FLAGS=20000000 VLAN=0000 RPLL=000C XPLL=000C
R1 0495 BSTT613I OSAX620 Interface 2 IP address 10.1.1.239
R1 0495 BSTT600I 14 INITIATED DEVOSAX Build255 05/23/14 11.16
R1 0495 BSTT605I 14 DEVICE 02 OSAX620 TYPE OSAX UNIT 0620
R1 0495 BSTT014I IJBOSA LOADED A=80ADA000 L=00010CE8
R1 0495 BSTT010I IJBOSA DY47264 11318 145512L
R1 0495 BSTT717I IJBOSA FLAGS=20000000 VLAN=0000 RPLL=000C XPLL=000C
R1 0495 BSTT600I 15 INITIATED rhomec Build254 04/25/13 10.32
R1 0495 BSTT613I TCP/IP-TOOLS TCP/IP Stack Initialization Complete
R1 0495 BSTT601I 2 TERMINATED netstart
R1 0495 BSTT601I 15 TERMINATED rhomec
R1 0045 BSTT010I HOTSWAP OSAX610 0630 0632 0
R1 0496 BSTT011I COMMAND PROCESSING COMPLETE
 
* cp detach nic 610
AR 0015 NIC 0610 is destroyed; devices 0610-0612 detached
 
R1 0495 BSTT013E IJBOSA ERROR R15=00000020 R0=0000007A R1=00AA7554
R1 0495 0S39I ERROR DURING OSA EXPRESS PROCESSING,REASON=0030
        CUU=0611
R1 0495 BSTT732W 13 HOTSWAP ACTIVATED OSAX610 0630 0632 0000
R1 0495 BSTT717I IJBOSA FLAGS=20000000 VLAN=0000 RPLL=000C XPLL=000C
You can virtualize the OSA Express adapter in your IOCP to allow many z/VSE images to share port 0 of the available adapters while using port 1 of different adapters as HOTSWAP devices.
1.3 Software options
This section describes the available software options, which include the use of different IP stacks (TCP/IP for VSE/ESA, IPv6/VSE, and Fast Path to Linux on System z Linux Fast Path) and IP protocols (IPv4, IPv6, and a mixture of both).
1.3.1 IPv4
Internet Protocol version 4 (IPv4) is the standard protocol for routing traffic through the Internet. IPv4 is described in IETF publication RFC 791 from September 1981. An IPv4 IP address is a number with 32 bits (4 bytes). The resulting limit of 232 (approximately 4.3 billion) different addresses was one of the main reasons that lead to the development of IPv6.
1.3.2 IPv6
Internet Protocol version 6 (IPv6) is the successor to Internet Protocol version 4 (IPv4), which was the first protocol version that was used in the Internet. In “old economy” countries, such as Europe and North America, IPv4 is still used today. Emerging countries, such as South America, India, and China, are forced to use IPv6 because of the exhaustion of IPv4 addresses. A version 5 was developed experimentally, but was never publicly used.
Each IPv4 IP address is a 4-byte number, which provides a maximum of 232 (about 4.3 billion) addresses. In the early 1990s, it became obvious that because of the rapid growth of the number of computers in the world, this number would be exceeded in the foreseeable future. On 3 February 2011, the Number Resource Organization (NRO) announced that the free pool of available IPv4 addresses was fully depleted.
An IPv6 IP address has 16 bytes, which allows for a total number of 2128 different addresses. This number is so large that all people alive in 2013 (approximately 7.0 billion) can each have billions of unique addresses. Therefore, it is likely that the pool of IPv6 addresses is never going to be used up.
IPv6 addresses often are written as eight groups of four hexadecimal digits (each group representing 16 bits, or 2 bytes), where each group is separated by a colon (:), as shown in the following example:
2001:0db8:85a3:08d3:1319:8a2e:0370:7344
Leading zeros in a group can be omitted (but at least one digit per group must be left), so the following notations can be used for the same address:
•2001:0db8:0000:08d3:0000:8a2e:0070:7344
•2001:db8:0:8d3:0:8a2e:70:7344
A string of consecutive all-zero groups can be replaced by two colons. To avoid ambiguity, this simplification can be applied only once, so again, the following notations refer to the same address:
•2001:db8:0:0:0:0:1428:57ab
•2001:db8::1428:57ab
The IPv6 protocol is described in Internet standard document RFC 2460, which was published in December 1998.
1.3.3 Why IPv6?
Consider the following points as you decide whether to upgrade your networking environment to IPv6:
•Your Internet service provider (ISP) upgrades to IPv6.
•It might happen that your customers or business partners are only reachable by using IPv6 (for example, China).
•Governmental organizations might allow only manufacturers of IPv6 capable-products and applications to participate in advertised biddings. For example, the US Department of Defense (DoD) allows only products that are on the “Unified Capabilities Approved Products List” (IBM UC™ APL) for its advertised biddings.
•No Network Address Translation (NAT). Because every device in the world can have a globally unique IPv6 address, NAT becomes unnecessary.
1.3.4 Dual stack support
Dual stack means that a host can run IPv4 and IPv6 applications at the same time. Therefore, hosts simultaneously reach IPv4 and IPv6 destinations, which makes dual stack the most popular coexistence strategy.
Dual stack includes the following benefits:
•Native dual stack does not require any tunneling mechanisms on internal networks.
•IPv4 and IPv6 run independent of each other.
•Dual stack supports gradual migration of endpoints, networks, and applications.
IPv6/VSE has two TCP/IP stacks: an IPv4 stack and an IPv6 stack. These TCP/IP stacks can be run individually, together (COUPLED), or stand alone.
1.3.5 Migration from IPv4 to IPv6
Contrary to popular belief, IPv6 is not compatible with an earlier version, but IPv4 and IPv6 networks can be used concurrently over the same cable and with the same endpoint.
The following transition methods are available:
•Dual IP Stacks
This is the easiest method. The IP stack supports both protocols concurrently. Examples are Linux since Kernel 2.6 and Windows since XP SP1. Existing IPv4 applications can continue to run unchanged. Applications can be IPv6-enabled over time, one after the other.
•Tunneling
IPv6 packets are sent as payload of other protocols (usually IPv4) to a tunneling broker, which is in an IPv6 network. The broker extracts the IPv6 packet from the payload and sends it as IPv6 packet through IPv6 routing to the final destination. An example is “6in4” that uses Tunneling-Broker.
The following infrastructure components must be upgraded:
•Layer 1 devices (for example hubs), which are not apparent for IPv6.
•Layer 2 devices (switches) that were purchased within the last 10 years most likely support IPv6 already.
•Layer 3 devices (routers), which often are not required for local LANs. Today, most router manufacturers provide IPv6-capable routers. Routers that use Multiprotocol Label Switching (MPLS) are protocol-independent.
•Endpoints (PCs, Server). Most modern operating systems support IPv6.
•Applications might need to be adapted (IPv6-enabled) to work with IPv6 addresses.
1.3.6 IPv6 products for z/VSE
In this section, we describe the available IPv6 products for z/VSE.
IPv6/VSE
IPv6/VSE is a registered trademark of Barnard Software, Inc. (BSI). The IPv6/VSE V1 product is designed to provide the following IPv6 solution for z/VSE:
•z/VSE users can participate in an IPv6 network.
•It brings the benefits of IPv6 functionality to z/VSE users.
•It helps z/VSE users to meet the requirements of the commercial community and governmental agencies, thus it fulfills the statement of direction in Software Announcement 209-319, dated October 20, 2009.
IPv6/VSE V1 is designed to provide an IPv6 TCP/IP stack, IPv6 application programming interfaces (APIs), and IPv6-enabled applications.
The IPv6/VSE product also includes a full-function IPv4 TCP/IP stack, IPv4 application programming interfaces, and IPv4 applications. The IPv4 TCP/IP stack does not require the IPv6 TCP/IP stack to be active.
IPv6/VSE V1 supports the IPv6 and IPv4 protocols, whereas TCP/IP for VSE/ESA V1.5 supports the IPv4 protocol only.
LFP
LFP is part of z/VSE since z/VSE 4.3. LFP is IPv6-enabled since z/VSE 5.1.
1.3.7 Securing your connections with Secure Sockets Layer
Secure Sockets Layer (SSL) and its successor Transport Layer Security (TLS) are cryptographic protocols that provide network security. There are several versions of these protocols in use by all kinds of applications, such as web browsers, FTP clients and servers, Telnet, and instant messaging.
Up to now, the supported protocol versions on z/VSE were SSL 3.0 (which is sometimes referred to as SSL 3.1) and TLS 1.0.
There already is a push towards TLS 1.2, which has several advantages to previous versions. Most important is the increased number of cipher suites, including the SHA-2 family of hash algorithms. Earlier protocol versions support only SHA-1, which today is considered broken. Various sources about cryptographic attacks against SHA-1 in 2005 and following years are available.
APAR DY47499 provides support for TLSv1.2 with OpenSSL 1.0.1e for z/VSE 5.1. For more information about how to use this new support, see 3.7.15, “Using TLSv1.2” on page 110.
Table 9 on page 13 of NIST Special Publication Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths, 800-131A, shows that the use of the SHA-1 hash function was disallowed after December 31, 2013, except for non-digital signature applications. This document is available at this website:
Because the new NIST SP800-131a standard was mandatory by the end of 2013, IBM products with cryptographic functionality perform their updates immediately to give customers time to test and upgrade their applications to become compliant.
1.3.8 Options for printing
When setting up for printing, you have several choices available.
Line printer requester (LPR)/Line printer daemon (LPD) is a platform-independent printing protocol for remote printing with which multiple platforms can print to the same printer without any extra configurations. This requires an LPD on the platform where the printer is connected.
TN3270E provides printing to workstation printers without the need for an LPD. However, it requires an emulator program with TN3270E support. With TN3270E, the 3270 print data stream is passed unchanged to the TN3270E printer client software that is running on a remote workstation. It is the function of the TN3270E printer client to translate the data and adjust the print output including font and pitch.
A TN3270E server has more than 3270 terminal display capabilities. It can also support the SNA print data stream. It accepts the print data stream from the application and forwards it to the TN3270E client that is running on the workstation. The workstation can then print the data by using normal workstation printer facilities.
Table 1-2 shows the printing options that are provided by TCP/IP for VSE/ESA and IPv6/VSE.
Table 1-2 Printing options by stack
 
TCP/IP for VSE/ESA
IPv6/VSE
LPR
Yes
Batch LPR and Auto LPR
LPD
Yes
Yes
General Printer Server (GPS)
Yes
LPR printer sessions (these are the same as GPS printers)
TN3270E
No
TN3270E printer sessions (both SNA and non-SNA)
DIRECT
No
DIRECT printer sessions that use port 9100
FTP
No
FTP print output to FTP server or printer
1.3.9 Overview of APIs
Table 1-3 provides an overview of the socket APIs that are available for z/VSE and where they are documented.
Table 1-3 Overview on APIs
API
Programming languages
Standard/Proprietary
SSL support
IPv6 support
Stack support
Doc1
LE/C Socket API
C
Standard BSD Sockets, mostly compatible with IBM z/OS and other distributed systems (UNIX, Linux, Windows, Mac, …)
Yes
Since z/VSE 5.1, IPv6/VSE and LFP only
TCP/IP for VSE/ESA, IPv6/VSE, LFP
1
EZA APIs
•EZASMI
•EZASOCKET
 
Assembler
COBOL, PL/I, Assembler
Standard BSD Sockets, mostly compatible with z/OS
Yes
Since z/VSE 4.2 with IPv6/VSE, since z/VSE 5.1 with LFP, too
TCP/IP for VSE/ESA, IPv6/VSE, LFP
1
CSI SOCKET Macro
Assembler
CSI proprietary
No
No (IPv6/VSE and LFP support IPv6 extensions)
TCP/IP for VSE/ESA, BSI*, LFP* *) Not all features supported
2
CSI Preprocessor API (EXEC TCP)
COBOL, PL/I, Assembler
CSI proprietary
No
No
TCP/IP for VSE/ESA (BSI provides conversion tool for EXEC TCP to EZA for COBOL programs)
2
CSI BSD Socket API
C, Assembler (COBOL, PL/I)
BSD-like socket API with limited standard compatibility
CSI proprietary
Yes
No
TCP/IP for VSE/ESA
2
IBM REXX Sockets
REXX
Standard BSD Sockets
Yes
No
TCP/IP for VSE/ESA, BSI, LFP (internally uses LE/C Sockets)
3
CSI REXX Sockets
REXX
CSI proprietary
No
No
TCP/IP for VSE/ESA
2
1 The numbers that are used in the Doc column correspond to the following publications:
1. z/VSE TCP/IP Support, SC34-2640, which is available at this website:
2. TCP/IP for VSE Programmer’s Guide, which is available at this website:
3. REXX/VSE Reference, SC33-6642, which is available at this website:
1.3.10 Available applications
In this section, we describe the applications that are available for the different IP stacks.
IBM
IBM provides the following applications, which can be used with all IP stacks:
•VSE Connector Server
•IBM CICS® Web Support (CWS)
•DB Call Level Interface (CLI)
•VSAM Redirector
•Web Services (SOAP)
•IBM WebSphere® MQ for z/VSE
•z/VSE SNMP Monitoring Agent
•z/VSE SNMP Trap Client
•IBM DB2® Server / Client
•z/VSE Virtual FTP daemon
The LFP stack supports IPv6 since z/VSE 5.1, but the applications currently are not IPv6-enabled. The Virtual z/VSE FTP Daemon is a Java application and is IPv6-capable. However, it uses the VSE Connector Server as the back end; therefore, if the VSE Connector Server does not support IPv6 addresses, the FTP daemon has the same restriction.
TCP/IP for VSE/ESA
The following applications are part of the TCP/IP for VSE/ESA product:
•File Transfer Protocol (FTPD, FTPBATCH, interactive FTP client in CICS, Auto-FTP)
•Telnet TN3270 Server (TELNETD)
•Email
•LPR client for printing
•General Printer Server (GPS)
•Web Server (HTTPd)
•TLS daemon (TLSD)
•PDF conversion
•Automation daemon for automatically sending Power LST queue entries by using FTP, email, or LPR
•REXEC client for sending commands to a remote REXEC daemon
•Ping, Traceroute, Discover, and other tools to analyze the network from VSE
A structured file system is also provided that allows transparent access to SAM (Disk and Tape), VSAM (ESDS and KSDS), Power (RDR PUN and LST queues), Librarian, VTOC, HFS, ICCF, Epic managed, Data Spaces, and user-defined file I/O drivers from all these applications.
Applications that are provided with TCP/IP for VSE/ESA currently are not IPv6-enabled.
IPv6/VSE
Barnard Software Inc. provides the following applications with the IPv6/VSE product:
•FTP server (IBM VSE/POWER®, VSAM, SAM, LIBR, Tape, Userexit)
•Batch FTP Client
•TN3270E server (TN3270/TN3270E Terminal & TN3270E Printer Sessions)
•Network Time Protocol Server (NTP server)
•Network Time Protocol Client (NTP client)
•System Logger Client
•Batch Email Client
•Batch LPR
•LPD
•Batch Telnet
•Batch Remote Execution client (REXEC)
•Batch PING
•GZIP data compression
•REXX automation
•PDF Generation by using VSE2PDF/Lite
•BSTTPRXY SSL Proxy Server
•BSTTATLS Automatic TLS facility
All applications that are provided with IPv6/VSE are IPv6-enabled and work with LFP and TCP/IP for VSE/ESA stacks.
1.3.11 Choosing a socket API when designing your applications
When you are designing an application that uses network communications, you should carefully choose the correct socket application. The available socket APIs differ not only in functionality, but in support when they are used with different stack versions or vendors. Because of this issue, you should use one of the following standard conforming APIs that are provided by IBM:
•EZA APIs (EZASMI and EZASOCKET)
•LE/C Socket API
•IBM REXX Sockets
These APIs work with all available TCP/IP stacks. Also, these APIs follow the Berkeley Sockets standard (BSD). The Berkeley Sockets API was introduced in the early 1980s for the UNIX operating system and was the de facto standard for many years. Meanwhile, the BSD API is part of the Portable Operating System Interface (POSIX) specification.
Technically, the IBM socket APIs separate the API layer from the implementation. That way, the API can be kept stable, but the implementation can be exchanged when different TCP/IP Stacks are used.
Figure 1-1 shows that the LE/C and the EZA APIs consist of a stack independent API interface part and a stack-dependent implementation that is provided with the stack.
Figure 1-1 Vendor-related parts of socket APIs
If you choose a proprietary Socket API that is supported by only one specific TCP/IP stack, you are bound to this stack version or vendor. When you are migrating to another TCP/IP stack, you might have to change your applications.
1.3.12 Enabling your applications for IPv6
You must adapt your applications to enable them to support IPv6. This is necessary because the application must work with longer IPv6 addresses (16 bytes instead of 4 bytes with IPv4). There also are some other socket functions that are available that must be used with IPv6. Some of them are replacements for older socket functions that work only with IPv4 addresses. Some of the new functions are optional, but also can be used with IPv4 addresses.
 
Note: Not all APIs support IPv6. For more information about available APIs and their IPv6 support status, see Table 1-3 on page 21.
In the following sections, we describe some general considerations for when you are enabling applications for IPv6. We also describe hints and tips for how to design your code for best compatibility with various TCP/IP stacks and vendors.
Changes in the LE/C and EZA Socket API to support IPv6
The following socket calls now support AF_INET6 (in addition to AF_INET):
•socket: allocate an IPv6 socket
•getclientid: Get the callers ID (needed for givesocket and takesocket)
•givesocket: Give a socket to another thread, task, or process
•takesocket: Take a socket from another thread, task, or process
•gethostbyaddr: Get domain and alias names of an address
The following functions now also accept a sockaddr_in6 structure:
•bind: Bind a socket to a local address (IP and port)
•connect: Establish a connection to a foreign address
•getsockname: Get the socket’s local address
•getpeername: Get the address of the communication partner
•accept: Accept a new client and get its foreign address
•sendto: Send a message to a foreign address (typically used for UDP)
•recvfrom: Receive a message and get the senders address (typically used for UDP)
The following new functions were added to support IPv6:
•getaddrinfo: Translate a domain name or service name into a socket address (replaces gethostbyname)
•getnameinfo: Translate a socket address into a domain name or service name (replaces gethostbyaddr)
•freeaddrinfo: Frees information that is returned by getaddrinfo
•inet_ntop: Convert a binary address into its textual form (replaces inet_ntoa)
•inet_pton: Convert a textual IP address (IPv4 or IPv6) into a binary address (replaces inet_addr)
IPv6 address handling
Internally, IPv4 addresses are represented by 32 bits (4 bytes) whereas IPv6 addresses are represented by 128 bits (16 bytes). Externally, IPv4 addresses are displayed in the format a.b.c.d where a - d are decimal numbers 0 - 255, which are separated by a period.
IPv6 addresses are displayed in the format aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh, where aaaa - hhhh are hexadecimal, 2-byte blocks that are separated by a colon. (Leading zeros can be omitted in each block.) You also can replace consecutive zeros with a double colon once per IPv6 address.
Because converting binary IPv6 addresses into their presentation format and vice versa is not as easy as for IPv4 addresses, you should not try to implement the conversion algorithm on your own. Instead, you should use the following API functions that are provided by the Socket API:
•NTOP (EZA), inet_ntop (LE/C): Converts binary IP addresses from their network format to their (textual) presentation format.
•PTON (EZA), inet_pton (LE/C): Converts IP addresses from their (textual) presentation format to their network format (binary).
 
Note: These functions work for IPv6 and IPv4 addresses.
In addition to these functions, the socket functions GETADDRINFO and GETNAMEINFO can be useful to convert textual IP addresses and host names to binary IP addresses and vice versa.
The length of a field that is holding a textual IPv4 address must be at least 15 characters long (4 * 3 digits + 3 periods). The length of a field holding a textual IPv6 address must be at least 39 characters long (8 * 4 hex digits + 7 colons).
Specifying port numbers as part of an IPv6 address
Some existing client applications allow specifying a port number as part of the IP address or host name. Usually, a colon is used to separate the IP address or host name from the port number; for example, 1.2.3.4:80 or ibm.com:80.
This configuration works fine for IPv4 addresses and host names. However, it does not work for IPv6 addresses because IPv6 addresses contain colons. Appending only the port number that is separated by another colon is ambiguous. Therefore, IPv6 addresses are encapsulated in square brackets and the port number is appended with a colon; for example, [2000:123::4]:80.
For more information, see Domain Names - Implementation and Specification, RFC 2732, which is available at this website:
The problem with square brackets in z/VSE is that these characters are on different code page positions, depending on which code page is used. Users might not be able to type the square brackets in the same code page that the code uses to parse the data. Thus, the code might not recognize the square brackets and shows errors.
To avoid such code page problems, angle brackets (< … >) can be used as an alternative; for example, <2000:123::4>:80. Some implementations also use single quotation marks instead of brackets; for example, '2000:123::4':80. However, because single quotation marks are often used by JCL and other parsers to enclose parameters, the use of single quotation marks might not be the best way for z/VSE.
To have a common look and feel, all IPv6-enabled z/VSE applications should follow the following rules if they must specify port numbers as part of IP addresses:
•They must accept IPv6 addresses to be enclosed in angle brackets (< .. >).
•They can accept IPv6 addresses to be enclosed in squared brackets ([ .. ]), where code page 1047 should be used.
•They can accept IPv6 addresses to be enclosed in single quotation marks (' .. ').
•If an IPv6 address does not contain a port specification, it might not be enclosed, but it can be.
•IPv4 addresses and host names must not be enclosed.
IPv6 addresses as input
Typically, IP addresses are entered by users at several places in z/VSE applications that use network communications.
All places where IP addresses are used as input should follow the following rules:
•Enable entering an IPv4 address, IPv6 address, or a host name.
•You should not use different fields for IPv4 address, IPv6 address, or host name. Instead, one single field should be used, which allows specification of the three options.
•The field should be long enough to hold a complete host name of 255 characters. For more information, see RFC 1035, which is available at this website:
When a URL is expected as input, the field must be long enough for 255+1+5 characters (host:65535).
•The user should not have to specify separately whether the entered data is an IPv4 address, IPv6 address, or host name. Instead, the underlying code should detect that status on its own based on the entered data (which can be done by using PTON or GETADDRINFO functions).
•Interfaces should not have preformatted input fields for IP addresses (such as, four fields with periods in between for entering IPv4 addresses). This setup avoids problems with copy and paste from other sources.
 
Note: The preferred method of specifying a target host address should be the use of host names. Host names are independent of IPv4 or IPv6, which makes IPv4-to-IPv6 transitions much easier for the user.
IPv6 addresses as output
IP addresses are often part of output, such as messages and listings. The textual presentation format of such addresses should be constructed by using the NTOP Socket API function (at least for IPv6 addresses). Alternatively, you can format the IP addresses on your own (for example, if the NTOP functions not available). In this case, you should print all IPv6 2 byte blocks with full 4 hex digits. Do not try to shorten the IPv6 address by skipping leading zeros or omitting zero blocks.
Enabling client/server applications for IPv6
IPv6-enabled applications should work with IPv4 and IPv6 sockets concurrently. Thus, you should not design your application to work with IPv6 only. IPv6 enablement always means to support IPv6 and IPv4.
An IPv6-enabled client application should take an IPv4 address, IPv6 address, or a host name as input and detect at run time whether to allocate an IPv4 socket or an IPv6 socket to connect to the remote server.
An IPv6-enabled server application should accept IPv4 clients and IPv6 clients concurrently. Server applications might have an option to restrict clients to IPv4 or IPv6 only; however, in general, a server should handle both.
Because old (IPv4 only) TCP/IP versions might still be used at your site, your application must still work with an IPv4 stack that does not support the new IPv6 specific API functions (NTOP, PTON, GETNAMEINFO, GETADDRINFO, and FREEADDRINFO). If you call an IPv6-specific function, you receive an error code even though the stack your application is using does not support IPv6. Your code must have a fallback code path to use only IPv4-specific functions.
Consider the following situations:
•IPv4-only stack (old CSI or old BSI stack): No support of IPv6 and no support of IPv6 specific functions. Use fallback code path by using old IPv4 specific functions only.
•IPv6 only stack (BSI IPv6/VSE without a coupled IPv4 stack): All functions are available (including old IPv4 specific functions), but you cannot allocate an IPv4 socket (AF_INET). IPv6 sockets only (AF_INET6). Mapped IPv4 addresses are not supported.
•True dual-mode stack (Linux Fast Path, BSI IPv6/VSE coupled with full IPv4 stack): All functions are available. You can allocate IPv4 (AF_INET) and IPv6 (AF_INET6) sockets. Mapped IPv4 addresses can also be used.
To make IPv6 enabling easier, we describe best practices for how to IPv6 enabling client and server applications in the following sections. Sample code (LE/C) also is available to show the call flow.
Enabling client applications for IPv6
An IPv6-enabled client application should take an IPv4 address, IPv6 address, or a host name as input and detect at run time whether to allocate an IPv4 socket or an IPv6 socket to connect to the remote server.
The client application also should detect if it is working with an IPv6 capable stack. Depending on the combination of input address family (IPv4, and IPv6) and stack capabilities, different code paths are run.
The following general flow is used:
•Try to use GETADDRINFO with user-provided destination address (IPv6 address, IPv4 address, or host name)
•If return code is EAI_NONAME, the error: host not found is received.
•If return code is not zero, assume for an IPv4 only stack:
 – Use inet_addr to convert IPv4 address to binary
 – If there is an error, assume that the host name is specified and use gethostbyname to resolve the host name issue
 – Set the address family to AF_INET
•Else (return code is zero), use first result.
•Allocate a socket with wanted address family (from ADDRINFO result)
•If the error is EAFNOSUPPORT, assume for IPv6 only stack:
 – Build mapped IPv4 address
 – Allocate AF_INET_6 socket
•Connect to wanted address
•Proceed with other processing on the socket
Figure 1-2 shows this flow of control.
Figure 1-2 Enabling client applications for IPv6
Enabling server applications for IPv6
An IPv6-enabled server application should accept IPv4 clients and IPv6 clients concurrently. Server applications might have an option to restrict clients to IPv4 or IPv6 only; however, in general, they should handle both.
The server application should detect if a client is working with an IPv6 capable stack. Depending on the combination of the stack capabilities and the client's address family (IPv4 or IPv6), different code paths are run.
The general flow is as follows:
•Try to allocate a listening socket with AF_INET6.
•If an error is received, assume IPv4 stack only: Allocate an AF_INET socket instead.
•Bind the socket to ANY address (IPv4 or IPv6) plus listening port.
•Set the socket into listening mode.
•Accept new clients (use select to wait for listening socket ready, if needed, then call accept).
•Inspect the address family of the newly accepted client:
 – If AF_INET6 (IPv6):
 • If mapped IPv4 address, convert to IPv4 address and display IPv4 address (use inet_ntop or inet_ntoa to convert into presentation format).
 • Else display IPv6 address (use inet_ntop to convert into presentation format).
 – If AF_INET (IPv4): Display IPv4 address (use inet_ntoa (!) to convert into presentation format).
•Proceed with other processing on the socket and return to accept new clients.
Figure 1-3 shows this flow of control.
Figure 1-3 Enabling server applications for IPv6
Detecting the TCP/IP stack on which you are running
Normally, an application should not need to identify the TCP/IP stack it is using. However, you can use the getibmopt socket call (with LE/C and EZA socket APIs) to perform this detection.
On a stack, the getibmopt call might be supported. If the call fails (bad return code), assume that you are running with a CSI stack.
If it works, you can inspect the returned information, as shown in the following example:
TCP-IMAGE-NAME is ‘SOCKETnn’
TCP-IMAGE-STATUS:
X'80vv': Active
X'40vv': Terminating
X'20vv': Down
X'10vv': Stopped or stopping
In this example, vv indicates with which stack you are running, as shown in the following example:
00: CSI
01: BSI IPv4
02: BSI IPv6
03: IBM LFP
1.4 Known problems
In this section, we describe some of the issues and insights we had in our test setup.
1.4.1 ERROR DURING OSA EXPRESS PROCESSING,REASON=002C CUU=nnnn,RETCODE=E00A
The following problem occurs when starting an OSAX link.
Symptom
These messages are issued when starting an OSAX link.
Y1 0114 0S39I ERROR DURING OSA EXPRESS PROCESSING,REASON=002C
CUU=nnnn,RETCODE=E00A
Y1 0112 0005: IPL605E Unable to Initialize IJBOSA, return code: 121
Y1 0112 0005: IPL609E Unable to initialize OSA Express, Link: CHPIDC0
Possible reason
Return code E00A says that the IP address of this OSAX adapter is already registered with another adapter.
Possibly you defined two OSAX links with the same IP address for failover reasons. The IP address remains registered on the second OSAX adapter even when the second link is stopped. The STOP LINKID command does not remove the IP address from the IJBOSA device driver.
The only solution is a DELETE LINK / DEFINE LINK.
 
 
1 From Networking on z/OS, which is available at this website:
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.191.240.222