Overview

 

Nfilter is a program that executes, filters, and displays output from the z/OS Communication Server onetstat command.  The Nfilter program allows you to filter on any Netstat data field for equality (=), less than (<), greater than (>), or not equal (!=), giving you the ability to locate and display information about TCP/IP resources of specific interest to you.  This tool is available only in REXX and will run under the following environments: NetView, TSO/E, ISPF, The z/OS UNIX System Services shell, and MVS.

 

Netstat output is displayed in its original format when possible.  Not all Netstat reports are filterable in their original format, the IPv4 onetstat -r report for example.  In these situations Nfilter will convert the original Netstat report to a filterable format, and display any matching data using the new format.  If you prefix any Nfilter report with the at sign (@), Nfilter will produce a display that contains only the filters you provide on the command line.  Nfilter supports filtering on the following Netstat commands.

Nfilter report       Netstat command

ALL                  onetstat -A

BYTE                 onetstat -b

DEV                  onetstat -d

DROP                 onetstat -A

HOMELIST             onetstat -h

IDS                  onetstat -k

QOS | SLAPM          onetstat -j

PORTL                onetstat -o

ROUTE | RTTABLE      onetstat -r

TTLS                 onetstat -x GR DETAIL

VDPT                 onetstat -O DETAIL

VCRT | VIPACONN      onetstat -V DETAIL

VIPAINFO             onetstat -F

SRCIP                onetstat -J

STACKINFO            onetstat -f

STATS                onetstat -S

 

Nfilter provides several specialty reports.  These reports are filterable, and limit the display of Netstat data to specific data fields.  These reports can be extended to display additional information as needed.

 

Nfilter report Netstat command           Description

CONNS          onetstat -A               One line list of connection status

CONND          onetstat -A               Detailed list of connection status

CONNPR         onetstat -A               Connections mapped to Routing Policy

DEVSTATUS      onetstat -d               One line list of device status

DEVCONFIG      onetstat -d               A shortened version of DEV

DEVPKTRACE     onetstat -d               List of dev packet trace status

IDSTCP         onetstat -k PROTO TCP     IDS TCP report only

IDSUDP         onetstat -k PROTO UDP     IDS UDP report only

LANGROUPV4     onetstat -d               Information about vlans

LANGROUPV6     onetstat -d               Information about vlans

RTTABLED       onetstat -r DETAIL        detailed routing information

SERVER         onetstat -A               Shows only server resources

SERVERL        onetstat -A               One line list of active servers

SERVERS        onetstat -A               Shortened version of SERVER

TCONNINFO      onetstat -x CONN y DETAIL TLS specific connection info

PRULES         onetstat -j               Shortened list of in use QOS rules

PALL           onetstat -j               Shortened list of all QOS rules on system

OSAINFO        onetstat -d               Shows device OSA information

VIPADEST       onetstat -O DETAIL        Shortened VDPT report

 



Additional reports:

Reports calling onetstat -F

VIPABACKUP, VIPADEFINE, VIPARANGE, VIPADISTRIBUTE

 

Reports calling onetstat -f

TCPCONFIG, UDPCONFIG, IPCONFIG, IPV6CONFIG, ZIIPCONFIG,

NETMONCONFIG, SYSPLEXMON, SMF119CONFIG, SMF118CONFIG

 

 

Nfilter provides the following report commands for filtering output from the Ipsec command.  The information in this document is specific to filtering the Netstat commands, but the same concepts apply to filtering Ipsec command output.

 

Default reports:

 

IPSEC                ipsec -y display -c all   

IPSECFILTER          ipsec -f display           

 

Specialized reports:

 

IPSECTUNNEL          ipsec -y display -c all    List of tunnels and their state

IPSECFILTERS         ipsec -f display           List of ipsec filters

 

Program Requirements

 

Nfilter requires the following in order to process data correctly.

Restriction:  This tool will not work with the Japanese language.

 

·         Ensure that your Netstat security environment is setup properly.  Nfilter performs no authorization checks.  The programs Nfilter calls to collect data may perform authorization checks. Ensure that your z/OS Communications Server security is properly configured for the Netstat and Ipsec commands. 

Nfilter supports the Netstat DROP command. Before making this program available on your systems you should ensure that only authorized users have authority to use the Netstat DROP command. You can do this by having your security administrator issue the RACF command:

   RDEFINE OPERCMDS MVS.VARY.TCPIP.DROP UACC(NONE)

