all: import netsniff-ng 0.5.8-rc0 source

We decided to get rid of the old Git history and start a new one for
several reasons:

 *) Allow / enforce only high-quality commits (which was not the case
    for many commits in the history), have a policy that is more close
    to the one from the Linux kernel. With high quality commits, we
    mean code that is logically split into commits and commit messages
    that are signed-off and have a proper subject and message body.
    We do not allow automatic Github merges anymore, since they are
    total bullshit. However, we will either cherry-pick your patches
    or pull them manually.

 *) The old archive was about ~27MB for no particular good reason.
    This basically derived from the bad decision that also some PDF
    files where stored there. From this moment onwards, no binary
    objects are allowed to be stored in this repository anymore.

The old archive is not wiped away from the Internet. You will still
be able to find it, e.g. on git.cryptoism.org etc.

Signed-off-by: Daniel Borkmann <dborkman@redhat.com>
Signed-off-by: Tobias Klauser <tklauser@distanz.ch>

1 files changed, 97 insertions, 0 deletions

diff --git a/Documentation/KnownIssues b/Documentation/KnownIssues
new file mode 100644
index 0000000..eb17a3f
--- /dev/null
+++ b/Documentation/KnownIssues
@@ -0,0 +1,97 @@
+netsniff-ng's known issues:
+///////////////////////////
+
+Q: When I perform a traffic capture on the Ethernet interface, the PCAP file is
+   created and packets are received but without 802.1Q header. If I use
+   tshark, I get all headers but netsniff-ng removes 802.1Q headers. Is that
+   normal behavior?
+A: Yes and no. The way how VLAN headers are handled in PF_PACKET sockets by the
+   kernel is somewhat problematic [1]. The problem in the Linux kernel is that
+   some drivers already handle VLAN, others not. Those who handle it have
+   different implementations, i.e. hardware acceleration and so on. So in some
+   cases the VLAN tag is even stripped before entering the protocol stack, in
+   some cases probably not. Bottom line is that the netdev hackers introduced
+   a "hack" in PF_PACKET so that a VLAN ID is visible in some helper data
+   structure that is accessible from the RX_RING. And then it gets really messy
+   in the user space to artificially put the VLAN header back into the right
+   place. Not mentioning about the resulting performance implications on that
+   of /all/ libpcap tools since parts of the packet need to be copied for
+   reassembly. A user reported the following, just to demonstrate this mess:
+   Some tests were made with two machines, and it seems that results depends on
+   the driver ...
+
+    1) AR8131
+        * ethtool -k eth0 gives "rx-vlan-offload: on"
+        -> wireshark gets the vlan header
+        -> netsniff-ng doesn't get the vlan header
+
+        * ethtool -K eth0 rxvlan off
+        -> wireshark gets twice the same vlan header (like QinQ even though
+           I never sent QinQ)
+        -> netsniff-ng gets the vlan header
+
+    2) RTL8111/8168B
+        * ethtool -k eth0 gives "rx-vlan-offload: on"
+        -> wireshark gets the vlan header
+        -> netsniff-ng doesn't get the vlan header
+
+        * ethtool -K eth0 rxvlan off
+        -> wireshark gets the vlan header
+        -> netsniff-ng doesn't get the vlan header
+
+    Even if we would agree on doing the same workaround as libpcap, we still
+    will not be able to see QinQ, for instance, due to the fact that only /one/
+    VLAN tag is stored in this kernel helper data structure. We think that
+    there should be a good consensus on the kernel space side about what gets
+    transferred to the userland.
+
+    [1] http://lkml.indiana.edu/hypermail/linux/kernel/0710.3/3816.html
+
+    Update (28.11.2012): the Linux kernel and also bpfc has built-in support
+    for hardware accelerated VLAN filtering, even though tags might not be
+    visible in the payload itself as reported here. However, the filtering
+    for VLANs works reliable if your NIC supports it. bpfc example for filtering
+    for any tags:
+
+	_main:
+	 ld #vlanp
+	 jeq #0, drop
+	 ret #-1
+	drop:
+	 ret #0
+
+   Filtering for a particular VLAN tag:
+
+	_main:
+	 ld #vlant
+	 jneq #10, drop
+	 ret #-1
+	drop:
+	 ret #0
+
+   Where 10 is VLAN ID 10 in this example. Or, more pedantic:
+
+	_main:
+	 ld #vlanp
+	 jeq #0, drop
+	 ld #vlant
+	 jneq #10, drop
+	 ret #-1
+	drop:
+	 ret #0
+
+Q: When I start trafgen, my kernel crashes! What is happening?
+A: We have fixed this ``bug'' in the Linux kernel under commit
+   7f5c3e3a80e6654cf48dfba7cf94f88c6b505467 (http://bit.ly/PcH5Nd). Either
+   update your kernel to the latest version, e.g. clone and build it from
+   git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git or don't
+   start multiple trafgen instances at once resp. start trafgen with flag -A
+   to disable temporary socket memory tuning! Although trafgen's mechanism is
+   written in a correct manner, some probably Linux internal side-effects
+   cause the tigger of the BUG macro. Why tuning? In general, if not otherwise
+   specified, the netsniff-ng suite tries to get a good performance on default.
+   For instance, this includes things like tuning the system's socket memory,
+   enabling the BPF JIT compiler, migrating the NIC's interrupt affinity and
+   so on. If you don't want netsniff-ng to do this, look at the relevant cmd
+   line options that disable them with ``--help'' and explicitly specify them
+   on the program start.