Previous Contents Next

niftap: Network Interface Tap

niftap is the key application in the Network-I suite. It's the sniffer which actually snoops on the network interface and captures the network packets, writing them out to a binary log file on its standard output.
niftap can run either in the foreground or background, and will terminate on receipt of an interrupt (eg. hitting Control-C if in foreground) or a termination signal (SIGTERM).
You have to be root to run niftap, as it taps directly into the network interface, and reads network traffic.

niftap can run in the following two modes (which may be combined):

Capture packets to a binary log file, for subsequent analysis. The capture criteria is set by the filtering rules. The log file is platform-independent, eg. it can be created on one hardware platform, and later viewed on another incompatible architecture.
The log file also contains a trailer specifying the total stats for the session.
Create a frequency file, to measure traffic rates. This is a text file, updated every x seconds (where the x interval is specified at startup), to record the bytes/second and packets/second over the preceding interval, as well as the cumulative packet and byte totals.

All of these modes can make use of the filter rules to determine which packets are processed and which are completely ignored.

Command-line Syntax
Environment Variables
Frequency File
Solaris/Linux Differences
64-Bit Solaris Limitations

Command-Line Syntax

niftap	[-i interface] [-b SAP] [-v] [-p] [-c \| -t len] [-r filename[:frequency]] [-f\|-F filter] [shorthand filter-spec]
niftap	-h

-i	Interface name, eg. le0, eth0 etc. For Linux, the default is to listen on all interfaces. Note that in this case, none of the interfaces are put into promiscuous mode, and all the interfaces are assumed to have the same link layer framing as the first non-loopback one that is marked up. If any interface does not satisfy the latter condition, then filtering (see -f option) will not work on it. If these restrictions of the all-interfaces mode conflict with your requirements, then you would need to run a separate instance of Niftap on each interface you're interested in. For Solaris, the default is the first "up" non-loopback interface found. On either platform, if you do end up running simultaneous instances of Niftap on multiple interfaces, you can still merge the resulting logfiles using nifmerge, so as to view the packets along a single timeline (just as if you had run a single Niftap in all-interfaces mode).
-b	For Linux, this argument is the protocol to bind to, within the selected socket address family (which is semantically equivalent to a Solaris DLPI SAP). What this means, is an ethernet protocol ID as defined in the <linux/if_ether.h> header, and it defaults to all protocols (ie. ETH_P_ALL=3). However, the value needs to be in decimal format, not hexadecimal as represented in that file. For Solaris, this is the Data Link SAP (DLPI Service Access Point) to bind to: -1 (the default) is a wildcard spec (ie. all SAPs) 0 means 802.3 frames only >0 specifies a particular EtherType. Note that for both platforms, this argument can also be emulated within the filter expression, but using this argument yields better performance, as it instructs the network driver to drop non-matching frames for us.
-v	Verbose mode. Issues progress messages on standard error, including a packet counter. This obviously imposes a performance hit, and should ideally be used only when testing out a niftap command line, rather than when doing packet capture in anger.
-p	Disable promiscuous mode (ie. only capture data to/from this host) on the network interface. Default is to capture all packets on the network. If you're only interested in data to/from this host, then avoiding promiscuous mode can improve niftap performance, and reduce the load on the machine.
-c	Count-only mode, ie. measure traffic volumes, but don't capture any packets in the log file. The log file will merely record the overall traffic stats.
-t	Truncation, ie. captured packets are truncated to this length. Default is 600, unless count-only mode (-c switch) was specified. -t 0 means no truncation. Note that while -t0 is the only setting which allows checksums to be verified, it will also make niftap less efficient (lesser truncation equals greater volumes of packet data flowing through the system).
-r	Record traffic rates in the specified file (known as a frequency file). The frequency is the sampling interval, in seconds, and the default is every second. Note that -r alone does not disable packet capture, so if you are not interested in recording any packet contents, it should be combined with -c for maximum efficiency.
-f	Specify a filter-expression string.
-F	Specify the name of a file containing a filter expression, ie. the contents of this file should be equivalent to a -f string.
-h	Display a usage synopsis.
*shorthand filter-spec*	A quick notation for simple filters. Simpler to type in than the formal filter notation. Click here for details.

