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, 160 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..74fc8e4
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,160 @@
+Currently only operating systems running on Linux kernels with the option
+CONFIG_PACKET_MMAP enabled. This feature can be found even back to the days of
+2.4 kernels. Most operating systems ship pre-compiled kernels that have this
+config option enabled and even the latest kernel versions got rid of this
+option and have this functionality already built-in. However, we recommend a
+kernel >= 2.6.31, because the TX_RING is officially integrated since then. In
+any case, if you have the possibility, consider getting the latest kernel from
+Linus' Git repository, tweak and compile it, and run this one!
+
+A note for distribution package maintainers can be found at the end of the file.
+
+What additional tools are required to build netsniff-ng?
+
+ - ccache (optional)
+ - flex, bison (bpfc, trafgen)
+
+What libraries are required?
+
+ - libncurses (ifpps, flowtop)
+ - libGeoIP >=1.4.8 (astraceroute, flowtop, netsniff-ng)
+ - libz (astraceroute, flowtop, netsniff-ng)
+ - libnacl (curvetun)
+ - libnetfilter-conntrack (flowtop)
+ - libpcap (netsniff-ng, for tcpdump-like filters)
+ - liburcu (flowtop)
+ - libnl3 (netsniff-ng, trafgen)
+
+What additional tools are recommended after the build?
+
+ - cpp (trafgen)
+ - ntpd (curvetun)
+ - setcap (all)
+
+It is common, that these libraries are shipped as distribution packages
+for an easy installation. We try to keep this as minimal as possible.
+
+One-liner installation for *all* dependencies on Debian:
+
+  $ sudo apt-get install ccache flex bison libnl-3-dev \
+  libnl-genl-3-dev libgeoip-dev libnetfilter-conntrack-dev \
+  libncurses5-dev liburcu-dev libnacl-dev libpcap-dev \
+  zlib1g-dev
+
+One-liner installation for *all* dependencies on Fedora:
+ 
+  $ sudo yum install ccache flex bison ccache libnl3-devel \
+  GeoIP-devel libnetfilter_conntrack-devel ncurses-devel \
+  userspace-rcu-devel nacl-devel libpcap-devel zlib-devel
+
+After downloading the netsniff-ng toolkit, you should change to the
+repository root directory:
+
+  $ cd netsniff-ng/
+
+The installation (deinstallation) process done by make is fairly simple:
+
+  $ make
+  # make install
+
+  (# make distclean)
+  ($ make clean)
+  (or for both at once: # make mrproper)
+
+You can also build only a particular tool, e.g.:
+  
+  $ make trafgen
+  # make trafgen_install
+
+  (# make trafgen_distclean)
+  ($ make trafgen_clean)
+
+Currently mausezahn is experimental and not included in the default repository
+resp. build:
+
+  $ git pull origin with-mausezahn
+
+This means if you want to use mausezahn, you have to execute 'make mausezahn'
+for a build. This will be changed at the time when we have cleaned up and
+fixed the imported code.
+
+If you want to build all tools, but curvetun (i.e. because you don't need
+the tunneling software and the NaCl build process lasts quite long):
+
+  $ make allbutcurvetun
+  # make install_allbutcurvetun
+
+  (# make mrproper)
+
+In order to build curvetun, libnacl must be built first. A helper script
+called build_nacl.sh is there to facilitate this process. If you want to
+build NaCl in the directory ~/nacl, the script should be called this way:
+
+  $ cd curvetun
+  $ ./build_nacl.sh ~/nacl
+
+There's also an abbreviation for this by simply typing:
+
+  $ make nacl
+
+This gives an initial output such as "Building NaCl for arch amd64 on host
+fuuubar (grab a coffee, this takes a while) ...". If the automatically
+detected architecture (such as amd64) is not the one you intend to compile
+for, then edit the (cc="gcc") variable within the build_nacl.sh script to
+your cross compiler. Yes, we know, the build system of NaCl is a bit of a
+pain, so you might check for a pre-built package from your distribution in
+case you are not cross compiling.
+
+If NaCl already has been built on the target, it is quicker to use
+nacl_path.sh this way:
+
+  $ cd curvetun
+  $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
+
+When done, netsniff-ng's build infrastructure will read those evironment
+variables in order to get the needed paths to NaCl.
+
+If you're unsure with any make targets, check out: make help
+
+In order to run the toolkit as a normal user, set the following privilege
+separation after the build/installation:
+
+  $ sudo setcap cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_net_admin=eip {toolname}
+
+For cross-compiling netsniff-ng, the process is faily simple. Assuming you
+want to build netsniff-ng for the Microblaze architecture, update the PATH
+variable first, e.g.:
+
+  $ export PATH=<cc-tools-path>/microblazeel-unknown-linux-gnu/bin:$PATH
+
+And then, build the toolkit like this:
+
+  $ make CROSS_COMPILE=microblazeel-unknown-linux-gnu- \
+	 CROSS_LD_LIBRARY_PATH=<cc-lib-search-path>
+
+Note that some adaptations might be necessary regarding the CFLAGS, since not
+all might be supported by a different architecture.
+
+For doing a debug build of the toolkit with less optimizations and non-stripped
+symbols, do:
+
+  $ make DEBUG=1
+
+For debugging the build system, full commands are shown if every make target is
+executed with:
+
+  $ make Q=
+
+Concerning packaging the toolkit for a Linux distribution, by default,
+netsniff-ng has some architecture-specific tuning options enabled that don't
+belong into a package binary of a distribution. Hence, you might want to adapt
+some build-related things before starting to package the toolkit. All
+necessary things (e.g., CFLAGS,WFLAGS) can be found in Makefile. Hence,
+you need to adapt it there. You can then build and install the toolkit into
+a prefixed path like:
+
+  $ make PREFIX=<path-prefix-for-package>
+  $ make PREFIX=<path-prefix-for-package> install
+
+Thanks for maintaining netsniff-ng in your distribution. Further questions
+will be answered on the public mainling list.