and then PERMIT authorized users to this resource with CONTROL access.

 

·         Authority to write to the /tmp directory and adequate /tmp space.  Nfilter creates one or more temporary files during the filtering process.  These files can be very large depending upon the number of Netstat records Nfilter needs to process.  To determine if you have adequate /tmp space, issue the command onetstat -A > nfilter.tst during a period of peak TCP/IP usage.  If multiple users will be using nfilter you will need adequate space for each user.

·         All data being filtered by this tool must be in the standard IBM-1047 code page.  Results will be unpredictable if the data is in a different format.

·         The program BPXWUNIX, which Nfilter calls, to execute the onetstat program.  If this program is not available in your link list you will be unable to use Nfilter.

 

Program Guidelines

 

Some guidelines to follow when running Nfilter
 

·         If this program is executed under a TSO/E session use the attention key to break out of the program. When prompted, type HT to halt the REXX execution.

·         If this program is executed under a z/OS UNIX System Services shell environment, issue a ctrl-c to break out of the program. When prompted, select 5 Halt type.

·         If this program is executed as a NetView clist from a class console, the output may wrap.  To prevent wrapping, issue the console command: K S,MFORM=(X).

·         If Nfilter is executed as a NetView clist, the Nfilter output may be inter-mixed with other system log messages.  To prevent this inter-mixing you can use the following technique:

/*REXX*/
parse arg p_cmdline
'PIPE NETV NFILTER 'p_cmdline,
   '| TOSTRING /NFIL002I/',
   '| COLLECT',
   '| CONSOLE'
exit

 

Limitations and Performance


Because Nfilter is performing text based data comparisons, be prepared for long processing times if the number of records exceeds 5,000.   Whenever possible, use the Nfilter keywords CLIENTNAME and PORT to reduce the amount of data that needs to be processed.

 

Installation


This package includes the complied REXX version of this program.  These instructions assume you will be using this program under TSO/E, NetView, or from the z/OS UNIX System Services shell environment.

 

Requirement: Before running this program from the shell it must have execute authority. 
Issue chmod +x nfilter

 

Installing the compiled REXX version:

 

·         Download the nfilter.tar package. This package contains the compiled REXX program.

·         Perform a FTP binary transfer of nfilter.tar to a z/OS UNIX System Services directory.

·         Extract the Nfilter program using the command: tar -x -f nfilter.tar

·         If you are installing this program for use under the z/OS UNIX System Services shell environment, then copy the Nfilter program into a directory that is part of your PATH environment variable, or into your home directory.     

·         If you are installing this program for use under TSO/E or NetView, then copy the Nfilter program into a MVS data set in your TSO/E SYSPROC or NetView DSICLIST DD concatenation. If you choose to place this program in an alternate location, place the file into a data set with a RECFM of F,B and a LRECL of 80.

You can transfer the program to an MVS data set using either FTP or the shell command cp. If you use FTP, perform a binary transfer to a data set in your SYSPROC or DSICLIST concatenation. If you use the cp command you will need to perform the following steps:

1.     From TSO 3.2 create a temporary PDS data set with space units=track, recfm=FB, lrecl=80, directory blocks=1, and pri=5.

2.     Issue the command:  cp -B nfilter "//'userid.temp.clist'"
where 'userid.temp.clist' is your temporary data set.

3.     Copy the nfilter program from this data set into a data set in your SYSPROC or DSICLIST concatenation.

 

Syntax

 

>>-- NFILTER -- [@]report ­--+-----------+--+--------------+----><

                            +-- stack --+  +<-------------+

                                           +-- ,filter  --+  

                                           +-- ,keyword --+

 

where

report    The Nfilter report to display.  This is a required parameter.  The at sign (@) is optional. If the at sign (@) is present Nfilter will display only information about the filters or keywords you provide on the command line.   Most Nfilter reports properly display data when the at sign (@) is present. However due to the format of Netstat output and how Nfilter maintains Netstat data internally, some reports may produce unexpected results.


The following basic reports are available; these reports display Netstat data in their original format if possible.
ALL, BYTE, DEV, DROP, HOMELIST, IDS, QOS, SLAPM, PORTL, ROUTE, RTTABLE, TTLS, VCRT, VDPT, VIPAINFO, SRCIP, STACKINFO, STATS, IPSEC, IPSECFILTER

