OSAENTA statement

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.

Parameters

PORTNAME=osa_port_name

Specifies the required port name of the OSA-Express for which you want to enable tracing. This is the same port name that is defined on the PORTNAME keyword of the VTAM® TRLE statement. This is the same port name that is either defined on the PORTNAME keyword of the VTAM TRLE statement or is dynamically created by VTAM for OSX interfaces (configured with the CHPID parameter) or for OSM interfaces. For more information about OSM and OSX interfaces, see z/OS Communications Server: IP Configuration Guide..

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.

ABBREV

Specifies the amount of data that is to be traced for each frame. You can specify a length in the range 64 - 65472 or use the default value 224. The value is rounded up to the next 32 byte boundary. The ABBREV parameter can be used to control the volume of data stored in the trace buffers and file. The actual amount of data traced might be limited by the OSA adapter.

Tip: The size value that OSA returns is the maximum amount of trace data that OSA can return. Depending on the model, OSA can return fewer bytes than the maximum. OSA-Express3 or later version returns only 120 bytes for unicast packets, and return up to the maximum amount of trace data for multicast, broadcast, or unrouteable packets.

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.

CLEARFILTER

Clears any previous OSAENTA trace filters for the specified OSA-Express port name.

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.

DATA

Specifies the number of megabytes of data to be collected before stopping the trace. The minimum value is 1 megabyte, the default value is 1024 megabytes, and the maximum value is 2147483647 megabytes. If a value of 0 is specified, then the maximum value is set.

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.

DEL

Removes the OSAENTA interface definition. The OSAENTA interface must be inactive in order to specify the DELETE parameter. To deactivate the OSAENTA interface, you can respecify the OSAENTA statement with the OFF parameter, or use the V TCPIP,,OSAENTA command with the OFF parameter.

DEVICEID

Specifies the 8-digit hexadecimal value that identifies a host that is sharing the OSA-Express feature. The value is in the form csmfclus, where:

cs

The channel subsystem ID for this datapath device.

mf

The LPAR Multiple Image Facility ID for the LPAR using this datapath device.

cl

The control unit logical identifier for this datapath device.

ua

The unit address for this datapath device.

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.

DISCARD

Specifies which frames that are discarded by the OSA-Express feature should be traced. Discarded frames include frames that OSA-Express feature could not transmit outbound or could not forward inbound. Discarded frames that match the DISCARD= setting are traced whether or not they match any filters that might be in effect. You can specify the DISCARD parameter on multiple OSAENTA statements. The ALL and NONE values reset any previous DISCARD values that are in effect, and the EXCEPTION value or a discard code resets the setting ALL or NONE. The EXCEPTION value and discard_code values are cumulative for a given OSA-Express feature.

ALL

Specifies that all frames that are discarded by the OSA-Express feature are traced. This includes both exception conditions and expected discards, such as ARP packets received for non-registered IP addresses or packets for non-supported ethernet types.

EXCEPTION

Specifies that frames discarded by the OSA-Express feature for exception conditions are traced. These are frames that are typically discarded for anomalous conditions. Examples of anomalous conditions are:

• An inbound IP packet destined for an IP address that is not registered with the OSA-Express feature and no PRIROUTER or SECROUTER parameter is in effect.
• An outbound IP packet that could not be delivered because no storage was available within the OSA-Express feature.

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.

NONE

Specifies that no discarded frames are traced.

discard_code

Specifies that frames discarded for the reason specified by the discard_code value are traced. This option should be used only under the direction of IBM® service personnel. Valid values are in the range 1 - 4087. As many as 8 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.

ETHTYPE

Specifies the Ethernet frame type to be traced. This can be specified as one of the literals IPV4, IPV6, ARP, SNA or as a hexadecimal number in the range 0600 - FFFF (IPV4=0800, IPV6=86DD, ARP=0806, and SNA=80D5). If the ETHTYPE parameter has been omitted or an asterisk (*) is specified, then all packets meet the criteria for this filter.

FRAMES

Specifies the number of frames to be recorded before tracing is stopped. The minimum value is 100 frames. The maximum value is 2147483647 frames. If a value of 0 is specified, then the maximum value is set.

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.

FULL

Specifies that the entire frame is to be traced if possible. (OSA-Express might limit the amount of data actually traced.)

IPADDR

Specifies an IP address (either a 32-bit IPv4 address in dotted decimal notation, or a 128-bit IPv6 address in colon hexadecimal notation) to be 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 frame meets the criteria for this filter. If the IPADDR option is omitted or an asterisk (*) is specified, then all packets meet the criteria for this filter. If the IPADDR filter is specified, then only frames containing IP packets or ARP packets are subject to tracing.

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.

Note:

1. If an IP address has never been specified on the OSAENTA command for the OSA portname, IPADDR=* is the default.
2. If IPADDR is specified on the command, you can specify one of the following values:
   • *
   • An IPv4 address
   • An IPv6 address
   There is no default if the IPADDR parameter is specified alone. If this parameter is specified by itself, it is a syntax error . Specify IPADDR=* to remove all previous IP addresses from the filter. Specify IPADDR=IPv4_address or IPADDRr=IPv6_address to add this address to the list of addresses for the IP address filter.

MAC

Specifies the twelve hexadecimal digits of the MAC address. The address is compared with both the source and destination MAC address of inbound and outbound frames. If either the source or destination address of a frame matches the specified MAC address, the frame meets the criteria for this filter. If the MAC option has been omitted or an asterisk (*) is specified, then all packets meet the criteria for this filter.

