Taking line traces in Data ONTAP™

Pktt is a built-in packet tracer available on Network Appliance filers. The trace files taken with it are viewable with the popular ethereal line trace analyser.

pktt is invoked as follows:

Each of the subcommands must be followed by an interface name or the word "all." A small exception to this is that "pktt status -v" is equivalent to "pktt status all -v". The available interface names can be found via "ifconfig -a" or "pktt status."

pktt start
The "start" subcommand is used to start tracing, (or restart if it has been paused). The packet trace data is stored in "tcpdump" format in a circular buffer in memory. The flags that can optionally be supplied are as follows

-d dir
This specifies the path to an existing directory in which the trace data file will be written. The file will always have the name ".trc" where "" is the interface name (e.g. e4, fa3, etc.). If this option is missing, the trace data will only be collected in memory, and after the buffer fills, new packets will replace existing packets. However, it is always possible to dump the contents of the buffer at any time using the "pktt dump" command. One thing to be aware of when writing trace data to disk is that if the filesystem cannot keep up with the network traffic you may not log all packets. This will show up in the "dropped" counts when looking at status. Along with this, you should remember that logging all traffic may generate a heavy write load on the filer which may bog it down. If possible, use the IP filter to reduce the amount of data to log. Note that the default value of the -b flag is too small when logging to disk if there is much traffic. You should set -b 128k or larger. (But not too large! See below.)

-s size
This allows you to set a maximum size of the trace file. If you don't specify this the file can grow to 32GB, so set it to a reasonable value if you think there is a chance you might forget you have left the trace going. This parameter is only useful in conjunction with the "-d" option. After the maximum size has been reached, packets continue to be logged to the buffer, but not to disk.

-m pklen
This sets the length at which packets will be truncated. The default is 1500 bytes, which results in full packets for Ethernet. Note that in 5.3 the default of 1500 is incorrect for Ethernet. You must override with "-m 1514" to get the full packets. It is sometimes useful to limit the data stored when every byte of the packet is not critical. However, for many debugging tasks it is useful to have the entire packet. In the case where the packet size can be larger than 1500 you may want to specify a larger maximum. However, many of the decoders refuse to deal with packets larger than 1500 bytes so you should only specify a larger value if that seems critical to finding the problem.

-b bsize
This sets the buffer size, which may be specified as a number with an optional trailing 'k' or 'm' multiplier. The default is 32K, which should be large enough to find "packet of death" bugs and similar problems. You should use a value of at least 128K when using the -d option. The value may range from 8K to 128M, but only in the most exceptional cases would it be necessary to increase the size beyond 1-2M. In cases where the network is very busy and it is not practical to log all the traffic to disk you may need to use a larger buffer.
WARNING! - Do not specify a value larger than 3MB, even on a 1GB 760 filer. You may hang the system console or cause WAFL to run out of memory. This will be enforced in later versions, but in 5.3 you must not specify too large a buffer size.

-i ipaddr [-i ipaddr] ?
This allows limited filtering capability. Up to four IP address may be specified, which causes only traffic to or from any of those IP addresses to be logged. This will prevent logging of any non-IP (e.g. arp/rarp) traffic).

-v
This causes "pktt status -v" information to be displayed as tracing starts.

Examples of "pktt start"
pktt start e0
This will start capturing network traffic from the "e0" interface. All traffic will be logged to a 32K circular buffer. Or, if tracing had been suspended previously it would be restarted.

pktt start fa3 -d / -s 100m -b 128k
This starts capturing traffic on the "fa3" interface, writing to a file called "/fa3.trc" which will be allowed to grow to a maximum size of 100MB, with a 128K buffer.

pktt start el10 -d /home -m 10k -b 1m -i ehost1 -i ehost2
This starts capturing traffic to and from the hosts "ehost1" and "ehost2", storing the traces into the file "/home/el10.trc". Up to 10K of each packets will be stored, in a 1MB buffer.

pktt start all -b 128k -i 172.20.4.1
All interfaces will start capturing traffic to and from the specified IP address. This is a quick way to look at traffic if you're not sure which interface to use but you want to see the packets from one or more IP addresses.

pktt pause
The "pause" subcommand is used to temporarily stop capturing traffic from one or all interfaces. If any unwritten data is in the trace buffer it will be flushed to disk. Use "pktt start" without any options to restart a paused interface.

pktt dump
The "dump" subcommand causes the contents of the packet trace buffer to be written to a file. If the "-d [dir]" option is used the file will be written to that directory, otherwise it will be written to the root directory of the root volume. The name of the file is always .trc, and the contents are in "tcpdump" format. If a file by that name already exists it will be overwritten.

pktt stop
This causes all tracing to stop on the named interface, or all interfaces. If any unwritten data is in the trace buffer it will be flushed to disk. If you have not dumped the trace data and you were not tracing to a disk file, the trace data will be lost. This action is not confirmed, so be careful when using this command.

pktt status
This can be used to display the buffer and file status of an existing trace. Using "pktt status -v" will give you full tracing status for all interfaces. This can be used to display the buffer and file status of an existing trace. Using "pktt status -v" will give you full tracing status for all interfaces.


Support

The sample code and documents in the SDK are unsupported by Network Appliance CS. To obtain direct engineering support for your development effort and purchase incident packs, please contact Network Appliance by sending email to dl-manage-ontap-api@netapp.com.

Your feedback is important to us. If you have suggestions for improvement of this sample code or documentation, please send them to sdk-feedback@netapp.com.