nettrace(1M) — ADMINISTRATOR COMMANDS
NAME
nettrace − trace host network packets
SYNOPSIS
nettrace [−gpbhrtnsaCI] [−f diskfile] [−i count] [−D num] [−d ifcontrol device] [−F filterDescFile ] [ifname] [! filterDesc value] [filterDesc value] ...
DESCRIPTION
nettrace allows the super-user to trace packets at the interface level. The traced packets may be those received, sent, or both. Filters are provided to remove broadcast packets, to select received and/or transmitted packets and to match values at specified offsets. Packets may be captured to a disk file or displayed as captured. The default display decodes as much of the internet protocol as possible.
The options have the following meaning:
−g Get packets. This option arms the driver for packet capture. The −r, −t, −b options specify the capture filter.
−p Print packets. This option displays the captured packets. If used with the −g option, the packets are displayed as they are captured. Without −g, the display comes from the disk file.
−r Set capture filter to receive. This option is only valid with −g (get packets). The default is to capture transmit and receive packets. Specification of either −r or −t will reset default filter.
−t Set capture filter to transmit. This option is only valid with −g (get packets). The default is to capture transmit and receive packets. Specification of either −r or −t will reset default filter.
−b Set capture filter to ignore broadcasts. This option is only valid with −g (get packets). This option does not reset the default filter.
−h By default, packets are interpreted and displayed in a verbose format. This option interprets Ethernet headers and displays the rest of the packets as hexadecimal bytes.
−n Display host addresses in numerical format. The default display translates addresses into host names. This option is only valid with −p set. When using −gp, this option is recommended since packets are processed faster.
−s Shorten data display. This option displays only the first 16 and last 8 bytes of the data field of each packet. It is useful for examining protocol headers without all the data. This option is only valid with the −p (print) option.
−a Turn on promiscuous mode tracing if supported by the interface. This allows the capture of all packets on a medium.
−f diskfile
Specify a diskfile for capture or display. The default filename is netif.data.
−i count
Capture count packets and quit. This option is only valid with −g (get packets). The default action is to capture until killed.
−d ifcontrol device
Specify the interface control device to be used for tracing. The default device is /dev/m376_c0.
−C Verify IP, TCP and UDP checksums. If the checksum field of any of the above headers is non-zero, the Internet checksum algorithm is applied to the appropriate portion of the packet. If the result is not 0xffff, it is printed within [] brackets next to the checksum value contained in the header.
−I Ignore IP length field, and print out any padded data passed up from the driver.
-D num
Set debug bits to print internal information.
−F filterDescFile
Specify a filter description file (the default is /etc/filter_desc).
ifname
Used as a shorthand for specifying the tracing device name. It is the interface name as displayed by netstat -i, or that returned by the SIOCGIFCONF ioctl(2). ifname is converted internally to a device name. The default interface is m3760 which corresponds to device /dev/m376_c0.
filterDesc and value pairs are used to select packets based on given values at specified offsets into a packet. A filter description consists of:
type (S) compare with the physical source address in the DL_UNITDATA_IND, (D) compare with the physical destination address in the DL_UNITDATA_IND or (P) compare with packet data, starting after the physical header (.e.g the IP header).
offset the offset of the bytes to compare
length the length of the bytes to compare (max 16)
mask the bits of the specified bytes to compare, specified in hex.
The format of the filter descriptions is type:offset:length:mask.
When specifying filterDesc and value pairs on the command line, the filter description can be the name of a description from the filterDescFile or an actual description. The value to match against the filter description is specified as follows. A value less than or equal to four bytes in length can be specified in hex (0x), octal (0) or decimal. Four bytes can be specified in internet dot notation (e.g. 127.0, 144.191.15.1). More than four bytes must be specified in hex.
The filter description file (filterDescFile) is made up of lines containing a name and a filter description separated by white space. Comments start with the comment character #, and go until the end of the line.
Filtering is done by a STREAMS module, trcmod, during packet capture and does not work if the module is not configured in the kernel (this includes the -b, -t and -r options). While printing a capture file, the filter description and value pairs are the only form of filtering that work. Also, packet sequence numbers are assigned by the trace module. A gap in the sequence number is an indication of packets filtered or packets lost because of an allocation error. Other packets can be lost during heavy tracing activity and STREAMS flow control conditions. These are usually indicated by the driver statistics since trcmod does not participate in flow control (because it has no read service procedure).
If the −g option is used, the tracing device is selected as follows:
1. The device specified by the −d option
2. The control device in the /dev directory corresponding to ifname
3. If ifname is not specified, the first nonloopback interface configured on the system (as shown by netstat(1M)).
4. The default interface, m3760.
The argument diskfile allows an alternate file for netif.data. The interface control device is restricted to use by the super-user. The interface driver must support the ioctl(2) requests required for tracing.
nettrace is a tool to allow the tracing of packets at the interface level. By default, it does not capture packets from the media that are not addressed to the interface. The normal method for capture is to use the −g option to capture into a file and then use the −p option to display the captured packets. This allows for the fastest capture with a minimum of lost packets.
If fast capture is not required, the −g and −p options may be combined to display packets as they are captured.
NOTES
nettrace now has a different output file format. An older copy called onettrace is available to print older style capture files. The old version cannot capture packets.
nettrace no longer works on the loopback driver, lo0, because there is no loopback driver (really).
SEE ALSO
BUGS
The packets captured are only those received/transmitted at the interface. It is not possible to use nettrace as a media monitor unless promiscuous mode is supported and enabled on the interface.
nettrace is sensitive to keyboard interrupts, even if run in background (with ’&’). This is a mixed blessing.
— TCP/IP