ifpps.8

   1 .\" netsniff-ng - the packet sniffing beast
   2 .\" Copyright 2013 Daniel Borkmann.
   3 .\" Subject to the GPL, version 2.
   4 .TH IFPPS 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
   5 .SH NAME
   6 ifpps \- top-like networking and system statistics
   7 .PP
   8 .SH SYNOPSIS
   9 .PP
  10 \fBifpps\fR { [\fIoptions\fR] | [\fIdevice\fR] }
  11 .PP
  12 .SH DESCRIPTION
  13 .PP
  14 ifpps is a small utility which periodically provides top-like networking
  15 and system statistics from the kernel. ifpps gathers its data directly
  16 from procfs files and does not make use of any user space monitoring
  17 libraries which would falsify statistics under high load.
  18 .PP
  19 For instance, consider the following scenario: two directly connected
  20 Linux machines with Intel Core 2 Quad Q6600 2.40GHz CPUs, 4 GB RAM, and
  21 an Intel 82566DC-2 Gigabit Ethernet NIC are used for performance evaluation.
  22 One machine generates 64 byte network packets by using the kernel space
  23 packet generator pktgen with a maximum possible packet rate. The other
  24 machine displays statistics about incoming network packets by using i)
  25 .BR iptraf (8)
  26 and ii) ifpps.
  27 .PP
  28 iptraf which incorporates
  29 .BR pcap (3)
  30 shows an average packet rate of 246,000 pps while on the other hand ifpps shows
  31 an average packet rate of 1,378,000 pps. Hence, due to packet copies and
  32 deferring statistics creation into user space, a measurement error of
  33 approximately 460 percent occurs. Tools like iptraf might display much more
  34 information such as TCP per flow statistics (hence the use of the pcap library).
  35 This is not possible with ifpps, because overall networking statistics are its
  36 focus; statistics, which are also fairly reliable under high packet load.
  37 .PP
  38 ifpps also periodically displays CPU load, interrupt, software interrupt
  39 data per sample interval as well as total interrupts, all per CPU. In case
  40 the number of CPUs exceeds 5 or the number specified by the user with the
  41 \fB-n\fP command line option, ifpps will only display this number top
  42 heavy hitters. The topmost heavy hitter CPU will be marked with \[lq]+\[rq].
  43 The least heavy hitter will always be displayed and is marked with
  44 \[lq]-\[rq]. In addition, the average for all the above per-CPU data is
  45 shown. Optionally the median values can be displayed using the \fB-m\fP
  46 command line option.
  47 .PP
  48 ifpps also supports directly the
  49 .BR gnuplot (1)
  50 data sample format. This facilitates creation of gnuplot figures from ifpps time
  51 series.
  52 .PP
  53 .SH OPTIONS
  54 .TP
  55 .B -d <netdev>, --dev <netdev>
  56 Networking device to fetch statistics from, for example eth0, wlan0.
  57 .TP
  58 .B -n, --num-cpus
  59 Set maximum number of top hitter CPUs (in terms of time spent in system/user
  60 mode) to display in ncurses mode, default is 10.
  61 .TP
  62 .B -t <time>, --interval <time>
  63 Statistics refresh interval in milliseconds, default is 1000ms.
  64 .TP
  65 .B -c, --csv
  66 Output (once) the ncurses data to the terminal as
  67 .BR gnuplot (1)-ready
  68 data.
  69 .TP
  70 .B -l, --loop
  71 Continuously output the terminal data after a refresh interval. This option
  72 is only available if option \fB-c\fP is given. For \fB-l\fP it is
  73 usually recommended to redirect the output into a file that is to be processed
  74 later with
  75 .BR gnuplot (1).
  76 .TP
  77 .B -m, --median
  78 Show median values across all CPUs for CPU load, interrupts (per interval and
  79 absolute) and software interrupts.
  80 .TP
  81 .B -o, --omit-header
  82 Omit printing the CSV header. This option is only available if \fB-c\fP is given.
  83 .TP
  84 .B -p, --promisc
  85 Turn on promiscuous mode for the given networking device.
  86 .TP
  87 .B -P, --percentage
  88 Show percentage of current throughput in relation to theoretical line rate.
  89 .TP
  90 .B -W, --no-warn
  91 Suppress possible warnings in the ncurses output, e.g. about a too low sampling
  92 interval that could cause performance regression.
  93 .TP
  94 .B -v, --version
  95 Show version information.
  96 .TP
  97 .B -h, --help
  98 Show user help.
  99 .PP
 100 .SH USAGE EXAMPLE
 101 .TP
 102 .B ifpps eth0
 103 Default ncurses output for the eth0 device.
 104 .TP
 105 .B ifpps -pd eth0
 106 Ncurses output for the eth0 device in promiscuous mode.
 107 .TP
 108 .B ifpps -lpcd wlan0 > plot.dat
 109 Continuous terminal output for the wlan0 device in promiscuous mode.
 110 .PP
 111 .SH NOTE
 112 On 10Gbit/s cards or higher, receive and transmit statistics are usually
 113 accumulated at a higher duration interval than 1 second. Thus, it might
 114 be advisable to alter the timing to a higher accumulation interval for such cards.
 115 .PP
 116 .SH LEGAL
 117 ifpps is licensed under the GNU GPL version 2.0.
 118 .PP
 119 .SH HISTORY
 120 .B ifpps
 121 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
 122 is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
 123 Borkmann <dborkma@tik.ee.ethz.ch>.
 124 .PP
 125 .SH SEE ALSO
 126 .BR netsniff-ng (8),
 127 .BR trafgen (8),
 128 .BR mausezahn (8),
 129 .BR bpfc (8),
 130 .BR flowtop (8),
 131 .BR astraceroute (8),
 132 .BR curvetun (8)
 133 .PP
 134 .SH AUTHOR
 135 Manpage was written by Daniel Borkmann.
 136 .PP
 137 .SH COLOPHON
 138 This page is part of the Linux netsniff-ng toolkit project. A description of the project,
 139 and information about reporting bugs, can be found at http://netsniff-ng.org/.