VARY TCPIP,,PKTTRACE

Use the VARY TCPIP,,PKTTRACE command to set up tracing.

Format


>>-Vary --TCPIP--,--+----------+-------------------------------->
                    '-procname-'   

>--,--PKTtrace--+-------------+--------------------------------><
                '-| Command |-'   

Command

                                                .-----------------------------.           
                                                V                             | (1) (2)   
|--,--+---------------------------+--+-ON----+----+-------------------------+-+----------|
      +-LINKName--=--*--,---------+  +-OFF---+    +-| Packet Length |-------+             
      +-LINKName--=--link_name--,-+  '-CLEAR-'    +-| Protocol Type |-------+             
      +-INTFName--=--*--,---------+               +-| Packet Dest Address |-+             
      '-INTFName--=--intf_name--,-'               +-| Packet Source Port |--+             
                                                  +-| Packet Dest Port |----+             
                                                  +-| Packet Port Number |--+             
                                                  '-| Packet Discard Code |-'             

Packet Length

   .-,FULL-------------------------.   
|--+-------------------------------+----------------------------|
   |          .-=--200-----------. |   
   '-,ABBREV--+------------------+-'   
              '-=--abbrev_length-'     

Protocol Type

   .-,PROT--=--*---------------.   
|--+---------------------------+--------------------------------|
   +-,PROT--=--TCP-------------+   
   +-,PROT--=--UDP-------------+   
   +-,PROT--=--ICMP------------+   
   +-,PROT--=--ICMPV6----------+   
   '-,PROT--=--protocol_number-'   

Packet Dest Address

   .-,IPaddr--=--*---------------------------------------------.   
|--+-----------------------------------------------------------+--|
   |                           .-,SUBNet--=--255.255.255.255-. |   
   +-,IPaddr--=--ipv4_address--+-----------------------------+-+   
   |                           +-,SUBNet--=--subnet_mask-----+ |   
   |                           '-/num_mask_bits--------------' |   
   |                           .-/128----------.               |   
   '-,IPaddr--=--ipv6_address--+---------------+---------------'   
                               '-/prefixLength-'                   

Packet Source Port

   .-,SRCPort--=--*-----------.   
|--+--------------------------+---------------------------------|
   '-,SRCPort--=--source_port-'   

Packet Dest Port

   .-,DESTport--=--*----------------.   
|--+--------------------------------+---------------------------|
   '-,DESTport--=--destination_port-'   

Packet Port Number

   .-,PORTNUM--=--*-----------.   
|--+--------------------------+---------------------------------|
   '-,PORTNUM--=--port_number-'   

Packet Discard Code

   .-DISCard=NONE--------.   
|--+---------------------+--------------------------------------|
   +-DISCard=*-----------+   
   +-DISCard=ALL---------+   
   '-DISCard=reason_code-'

Notes:

Each option can be specified only once. The order of options is not important.
The MVS™ TRACE command must also be issued for component SYSTCPDA to activate the packet trace. See the z/OS Communications Server: IP Diagnosis Guide for details.

Parameters

procname

The identifier of the TCP/IP address space. When the procname value is not specified, there can be only one TCP/IP address space started. If more than one TCP/IP address space is available and no procname value is specified, the request will fail with an error message.

PKTtrace

Specifies this command is for PKTTRACE information.

LINKName=link_name

INTFName=intf_name

Specifies the name of the network interface that is defined on a preceding LINK or INTERFACE statement. If the LINKName/INTFName parameter is omitted or if an asterisk (*) is specified for either parameter, the PKTTRACE parameters apply to all IPv4 and IPv6 interfaces.

To facilitate defining packet tracing when many interfaces are involved, use the PKTTRACE statement with the LINKName=* or INTFName=* option to define packet tracing characteristics for the majority of the interfaces. Then use individual PKTTRACE statements with specific LINKName/INTFName parameters for each interface that must be defined differently from the majority.

