VARY TCPIP,,OSAENTA

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.

The OSAENTA command consists of two parts.

The first part defines the OSA that is to be traced and the characteristics of the tracing.
The second part turns tracing on or off, or clears the trace settings.

The tracing characteristics are identified by filters that specify under which conditions a frame should be traced. A frame must meet all of the conditions specified on the OSAENTA commands for it to be traced. For example, if the OSAENTA command identifies PROTOcol=TCP and PORTNum=21, then only IP packets that have both a protocol of TCP and a port number of 21 are traced. Only one value can be specified for a given filter each time the OSAENTA command is issued.

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.

Tips:

You can specify the parameters for this statement in any order.
If a keyword on a given command is specified multiple times, the last value specified is used.
If an error is found while parsing the OSAENTA command, an error message is generated and the command is ignored.

Format


>>-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-----'

Notes:

Each option can be specified only once. The order of options is not important.
You must also issue the MVS TRACE command for component SYSTCPOT to activate the OSAENTA 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 fails with an error message.

OSAENTA

Specifies that this command is for OSAENTA information.

PORTNAME=osa_port_name

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

Tip:

You are not required to also define OSA-Express to TCP/IP using the DEVICE/LINK 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 Defining an OSA-Express device to z/OS® Communications Server using QDIO in z/OS Communications Server: SNA Network Implementation Guide.

Restriction: Multiple stacks cannot use the tracing function concurrently for a given OSA.

FULL

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

ABBREV={abbrev_length|224}

Specifies the amount of data that is to be traced for each frame.

You can specify a data 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.

Guideline: Use a large value or the FULL parameter if you want to maximize the amount of data traced for each packet because TCP segmentation offload packets are traced before the packet is segmented and can be larger than the largest frame size on the LAN. See TCP segmentation offload in the z/OS Communications Server: IP Configuration Guide for information about which parameters affect the size of TCP segmentation offload packets.

Restriction: Many OSA models limit the amount of data recorded to 120 bytes. The OSAENTA command accepts a larger size (or FULL) without any errors, but the actual trace entries are as if ABBREV=120 is specified.

CLEARFILTER

Clears any previous OSAENTA trace filters for the port specified by the osa_port_name value.

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.

DATA={trace_amount|1024}

Specifies the number of megabytes (MB) of data to be collected before stopping the trace.

The minimum value is 1 MB
The default value is 1024 MB
The maximum value is 2 147 483 647 MB

If a value of 0 is specified, then the maximum value is set.

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.

DEL

Removes the OSAENTA interface definition. The OSAENTA interface must be inactive for you to specify the DEL parameter. To dactivate the OSAENTA interface, you can respecify the OSAENTA statement with the OFF parameter, or use the VARY TCPIP,,OSAENTA command with the OFF parameter.

DEVICEID={device_id|*}

Specifies the 8-digit hexadecimal value that identifies a host that is sharing the OSA. This value is in the form csmfclua where the digits have the following values:

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 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.

DISCARD={ALL|EXCEPTION|NONE|discard_code}

Specifies which frames that were discarded by the OSA-Express device should be traced. Discarded frames include frames that the OSA-Express device could not transmit outbound or could not forward inbound. Discarded frames that match the DISCARD= setting are traced whether they match any filters that are in effect or not.

ALL

All frames discarded by the OSA-Express device are traced. This includes both exception conditions and more expected discards, such as ARP packets received for non-registered IP addresses or packets for non-supported Ethernet types.

EXCEPTION

Frames discarded by the OSA-Express device for exception conditions are traced. These are frames that are typically discarded for anomalous conditions. See the following examples of anomalous conditions:

An inbound IP packet destined for an IP address that is not registered with the OSA-Express device 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 device.

NONE

No discarded frames are traced.

discard_code

Frames discarded for the reason specified by the discard_code value are traced. Use this option only under the direction of IBM® Service personnel. Values in the range 1-4087 are accepted. Up to eight discard codes can be active for one OSA-Express device.

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.

