| blob | 5334f81765988d088ba3c01419aa44dc91041f58 |
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
4 <head>
14 </style>
18 {
22 }
23 </script>
24 </head>
26 <body>
28 <blockquote>
30 <br>
31 <p>
33 <tr>
34 <td>
35 <a href="http://netsniff-ng.org"><img src="http://netsniff-ng.org/img/logo.png" border="0" alt="netsniff-ng"></a>
36 </td>
37 <td>
38 <br><br><br>
40 </td>
41 </tr>
42 </table>
43 </p>
44 <br>
46 <div xml:lang="en" class="refentry" title="netsniff-ng" lang="en"><a id="id3020635"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>netsniff-ng — the packet sniffing beast</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><span class="emphasis"><em>netsniff-ng</em></span> [-d netdev] [-p pcap-file] [-r pcap-file] [-i pcap-file]<br />
47 [-f bpf-file] [-t pkt-type] [-b cpu-range] [-B cpu-range]<br />
48 [-S ring-size] [-e regex] [-IMHQnsqlxCXNvh]</p></div></blockquote></div></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>netsniff-ng is is a free (GPL), performant Linux network sniffer for
49 packet inspection.</p><p>The gain of performance is reached by <span class="emphasis"><em>zero-copy</em></span> mechanisms, so that
50 the kernel does not need to copy packets from kernelspace to userspace.</p><p>For this purpose netsniff-ng is libpcap independent, but nevertheless
51 supports the pcap file format for capturing, replaying and performing
52 offline-analysis of pcap dumps. Furthermore we are focussing on building
53 a robust, clean and secure analyzer and utilities that complete
54 netsniff-ng as a support for penetration testing.</p><p>netsniff-ng can be used for protocol analysis, reverse engineering and network
55 debugging.</p></div><div class="refsect1" title="OPTIONS"><a id="_options"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">
59 </span></dt><dd>
61 be a typical device like eth0 or wlan0. Running netsniff-ng without
62 a given device parameter, it looks for up and running networking
63 devices and selects the first device that has been found.
68 </span></dt><dd>
70 It understands the PCAP specification, so that dumps can be read or
71 postprocessed with other tools, too. Usually, this option should be
72 combined with --silent and --bind-cpu to win some performance.
77 </span></dt><dd>
79 TX_RING. A BPF filter may be combined to only replay parts of the PCAP
80 formatted file.
85 </span></dt><dd>
87 perform an offline analysis. Same here: a BPF may be combined to only
88 show relevant parts of the PCAP formatted file. Next to this, packet
89 printing that are enabled on the normal mode are supported, too.
94 </span></dt><dd>
95 Attaches a Berkeley Packet Filter to the socket in order to pre-filter
96 traffic within the kernel. Example files are given within
97 /etc/netsniff-ng/rules/. The section <span class="emphasis"><em>BERKELEY PACKET FILTER</em></span> describes
98 how to write filter files.
103 </span></dt><dd>
105 context (therefore slower than BPF). The following types are supported:
106 host - only show incoming packets to our host,
107 broadcast - only show Broadcast packets,
108 multicast - only show Multicast packets,
109 others - only show packets from other hosts (promiscuous mode),
110 outgoing - only show outgoing packets from our host
115 </span></dt><dd>
116 Force system scheduler to schedule netsniff-ng only on specific CPUs.
117 Parameters may be <span class="emphasis"><em>0</em></span> for using only CPU0, <span class="emphasis"><em>0,1</em></span> for using CPU0 and
118 CPU1 or even <span class="emphasis"><em>0-4</em></span> for using a whole CPU range. If you have a customized
119 init process that leaves out a special CPU you could bind netsniff-ng
120 on that free CPU for maximal performance. On the other hand, you can
121 avoid scheduling netsniff-ng on CPUs which are reserved for other
122 critical tasks. This can also be combined with taskset(1) in order to
123 reschedule other processes on other CPUs to let netsniff-ng run on its
124 own CPU.
129 </span></dt><dd>
130 Force system scheduler to not schedule netsniff-ng on specific CPUs.
131 The parameter syntax is equivalent to -b and also the semantics are
132 inverted to -b.
137 </span></dt><dd>
138 This manually sets the desired ring size for RX_RING or TX_RING. You
139 should only use this option, if you know what you are doing, because
140 choosing a ring size which is too large for your system, the kernel
141 does neither warn you nor throws an error. It simply kills other
142 processes to grab their space. The parameter can be defined in KB,
145 -I
147 --info
148 </span></dt><dd>
149 Shows information about available networking devices.
151 -M
153 --no-promisc
154 </span></dt><dd>
155 Forbids the NIC to enter the promiscuous mode. The promiscuous mode is
156 activated by default. It is a configuration of a network card that makes
157 the card pass all traffic it receives to the central processing unit
158 rather than just frames addressed to it. Well, do not ask yourself why
159 you cannot see traffic by others within a switched network. Unlike old
160 hubs, switches are some kind of intelligent devices with internal ARP
161 tables for each port in order to reduce traffic load and prevent
162 sniffing other connections. If you really intent to sniff others traffic,
163 go read about ARP cache poisoning / MITM.
165 -H
167 --prio-norm
168 </span></dt><dd>
169 This option prevents to automatically high priorize itself. Normally,
170 netsniff-ng will be scheduled with high priority thus it use the
171 full CPU timeslice.
173 -Q
175 --notouch-irq
176 </span></dt><dd>
177 If netsniff-ng will be bound to a single CPU, say CPU0, then it
178 automatically rebinds the NIC interrupt affinity to that CPU, too for
179 a better performance. This feature is intended to be enabled on
180 non-wireless interfaces. notouch-irq forbids netsniff-ng to move the
181 IRQ affinity.
183 -n
185 --non-block
186 </span></dt><dd>
187 Lets netsniff-ng run in non-blocking mode. Generally, you won’t need
188 this feature very often unless there is some interest in performance
189 behaviour analysis. This will bypass the ring polling mechanism thus
190 CPU load will most certainly rise to 100 percent.
192 -s
194 --silent
195 </span></dt><dd>
196 Does not print packets to the terminal.
198 -q
200 --less
201 </span></dt><dd>
202 Prints one-liner information summary per packet.
204 -l
206 --payload
207 </span></dt><dd>
208 Shows only the payload information of the packet.
210 -x
212 --payload-hex
213 </span></dt><dd>
214 Shows only the payload information of the packet in hexadecimal format.
216 -C
218 --c-style
219 </span></dt><dd>
220 Instead of printing packet in usual hex format, a copy-and-paste C like
221 format will be printed to the terminal.
223 -X
225 --all-hex
226 </span></dt><dd>
227 Shows not only the payload in hexadecimal format, but the whole packet.
229 -N
231 --no-payload
232 </span></dt><dd>
233 Shows only the packet header, not the payload.
238 </span></dt><dd>
239 Regular expression printing is useful for grepping ASCII text out of
240 packets, say certain HTML code for instance. Beware, that this has a
241 impact on performance. Regular expressions that comply with the POSIX
242 extended regular expression format are allowed.
244 -v
246 --version
247 </span></dt><dd>
248 Shows version number and exits.
250 -h
252 --help
253 </span></dt><dd>
254 Shows help and exits.
255 </dd></dl></div></div><div class="refsect1" title="BERKELEY PACKET FILTER"><a id="_berkeley_packet_filter"></a><h2>BERKELEY PACKET FILTER</h2><p>The Berkeley Packet Filter or BSD Packet Filter was first introduced in 1993
256 by Steven McCanne and Van Jacobson at the USENIX. Its purpose is to filter
257 packets within the kernel as early as possible, so that only the relevant
258 packets will be brought to the user-level process.</p><p>The Linux kernel has adapted this feature, which nowadays is available in
259 PF_PACKET. BPF therefore uses a register-based filter-machine that is
260 efficient on todays RISCs. Since most applications of a packet filter reject
261 far more packets than they accept and, thus, good performance of the packet
262 filter is critical to good overall performance [1]. This should also be kept
263 in mind during development of filters.</p><p>If you don’t want to write your own filters, we currently ship some examples
264 within /etc/netsniff-ng/rules/ that can be used with netsniff-ngs -f option.
265 Furthermore <span class="emphasis"><em>tcpdump -dd</em></span> provides filter creation that netsniff-ng can read,
266 but be warned - most certainly you might need to edit the return value, which
267 defines the packet snaplen for your needs. Read section NOTES for more
268 information about this. In future versions netsniff-ng will also ship its own
269 filter compiler for a simple usage.</p><p>If you are an advanced user and if you would like to have full control of what
270 should be filtered and what not, then writing your own filter could be a suitable
271 choice. Hence, in the following the language specification will be described
272 in short with given examples on how to use it.</p><p>The BPF pseudo-machine consists of an accumulator, an index register (X), a
273 scratch memory store and an implicit program counter. Operations on this machine
274 can be categorized into (all the following refering to [1]):</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
276 Load instructions copy a value into the accumulator or index register. The
277 source can be an immediate value, packet data at a fixed offset, packet data
278 at a variable offset, the packet length, or the scratch memory store.
281 Store instructions copy either the accumulator or index register into the
282 scratch memory store.
285 ALU instructions perform arithmetic or logic on the accumulator using the index
286 register or a constant as an operand.
289 Branch instructions alter the flow of control, based on comparison test between
290 a constant or x register and the accumulator.
293 Return instructions terminate the filter and indicated what portion of the packet
294 to save. The packet is discarded entirely if the filter returns 0.
297 Misc instructions comprise everything else - currently, register transfer
298 instructions.
299 </li></ol></div><p>The instruction format is of fixed length that is defined as the following:</p><pre class="literallayout">+-----------+------+------+------+
301 +-----------+------+------+------+</pre><p>The opcode field indicates the instruction type and addressing modes. The jt
302 and jf fields are used by the conditional jump instructions and are the offsets
303 from the next instruction to the true and false targets. The K field is a generic
304 field used for various purposes.</p><p>All values are 32 bit words.</p><p>The Linux kernel has adapted this within linux/filter.h:</p><pre class="literallayout">struct sock_filter { /* Filter block */
305 __u16 code; /* Actual filter code */
306 __u8 jt; /* Jump true */
307 __u8 jf; /* Jump false */
308 __u32 k; /* Generic multiuse field */
309 };
311 struct sock_fprog { /* Required for SO_ATTACH_FILTER. */
312 unsigned short len; /* Number of filter blocks */
313 struct sock_filter __user *filter;
314 };</pre><p>The instruction set is similar to assembler syntax. There are several instruction
315 classes which are similar to the previous categorization:</p><pre class="literallayout"> LD 0x00 Copy indicated value into accumulator
316 LDX 0x01 Copy indicated value into index register
317 ST 0x02 Copy accumulator value into the scratch memory store
318 STX 0x03 Copy index register value into the scratch memory store
319 ALU 0x04 Perform arithmetic or logic operation on the accumulator
320 JMP 0x05 Perform a branch instruction
321 RET 0x06 Return/exit from filter program
322 MISC 0x07 Data transfer between index register and accumulator</pre><p>Next to classes, there are class-specific fields which are usually combined with
327 IMM 0x00 Literal value stored in K
328 ABS 0x20 Byte, halfword or word at offset K in the packet
329 IND 0x40 Byte, halfword or word at offset X + K in the packet
330 MEM 0x60 Word at offset K in the scratch memory store
331 LEN 0x80 Length of the packet
333 of the byte at offset K in the packet</pre><p>ALU/JMP operations perform the indicated operation using the accumulator and
334 operand, and store the result back into the accumulator. Division by zero
336 ADD 0x00 Addition
337 SUB 0x10 Subtraction
338 MUL 0x20 Multiplication
339 DIV 0x30 Division
341 OR 0x40 Bitwise OR
342 AND 0x50 Bitwise AND
343 LSH 0x60 Left Shift
344 RSH 0x70 Right Shift
345 NEG 0x80 Negation
347 (Jump, to an offset by the current instruction + JT/JF + 1)
350 JEQ 0x10 Jump if K or X equals accumulator
351 JGT 0x20 Jump if K or X is greater than accumulator
352 JGE 0x30 Jump if K or X is greater or equals the accumulator
353 JSET 0x40 Jump if K or X bitwise AND the accumulator > 0</pre><pre class="literallayout"> Source:
354 K 0x00 Value stored in K
355 X 0x08 Value stored in the index register</pre><p>RET specific fields:</p><pre class="literallayout"> Return val:
356 A 0x10 Value stored in the accumulator
357 K 0x00 Value stored in K
358 X 0x08 Value stored in the index register</pre><p>The index register cannot use the packet addressing modes. Instead, a packet
359 value must be loaded into the accumulator and transferred to the index
360 register, via tax. This is not a common occurrence, as the index register is
361 used primarily to parse the variable length IP header, which can be loaded
362 directly via the 4*([k]&0xf) addressing mode.</p><p>MISC specific fields:</p><pre class="literallayout"> Operation:
363 TAX 0x00 Transfer value from accumulator into index register
364 TXA 0x80 Transfer value from index register to accumulator</pre><p>Example filter:</p><p>netsniff-ngs filter parser treats all lines that doesn’t match a format of
365 <span class="emphasis"><em>{ 0xYY, X, X, 0xYYYYYYYY },</em></span> (X: decimal value, Y: hex value) as comments.</p><p>/etc/netsniff-ng/rules/arp.bpf:</p><pre class="literallayout">1: { 0x28, 0, 0, 0x0000000c },
368 4: { 0x06, 0, 0, 0x00000000 },</pre><p>The first instruction line is a load instruction, because we have LD|H|ABS which
370 copied into the accumulator. This is the Ethernet type field. Instruction line 2
371 belongs to the class JMP, more specific JMP|JEQ and takes the value which is stored
373 has been loaded into the accumulator, the instruction pointer points to the current
375 which is the return opcode as RET|K. By using 0xffffffff as K, we tell the kernel
376 that we would like to have a packet snaplen of 0xffffffff, which means that we end
377 up with the complete (<span class="emphasis"><em>uncut</em></span>) packet. 0xffffffff will be replaced by the real packet
378 length if the kernel detects packets less than a length of 0xffffffff. Well, on the
379 other hand we would trap into the jf value if we don’t have an ARP packet. There, the
380 instruction pointer will point to line 4 where we tell the kernel to drop the packet.
381 The length of 0 simply means: Do not hand over the packet to the BPF attached socket.</p><p>In pretty-print this filter looks like:</p><pre class="literallayout">(000) ldh [12]
384 (003) ret #0</pre><p>Source: [1] <a class="ulink" href="http://www.tcpdump.org/papers/bpf-usenix93.pdf" target="_top">http://www.tcpdump.org/papers/bpf-usenix93.pdf</a></p></div><div class="refsect1" title="BARE-METAL PERFORMANCE"><a id="_bare_metal_performance"></a><h2>BARE-METAL PERFORMANCE</h2><p>This section will provide some figures about the performance of the RX_RING
388 used on the opposite side for traffic generation (Gigabit wire speed).
389 Date: 17 Sep 2010.</p><p>TX_RING, 1GbE:</p><p>The test was about flushing as much frames as possible of a fixed size. The
390 IXIA was the counterpart that showed the incoming figures. Figures have been
398 1,500 82,000</pre><p>RX_RING, 1GbE:</p><p>The test included the reception of frames into the ring buffer, a counter
399 increment per frame and the summation of the frame length. Figures have been
401 Pkt rate (IXIA), % of BW, RX_RING pps
408 Pkt rate (IXIA), % of BW, RX_RING pps
413 Pkt rate (IXIA), % of BW, RX_RING pps
417 Pkt rate (IXIA), % of BW, RX_RING pps
419 Pkt rate (IXIA), % of BW, RX_RING pps
423 334,000 100.00 303,000</pre><pre class="literallayout">Tolly distribution (64:55, 78:5, 576:17, 1518:23)
424 Pkt rate (IXIA), % of BW, RX_RING pps
427 247,000 100.00 193,000</pre></div><div class="refsect1" title="EXAMPLES"><a id="_examples"></a><h2>EXAMPLES</h2><p>Dump packets on eth0 into a file:</p><pre class="literallayout">netsniff-ng --dev eth0 --dump out.pcap --silent --bind-cpu 0</pre><p>Replay a PCAP file via eth0:</p><pre class="literallayout">netsniff-ng --dev eth0 --replay out.pcap --bind-cpu 0</pre><p>Only show ICQ related packets:</p><pre class="literallayout">netsniff-ng --filter /etc/netsniff-ng/rules/icq.bpf</pre><p>Show only packet headers of a PCAP file:</p><pre class="literallayout">netsniff-ng --read out.pcap --no-payload</pre><p>Show only packets that match a regular expression:</p><pre class="literallayout">netsniff-ng --regex "foo.*bar"</pre><p>Show only outgoing packets in hex format from wlan0:</p><pre class="literallayout">netsniff-ng --dev wlan0 --all-hex --type outgoing</pre></div><div class="refsect1" title="NOTES"><a id="_notes"></a><h2>NOTES</h2><p>If you try to create custom socket filters with <span class="emphasis"><em>tcpdump -dd</em></span>, you have
428 to edit the <span class="emphasis"><em>ret</em></span> opcode of the resulting filter, otherwise your payload
429 will be cut off:</p><p>0x6, 0, 0, 0xFFFFFFFF instead of 0x6, 0, 0, 0x00000060</p><p>The Linux kernel now takes skb→len instead of 0xFFFFFFFF. If you do not
430 change it, the kernel will take 0x00000060 as buffer length and packets
431 larger than 96 Byte will be cut off (filled with zero Bytes)!</p><p>Read <a class="ulink" href="http://dev.netsniff-ng.org/#4" target="_top">http://dev.netsniff-ng.org/#4</a> for further technical details.</p></div><div class="refsect1" title="LICENSE"><a id="_license"></a><h2>LICENSE</h2><p>This program is distributed under the terms of the GNU General Public
432 License as published by the Free Software Foundation. See COPYING
433 for details on the License and the lack of warranty.</p></div><div class="refsect1" title="AVAILABILITY"><a id="_availability"></a><h2>AVAILABILITY</h2><p>The latest version of this program can be found at
434 <a class="ulink" href="http://pub.netsniff-ng.org/netsniff-ng/" target="_top">http://pub.netsniff-ng.org/netsniff-ng/</a>.</p></div><div class="refsect1" title="BUGS"><a id="_bugs"></a><h2>BUGS</h2><p>Bugs, what bugs? ;-)
435 Okay, seriously …</p><p>The TX_RING is part of the kernel since 2.6.31. Needs kind of a compatibility
436 mode for older kernels.</p><p>Currently, we don’t have a BPF compiler built-in, so that either the user needs
437 to use filter definitions from /etc/netsniff-ng/rules, tcpdump -dd or write his
438 own filter by hand.</p><p>Please send problems, bugs, questions, desirable enhancements, etc. to
439 <a class="ulink" href="mailto:bugs@netsniff-ng.org" target="_top">bugs@netsniff-ng.org</a>.</p></div><div class="refsect1" title="GIT"><a id="_git"></a><h2>GIT</h2><p>git clone git://repo.or.cz/netsniff-ng.git</p></div><div class="refsect1" title="AUTHOR"><a id="_author"></a><h2>AUTHOR</h2><p>netsniff-ng was originally written by Daniel Borkmann (<a class="ulink" href="mailto:daniel@netsniff-ng.org" target="_top">daniel@netsniff-ng.org</a>).</p><p>Current authors:</p><p>Daniel Borkmann (<a class="ulink" href="mailto:daniel@netsniff-ng.org" target="_top">daniel@netsniff-ng.org</a>),
440 Emmanuel Roullit (<a class="ulink" href="mailto:emmanuel@netsniff-ng.org" target="_top">emmanuel@netsniff-ng.org</a>)</p><p><a class="ulink" href="http://www.netsniff-ng.org/" target="_top">http://www.netsniff-ng.org/</a></p><p>The manpage has been written by Daniel Borkmann.</p></div><div class="refsect1" title="SEE ALSO"><a id="_see_also"></a><h2>SEE ALSO</h2><p>bpf(4), pcap(3), tcpdump(8)</p></div><div class="refsect1" title="IN HONOREM"><a id="_in_honorem"></a><h2>IN HONOREM</h2><p>To my alma mater:</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p>Leipzig University of Applied Science,<br />
441 Faculty of Computer Science, Mathematics and Natural Sciences</p></div></blockquote></div></div></div>
442 <br>
444 <a href="http://www.debian.org/"><img src="http://netsniff-ng.org/img/debian.png" border="0" alt="powered by Debian"></a>
445 <a href="http://www.vim.org/"><img src="http://netsniff-ng.org/img/vim.png" border="0" alt="powered by vim"></a>
446 <a href="http://www.anybrowser.org/campaign/"><img src="http://netsniff-ng.org/img/vt100.gif" border="0" alt="best viewed with vt100"></a>
447 <a href="http://eupat.ffii.org/"><img src="http://netsniff-ng.org/img/no_epatent.png" border="0" alt="no epatents"></a>
448 <a href="http://www.laquadrature.net/"><img src="http://netsniff-ng.org/img/qdn.png" border="0" alt="qdn"></a>
450 <p>
451 <hr>
452 </p>
455 <tr>
456 <td>
463 </address>
464 </td>
465 </tr>
466 </table>
468 </blockquote>
469 </body>
471 </html>