The LINKName and INTFName parameters are interchangeable.

ON

Turns on packet tracing, clears all settings previously defined and refreshes just the default settings.

If you use LINKName=* or INTFName=* and all other parameters are defaults, even if the defaults are specified, the command results replaces any existing trace structures for all existing IPv4 and IPv6 interfaces.

If you use LINKName=link_name or INTFName=* and another non-default parameter, the command results are added to any existing trace structures. However, if the existing trace structure for link_name or intf_name is all defaults, the existing trace structure will be discarded.

OFF

Disables packet tracing for the interfaces specified and removes the characteristics defining how they should be traced.

If LINKName=* or INTFName=* and all other parameters are defaults, all trace structures are deactivated and removed from all existing IPv4 and IPv6 interfaces.

If LINKName=* or INTFName=* and PROT=UDP, all trace structures for all resources are analyzed; any matches are removed. If no trace structures remain, trace is deactivated for that resource.

If LINKName=link_name or INTFName=intf_name and there are no other parameters, all trace structures for link_name or intf_name are deactivated and removed.

If LINKName=link_name and IP=127.0.0.1 or INTFName=intf_name and IP=::1, that particular trace structure is removed if it is found. If there is only one trace structure, then that structure is removed and trace is deactivated for that resource.

CLEAR

Disables packet tracing for the interfaces specified and removes the characteristics that define how the interfaces should be traced.

FULL

Specifies that the entire IP packet is to be traced.

ABBREV

Specifies that a truncated portion of the IP packet is to be traced. You can specify a length in the range 0 - 65,535 or use the default of 200. The ABBREV parameter can be used to reduce the volume of data stored in the trace file.

Note: The protocol headers are always included even if they exceeds the ABBREV value.

PORTNUM

Specifies a port number that is compared with the destination port and source port of inbound and outbound packets. You can use this parameter instead of using the SRCPORT and DESTPORT parameters. The port number is an integer in the range 1 - 65,535. If the destination port or source port of a packet is the same as the specified port number, the packet is traced. This comparison is performed only for packets that use the TCP or UDP protocol; packets using other protocols are not traced. If the PORTNUM parameter is omitted and the SRCPORT and DESTPORT parameters are also omitted, the port numbers of packets are not checked. If an asterisk (*) is specified, packets of any protocol and of any destination or source port are traced.

IPSec Encapsulating Security Payload (ESP) packets cannot be traced by port number because the TCP or UDP headers are encrypted.

Guideline: SRCPORT and DESTPORT parameters should not be specified on the same PKTTRACE statement as the PORTNUM parameter. When the PORTNUM parameter is specified after the DESTPORT or SRCPORT parameters, the DESTPORT and SRCPORT parameters are ignored.

PROT

Specifies the protocol type to be traced. This can be specified as one of the literals TCP, UDP, ICMP, or ICMPV6, or as a number in the range 1 - 255 (ICMP=1, TCP=6, UDP=17, and RAW=255). If the PROT parameter is omitted or an asterisk (*) is specified, packets of any protocol are traced.

IPaddr

Specifies an IP address (either a 32-bit IPv4 address in dotted decimal notation, or a 128-bit IPv6 address colon hexadecimal notation) that is compared with both the source and destination addresses of inbound and outbound packets. If either the source or destination address of a packet matches the specified IP address, the packet is traced. If the IP option is omitted, or an asterisk (*) is specified, then all IP addresses are traced.

If an IPv6 address is specified, then an optional prefixLength (range 1 - 128) is allowed. IPv4 addresses and IPv4-mapped IPv6 addresses are treated as equivalent addresses. The default prefixLength is 128. If an IPv4 address is specified, then /num_mask_bits can be used. The num_mask_bits and SUBNET values are mutually exclusive. An error message is displayed if both are coded.

SUBNET

