IPTRACE | z/OS Mainframe

This program came from a project requirement to search for strings in packets from z/OS TCP/IP trace data - a feature that was missing from IBM's IPCS. This was made more challenging as the format of the CTRACE and IP blocks were not fully documented in IBM's manuals. As there is normally a large amount of data, it is read into a Dataspace and parsed, with the output being written to DD:SYSPRINT. A TSO/ISPF front end (not available) was developed to aid the end-user when searching for specific dates/text etc.

Download

XMI

iptrace_asm.xmi

History

1.1.0

(21/08/2014) - Handles protocol headers correctly so will exit if its not supported. More checks for packet lengths of zero.

1.2.0

(25/02/2015) - Handles missing data from packets and displays the data after the original display - caused S0C4-11.

1.3.0

(22/05/2015) - Data is now extracted from the CTE and copied into the dataspace.

(29/05/2015) - Data from split buffers is now added after the previous packet so a proper search can be performed.

1.4.0

(21/08/2020) - Added ASCII_SEARCH and SHOW_ASCII_PACKET parameters.

1.4.1

(27/11/2020) - Removed Abend when unknown packet is received as EE packets (0006) were being collected.

1.5.0

(12/03/2021) - Converted to relative addressing.

(22/04/2021) - Finished PCAP routine - packet times are local whereas PCAP are UTC. DD:SYSPRINT can be redirected to a dataset or SYSOUT.

(28/04/2021) - Date comparison is now performed using TOD clocks and is used in BUILDTRC to reduce total packet size for PCAP files.

(29/04/2021) - Using PCAP now sets some options to off.

(05/05/2021) - Wireshark reported the PCAP capture files as corrupt - corrected the Maximum Packet length and updated the padding to hex zeros.

1.5.1

(04/03/2022) - Fixed reentrant for DCB for DD:SYSIN.

1.5.2

(23/05/2022) - Improved RDW handling and fixed bug with file totals. Issue with lost packets fixed by commenting the check for CTEFMTID (PKTTRACE).

1.5.3

(22/05/2023) - LRECL for displays are set programmatically. Format 6 CTEs are now skipped correctly to avoid missing packets.

Planned Changes

None

Screenshots / Output

Description & Parameters

This program is used to process TCPIP Packet Trace data. All parameters are specified in DD:SYSIN - see the JCL Setup below.

FULL | SUMMARY | PCAP

Displays a FULL or SUMMARY report – a full report gives full details of each packet whereas the summary shows the payload length and source and destination addresses.

PCAP creates a PCAP capture file in DD:SYSPRINT which can be downloaded and viewed in Wireshark - see below.

DATASET_DETAIL

Records the details to DD:SYSUT2 – this is used when a TCPIP trace dataset is copied and the start and end date/time with the dataset generation name are recorded. These details are used by the TSO CLIST (not available) to find the correct trace dataset for processing. An example of the output is shown in the 3rd screenshot above.

START(yyyymmdd.hhmmss)

Start Date/Time

END(yyyymmdd.hhmmss)

End Date/Time

PORT(nnn)

Search by Port

IPADDRESS(nnn)

Search by TCPIP Address

SEARCH(sss)

Search packet data for string

ASCII_SEARCH

Searches the ASCII and EBCDIC translations of the packet data

SHOW_ASCII_PACKET

Displays a larger 80 byte wide representation of the packet data in ASCII

SHOW_TCP_HEADER

Show the TCP header in the FULL display

SHOW_PROTOCOL_HEADER

Show the PROTOCOL header in the FULL display

INCLUDE_ALL_PORTS

If a search finds a specific port (specified above), this option will go back and re-read the complete trace data again and display data for all ports.

JCL Example

This example JCL is set up as follows:

DD:SYSUT1

TCPIP Trace dataset created by PTTCP

DD:SYSUT2

Log file for use with the TSO application - see DATASET_DETAIL parameter above

DD:SYSPRINT

