Use the OSAENTA statement to control the OSA-Express Network Traffic Analyzer (OEAENTA) tracing facility in the OSA-Express adapter. You can use this statement to select frames as candidates for tracing and subsequent analysis; OSAENTA traces are recorded externally using the TRACE command. See z/OS Communications Server: IP Diagnosis Guide for information about the steps required to perform an OSAENTA trace.
The OSAENTA statement consists of two parts. One part defines the OSA-Express that is to be traced and characteristics of the tracing. A second part turns tracing on or off or clears the trace settings. The tracing characteristics are identified by filters which specify under which conditions a frame should be traced. A frame must meet all the conditions specified on the OSAENTA statements for it to be traced. For example, if the OSAENTA statement identifies PROTOCOL=TCP and PORTNUM=21, only IP packets that have both a protocol of TCP and a port of 21 are traced. Only one value can be specified for a given filter on one OSAENTA statement.
Multiple OSAENTA statements can be included in the PROFILE.TCPIP data set, and can control tracing for multiple OSAs. The filters on multiple OSAENTA statements are cumulative for a given OSA-Express port. Each OSAENTA statement that specifies filters adds to the filters that are already in effect for that OSA-Express port. You can use multiple OSAENTA statements, multiple filter values can be assigned to each filter. There is a limit of eight filter values for each filter for each OSA-Express port. For example, you can specify up to eight IP protocols, up to eight VLAN IDs, and so on. For IP addresses, you can specify up to eight IPv4 addresses and up to eight IPv6 addresses. If a frame matches any of the values for that filter, it is considered to meet the condition of that particular filter. For example, if IPADDR=9.67.1.1,PROTO=TCP, and PORTNUM=21 is specified on one OSAENTA statement for OSA1, and IPADDR=9.67.1.2 is specified on another OSAENTA statement for OSA1, all frames sent to either IP address 9.67.1.1 or 9.67.1.2 with a protocol of TCP and a port of 21 are traced.
The OSAENTA statement dynamically defines a QDIO interface to the OSA-Express being traced, called an OSAENTA interface. That interface is used exclusively for capturing OSA-Express Network Traffic Analyzer traces.
The OSAENTA statement enables an installation to trace data from other hosts connected to OSA-Express. The trace data collected should be considered confidential and TCP/IP system dumps and external trace files containing this trace data should be protected.
If an error is found while parsing the OSAENTA statement, an error message is generated and the statement is ignored.
Tip: Specify all parameters, except the PORTNAME parameter, for this statement in any order. If a keyword on a given statement is specified multiple times, the last value specified is used.
>>-OSAENTA--PORTNAME=osa_port_name--+-----+--| Parameter |------> +-ON--+ +-OFF-+ '-DEL-' >--| Filter |-------------------------------------------------->< Parameter |--+-------------+--+-------------------------+-----------------> '-CLEARfilter-' | .-1024---------. | '-DATA=--+-trace_amount-+-' .-DISCARD=EXCEPTION----. .-FULL-----------------------. >--+----------------------+--+----------------------------+-----> +-DISCARD=ALL----------+ | .-224-----------. | +-DISCARD=NONE---------+ '-ABBREV=--+-abbrev_length-+-' '-DISCARD=discard_code-' .-NOFILTER=NONE-. >--+---------------+--+--------------------------+--------------> '-NOFILTER=ALL--' | .-2147483647--. | '-FRAMES=--+-trace_count-+-' >--+-----------------------+------------------------------------| | .-10080------. | '-TIME=--+-trace_time-+-' Filter .-IPaddr=*----------------------. .-DEVICEID=*---------. |--+-------------------------------+--+--------------------+----> '-IPaddr=--+-| IPv4_address |-+-' '-DEVICEID=device_id-' '-| IPv6_address |-' .-ETHType=*-------------. .-MAC=*-----------. >--+-----------------------+--+-----------------+---------------> +-ETHType=IPV4----------+ '-MAC=mac_address-' +-ETHType=IPV6----------+ +-ETHType=ARP-----------+ +-ETHType=SNA-----------+ '-ETHType=ethernet_type-' .-PORTNum=*-----------. .-PROTOcol=*---------------. >--+---------------------+--+--------------------------+--------> '-PORTNum=port_number-' +-PROTOcol=TCP-------------+ +-PROTOcol=UDP-------------+ +-PROTOcol=ICMP------------+ +-PROTOcol=ICMPv6----------+ '-PROTOcol=protocol_number-' .-VLANID=*-------. >--+----------------+-------------------------------------------| +-VLANID=vlan_id-+ '-VLANID=ALL-----' IPv4_address |--+-ipv4_address---------------+-------------------------------| '-ipv4_address/num_mask_bits-' IPv6_address |--+-ipv6_address---------------+-------------------------------| '-ipv6_address/prefix_length-'
Tip: You do not also have to define the OSA-Express to TCP/IP using the DEVICE or LINK statements or INTERFACE statement or activate it on the tracing stack in order to collect trace data from other stacks using that OSA-Express. For an OSX interface configured with the CHPID parameter or for an OSM interface, specify the port name according to the VTAM naming convention for these dynamic TRLEs, and VTAM will dynamically create the TRLE when you activate the OSAENTA interface. For details about the naming convention for these dynamically generated TRLEs, see z/OS Communications Server: SNA Network Implementation Guide.
Restriction: OSA-Express does not allow multiple stacks to concurrently use the tracing function for a given OSA-Express feature.
Guideline: Use a large value or specify the FULL parameter if you want to maximize the amount of data traced for each packet; TCP segmentation offload packets are traced before the packet is segmented, and can be larger than the largest frame size on the LAN. See the segmentation offload information in z/OS Communications Server: IP Configuration Guide for information about which parameters affect the size of TCP segmentation offload packets.
If you specify the CLEARFILTER parameter and the OSAENTA interface is active, either all frames are traced or no frames are traced, depending on the setting of the NOFILTER parameter. The trace buffers are likely to fill up very quickly if you clear all the filters without setting new filters to filter out an adequate percentage of the packets.
Tip: Specifying CLEARFILTER clears all filters. To clear all values for a single filter, use OSAENTA and specify an asterisk (*) for the filter value.
Result: If the OSAENTA interface is inactive, then the data limit takes effect when the OSAENTA trace is enabled with the ON parameter. If the OSAENTA interface is active and the trace_amount value is modified, then the stack resets the data counter to 0 and puts the new data limit into effect.
Each identifier is a 2-digit hexadecimal value in the range 00 - FF.
If the frame was either inbound or outbound to the host identified by the device_id value, then the frame meets the criteria for this filter. If the DEVICEID option has been omitted or an asterisk (*) is specified, then all packets meet the criteria for this filter.
Tip: You can obtain the device_id values for any user of the OSA-Express feature by using the Hardware Management Console (HMC). For a data device that is active on a z/OS® stack, you can obtain the device_id value for that data device from message IST2190I in the output from the D NET,TRL,TRLE=name command.
Rule: If the EXCEPTION value and discard codes are specified on multiple OSAENTA statements, all frames that are discarded for exception conditions and all frames that are discarded for any of the discard codes in effect are traced.
Restriction: When the EXCEPTION value is specified, only seven or fewer discard codes can be active for one OSA-Express feature.
Rule: The CLEARFILTER parameter does not affect the state of the DISCARD parameter.
Result: A frame can be traced twice; once when the packet is passed to the OSA-Express feature, and again as a discarded packet during the processing of the packet.
Guideline: To reset the current set of active discard codes, specify DISCARD=ALL or NONE followed by OSAENTA statements with the DISCARD parameters that you want to specify.
Result: If the OSAENTA interface is inactive, then the FRAMES limit takes effect when the OSAENTA trace is enabled with the ON parameter. If the OSAENTA interface is active and the trace_count value is modified, then the stack resets the frame counter to 0 and puts the new frame limit into effect.
If an IPv4 address is specified, then the /num_mask_bits variable (range 1-32) can be used to designate a subnet. The default number of bits is 32.
If an IPv6 address is specified, then an optional prefix_length value (range 1-128) can be specified. The default prefix_length value is 128.
Guideline: If you clear filters using the CLEARFILTER parameter with the OSAENTA interface active, and specify NOFILTER=ALL, ensure that you also specify sufficient new filters. The trace buffers are likely to fill up very quickly if you clear all the filters without setting new filters to filter out an adequate percentage of the packets.
Guideline: Ensure that you have specified sufficient trace filters before starting the trace. The trace buffers are likely to fill up very quickly if you activate the trace with either no filters (NOFILTER=ALL) or with a set of filters that does not filter out an adequate percentage of the packets.
IPSec Encapsulating Security Payload (ESP) packets cannot be traced by port number because the TCP or UDP headers are encrypted.
Rule: For encapsulated packets, OSAENTA bases collection on whether the specified protocol filter matches the outermost packet protocol. For example, if TCP was specified as the protocol filter, and a TCP packet was received encapsulated in an IPSEC packet with protocol 50, this TCP packet is not collected. Protocol 50 must be specified to collect these packets.
Result: If the OSAENTA interface is inactive, then the time limit takes effect when the OSAENTA trace is enabled with the ON parameter. If the OSAENTA interface is active and the trace_time value is modified, then the stack resets the time counter to 0 and puts the new time limit into effect.
As previously indicated, the OSAENTA statements are cumulative for a given OSA-Express adapter, and any subsequent OSAENTA statement processed adds to the filters that are already in effect for that OSA-Express feature. To actually change a value for a given filter, the following options are available:
Tip: If the trace is currently enabled, the trace continues to run while each filter is modified or added. This can become an issue when changing a value for a given filter. Because both options involve deleting current filters, more data than you want is being traced during this time. Turn the trace off (define an OSAENTA statement with the OFF option) before changing filter values.
Examples for enabling, disabling, and modifying the OSA-Express feature tracing facility are shown in Examples.
You can also modify existing OSAENTA settings by using the VARY TCPIP,,OSAENTA command. See z/OS Communications Server: IP System Administrator's Commands for more information. Use the Netstat DEvlinks/-d command to display the results.
The following differences exist between the OSAENTA and PKTTRACE statements:
;
;
; set up the filters to trace for TCP packets on PORT 5003 with a source
;or destination
; IP address of 9.67.116.124 over MAC address 000084576893
OSAENTA PORTNAME=OSA4 PROT=TCP IP=9.67.116.124 PORTNUM=5003
OSAENTA PORTNAME=OSA4 MAC=000084576893
; activate the tracing (the trace will self-deactivate after 20,000 frames)
OSAENTA PORTNAME=OSA4 ON FRAMES=20000
;
; deactivate the tracing
OSAENTA OFF PORTNAME=OSA4
;
; Reactivate the tracing for another 20,000 frames
OSAENTA ON PORTNAME=OSA4
;
; Modify tracing to change a port filter
OSAENTA PORTNAME=OSA4 PORTNUM=*
OSAENTA PORTNAME=OSA4 PORTNUM=21
;
; Change the parameters (add an IP address)
OSAENTA IP=9.67.116.125 PORTNAME=OSA4
;
; Set up tracing for a new problem on OSA5
; trace frames on VLAN 192 or 193 with an IPaddress 9.37.124.00 to .255 or
; 9.37.125.00 to .255 or
; 9.37.126.00 to .255
OSAENTA PORTNAME=OSA5 ABBREV=480 TIME=5
VLANID=192 IP=9.37.124/24
OSAENTA PORTNAME=OSA5 IP=9.37.125/24
OSAENTA PORTNAME=OSA5 VLANID=193 IP=9.37.126/24
; Now activate the trace with the new filters for 5 minutes
OSAENTA ON PORTNAME=OSA5
; Reset the VLANID filter and restart tracing for another 5 minute interval
OSAENTA ON PORTNAME=OSA5 VLANID=*