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.

Syntax

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.

Read syntax diagramSkip visual syntax diagram
>>-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-'   

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:

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

The following differences exist between the OSAENTA and PKTTRACE statements:

Examples

The following sample includes several examples of the OSAENTA statement:
Figure 1. Example of the OSAENTA statement
;
     ;
     ; 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=*

Related topics