Displays output

DD:LOG

Messages from processing

DD:SYSIN

Input parameters (start in column 3)

This example shows the FULL display and both headers will be shown. Search DD:LOG for '>>> Packets Filtered' to show you how many packets matched your search arguments.

//STEP1   EXEC PGM=IPTRACE,REGION=0M                          
//STEPLIB  DD DISP=SHR,DSN=YOUR.LOADLIB                
//SYSUT1   DD DISP=SHR,DSN=TCPIP.TRACE.DATA          
//SYSUT2   DD DISP=MOD,DSN=TCPIP.TRACE.DATA.LOG           
//SYSPRINT DD SYSOUT=*,OUTLIM=4000000                         
//LOG      DD SYSOUT=*                                        
//SYSIN    DD *                                               
  FULL                                                        
  SHOW_TCP_HEADER                                             
  SHOW_PROTOCOL_HEADER                                        
/*

Searching

The SEARCH parameter allows searching for mixed case arguments within the EBCDIC translation of the data. If you cannot find your search argument, specify ASCII_SEARCH and resubmit your JCL.

Redirecting DD:SYSPRINT to a Dataset

Normally DD:SYSPRINT is set to SYSOUT=* so it is available for online viewing. You can change this to write to a sequential dataset of RECFM=FB with LRECL=80.
The displays for FULL and SUMMARY are fixed at LRECL=105 whereas PCAP and DATASET_DETAIL are fixed at LRECL=80.

Creating PCAP Capture Files for Wireshark

IPTRACE can create PCAP version 2.4 files for use with Wireshark. The PCAP option creates the data in DD:SYSPRINT which should be written to a dataset and downloaded as binary to your PC. When you specify the PCAP option, some incompatible options will be turned off.

IBM record timestamps in the TCPIP packets as local time whereas the PCAP format specifies UTC with a time offset. Therefore you might notice that the timestamps are different when they are opened in Wireshark as it increments the time by the timezone offset. The packet data is not translated from EBCDIC to ASCII as Wireshark allows you to view the data as both. This makes it useful when MVS connects to a Unix system.

Wireshark may show some messages reporting cut short packets - this is due to the padding bytes on the Fixed Block 80-byte record at the end of the capture file - the capture file will still be processed correctly.

The PCAP capture file is created as follows with a Global Header, Record Header, Data, Record Header, Data etc…

Global Header

Magic Number

This indicates the file format – this is set to 0xA1B2C3D4

Version_Major

Set to 02

Version_Minor

Set to 04 (current version is 2.4)

This Zone

Time correction in seconds between GMT/UTC and local time – this is always set to zero.

Snaplen

Snapshot length of the capture - currently set to 262144 as per fix from https://f00l.de/pcapfix/

Network Link Layer

Currently set to x12 - CEE.SCEEH.SYS.H(SOCKET) defines AF_LINK (Link Layer Interface) as 18.
See https://www.tcpdump.org/linktypes.html.

Record (Packet) Header

Timestamp seconds

Seconds since UNIX EPOCH of 1/1/1970 00:00:00 - the IBM MVS EPOCH is 1/1/1900 00:00:00

Timestamp microseconds

Number of microseconds

Number of octets saved in file

Bytes captured (incl_len)

Actual length of packet

Actual length of packet.

Packet Data

The actual packet data will immediately follow the packet header as data of incl_len bytes.

See https://wiki.wireshark.org/Development/LibpcapFileFormat for more details.

Abend or Error Codes

U0001

Unable to open DD:SYSUT1

U0002

Unable to open DD:SYSUT2

U0003

Unable to open DD:SYSIN

U0004

JFCB call failed

U0005

Unable to open DD:LOG

U0100

Unknown CTE Format ID

Environment

This program was written in z/OS HLASM Assembler and will run under z/OS 31bit. The code is re-entrant.
No additional authorisations are required.

This program was developed and tested under z/OS 1.12 up to z/OS 2.4.

Additional Macros

The program uses the STRING macro from https://gsf-soft.com/Freeware/STRING.html - I highly recommend this.

IPTRACE also uses an internal macro, VERSION, which is included in the XMIT file.

Assemble & Link

The program contains multiple source members. Each member will compile into object files in a separate dataset. Member #BUILD will link these modules together. The JCL runs under JES3 so you will probably need to tailor it for your environment.

TCP and Protocol Headers are found in TCPIP.SEZACMAC(EZAAI03J/FMTIPPKT). These are not used as more meaningful names are used in the source.

FORMAT (Common Trace Element) =                                                   
                                                                 
 .-------------------------------------.                         
 |......|..........................|...|                         
  CTE    | CTEDATA                |  CTELENE                     
        /------------------------ \                              
       | PTHDR | IPH | HDR | DATA  |                             
       '----------------|----------'                             
                        TCP, UDP, OSPF, ICMP

CTEs contain the CTE element and the CTEDATA contains the PTHDR, Internet Protocol Header, the Protocol Header (TCP, UDP, OSPF or ICMP) followed by the data. In the case of split buffers, only the PTHDR and DATA exist.

FORMAT (DATASPACE) =                            
                                               
 .-------------------------------------.       
 |........|............................|       
  LENGTH  |PACKET                      |       
  (2bytes) /---------------------------\       
          | PTHDR | IPH | HDR | DATA   |       
          '----------------|-----------'       
                           TCP, UDP, OSPF, ICMP

TCP/IP Tracing Setup

Setting up TCPIP tracing on MVS is quite simple. We run tracing 24x7 so we use a small GDG (7 generations) for the PTTCP data. When it is stopped hourly, we copy that GDG to another GDG (255 generations) - this allows DFHSM to migrate the second GDG when it's not in use.

Create a task named PTTCP in the PROCLIB concatenation as below - we define the DD:TRCOUT01 as a GDG (as mentioned):

//PTTCP    PROC                                                   
//*
//* TCPIP PACKET TRACE WRITER                                         
//*                                                             
//IEFPROC  EXEC PGM=ITTTRCWR                                   
//TRCOUT01   DD DSNAME=SYS0.IPTRACE(+1),            
//              SPACE=(CYL,(150,130),RLSE),DISP=(NEW,CATLG),DSORG=PS

Start TCP/IP Tracing

To start tracing, issue the following commands (we have automated responses to the replies):

D TRACE,COMP=SYSTCPDA,SUB=(TCPIP)
- Display options (look for OPTIONS and WRITER)

TRACE CT,WTRSTART=PTTCP,WRAP
- Start CTRACE external writer

TRACE CT,ON,COMP=SYSTCPDA,SUB=(TCPIP)
- Connect the external writer to the TCPIP address space. Enter WTR=PTTCP,OPTIONS=(ALL),END to ITT006A message

D TRACE,COMP=SYSTCPDA,SUB=(TCPIP)
- Display options (look for OPTIONS and WRITER)

V TCPIP,,PKT,ON
- Start required TCPIP packet trace - add IP=xxx.xxx.xxx.xxx for specific tracing, SRCP=xxxx for source port and DEST=xxx for destination port

Issue TSO NETSTAT DEV and check IP address under Packet Trace Setting

Stop TCP/IP Tracing

To stop tracing, issue the following commands (we have automated the replies):

V TCPIP,,PKT,OFF
- Stop packet tracing

TRACE CT,OFF,COMP=SYSTCPDA,SUB=(TCPIP)
- Disconnect the external writer from the TCPIP address space

TRACE CT,WTRSTOP=PTTCP
- Stop CTRACE external writer

D TRACE,COMP=SYSTCPDA,SUB=(TCPIP)
- Display options (look for OPTIONS and WRITER)

After tracing has been stopped, use the DD:TRCOUT01 dataset as DD:SYSUT1 in the JCL example above.