The following special reports are available; these reports display Netstat data in non-standard formats.
CONNS, CONND, CONNPR, DEVSTATUS, DEVCONFIG, DEVPKTRACE, IDSTCP, IDSUDP, LANGROUPV4, LANGROUPV6, RTTABLED, SERVER, SERVERL, SERVERS, TCONNINFO, PRULES, PALL, OSAINFO, VIPADEST, VIPABACKUP, VIPADEFINE, VIPARANGE, VIPADISTRIBUTE, TCPCONFIG, UDPCONFIG, IPCONFIG, IPV6CONFIG, ZIIPCONFIG, NETMONCONFIG, SYSPLEXMON, SMF118CONFIG, SMF119CONFIG, IPSECTUNNEL, IPSECFILTERS

stack     This parameter is optional. Use this parameter to obtain onetstat data from a specific TCP/IP stack.  If not present the default TCP/IP stack is assumed.   There is no comma between the report parameter and this parameter.

filter    This parameter is optional. Use this parameter to code one or more comma separated filter conditions.  Only the records that satisfy all present filter conditions will be shown.  To aid in record selection Nfilter provides a set of built in filter commands.  See the section: How Nfilter Uses the Built-in Filtering Support of Netstat below for more information.

keyword   This parameter is optional. Use this parameter to select additional information from a record that passes filtering.   This parameter is useful only when used with one of the special reports, or if the @ symbol is present.

 

Guideline: Nfilter displays data in its original format, or in condensed or shortened reports.  Use the keyword parameter with the condensed reports to have Nfilter display additional data present in the record. 

 

Restrictions:

·         The report TCONNINFO requires the Clientid= filter be present.

·         The reports VIPADEST, VDPT, VIPACONN, and VCRT require that the PORT= filter be present.

·         You cannot use the PORT= filter on the IDS Nfilter reports.

·         The DROP command requires the CLIENTNAME= filter to be present.

Example: Display the connection state of all connections with a Client Name of  MXS*, and include the BytesIn and BytesOut data fields in the report.

 

nfilter conns,clientname=mxs*,bytesin,bytesout

 

How To Construct Nfilter Filters

 

The Netstat command displays information about the status of the local host, including information about TCP/IP connections, network clients, gateways, and devices.  Each Netstat record consists of multiple data fields describing a single TCP/IP resource.  For example a single record from the onetstat -A command might contain the following:

 

Client Name: DCLSWGE1                 Client Id: 005399AE

  Local Socket: 10.2.107.1..64858                                 

  Foreign Socket: 10.11.105.8..50030                                 

    BytesIn:            00000000000001128000

    BytesOut:           00000000000001128000

    SegmentsIn:         00000000000000001249

    SegmentsOut:        00000000000000001290

    Last Touched:       21:52:24         State:              Establsh

    RcvNxt:             0393603707       SndNxt:             2538621096

    ClientRcvNxt:       0393603707       ClientSndNxt:       2538621096

    InitRcvSeqNum:      0392475706       InitSndSeqNum:      2537493095

    CongestionWindow:   0000041412       SlowStartThreshold: 0000032697

    IncomingWindowNum:  0393731707       OutgoingWindowNum:  2538735298

    SndWl1:             0393599046       SndWl2:             2538621096

    SndWnd:             0000114202       MaxSndWnd:          0000131070

    SndUna:             2538621096       rtt_seq:            2538600692

    MaximumSegmentSize: 0000001211       DSField:            00

    Round-trip information:

      Smooth trip time: 2.000            SmoothTripVariance: 1.000    

    ReXmt:              0000000000       ReXmtCount:         0000000000

    DupACKs:            0000000046       RcvWnd:             0000128000

    SockOpt:            2000             TcpTimer:           00

    TcpSig:             14               TcpSel:             C0

    TcpDet:             F0               TcpPol:             02

    TcpPrf:             00

    QOSPolicy:          Yes

      QOSRuleName:      prPRD-DUMPIT-3-TCP~5                           

    TTLSPolicy:         No

    RoutingPolicy:      No

    ReceiveBufferSize:  0000064000       SendBufferSize:     0000064000

    TcpClusterConnFlag: 81

    ReceiveDataQueued:  0000000000

    SendDataQueued:     0000000000

    Application Data:   UNKNOWN 000017546000000 000017546000000.

 