ETHType={IPV4|IPV6|ARP|SNA|ethernet_type|*}

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 if an asterisk (*) is specified, then all packets meet the criteria for this filter.

FRAMES={trace_count|2147483647}

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 the value 0 is specified, then the maximum value is set.

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.

IPaddr={ipv4_address[/num_mask_bits]|ipv6_address[/prefix_length]|*}

Specifies an IP address (either a 32-bit IPv4 address in dotted decimal notation, or a 128-bit IPv6 address colon hexadecimal notation) to be compared with both the source and destination addresses of inbound and outbound packets. If either the source or the 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 if an asterisk (*) is specified, then all packets meet the criteria for this filter. If the IPaddr filter is specified, then only frames that contain IP packets or ARP packets are subject to tracing.

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.

MAC={mac_address|*}

Specifies the 12 hexadecimal digits of the MAC address. The address is compared with both the source and destination MAC addresses of both 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 if 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 can exist if no filters have been specified, if CLEARFILTER is specified, or when the current setting for every filter is set to an asterisk (*). When the NOFILTER=ALL setting is in effect, all packets are traced. When the NOFILTER=NONE setting is specified, no packets are traced. The NOFILTER parameter applies only to packets that were not discarded by the OSA-Express device. 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 quickly if you clear all filters without setting new filters to filter out an adequate percentage of the packets.

OFF

Disables OSA tracing for the port specified by the osa_port_name value by stopping the OSAENTA interface. The trace parameters and filters remain in effect if the OSAENTA trace is subsequently re-enabled.

ON

Enables OSA tracing for the port specified by the osa_port_name value 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 parameter limits.

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.

PORTNum={port_number |*}

Specifies a port number in the range 1–65535. The port number is compared with the destination or source port of both 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 either the TCP or UDP protocol; frames using other protocols are not traced when a port filter is in effect. If the PORTNum parameter is omitted or if an asterisk (*) has been specified, then all packets meet the criteria for this filter. If the port filter is used, only frames containing IP packets are subject to tracing.

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

PROTOcol={TCP|UDP|ICMP|ICMPV6|protocol_number|*}

Specifies the IP protocol type to be traced. This can be specified as one of the literals TCP, UDP, ICMP, 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 if an asterisk (*) has been specified, then all packets meet the criteria for this filter. If a 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, only frames containing IP packets are subject to tracing.

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.

TIME={trace_time|10080}

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

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.

VLANID={vlan_id|*|ALL}

Specifies a VLAN identifier value, which is a decimal number in the range 0–4094. The ALL keyword specifies that all frames that have a VLAN tag are included. If the VLANID parameter has been omitted or if an asterisk (*) is specified, then all frames meet the filter criteria. 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.

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. To actually change a value for a given filter, several options are available:

Define an OSAENTA statement with a filter value specified by an asterisk (*), 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 subsequently specify the entire list of filter attributes that you want to use.

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.

Examples

To trace all the packets for a particular application port, enter the following OSAENTA command:

VARY TCPIP,,OSAENTA,PORTNAME=osa4,ON,PORTNUM=21

Usage

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 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. A TRACE ON command is required to start recording of the trace data into the buffers. To halt the receipt of trace data from the OSA, specify the OSAENTA statement with the OFF parameter, or use the VARY TCPIP,,OSAENTA command with the OFF parameter.
Users can be authorized to invoke the command by permitting their user IDs for CONTROL access to the RACF® profile name MVS.VARY.TCPIP.OSAENTA.

The following differences exist between OSAENTA and PKTtrace:

The PKTTRACE command can collect only data for a single TCPIP stack. The OSAENTA command can collect data for other stacks sharing the OSA.
The PKTtrace data collection starts immediately. The OSAENTA data collection is not started until the ON parameter is used.
Each PKTtrace command or statement is one set of filters. OSAENTA command filters accumulate across multiple OSAENTA commands or statements.