Valid only with IP=ipv4_address. Specifies a subnet mask that applies to the host and network portions of the IP address specified on the IP=ipv4_address parameter. The subnet mask must be specified in dotted decimal notation and must be specified in conjunction with the IP=ipv4_address parameter. With an IPv4 address specified, the /num_mask_bits can be used. The num_mask_bits and SUBNET are mutually exclusive. An error message is displayed if both are coded.

SRCPORT

Specifies a port number that will be compared with the source port of inbound and outbound packets. The port number is an integer in the range 1 - 65,535. If the source port of a packet is the same as the specified port number, the packet is traced. This comparison is performed only for packets using either the TCP or UDP protocol; packets using other protocols are not traced. If the SRCPORT parameter is omitted, there is no checking of the source port of packets. If an asterisk (*) is specified, packets of any protocol and any source port are traced. If the SRCPORT and PORTNUM parameters are omitted, or if an asterisk (*) is specified for the SRCPORT parameter, the source port of packets is not checked.

IPSec Encapsulating Security Payload (ESP) packets cannot be traced by port number because the TCP or UDP headers are encrypted.

DESTPORT

Specifies a port number that will be compared with the destination port of inbound and outbound packets. The port number is an integer in the range 1 - 65,535. If the destination port of a packet is the same as the specified port number, the packet is traced. This comparison is performed only for packets tat use the TCP or UDP protocol; packets using other protocols are not traced. If the DESTPORT and PORTNUM parameters are omitted or if an asterisk (*) is specified for the DESTPORT parameter, the destination port of packets is not checked.

IPsec Encapsulating Security Payload (ESP) packets cannot be traced by port number because the TCP or UDP headers are encrypted.

DISCARD

Specifies the IP packet discard reason code of the packets which should be traced. All IP packets contain a discard reason code that is normally set to 0. When the TCP/IP stack decides to discard a packet, a specific discard reason code is set in this field. See IP Discard reason codes information in z/OS Communications Server: IP and SNA Codes for a list of all the discard reason codes. Normally, the TCP/IP stack does not trace discarded packets. You must specify a DISCARD value other than NONE in order to trace discarded packets.

NONE: Specifies that only IP packets that were not discarded should be traced. This is the default value.
*: The DISCARD parameter is not applied to the selection of packets. All packets are traced.
ALL: Specifies that IP packets with a nonzero discard reason code should be traced. Specifying this value results in tracing all discarded packets.
reason_code: Specifies that only IP packets with the specified discard reason code should be traced. Valid reason_code values are numbers in the range 4096 -20,479. The value 0 can also be specified, which is the equivalent of specifying DISCARD=NONE.

Tips:

Specifying the SRCPORT, DESTPORT, IPADDR, PORTNUM, or PROTOCOL parameters might prevent malformed packets from being traced.
A packet might be traced twice, once at the lower level IP layer when a packet arrives, and again as a discarded packet in an upper level protocol layer of TCP/IP.

You can use one packet trace profile statement per discard reason code. You can also specify a packet trace statement with the DISCARD=ALL option to trace all packets that are dropped. The other specified parameters further identify which discarded packets are traced. The following example collects packets with the discard reason code 4138 on all TCP and UDP packets that specify the PORT number 20.

PKTTRACE ON,DISCARD=4138,PORTNUM=20

Examples

To trace all packets for a particular application port, enter the following two PKTTRACE commands:

    v tcpip,,pkt,on,dest=21
    v tcpip,,pkt,on,srcp=21

The two commands will capture all the packets received and all the packets sent for a particular port. If other options are specified, then they should be the same on both commands.

Usage

The results are cumulative when you issue multiple PKTTRACE commands. Use the NETSTAT DEvlinks (netstat -d) command to display the results. An IP packet is traced according to the first setting that matches. You might need to issue the CLEAR command to reset active PKTTRACE filters if existing filters are not needed before you enable new PKTTRACE filters
Users can be authorized to invoke the command by permitting their user IDs for CONTROL access to the RACF® profile name MVS.VARY.TCPIP.PKTTRACE.