This article contains information about the enhancements to the nstrace functionality that were added in NetScaler software release 9.0. These enhancements include the addition of the filter, link, and name parameters, along with the addition of nstrace as a command in the command line interface.

nstrace.sh vs nstcpdump.sh

The NetScaler has two separate mechanisms available to capture the network traffic through the appliance: nstrace.sh and nstcpdump.sh. These mechanisms each have distinct advantages and disadvantages in their use:

Advantages of nstrace.sh

• Records network packets trace in the native NetScaler trace format, which provides specific NIC device information including device number and whether the packet was transmitted or received.

• Provides connection link information, allowing identification of links between client to virtual server and SNIP/MIP to server TCP connections.

• Allows creation of multiple files based on a set amount of time and number of files per cycle by using the –nf and –time options.

• Allows creation of separate trace files per NIC by using the –nic option.

• Allows packet capture in tcpdump format if required.

Disadvantages of nstrace.sh

• Filters are not supported in NetScaler software release earlier than 9.0.

• No ability to send packet capture data directly to stdout (standard output).

• No flexibility in setting file names in NetScaler software release earlier than 9.0.

Advantages of nstcpdump.sh

• Ability to send packet capture data to stdout by omission of the –w option.

• Allows use of standard tcpdump filters.

Disadvantages of nstcpdump.sh

• Native NetScaler trace format is not supported.

• nstcpdump.sh is more resource intensive than nstrace.sh because this script runs both nsapimgr to capture packets, and tcpdump to output data either to a file or to the screen.

Enhancements to nstrace.sh

The enhancements to nstrace.sh available in NetScaler software release 9.0 add flexibility to how the appliance generates and saves network traces, to make the function more useful as a tool for troubleshooting. Enhancements for nstrace.shIn NetScaler software release 9.0, nstrace.sh has the following options available which are not available or are modified in NetScaler software release 8.0 and earlier:

-m        - Capturing mode: sum of the values (def. 18):
               1 - Transmitted packets (TX)
               2 - Packets buffered for transmission (TXB)
               4 - Received packets (RX) before NIC pipelining
               8 - Translated IPv6 packets
              16 - Received packets (NEW_RX) after NIC pipelining
              32 – C2C messages to be captured in tracing  (added in 9.2)
-name     - name of the trace file
-filter   - Filter expression for trace filtering(maximum 255 characters)
-link     - Log filtered connection's peer's (linked connection's) traffic. Works only with -filter option
-id       - ID for the trace file name for uniqueness. Should be used only with -name option

Filter Syntax for nstrace

IP-based filtering, based on source and destination IP address

Qualifiers: sourceip, destip, ip
Operators: ==, eq, !=, neq

Examples:
nstrace.sh –filter “sourceip == 10.102.34.200”
nstrace.sh –filter “destip != 10.102.34.210”
nstrace.sh –filter “ip == 10.102.34.200 || ip == 10.102.34.210”

Port-based filtering, based on source and destination port

Qualifiers: sourceport, destport, port
Operators: ==, eq, !=, neq, >, gt, <, lt, >=, ge, <=, le, BETWEEN

Examples:
nstrace.sh –filter “sourceport == 80”
nstrace.sh –filter “destport != 22”
nstrace.sh –filter “port >= 22 && port != 80”
nstrace.sh –filter “sourceport >= 22 && destip != 10.102.34.200”

Qualifier: svcname
Operators: ==, eq, !=, neq

Examples:
nstrace.sh –filter “svcname == service1”

Qualifier: vsvrname
Operators: ==, eq, !=, neq

Examples:
nstrace.sh –filter “vsvrname == vs1”

TCP state-based filtering, based on the TCP state of the connection

Qualifier: state
Qualifier value:  CLOSE_WAIT, CLOSED, CLOSING, ESTABLISHED, FIN_WAIT_1,
                  FIN_WAIT_2, LAST_ACK, LISTEN, SYN_RECEIVED, SYN_SENT,
                 TIME_WAIT
operators: ==, eq, !=, neq

Examples:
nstrace.sh –filter “state != established”

Connection ID-based filtering, based on PCB devno (a NetScaler-specific identifier)

Qualifier: connid
Operators: ==, eq, !=, neq, >, gt, <, lt, >=, ge, <=, le, BETWEEN

Examples:
nstrace.sh –filter “connid == 123456”

Note: NetScaler filter syntax allows usage of && and || (logical AND and OR) to create complex expressions.

Link Option for nstrace

When the NetScaler proxies a given TCP connection, it creates an internal link for the Connection IDs for both the client to virtual server and the MIP/SNIP to server TCP connections. The –link option works in conjunction with the –filter option in nstrace function to capture peer data for whatever data captured in the filter. That is, if –link option is set to 1 (enabled) and you have configured nstrace to filter the client IP address, nstrace will also pick up the associated MIP/SNIP to server connection.

Example:
nstrace.sh –filter “vsvrname == vs1” –link 1
This command captures all traffic to the virtual server named vs1 and the corresponding traffic to the services which are bound to it.
Note: If you run the nstrace.sh script from the BSD shell, then the possible values for –link are 0 and 1. If you run the nstrace command from the command line interface, then the possible values are DISABLED and ENABLED.

The nstrace Command

> help nstrace

Usage:  nstrace [-nf <positive_integer>] [-time <secs>]
        [-size <positive_integer>] [-mode <mode> ...]
        [-tcpdump ( ENABLED | DISABLED )  [-perNIC ( ENABLED | DISABLED )]]
        [-name <string>  [-id <string>]] [-filter <expression>
        [-link ( ENABLED | DISABLED )]]

 where:
    <mode> = ( TX | TXB | RX | IPV6 | NEW_RX )
 Done

For more information refer to CTX120941 - How to Capture an nstrace from the Command Line Interface of NetScaler Appliance.