netsniff-ng: move contrib out

[netsniff-ng.git] / INSTALL

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)
 - libnacl (curvetun)
 - libnetfilter-conntrack (flowtop)
 - liburcu (flowtop)
 - libnl3 (netsniff-ng, trafgen)

For experimental tools (mausezahn branch):

 - libnet (mausezahn)
 - libpcap (mausezahn)
 - libcli (mausezahn)

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 libnet1-dev \
  libpcap-dev libcli-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 libnet-devel libpcap-devel \
  libcli-devel

After downloading the netsniff-ng toolkit, you should change to 'src':

  $ cd netsniff-ng/src/

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 src/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 src/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.

In case you have to manually install libgeoip in version 1.4.8 or higher, you
can also use the provided helper script called build_geoip.sh from the
src/astraceroute directory (depending on your distribution, you might want to
adapt paths within the script):

  $ cd src/astraceroute
  # ./build_geoip.sh

Again, there's also an abbreviation for this by simply typing:

  # make geoip

For downloading the latest GeoIP database, you should use the script that
is located at scripts/geoip-database-update, or use:

  # make update

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}

Man pages are generated out of the files from Documentation/Manpages dir.
They are written in asciidoc format. For this, you need the tool asciidoc which
is distributed with on most Linux systems.

For bpfc, we also have a Vim syntax highlighting file. Have a look at
scripts/bpf.vim for installation instructions.

netsniff-ng has been successfully tested on x86 and x86_64. It should also run
on most other major architectures. However, since we don't have a possibility
to test it, please drop us a short mail, if it runs successfully on hardware
other than x86/x86_64.

For using TUN/TAP devices as a user, e.g. create a file called
src/50-tuntap.rules in /etc/udev/rules.d/ with ...

KERNEL=="tun",NAME="net/%k",GROUP="netdev",MODE="0660",OPTIONS+="ignore_remove"

... and restart the udev daemon. Add yourself to the "netdev" group.

Add the flag -D__WITH_HARDWARE_TIMESTAMPING=1 into src/Makefile for
hardware timestamping support. Note that your kernel must be configured for
this (e.g. to ship the linux/net_tstamp.h header file).

The following warnings can be seen when compiling bpfc with flex 2.5.35 and
bison 2.4.1:
 - redundant redeclaration of ‘isatty’
 - cannot optimize loop, the loop counter may overflow

Those two warnings occur on generated C code produced by flex and bison and
there is no possibility on our side to fix them while staying with both tools.

Similar to that, gcc will throw a warning on strchr(3) which is a false
positive (http://gcc.gnu.org/bugzilla/show_bug.cgi?id=36513) from glibc:
 - warning: logical ‘&&’ with non-zero constant will always evaluate as true

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 src/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.