VARY TCPIP,,PKTTRACE
Use the PKTTRACE command to control the packet tracing facility in TCP/IP. You can use this command to select IP packets as candidates for tracing and subsequent analysis.
The PKTTRACE command 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, OFF or CLEARs packet trace settings for the interfaces specified on prior PKTTRACE commands or for a single interface if the LINKName/INTFName parameter is used.
Packet traces are recorded externally by using the TRACE command CTRACE writer instead of GTF. For information about the steps that are required to perform an IP packet trace, see Using IP packet trace in z/OS Communications Server: IP Diagnosis Guide.
Format
- 1 Each option can be specified only once. The order of options is not important.
- 2 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 theIP=ipv4_address
parameter. The subnet mask must be specified in dotted decimal notation and must be specified in conjunction with theIP=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.
- 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.
PKTTRACE ON,DISCARD=4138,PORTNUM=20
Examples
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.