Documentation/netsniff-ng.txt

   1 netsniff-ng(8)
   2 ==============
   3
   4 NAME
   5 ----
   6 netsniff-ng - the packet sniffing beast
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'netsniff-ng' [-d netdev] [-p pcap-file] [-r pcap-file] [-i pcap-file]
  12             [-f bpf-file] [-t pkt-type] [-b cpu-range] [-B cpu-range]
  13             [-S ring-size] [-e regex] [-IMHQnsqlxCXNvh]
  14
  15 DESCRIPTION
  16 -----------
  17 netsniff-ng is is a free (GPL), performant Linux network sniffer for
  18 packet inspection.
  19
  20 The gain of performance is reached by 'zero-copy' mechanisms, so that
  21 the kernel does not need to copy packets from kernelspace to userspace.
  22
  23 For this purpose netsniff-ng is libpcap independent, but nevertheless
  24 supports the pcap file format for capturing, replaying and performing
  25 offline-analysis of pcap dumps. Furthermore we are focussing on building
  26 a robust, clean and secure analyzer and utilities that complete
  27 netsniff-ng as a support for penetration testing.
  28
  29 netsniff-ng can be used for protocol analysis, reverse engineering and network
  30 debugging.
  31
  32 OPTIONS
  33 -------
  34 -d <netdev>::
  35 --dev <netdev>::
  36         <netdev> defines the packet capturing device. This can for instance
  37         be a typical device like eth0 or wlan0. Running netsniff-ng without
  38         a given device parameter, it looks for up and running networking
  39         devices and selects the first device that has been found.
  40
  41 -p <pcap-file>::
  42 --dump <pcap-file>::
  43         netsniff-ng stores the captured packets into the given <pcap-file>.
  44         It understands the PCAP specification, so that dumps can be read or
  45         postprocessed with other tools, too. Usually, this option should be
  46         combined with --silent and --bind-cpu to win some performance.
  47
  48 -r <pcap-file>::
  49 --replay <pcap-file>::
  50         The given <pcap-file> will be replayed via a memory mapped kernelspace
  51         TX_RING. A BPF filter may be combined to only replay parts of the PCAP
  52         formatted file.
  53
  54 -i <pcap-file>::
  55 --read <pcap-file>::
  56         <pcap-file> will be read in and printed to the console in order to
  57         perform an offline analysis. Same here: a BPF may be combined to only
  58         show relevant parts of the PCAP formatted file. Next to this, packet
  59         printing that are enabled on the normal mode are supported, too.
  60
  61 -f <bpf-file>::
  62 --filter <bpf-file>::
  63         Attaches a Berkeley Packet Filter to the socket in order to pre-filter
  64         traffic within the kernel. Example files are given within
  65         /etc/netsniff-ng/rules/. The section 'BERKELEY PACKET FILTER' describes
  66         how to write filter files.
  67
  68 -t <pkt-type>::
  69 --type <pkt-type>::
  70         A <pkt-type> specification allows to post-filter packets within userspace
  71         context (therefore slower than BPF). The following types are supported:
  72         host - only show incoming packets to our host,
  73         broadcast - only show Broadcast packets,
  74         multicast - only show Multicast packets,
  75         others - only show packets from other hosts (promiscuous mode),
  76         outgoing - only show outgoing packets from our host
  77
  78 -b <cpu-range>::
  79 --bind-cpu <cpu-range>::
  80         Force system scheduler to schedule netsniff-ng only on specific CPUs.
  81         Parameters may be '0' for using only CPU0, '0,1' for using CPU0 and
  82         CPU1 or even '0-4' for using a whole CPU range. If you have a customized
  83         init process that leaves out a special CPU you could bind netsniff-ng
  84         on that free CPU for maximal performance. On the other hand, you can
  85         avoid scheduling netsniff-ng on CPUs which are reserved for other
  86         critical tasks. This can also be combined with taskset(1) in order to
  87         reschedule other processes on other CPUs to let netsniff-ng run on its
  88         own CPU.
  89
  90 -B <cpu-range>::
  91 --unbind-cpu <cpu-range>::
  92         Force system scheduler to not schedule netsniff-ng on specific CPUs.
  93         The parameter syntax is equivalent to -b and also the semantics are
  94         inverted to -b.
  95
  96 -S <ring-size>::
  97 --ring-size <size>::
  98         This manually sets the desired ring size for RX_RING or TX_RING. You
  99         should only use this option, if you know what you are doing, because
 100         choosing a ring size which is too large for your system, the kernel
 101         does neither warn you nor throws an error. It simply kills other
 102         processes to grab their space. The parameter can be defined in KB,
 103         MB or GB as '10MB' for a 10 Megabyte ring size.
 104
 105 -I::
 106 --info::
 107         Shows information about available networking devices.
 108
 109 -M::
 110 --no-promisc::
 111         Forbids the NIC to enter the promiscuous mode. The promiscuous mode is
 112         activated by default. It is a configuration of a network card that makes
 113         the card pass all traffic it receives to the central processing unit
 114         rather than just frames addressed to it. Well, do not ask yourself why
 115         you cannot see traffic by others within a switched network. Unlike old
 116         hubs, switches are some kind of intelligent devices with internal ARP
 117         tables for each port in order to reduce traffic load and prevent
 118         sniffing other connections. If you really intent to sniff others traffic,
 119         go read about ARP cache poisoning / MITM.
 120
 121 -H::
 122 --prio-norm::
 123         This option prevents to automatically high priorize itself. Normally,
 124         netsniff-ng will be scheduled with high priority thus it use the
 125         full CPU timeslice.
 126
 127 -Q::
 128 --notouch-irq::
 129         If netsniff-ng will be bound to a single CPU, say CPU0, then it
 130         automatically rebinds the NIC interrupt affinity to that CPU, too for
 131         a better performance. This feature is intended to be enabled on
 132         non-wireless interfaces. notouch-irq forbids netsniff-ng to move the
 133         IRQ affinity.
 134
 135 -n::
 136 --non-block::
 137         Lets netsniff-ng run in non-blocking mode. Generally, you won't need
 138         this feature very often unless there is some interest in performance
 139         behaviour analysis. This will bypass the ring polling mechanism thus
 140         CPU load will most certainly rise to 100 percent.
 141
 142 -s::
 143 --silent::
 144         Does not print packets to the terminal.
 145
 146 -q::
 147 --less::
 148         Prints one-liner information summary per packet.
 149
 150 -l::
 151 --payload::
 152         Shows only the payload information of the packet.
 153
 154 -x::
 155 --payload-hex::
 156         Shows only the payload information of the packet in hexadecimal format.
 157
 158 -C::
 159 --c-style::
 160         Instead of printing packet in usual hex format, a copy-and-paste C like
 161         format will be printed to the terminal.
 162
 163 -X::
 164 --all-hex::
 165         Shows not only the payload in hexadecimal format, but the whole packet.
 166
 167 -N::
 168 --no-payload::
 169         Shows only the packet header, not the payload.
 170
 171 -e <regex>::
 172 --regex <expr>::
 173         Regular expression printing is useful for grepping ASCII text out of
 174         packets, say certain HTML code for instance. Beware, that this has a
 175         impact on performance. Regular expressions that comply with the POSIX
 176         extended regular expression format are allowed.
 177
 178 -v::
 179 --version::
 180         Shows version number and exits.
 181
 182 -h::
 183 --help::
 184         Shows help and exits.
 185
 186 BERKELEY PACKET FILTER
 187 ----------------------
 188 The Berkeley Packet Filter or BSD Packet Filter was first introduced in 1993
 189 by Steven McCanne and Van Jacobson at the USENIX. Its purpose is to filter
 190 packets within the kernel as early as possible, so that only the relevant
 191 packets will be brought to the user-level process.
 192
 193 The Linux kernel has adapted this feature, which nowadays is available in
 194 PF_PACKET. BPF therefore uses a register-based filter-machine that is
 195 efficient on todays RISCs. Since most applications of a packet filter reject
 196 far more packets than they accept and, thus, good performance of the packet
 197 filter is critical to good overall performance [1]. This should also be kept
 198 in mind during development of filters.
 199
 200 If you don't want to write your own filters, we currently ship some examples
 201 within /etc/netsniff-ng/rules/ that can be used with netsniff-ngs -f option.
 202 Furthermore 'tcpdump -dd' provides filter creation that netsniff-ng can read,
 203 but be warned - most certainly you might need to edit the return value, which
 204 defines the packet snaplen for your needs. Read section NOTES for more
 205 information about this. In future versions netsniff-ng will also ship its own
 206 filter compiler for a simple usage.
 207
 208 If you are an advanced user and if you would like to have full control of what
 209 should be filtered and what not, then writing your own filter could be a suitable
 210 choice. Hence, in the following the language specification will be described
 211 in short with given examples on how to use it.
 212
 213 The BPF pseudo-machine consists of an accumulator, an index register (X), a
 214 scratch memory store and an implicit program counter. Operations on this machine
 215 can be categorized into (all the following refering to [1]):
 216
 217 1. 'Load instructions:'
 218 Load instructions copy a value into the accumulator or index register. The
 219 source can be an immediate value, packet data at a fixed offset, packet data
 220 at a variable offset, the packet length, or the scratch memory store.
 221
 222 2. 'Store instructions:'
 223 Store instructions copy either the accumulator or index register into the
 224 scratch memory store.
 225
 226 3. 'ALU instructions:'
 227 ALU instructions perform arithmetic or logic on the accumulator using the index
 228 register or a constant as an operand.
 229
 230 4. 'Branch instructions:'
 231 Branch instructions alter the flow of control, based on comparison test between
 232 a constant or x register and the accumulator.
 233
 234 5. 'Return instructions:'
 235 Return instructions terminate the filter and indicated what portion of the packet
 236 to save. The packet is discarded entirely if the filter returns 0.
 237
 238 6. 'Misc instructions:'
 239 Misc instructions comprise everything else - currently, register transfer
 240 instructions.
 241
 242 The instruction format is of fixed length that is defined as the following:
 243
 244  +-----------+------+------+------+
 245  | opcode:16 | jt:8 | jf:8 | k:32 |
 246  +-----------+------+------+------+
 247
 248 The opcode field indicates the instruction type and addressing modes. The jt
 249 and jf fields are used by the conditional jump instructions and are the offsets
 250 from the next instruction to the true and false targets. The K field is a generic
 251 field used for various purposes.
 252
 253 All values are 32 bit words.
 254
 255 The Linux kernel has adapted this within linux/filter.h:
 256
 257 .................
 258 struct sock_filter {    /* Filter block */
 259         __u16   code;   /* Actual filter code */
 260         __u8    jt;     /* Jump true */
 261         __u8    jf;     /* Jump false */
 262         __u32   k;      /* Generic multiuse field */
 263 };
 264
 265 struct sock_fprog {                        /* Required for SO_ATTACH_FILTER. */
 266         unsigned short             len;    /* Number of filter blocks */
 267         struct sock_filter __user *filter;
 268 };
 269 .................
 270
 271 The instruction set is similar to assembler syntax. There are several instruction
 272 classes which are similar to the previous categorization:
 273
 274 .................
 275  LD    0x00  Copy indicated value into accumulator
 276  LDX   0x01  Copy indicated value into index register
 277  ST    0x02  Copy accumulator value into the scratch memory store
 278  STX   0x03  Copy index register value into the scratch memory store
 279  ALU   0x04  Perform arithmetic or logic operation on the accumulator
 280  JMP   0x05  Perform a branch instruction
 281  RET   0x06  Return/exit from filter program
 282  MISC  0x07  Data transfer between index register and accumulator
 283 .................
 284
 285 Next to classes, there are class-specific fields which are usually combined with
 286 bitwise OR:
 287
 288 LD/LDX specific fields:
 289 .................
 290  Size:
 291   W    0x00  Unsigned Word (32 Bit)
 292   H    0x08  Unsigned Halfword (16 Bit)
 293   B    0x10  Unsigned Byte
 294 .................
 295
 296 .................
 297  Mode:
 298   IMM  0x00  Literal value stored in K
 299   ABS  0x20  Byte, halfword or word at offset K in the packet
 300   IND  0x40  Byte, halfword or word at offset X + K in the packet
 301   MEM  0x60  Word at offset K in the scratch memory store
 302   LEN  0x80  Length of the packet
 303   MSH  0xa0  4*([K]&0xf): four times the value of the low four bits
 304              of the byte at offset K in the packet
 305 .................
 306
 307 ALU/JMP operations perform the indicated operation using the accumulator and
 308 operand, and store the result back into the accumulator. Division by zero
 309 terminates the filter.
 310
 311 ALU/JMP specific fields:
 312 .................
 313  Operation:
 314   ADD  0x00  Addition
 315   SUB  0x10  Subtraction
 316   MUL  0x20  Multiplication
 317   DIV  0x30  Division
 318
 319   OR   0x40  Bitwise OR
 320   AND  0x50  Bitwise AND
 321   LSH  0x60  Left Shift
 322   RSH  0x70  Right Shift
 323   NEG  0x80  Negation
 324
 325   (Jump, to an offset by the current instruction + JT/JF + 1)
 326
 327   JA   0x00  Jump to the current instruction + K + 1
 328   JEQ  0x10  Jump if K or X equals accumulator
 329   JGT  0x20  Jump if K or X is greater than accumulator
 330   JGE  0x30  Jump if K or X is greater or equals the accumulator
 331   JSET 0x40  Jump if K or X bitwise AND the accumulator > 0
 332 .................
 333
 334 .................
 335  Source:
 336   K    0x00  Value stored in K
 337   X    0x08  Value stored in the index register
 338 .................
 339
 340 RET specific fields:
 341 .................
 342  Return val:
 343   A    0x10  Value stored in the accumulator
 344   K    0x00  Value stored in K
 345   X    0x08  Value stored in the index register
 346 .................
 347
 348 The index register cannot use the packet addressing modes. Instead, a packet
 349 value must be loaded into the accumulator and transferred to the index
 350 register, via tax. This is not a common occurrence, as the index register is
 351 used primarily to parse the variable length IP header, which can be loaded
 352 directly via the 4*([k]&0xf) addressing mode.
 353
 354 MISC specific fields:
 355 .................
 356  Operation:
 357   TAX  0x00 Transfer value from accumulator into index register
 358   TXA  0x80 Transfer value from index register to accumulator
 359 .................
 360
 361 Example filter:
 362
 363 netsniff-ngs filter parser treats all lines that doesn't match a format of
 364 '{ 0xYY, X, X, 0xYYYYYYYY },' (X: decimal value, Y: hex value) as comments.
 365
 366 /etc/netsniff-ng/rules/arp.bpf:
 367
 368  1: { 0x28, 0, 0, 0x0000000c },
 369  2: { 0x15, 0, 1, 0x00000806 },
 370  3: { 0x06, 0, 0, 0xffffffff },
 371  4: { 0x06, 0, 0, 0x00000000 },
 372
 373 The first instruction line is a load instruction, because we have LD|H|ABS which
 374 results in 0x28. So the 16 Bit valued halfword at the packet offset 0xc will be
 375 copied into the accumulator. This is the Ethernet type field. Instruction line 2
 376 belongs to the class JMP, more specific JMP|JEQ and takes the value which is stored
 377 in K (0x806, the Ethernet type identifier for ARP). If 0x806 equals the value that
 378 has been loaded into the accumulator, the instruction pointer points to the current
 379 instruction plus jt value (which is 0) plus 1. So we end up at instruction line 3,
 380 which is the return opcode as RET|K. By using 0xffffffff as K, we tell the kernel
 381 that we would like to have a packet snaplen of 0xffffffff, which means that we end
 382 up with the complete ('uncut') packet. 0xffffffff will be replaced by the real packet
 383 length if the kernel detects packets less than a length of 0xffffffff. Well, on the
 384 other hand we would trap into the jf value if we don't have an ARP packet. There, the
 385 instruction pointer will point to line 4 where we tell the kernel to drop the packet.
 386 The length of 0 simply means: Do not hand over the packet to the BPF attached socket.
 387
 388 In pretty-print this filter looks like:
 389
 390  (000) ldh      [12]
 391  (001) jeq      #0x806           jt 2   jf 3
 392  (002) ret      #-1
 393  (003) ret      #0
 394
 395 Source: [1] http://www.tcpdump.org/papers/bpf-usenix93.pdf
 396
 397 BARE-METAL PERFORMANCE
 398 ----------------------
 399 This section will provide some figures about the performance of the RX_RING
 400 and TX_RING. An IBM HS21 Blade with 2 x Intel Xeon E5430 (2.66GHz), 8 GB RAM,
 401 Broadcom NetXtreme BCM5704S Gigabit Ethernet cards and a 2.6.31-14 kernel
 402 (Ubuntu Server 9.10) has been used for testing purpose. The IXIA 400 has been
 403 used on the opposite side for traffic generation (Gigabit wire speed).
 404 Date: 17 Sep 2010.
 405
 406 TX_RING, 1GbE:
 407
 408 The test was about flushing as much frames as possible of a fixed size. The
 409 IXIA was the counterpart that showed the incoming figures. Figures have been
 410 rounded to thousands.
 411
 412 .................
 413 Pkt size, TX_RING pps
 414    64     422,000
 415   128     422,000
 416   250     402,000
 417   500     239,000
 418   750     162,000
 419 1,000     122,000
 420 1,500      82,000
 421 .................
 422
 423 RX_RING, 1GbE:
 424
 425 The test included the reception of frames into the ring buffer, a counter
 426 increment per frame and the summation of the frame length. Figures have been
 427 rounded to thousands.
 428
 429 .................
 430 64-Byte fixed
 431 Pkt rate (IXIA), % of BW, RX_RING pps
 432   100,000          6.75   100,000
 433   175,000         11.76   175,000
 434   250,000         16.80   250,000
 435   500,000         33.60   338,000
 436 1,000,000         67.20   354,000
 437 1,488,000        100.00   303,000
 438 .................
 439
 440 .................
 441 250-Byte fixed
 442 Pkt rate (IXIA), % of BW, RX_RING pps
 443 100,000           21.60   100,000
 444 175,000           37.80   175,000
 445 250,000           54.00   244,000
 446 463,000          100.00   381,000
 447 .................
 448
 449 .................
 450 500-Byte fixed
 451 Pkt rate (IXIA), % of BW, RX_RING pps
 452 100,000           41.60   100,000
 453 175,000           72.80   169,000
 454 240,000          100.00   226,000
 455 .................
 456
 457 .................
 458 1,500-Byte fixed
 459 Pkt rate (IXIA), % of BW, RX_RING pps
 460 82,000           100.00   82,000
 461 .................
 462
 463 .................
 464 IMIX distribution (64:7, 570:4, 1518:1)
 465 Pkt rate (IXIA), % of BW, RX_RING pps
 466 100,000           29.99   100,000
 467 175,000           52.35   175,000
 468 250,000           74.80   240,000
 469 334,000          100.00   303,000
 470 .................
 471
 472 .................
 473 Tolly distribution (64:55, 78:5, 576:17, 1518:23)
 474 Pkt rate (IXIA), % of BW, RX_RING pps
 475 100,000           40.50   100,000
 476 175,000           70.90   174,000
 477 247,000          100.00   193,000
 478 .................
 479
 480 EXAMPLES
 481 --------
 482 Dump packets on eth0 into a file:
 483
 484   netsniff-ng --dev eth0 --dump out.pcap --silent --bind-cpu 0
 485
 486 Replay a PCAP file via eth0:
 487
 488   netsniff-ng --dev eth0 --replay out.pcap --bind-cpu 0
 489
 490 Only show ICQ related packets:
 491
 492   netsniff-ng --filter /etc/netsniff-ng/rules/icq.bpf
 493
 494 Show only packet headers of a PCAP file:
 495
 496   netsniff-ng --read out.pcap --no-payload
 497
 498 Show only packets that match a regular expression:
 499
 500   netsniff-ng --regex "foo.*bar"
 501
 502 Show only outgoing packets in hex format from wlan0:
 503
 504   netsniff-ng --dev wlan0 --all-hex --type outgoing
 505
 506 NOTES
 507 -----
 508 If you try to create custom socket filters with 'tcpdump -dd', you have
 509 to edit the 'ret' opcode of the resulting filter, otherwise your payload
 510 will be cut off:
 511
 512 0x6, 0, 0, 0xFFFFFFFF instead of 0x6, 0, 0, 0x00000060
 513
 514 The Linux kernel now takes skb->len instead of 0xFFFFFFFF. If you do not
 515 change it, the kernel will take 0x00000060 as buffer length and packets
 516 larger than 96 Byte will be cut off (filled with zero Bytes)!
 517
 518 Read http://dev.netsniff-ng.org/#4 for further technical details.
 519
 520 LICENSE
 521 -------
 522 This program is distributed under the terms of the GNU General Public
 523 License as published by the Free Software Foundation. See COPYING
 524 for details on the License and the lack of warranty.
 525
 526 AVAILABILITY
 527 ------------
 528 The latest version of this program can be found at
 529 http://pub.netsniff-ng.org/netsniff-ng/.
 530
 531 BUGS
 532 ----
 533 Bugs, what bugs? ;-)
 534 Okay, seriously ...
 535
 536 The TX_RING is part of the kernel since 2.6.31. Needs kind of a compatibility
 537 mode for older kernels.
 538
 539 Currently, we don't have a BPF compiler built-in, so that either the user needs
 540 to use filter definitions from /etc/netsniff-ng/rules, tcpdump -dd or write his
 541 own filter by hand.
 542
 543 Please send problems, bugs, questions, desirable enhancements, etc. to
 544 bugs@netsniff-ng.org.
 545
 546 GIT
 547 ---
 548 git clone git://repo.or.cz/netsniff-ng.git
 549
 550 AUTHOR
 551 ------
 552 netsniff-ng was originally written by Daniel Borkmann (daniel@netsniff-ng.org).
 553
 554 Current authors:
 555
 556 Daniel Borkmann (daniel@netsniff-ng.org),
 557 Emmanuel Roullit (emmanuel@netsniff-ng.org)
 558
 559 http://www.netsniff-ng.org/
 560
 561 The manpage has been written by Daniel Borkmann.
 562
 563 SEE ALSO
 564 --------
 565 bpf(4), pcap(3), tcpdump(8)
 566
 567 IN HONOREM
 568 ----------
 569 To my alma mater:
 570
 571 [verse]
 572 Leipzig University of Applied Science,
 573 Faculty of Computer Science, Mathematics and Natural Sciences
 574