Use the VARY TCPIP,,OSAENTA command to control the OSA-Express network traffic analyzer (OSAENTA) tracing facility in the OSA-Express adapter. You can use this command to select frames as candidates for tracing and for subsequent analysis. OSAENTA traces are recorded externally using the TRACE command. See the z/OS Communications Server: IP Diagnosis Guide for information about the steps required to perform an OSAENTA trace.
Multiple OSAENTA commands can be included in a profile data set and can control tracing for multiple OSAs. The filters on multiple OSAENTA commands are cumulative for a given OSA. As each OSAENTA command is issued with filters, those filters are added to the filters that are already in effect for that OSA. By using multiple OSAENTA commands, multiple filter values can be assigned to each filter. There is a limit of eight filter values for each filter for each OSA. 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 meets the condition of that particular filter. For example, if you specify IPaddr=9.67.1.1, PROTOcol=TCP, and PORTNum=21 on one OSAENTA command for OSA1, and you specify IPaddr=9.67.1.2 on another OSAENTA command for OSA1, then all frames sent to either IP address 9.67.1.1 or 9.67.1.2 with a protocol of TCP and a port number of 21 are traced.
The OSAENTA command dynamically defines a QDIO interface to the OSA-Express adapter being traced, called an OSAENTA interface. That interface is used exclusively for capturing OSA-Express network traffic analyzer traces.
Security Rule: The OSAENTA command enables an installation to trace data from other hosts connected to an OSA. The trace data collected should be considered confidential and TCPIP system dumps and external trace files that contain this trace data should be protected. The OSAENTA command is protected by the operating system security product. The name of the protected OPERCMDS resource is MVS™.VARY.TCPIP.OSAENTA.
>>-Vary --TCPIP--,--+----------+--,--OSAENTA--+-------------+-->< '-procname-' '-| Command |-' Command .---------------------------. V | (1) (2) |--,--PORTNAME=osa_port_name--,--+-----+----+-----------------------+-+----------| +-ON--+ +-| Trace Parameters |--+ +-OFF-+ +-| Protocol Type |-----+ '-DEL-' +-| IP Address |--------+ +-| Packet Port |-------+ +-| Device Identifier |-+ +-| Ethernet Type |-----+ +-| MAC Address |-------+ '-| VLAN ID |-----------' Trace Parameters .-,FULL-------------------------. |--+-------------------------------+--+--------------+----------> | .-224-----------. | '-,CLEARfilter-' '-,ABBREV--=--+-abbrev_length-+-' .-,DISCARD=EXCEPTION----. >--+-------------------------+--+-----------------------+-------> | .-1024---------. | +-,DISCARD=ALL----------+ '-,DATA=-+-trace_amount-+-' +-,DISCARD=NONE---------+ '-,DISCARD=discard_code-' .-,NOFILTER=NONE-. >--+------------------------------+--+----------------+---------> | .-2147483647------. | '-,NOFILTER=ALL--' '-,FRAMES=-+-+-------------+-+-' '-trace_count-' >--+---------------------------+--------------------------------| | .-10080----------. | '-,TIME=-+-+------------+-+-' '-trace_time-' Protocol Type .-,PROTOcol--=--*---------------. |--+-------------------------------+----------------------------| +-,PROTOcol--=--TCP-------------+ +-,PROTOcol--=--UDP-------------+ +-,PROTOcol--=--ICMP------------+ +-,PROTOcol--=--ICMPV6----------+ '-,PROTOcol--=--protocol_number-' IP Address .-,IPaddr--=--*--------------------------------. |--+----------------------------------------------+-------------| | .-/32------------. | +-,IPaddr--=--ipv4_address--+----------------+-+ | '-/num_mask_bits-' | | .-/128-----------. | '-,IPaddr--=--ipv6_address--+----------------+-' '-/prefix_length-' Packet Port .-,PORTNum--=--*-----------. |--+--------------------------+---------------------------------| '-,PORTNum--=--port_number-' Device Identifier .-,DEVICEID--=--*---------. |--+-------------------------+----------------------------------| '-,DEVICEID--=--device_id-' Ethernet Type .-,ETHType--=--*-------------. |--+----------------------------+-------------------------------| +-,ETHType--=--IPV4----------+ +-,ETHType--=--IPV6----------+ +-,ETHType--=--ARP-----------+ +-,ETHType--=--SNA-----------+ '-,ETHType--=--ethernet_type-' MAC Address .-,MAC--=--*-----------. |--+----------------------+-------------------------------------| '-,MAC--=--mac_address-' VLAN ID .-,VLANID--=--*-------. |--+---------------------+--------------------------------------| +-,VLANID--=--vlan_id-+ '-,VLANID--=--ALL-----'
Guideline: If you specify the CLEARFILTER parameter and the OSAENTA interface is active, either all are frames traced or no frames are traced, depending on the setting of the NOFILTER parameter.
Tip: The CLEARFILTER parameter clears all filters. To clear all values for a single filter, use the OSAENTA command and specify an asterisk (*) for the filter that you want to use.
Result: If the OSAENTA interface is inactive, then the limit specified by the DATA parameter takes effect when the OSAENTA trace is enabled with the ON parameter. If the OSAENTA interface is active and the DATA parameter 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 that is identified by the device_id value, then the frame meets the criteria for this filter. If the DEVICEID option has been omitted or if an asterisk (*) is specified, then all packets meet the criteria for this filter.
Tip: You can obtain the device_idvalues for any user of the OSA by using the hardware management console (HMC). For a datapath device that is active on a z/OS stack, you can obtain the device_id value for that datapath device from message IST2190I of the output from the DISPLAY NET,TRL,TRLE= command.
Rule: As with filters, the DISCARD keyword can be specified on multiple OSAENTA statements. The ALL and NONE options reset any previous DISCARD values that are in effect; the EXCEPTION option or a discard code resets a current setting of ALL or NONE. EXCEPTION and discard_code options are cumulative for a given OSA. If EXCEPTION and discard_code options are specified on multiple OSAENTA statements, all frames discarded for exception conditions and all frames discarded for any of the discard codes that are in effect are traced. When the EXCEPTION option is in effect, a limit of seven discard codes can be active for one OSA-Express device.
Result: A frame can be traced twice; once when the packet is passed to the OSA-Express device, and again as a dropped packet during the processing of the packet.
Guideline: To reset the current set of active discard codes, specify the value DISCARD=ALL or DISCARD=NONE followed by OSAENTA statements with the required DISCARD options that you want to specify.
Result: If the OSAENTA interface is inactive, then the FRAMES parameter limit takes effect when the OSAENTA trace is enabled with the ON parameter. If the OSAENTA interface is active and the FRAMES parameter value is modified, then the stack resets the frame counter to 0 and puts the new FRAMES parameter limit into effect.
If an IPv4 address is specified, then you can specify a /num_mask_bits value in the range 1–32 to designate a subnet. The default number of bits is 32.
If an IPv6 address is specified, then you can specify an optional prefix_length value in the range 1–128. 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 quickly if you clear all 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 very quickly if you activate the trace with no filters or with a set of filters that does not filter a significant percentage of the packets.
IPSec Encapsulating Security Payload (ESP) packets cannot be traced by specifying a port number because the TCP or UDP headers are encrypted.
Rule: For encapsulated packets, OSAENTA collects packets based on whether the specified protocol filter matches the outermost packet protocol. For example, if you specify TCP as the protocol filter and a TCP packet is received that is encapsulated in an IPSec packet with protocol 50, this TCP packet is not collected. You must specify Protocol 50 to collect these packets.
Result: If the OSAENTA interface is inactive, then the TIME parameter limit takes effect when the OSAENTA trace is enabled with the ON parameter. If the OSAENTA interface is active and the TIME parameter value is modified, then the stack resets the time counter to 0 and puts the new TIME parameter limit into effect.
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 as previously described. Because both options involve deleting current filters, more data than you want is being traced during this time. For a more efficient trace, first disable the trace (define an OSAENTA statement with the OFF parameter) before changing filter values.
To trace all the packets for a particular application port, enter the following OSAENTA command:
VARY TCPIP,,OSAENTA,PORTNAME=osa4,ON,PORTNUM=21