Using the above Netstat output, a data field consists of a keyword, a colon (:), and a data value. A keyword is the concatenation of text preceding a colon (:).  A data value is the text following a colon (:).   Some examples of Netstat keywords and their assigned values:

 

Netstat Data Field

Keyword

Data value

Client Name

clientname

dclswge1

State

STATE

ESTABLSH

QOSRuleName

QosRuleName

prPRD-DUMPIT-3-TCP~5

ReXmtCount

Rexmtcount

0

Local Socket(1)

Localsocket

10.2.107.1

 

(1)    Netstat reports display a socket endpoint as an IP address, two periods, and a port number, for example, Local Socket: 10.2.107.1..64858. Nfilter recognizes this format and uses two keywords to represent the socket endpoint.  Nfilter assigns the address portion to the keyword representing the data field; in this case it is LOCALSOCKET, and assigns the Port to the same keyword with the word PORT appended to it; in this case it is LOCALSOCKETPORT.

 

An Nfilter filter condition consists of a keyword, equality or relational symbol, and a data value.  For equality, you can test for equal (=), or not equal (! =).  For a relational test, you can test for less than (<) or greater than (>).   Filters are case insensitive.  The not equal (! =) condition may fail when attempting to match text strings, or null data values.  This is usually due to the format of the Netstat output.  To match a null value you can try the filter: keyword!="" or keyword!=''

 

Example:  Display all connection records with a Client Name of DCLSWGE1, a STATE equal to ESTABLSH, and ReXmtCount > 5.

 

%nfilter ALL,clientname=DCLSWGE1,state=establsh,rexmtcount>5

Requirements:

·         In order to locate matching records, you must remove leading zeros from your filters. Internally Nfilter strips all leading zeros from data values when assigning the data to keywords. If your filter contains leading zeros, then Nfilter will not locate a match.  For example,
      the filter, clientid=005399AE, will not match.
      the filter, clientid=5399AE, will match.

·         Do not code the same keyword in multiple filters.  Doing so may result in unexpected results.

·         When filtering using the less than (<) or greater than (>) symbols, the data value the filter applies to must be numeric.  Otherwise no match will be found.

·         When filtering under the z/OS UNIX System Services shell, the less than (<) and greater than (>) symbols have special meaning.  Use the backslash character (\) to override the default behavior of these symbols.  Example:   nfilter conns,port=80,bytesin\>9000

 

Using the Wildcard function

 

Nfilter supports using the wildcard function for filter conditions of equality or non-equality of REXX non numerical data.  You can use the wildcard function to filter on only the data value. You use the wildcard function by coding an asterisk (*) after the character sting to match on. The presence of an asterisk causes Nfilter to search a filter's data value for the character string preceding the asterisk. If the character string exists anywhere in the data value, the record will match.

 

Guideline: Using the wildcard function may yield unexpected results if the data field you want to filter contains only the characters 0-9.

 

For example, if the LOCALSOCKET data field contains the address 10.1.2.3, the following is a valid use of the wildcard function:

 

LOCALSOCKET=10*       Find all records with the character string "10"

LOCALSOCKET=10.1.2*   Find all records with the character string "10.1.2"

 

If the BYTESIN data field contains the number 33333, the filter BYTESIN=3333* can result in the display of incorrect Netstat records, or no records.

 

Here are some examples of using the wildcard function.

 

Example 1:  Display all Netstat connection records that have DCL as part of their Client Name, and are in established state.

 

%nfilter all,clientname=DCL*,state=establsh

 

Example 2: Display all Netstat connection records that have 249 as part of their Foreign Socket address. 

 

%nfilter all,foreignsocket=249*


How Nfilter Uses the Built-in Filtering Support of Netstat

 

Where possible, Nfilter uses the built-in filtering capabilities of Netstat before applying additional filters.  Nfilter maps the following keywords to the Netstat filter option when the keyword is part of an Nfilter filter:

 

Keyword       Netstat filter option

IPADDR        Enables the -I option

PORT          Enables the -P option

CLIENTNAME    enables the -E option.


