Manual Pages


Table of Contents

NAME

pktt - Controls on-node packet tracing.

SYNOPSIS

pktt start {if | all} [-b bsize] [-d dir] [-s size] [-m pklen] [-v] [-i ipaddr] [-i ipaddr] ...

pktt pause {if | all}

pktt dump {if | all} [-d dir]

pktt stop {if | all}

pktt status [{if | all}] [-v]

pktt delete [filename.trc]+

pktt list

DESCRIPTION

The pktt command controls a simple on-node packet tracing facility. Packets can be captured into a trace buffer then dumped to a file, or the captured data can be logged to a file. The data is stored in "tcpdump" format, and can be directly viewed with tcpdump, ethereal, and perhaps other viewers. The output can also be converted using the editcap(1) program to a variety of other formats, including Sniffer, NetMon, and snoop.

It is helpful to have pktt available because it can capture traffic from switched networks, and from all the supported node network media types.

In addition, it is often useful to turn on pktt tracing before a node crash occurs, as the packet trace can be extracted from the core file.

USAGE

pktt start {if | all} [-b bsize] [-d dir] [-s size] [-m pklen] [-v] [-i ipaddr] [-i ipaddr] ...

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

-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 128K if you have not specified -d, which is fairly small but may be OK for finding "packet of death" bugs and the like. The default value is 1M when using the -d option. The value may range from 8K to 32M, but only in unusual cases should 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. The total amount of space that can be used by pktt is 64M.

-d dir

This specifies the path to an existing directory in which the trace data file(s) will be written. The files have the name "if.trc" where "if" is the interface name (for example, e4, fa3). 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 node which may bog it down. If possible, use the IP filter to reduce the amount of data to log. Also, if you don't need complete packets you can use -m to reduce the amount written per packet.

Be aware that any existing .trc files will be silently overwritten when the command is issued.

-s size

This allows you to set a maximum size of the trace file. Values can have an optional trailing "k", "m", or "g" multiplier. The default is 1G. 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 1514 bytes, which is fine for ethernet, but may be too short for gigabit ethernet with jumbo frames. 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 1514 you may want to specify a larger maximum. But be aware that some of the decoders (snoop, for example) refuse to deal with packets larger than 1514 bytes so you should only specify a larger value if that seems critical to finding the problem. The ethereal decoder does not have any problems with large packets.

-v

This causes the output of the pktt status -v command to be displayed as tracing starts.

-i ipaddr [-i ipaddr] ...

This allows a kind of primitive filtering capability. Up to sixteen IP address may be specified, which causes only traffic to or from any of those IP addresses to be logged. This will, of course, prevent logging of any non-IP (for example, arp/rarp) traffic. With IPv6 option enabled, IPv6 address can also be specified as filter IP to capture the packets that are coming from or to the IPv6 address.

start all

This will capture the traffic on all the interfaces.

pktt pause {if | all}

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 {if | all} [-d dir]

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 if.trc, and the contents are in "tcpdump" format. If a file by that name already exists it will be silently overwritten.

pktt stop {if | all}

This causes all tracing to stop on the named interface, or all interfaces. If you are logging to disk, any unwritten data in the trace buffer 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 [{if | all}] [-v]

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.

pktt delete [filename.trc]+

This allows you to delete one or more tracefiles from the root directory. At least one tracefile must be specified.

pktt list

This allows you to list all tracefiles in the root directory.

EXAMPLES

Examples of pktt start:

pktt start e0

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

pktt start fa3 -d / -s 100m -b 2m

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 2MB buffer.

pktt start el10 -d /home -m 10k -b 500k -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 of the packets will be stored, in a 500K buffer. Note that this will only work if the hostnames can be resolved.

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 start ns0 -i 3FFE:81D0:107:2082::1

After enabling IPv6 option, executing the pktt start command with IPv6 address as the filter will capture all packets that are coming from or to the IPv6 address. The trace file dumped after executing pktt dump command should display only the packets having the IPv6 address as the source or destination.

NOTES

A number of Win32 programs exist to convert from tcpdump format to NetMon. The Win32 version of "editcap" is preferred, but there are also the "capconv" and "captrans" programs.


Table of Contents