Use the PKTTRACE statement to control the packet tracing facility in TCP/IP. You can use this statement to select IP packets as candidates for tracing and subsequent analysis.
Restriction: An IP packet must meet all the conditions specified on the statement for it to be traced.
The PKTTRACE statement consists of two parts. The first part defines to TCP/IP the network interfaces that are to be traced and characteristics of how they are to be traced. The second part turns packet tracing ON or OFF or CLEARs packet trace settings for the interfaces specified on prior PKTTRACE statements or for a single interface if the LINKName/INTFName parameter is used.
Packet traces are recorded externally using the TRACE command CTRACE writer instead of GTF. See z/OS Communications Server: IP Diagnosis Guide for information about the steps required to perform an IP packet trace.
Syntax
Tip: Specify the parameters for this statement in any order.
.-----------------------------------------. V | >>-PKTTRACE----+-------------------------------------+-+------->< | .-DESTport--=--*----------------. | +-+-------------------------------+---+ | '-DESTport--=--destination_port-' | | .-DISCard=NONE--------. | +-+---------------------+-------------+ | +-DISCard=*-----------+ | | +-DISCard=ALL---------+ | | '-DISCard=reason_code-' | | .-FULL-------------------------. | +-+------------------------------+----+ | | .-=--200-. | | | '-+-ABBREV--+--------+-------+-' | | '-ABBREV--=--abbrev_length-' | | .-INTFName--=--*--------------. | +-+-----------------------------+-----+ | '-INTFName--=--interface_name-' | | .-IPaddr--=--*--------------------. | +-+---------------------------------+-+ | '-IPaddr--=--+-| IPv4_address |-+-' | | '-| IPv6_address |-' | | .-LINKName--=--*--------------. | +-+-----------------------------+-----+ | '-LINKName--=--tcpip_linkname-' | +-+-ON----+---------------------------+ | +-OFF---+ | | '-CLEAR-' | | .-PORTNum--=--*-----------. | +-+-------------------------+---------+ | '-PORTNum--=--port_number-' | | .-PROT--=--*---------------. | +-+--------------------------+--------+ | +-PROT--=--TCP-------------+ | | +-PROT--=--UDP-------------+ | | +-PROT--=--ICMP------------+ | | +-PROT--=--ICMPv6----------+ | | '-PROT--=--protocol_number-' | | .-SRCPort--=--*-----------. | '-+-------------------------+---------' '-SRCPort--=--source_port-' IPv4_address .-SUBNet=255.255.255.255-. |--+-ipv4_address--+------------------------+-+-----------------| +-ipv4_address--_SUBNet=--subnet_mask------+ '-ipv4_address/num_mask_bits---------------' IPv6_address |--+-ipv6_address--------------+--------------------------------| '-ipv6_address/prefixLength-'
Parameters
- 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.
The protocol headers are always included, even if they exceed the ABBREV value.
- CLEAR
- Disables packet tracing for the interfaces specified and removes the characteristics defining how they should be traced.
- DESTPORT
- Specifies a port number that is 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 using the TCP or UDP protocol;
packets using other protocols are not traced. If the DESTPORT parameter
is omitted, and the PORTNUM parameter is also omitted, or 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 using the port number because the TCP or UDP headers are encrypted.
- DISCARD
- Specifies the IP packet discard reason code for the packets that
should be traced. All IP packets have a discard reason code associated
with them, which is typically set to 0. When the TCP/IP stack discards
a packet, a specific discard reason code is set in this field. See
the IP discard reason codes information in z/OS Communications Server: IP and SNA Codes for a list of all the discard reason codes.
Typically, the TCP/IP stack does not trace discarded packets. You
must specify a DISCARD value other than NONE to trace discarded packets.
Valid values for DISCARD are:
- *
- 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 only discarded packets.
- NONE
- Specifies that only IP packets that were not discarded should be traced. This is the default value.
- reason_code
- Specifies that only IP packets with the specified discard reason_code value should be traced. The reason_code value is a number in the range of 4 096 - 20 479. You can also specify a value of 0, which is the equivalent of DISCARD=NONE.
Tips:- A packet can be traced twice, once at the lower level IP layer when a packet arrives (with a discard reason code of 0), 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 DISCARD=ALL
to trace all packets that are discarded. The other specified parameters
are used to further select which discarded packets are traced. For
example, use the following code to collect packets with discard reason
code 4138 on all TCP or UDP packets with PORT number 20:
PKTTRACE ON,DISCARD=4138,PORTNUM=20 - Specifying the SRCPORT, DESTPORT, IPADDR, PORTNUM or PROTOCOL parameters might prevent malformed packets from being traced.
- FULL
- Specifies that the entire IPADDR packet is to be traced.
- IPADDR
- Specifies an IPv4 or IPv6 address 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 IPADDR option is
omitted, or an asterisk (*) is specified, then all IP addresses are
traced. Guidelines:
- If an IPv6 address is specified, an optional prefix length in the range 1 - 128 is allowed. The default prefix length is 128.
- If an IPv4 address is specified, the /num_mask_bits value is allowed.
- /num_mask_bits
- Specifies a numeric mask in the range 1 - 32.
- /prefixLength
- Specifies a numeric prefix length in the range 1 - 128.
- LINKNAME|INTFNAME
- The LINKNAME and INTFNAME parameters are interchangeable. They
specify the name of the network interface defined on a preceding LINK
or INTERFACE statement. If the LINKNAME or INTFNAME parameter is omitted
or an asterisk (*) is specified for either parameter, the PKTTRACE
parameters apply to all IPv4 and IPv6 interfaces prior to this statement.
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 or INTFNAME parameters for each interface that must be defined differently from the majority or interfaces.
The PKTTRACE statement must appear after a valid LINK or INTERFACE statement for the link or interface in the PROFILE.TCPIP data set.
- OFF
- Disables packet tracing for the specified interfaces 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=interface_name and there are no other parameters, all trace structures for link_name/interface_name are deactivated and removed.
If LINKNAME=link_name and IP=127.0.0.1, or INTFNAME=interface_name and IP=::1, then 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.
- 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 replace any existing trace structures for all existing IPv4 and IPv6 interfaces.
If you use LINKNAME=link_name or INTFNAME=interface_name and another nondefault parameter, the command results are added to any existing trace structures. However, if the existing trace structure for link_name/interface_name is all defaults, the existing trace structures are discarded.
- PORTNUM
- Specifies a port number that is compared with the destination
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
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
using 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, then the port numbers of packets are
not checked. If an asterisk (*) is specified, packets of any protocol
and any destination or source port number are traced.
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 DESTPORT or SRCPORT parameters, the DESTPORT and SRCPORT parameters are ignored.
Restriction: IPSec Encapsulating Security Payload (ESP) packets cannot be traced by port number because the TCP or UDP headers are encrypted.
- 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 between 1 and 255 (ICMP=1, TCP=6, UDP=17, ICMPV6=58, and RAW=255). If the PROT parameter is omitted or an asterisk (*) is specified, packets of any protocol are traced.
- SRCPORT
- Specifies a port number that is compared with the source port
of inbound and outbound packets. The port number is an integer in
the range 1 - 65535. 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 the TCP or UDP protocol; packets
using other protocols are not traced. If the SRCPORT parameter is
omitted, and the PORTNUM parameter is also omitted, or 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.
- SUBNET
- Specifies a subnet mask that applies to the host and network portions of the IP address specified on the accompanying IPADDR parameter. The subnet mask must be specified in dotted decimal notation and must be specified in conjunction with the IPADDR parameter. The default is 255.255.255.255.
Steps for modifying
PKTTRACE ON,LINKNAME=*
LINK ...
DEVICE ...For more information about changing PKTTRACE parameters, see the descriptions for the ON and OFF parameters for PKTTRACE statement.
You can also modify existing PKTTRACE settings by using the VARY TCPIP,,PKTTRACE command. See z/OS Communications Server: IP System Administrator's Commands for more information.
PKTTRACE ON,DESTport=21
PKTTRACE ON,SRCport=21The two commands 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.
Use the Netstat DEvlinks/-d command to display the results. An IP packet is traced according to the first trace structure that the packet matches.
Statement dependency
- INTFName and LINKName are mutually exclusive. An error message is displayed if both are coded.
- The num_mask_bits and SUBNET= are mutually exclusive. An error message is displayed if both are coded.
- IP=* implies IP=0.0.0.0 and SUBNET=255.255.255.255.
- The IP address and subnet mask pair specified must be in the same network.
- Tracing is not done for packets whose destination and source IP address match. However, tracing is always done for packets using a loopback interface.
Usage notes
- Multiple PKTTRACE statements can be included in the PROFILE.TCPIP; the results are cumulative.
- If a keyword on a given statement is specified multiple times, the last value specified is used. If an option appears more than once on a statement, the value associated with the last occurrence of the option is used.
- If you do not specify any options on the PKTTRACE statement, all packets through all devices are traced except for discarded packets. The default is DISCARD=NONE.
- If an error is found while parsing the PKTTRACE statement, an error message is generated, the parameter in error is ignored, and the rest of the statement is parsed. If an error is produced by an incorrect ABBREV value, the ABBREV value is changed to the default.
- Each defined interface has an associated trace profile. The trace
profile stores the values of each of the trace options for the interface.
When you create or reset a trace profile for an interface using the
CLEAR option, the trace profile is set to the default values for the
trace options as follows:
- PROT
- All protocols
- IPADDDR
- All IP addresses
- SUBNET
- No checking
- SRCPORT
- No checking
- DESTPORT
- No checking
- FULL
- Trace of the whole IP packet
Examples
The following sample includes several examples of the PKTTRACE statement:
; CTC Device and Link
DEVICE CTC1 CTC D00
LINK CTCD00 CTC 1 CTC1
;
; CTC Device and Link
DEVICE CTC2 CTC D02
LINK CTCD02 CTC 1 CTC2
;
; CTC Device and Link
DEVICE CTC3 CTC D04
LINK CTCD04 CTC 1 CTC3
;
; LCS Device and Links
DEVICE LCS1 LCS 100
LINK TR1 IBMTR 1 LCS1
LINK LCSC00 ETHERNET 2 LCS1
LINK LCSF00 FDDI 3 LCS1
;
DEVICE LCS2 LCS 102
LINK LCS802 802.3 1 LCS2
;
DEVICE LCS3 LCS 104
LINK LCSE802 ETHEROR802.3 1 LCS3
;
; start pkttrace
PKTTRACE ON LINKNAME=*
;
; set defaults for all links not specified below
PKTTRACE
; set for CTCD00
PKTTRACE FULL LINKNAME=CTCD00 PROT=* IP=* SRCPORT=* DESTPORT=*
; set for CTCD02
PKTTRACE ABBREV LINKNAME=CTCD02 PROT=TCP IP=9.67.116.124
SRCPORT=5000 DESTPORT=161
; set for CTCD04
PKTTRACE ABBREV=1 LINKNAME=CTCD04 PROT=UDP IP=9.67.116.124
SUBNET=255.255.255.255 SRCPORT=161 DESTPORT=5000
; set for TR1
PKTTRACE ABBREV=200 LINKNAME=TR1 PROT=ICMP IP=*
SRCPORT=5000 DESTPORT=161
; set for LCSC00
PKTTRACE ABBREV=65535 LINKNAME=LCSC00 PROT=1 IP=9.67.116.124
SUBNET=255.255.255.255 SRCPORT=* DESTPORT=*
; set for LCSF00 not to trace
PKTTRACE OFF LINKNAME=LCSF00