NOFILTER=ALL|NONE

Specifies the filtering behavior when all filters (DEVICEID, MAC, ETHTYPE, VLANID, IPADDR, PROTOCOL and PORTNUM) have been cleared or are inactive. This condition might exist if no filters have been specified, if the CLEARFILTER parameter is specified, or when the current setting for every filter is set to an asterisk (*). When NOFILTER=ALL, all packets are traced. When NOFILTER=NONE is specified, no packets are traced. The NOFILTER parameter applies only to packets that were not discarded by the OSA-Express feature. The DISCARD parameter controls tracing of discarded packets.

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.

OFF

Disables OSA-Express feature tracing for the specified OSA-Express feature port name by stopping the OSAENTA interface. The trace parameters and filters remain in effect if you subsequently re-enable the OSAENTA trace.

ON

Enables OSA-Express feature tracing for the specified OSA port name by starting the OSAENTA interface using the OSAENTA trace parameters and filters that are currently in effect. If the OSAENTA interface is already active, then the ON keyword causes the stack to reset the active counters on the DATA, FRAMES, and TIME limits.

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.

PORTNUM

Specifies a port number in the range 1 - 65535. The port number is compared with the destination or source port of inbound and outbound packets. If the port of a packet is the same as the specified port number, then the frame meets the criteria for this filter. This comparison is performed only for packets using the TCP or UDP protocol; frames using other protocols are not traced when a PORTNum filter is in effect. If the PORTNum parameter is omitted or an asterisk (*) has been specified, then all packets meet the criteria for this filter. If the PORTNum filter is used, then only frames containing IP packets are subject to tracing.

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

PROTOCOL

Specifies the IP 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 0 - 255 (ICMP=1, TCP=6, UDP=17, ICMPV6=58). If the PROTOCOL parameter is omitted or an asterisk (*) has been specified, then all packets meet the criteria for this filter. If a PROTOCOL protocol value is specified and the frame does not contain an IP protocol packet, then the frame is not traced. If the PROTOCOL filter is used, then only frames containing IP packets are subject to tracing.

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.

TIME

Specifies the number of minutes that trace records are recorded before stopping. The minimum value is 1 minute. The maximum value is 10080 minutes (7 days). If a value of 0 is specified, then the maximum value is set.

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.

VLANID

Specifies a VLAN identifier value, which is a decimal number in the range 0 - 4094. The keyword ALL indicates that all frames that have a VLAN tag are included. If the VLANID parameter has been omitted or an asterisk(*) is specified, then all frames meet the criteria for this filter. If a VLAN identifier is specified, and the frame does not contain a VLAN tag or does not match the VLAN identifier, then the frame is not traced.

Steps for modifying

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:

• Define an OSAENTA statement with a filter value of *, effectively deleting all values for that one filter entirely. Then define subsequent OSAENTA statements with the new filter values.
• Define an OSAENTA statement with the CLEARFILTER parameter, which removes all existing filters, and specify the entire list of filter attributes.

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.

Usage notes

• You can use the Netstat DEvlinks/-d command to display the current OSAENTA trace settings.
• When the DATA, FRAMES, or TIME values are exceeded, the stack disables the OSAENTA trace, but this does not happen immediately. Trace records from the OSA-Express feature continue to be recorded until the stack has successfully contacted the adapter to stop the OSAENTA trace.
• To verify that the Ctrace component SYSTCPOT is active for a stack, issue DISPLAY TRACE,COMP=SYSTCPOT,SUB=(tcpip_procname).
• To write the data to the external writer, use the MVS™ TRACE,CT,WTRSTART=writer_procedure command to start the writer and the TRACE CT,ON,COMP=SYSTCPOT,SUB=(tcpip_procname) command to connect to the writer.
• The last buffer trace data are not written to the external writer until the writer has been disconnected from TCPIP and stopped.
• The TRACE CT,OFF,COMP=SYSTCPOT,SUB=(tcpip_procname) command stops the recording of trace data into TCPIP buffers and to the external writer. It does not stop the receipt of trace data from the OSA-Express feature. Issue a TRACE ON command to start recording the trace data into the buffers. To halt the receipt of trace data from the OSA-Express feature, specify the OSAENTA statement with the OFF parameter, or use the V TCPIP,,OSAENTA command with the OFF parameter.
• The OSAENTA trace can have performance implications if sufficient trace filters are not specified before enabling the trace. OSAENTA can reduce the amount of traffic the OSA-Express device can process and the amount of traffic that can be accelerated through that OSA-Express device. Also, host processing to collect the OSAENTA trace records can increase host CPU consumption. Specify sufficient filters to limit the amount of traffic traced to what is necessary for problem diagnosis.

The following differences exist between the OSAENTA and PKTTRACE statements:

• The PKTTRACE statement can collect data for only a single TCP/IP stack. The OSAENTA statement can collect data for other stacks that share the OSA-Express feature.
• Data collection enabled with the PKTTRAACE statement starts immediately. The data collection enabled with the OSAENTA statement is not started until the ON parameter is used.
• Each PKTTRACE command or statement is one set of filters. OSAENTA statement filters accumulate across multiple OSAENTA commands or statements.

Related topics

• V TCPIP,,OSAENTA command in z/OS Communications Server: IP System Administrator's Commands
• OSAENTA Trace in z/OS Communications Server: IP Diagnosis Guide
• OSA-Express Network Traffic Analyzer trace in z/OS Communications Server: IP Configuration Guide
• Display TRL command in z/OS Communications Server: SNA Operation