Rule:  Nfilter applies user filters only after Netstat applies its built-in filters.

 

Since Netstat allows only a single filter, Nfilter uses the following precedence to determine which filter to pass to Netstat when multiple filters are present.  Nfilter applies the remaining filters to any Netstat data returned.  IPADDR overrides PORT and CLIENTNAME, and PORT overrides CLIENTNAME.

 

Guideline: The use of IPADDR is strongly discouraged, unless its use will significantly reduce the amount of data Nfilter needs to parse, and you understand the limitations of the Netstat -I filter.  The -I filter is also not supported for all Netstat reports showing IP addresses.  You can achieve more accurate record matching using the keyword representing the Netstat data field for a socket endpoint, and Nfilter's own wildcard function support, but be prepared for possible performance degradation.

 

Example: Display all dynamic VIPA destination ports for the DESTXCF address of 10.199.103.10 and DEST address of 197.2.200.* for port 50030

 

nfilter vdpt,port=50030,destxcf=10.199.103.10,dest=197.2.200*

nfilter @vdpt,port=50030,destxcf=10.199.103.10,dest=197.2.200*

 

 

Nfilter Special Filter keywords for Netstat Reports

 

To aid in reducing and finding valid matches, Nfilter provides some special filtering keywords for some of the Nfilter reports. 

 

For the reports DEV, DEVSTATUS, and DEVCONFIG these special keywords are available:

NOVIPA               If present, Nfilter will not display any records for VIPA devices. 

INTFNAME=name        If present, Nfilter will find all device records which match either the LnkName or InftName Netstat data fields.  The wildcard function is available for this filter.

LINKNAME=name        If present, Nfilter will find all device records which match either the LnkName or InftName Netstat data fields.  The wildcard function is available for this filter.

Guideline: When using the at sign (@) and the filter NOVIPA, code NOVIPA at the end of your filter list.  Otherwise Nfilter will suppress any data assigned to filters following NOVIPA.

 

For the reports DEVSTATUS and DEVCONFIG these special keywords are available:

PKTRACE              If present, device packet trace information will be shown.

MULTICAST            If present, device multicast information will be shown.

LINKSTATS            If present, Link and Interface statistics will be show.

 

Restriction: You cannot filter on individual Multicast data fields.


Tips:

·         If the PKTRACE or LINKSTATS keywords are present, you can filter on packet trace and linkstats data fields.

·         Because of the way Netstat displays multicast, and how Nfilter represents it internally, if you code MULTICAST and use the at (@) symbol, Nfilter will display all the original Netstat multicast data. 

 

For the report STATS, these special keywords are available:

PROTOCOL=proto       Displays only the stats for the indicated protocol. Valid values for proto include: TCP, UDP, ICMP, IP, IPV4, IPV6, ICMPV6.

 

For the reports RTTABLE and RTTABLED, these special keywords are available:

INTFNAME=name        Matches on any value assigned to the Inft data field.

IPV6ONLY             Shows only IPv6 records.

IPV4ONLY             Shows only IPv4 records.

PR                   Shows Routing Policy information if available.

PR=NAME              Shows routing records using a specific Routing Policy.

 

For VDPT and VIPADEST these special keywords are available:

QOSPLCACT            If QOS policy information is present, this filter causes Nfilter to display it.

QOSPLCACT=name       Shows only those records were the QOS policy name matches the filter name.

 

Some Example commands and Output

 

nfilter @connpr,localsocket,foreignsocket,qospolicy=yes,state

Client Name: PAGENT                   Client Id: 00004F4F            

   LOCALSOCKET:      2000:10:11:80::110..2321                             

   FOREIGNSOCKET:    2000:10:11:80::109..1234                             

   QOSPOLICY:        Yes                                             

   STATE:            Establsh     

 

nfilter connpr,qospolicy=yes

Client Name: LBAGENT   Client id: 80        State: Establsh

   Local Socket:   2000:10:11:248::10..8000               

   Foreign Socket: 2000:10:11:248::1..8100                

      QOSPolicy:          Yes                              

         QOSRuleName:        prProtocolTCP_94              

      TTLSPolicy:         Yes                              

         TTLSRule:           LBAgentRuleDP_541             

         TTLSGrpAction:      gAct2                         

         TTLSEnvAction:      eAct5                         

      RoutingPolicy:      No