Environment Variables

NIF_KSDU: Overrides the default kernel buffer size (4 MB) into which packets are read, before being processed.
Increasing this buffer size should increase performance.
NIF_RAWLINK: y or n. Niftap normally sets raw mode (ie. capture the data-link protocol header, as well as the network layer above that) if at all possible, but setting this environment variable to N disables raw mode (if possible).
There is generally no benefit in disabling raw mode unless you have to, but it does enable niftap to work over datalink protocols which it doesn't understand (it currently only recognises Ethernet/802.3 and FDDI). In such situations, it would probably assume that the packets presented to it by the network driver begin with an LLC header.
NIF_TRCINFO also takes the values y or n, and turns on some extra trace-level verbosity.

Frequency File

This section gives a demonstration of how to run niftap for the sole purpose of creating a frequency file.
In this example, there is no filter (ie. all traffic is counted), and niftap was allowed to run for just over a minute, before being stopped. User input is shown in red, and output in green.

niftap -v -rall.frq:1 -c >/dev/null

Network-I Interface Tap, 1.3.0
Using interface 'nei0' (IP address = 192.168.68.1)
Interface put into promiscuous mode
Ready and waiting ...
   32^C
Terminating.

The file all.frq will now look as follows:

Niftap Frequency File
------------------------
File opened at Apr22 14:21:32.169819 by PID=22066 (interval=1)

Listening on interface ipdptp0 [158.152.30.68]
Promiscuous mode is on
Raw datalink capture mode is on
No packet filter in effect

Interval-End            Packets/Sec       Bytes/Sec      Total Packets
----------------------------------------------------------------------------
idle
Apr22 14:21:39              2.00             128               2
Apr22 14:21:40              2.00             128               4
Apr22 14:21:41              2.00             128               6
Apr22 14:21:42              2.00             128               8
Apr22 14:21:43              2.00             128              10
Apr22 14:21:44              2.00             128              12
Apr22 14:21:45              1.00              64              13
Apr22 14:21:46              3.00             192              16
Apr22 14:21:47              2.00             128              18
idle
Apr22 14:22:05              2.00             128              20
Apr22 14:22:06              2.00             128              22
Apr22 14:22:07              2.00             128              24
Apr22 14:22:08              2.00             128              26
Apr22 14:22:09              2.00             128              28
Apr22 14:22:10              2.00             128              30
Apr22 14:22:11              2.00             128              32
Apr22 14:22:12              2.00             128              34
Apr22 14:22:13              2.00             128              36

Terminating at Apr22 14:22:49.160856
	Total Bytes = 2304

Note that the totals (particularly bytes) may wrap around after a long session on a busy network, and they will then be invalid.

Shell scripts are provided to post-process the frequency file, sorting it by packet (nifsort-p) or byte (nifsort-b) frequencies.

Solaris/Linux Differences

The Linux version can listen on all interfaces simultaneously (including the loopback interface).
The Solaris version needs to bind to a specific interface, so the only way to monitor multiple interfaces simultaneously, is to to run a separate instance of niftap for each one (typically in the background, without the -v option). The nifmerge utility can subsequently be used to combine all the logfiles into one, for easier viewing. However, it cannot merge frequency files.

The Linux version can listen on the loopback interface, but the Solaris version cannot. Analysing the loopback interface might be helpful, when debugging some host problems.

64-Bit Solaris Limitations

The kernel filtering module employed by niftap is distributed as a 32-bit LKM (Loadable Kernel Module). Therefore, it will not work on Solaris 7+, if the OS is running in 64-bit kernel mode.

You will need to disable the kernel filtering on such systems, and you can do so by setting the environment variable NIF_KFILT=N. This will cause the packet filtering to be done in user space.
Note that this will make niftap considerably slower, and it will probably drop many more packets.

Previous Contents Next