docs: remove todo point

[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 is at the end of this document.

What tools are required to build netsniff-ng?

 - cmake (all)
 - flex, bison (bpfc, trafgen)
 - pod2man (all, only for manpages)

What libraries are required?

 - libc, including libm, librt, libpthread (all)
 - libncurses (ifpps, flowtop)
 - libGeoIP >=1.4.8 (astraceroute, flowtop)
 - libnacl (curvetun)
 - libnetfilter-conntrack (flowtop)
 - liburcu (flowtop)
 - libnl (netsniff-ng, trafgen)
 - libnet (mausezahn)
 - libcli (mausezahn)

What additional tools are recommended after the build?

 - ntpd, tlsdate or equivalent (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.

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

The installation process done by cmake is fairly simple:

  $ cd netsniff-ng/src/
  $ mkdir build
  $ cd build
  $ cmake ..
  $ make
  # make install

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

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 build infrastructure will read nacl_path.cmake 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

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_net_admin=eip {toolname}

Man pages are generated out of the files from Documentation/Manpages dir.
They are written in POD format. For this, you need the tool pod2man which
is distributed with Perl and should therefore be available on most systems.

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

To uninstall, simply remove all files referred in install_manifest.txt, e.g.
by running 'xargs rm < install_manifest.txt'.

Further notes:
//////////////

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/CMakeLists.txt for
hardware timestamping support. Note that your kernel must be configured for
this (e.g. to ship the linux/net_tstamp.h header file). However, it is likely
that our cmake module will detect this automatically for you.

If you are a package distribution maintainer, have a look at the patch set
under contrib/patches which makes packaging a little easier for you. In case
you want cmake to install manpages under /usr/share/man/, apply the following
patch from Emmanuel Roullit:

--- a/src/cmake/modules/Pod2Man.cmake
+++ b/src/cmake/modules/Pod2Man.cmake
@@ -47,7 +47,7 @@
 
        INSTALL(
                FILES ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}.gz
-               DESTINATION share/man/man${SECTION}
+               DESTINATION /usr/share/man/man${SECTION}
        )
 ENDMACRO(POD2MAN PODFILE MANFILE SECTION)

The same thing counts for installing relevant files from the documentation:

--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -5,7 +5,7 @@ cmake_minimum_required(VERSION 2.6)
 set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/modules)
 set(EXECUTABLE_INSTALL_PATH /usr/sbin)
 set(CONFIG_INSTALL_PATH /etc/netsniff-ng)
-set(DOC_INSTALL_PATH share/doc/netsniff-ng)
+set(DOC_INSTALL_PATH /usr/share/doc/netsniff-ng)
 
 set(VERSION "0.5.8")

In case there is already a NaCl library version shipped with your distribution
so that you only need to tell cmake pointers to the library and include path,
you can add a new cmake file into src/curvetun and apply the patch from Kartik
Mistry with perhaps changed paths:

--- /dev/null
+++ b/src/curvetun/nacl_path.cmake
@@ -0,0 +1,2 @@
+SET(NACL_INCLUDE_DIR /usr/include/nacl)
+SET(NACL_LIB_DIR /usr/lib)

Last but not least, if you package a binary distribution, make sure that
architecture specific tuning has been turned off. You can do this by changing
the following flags in the src/CMakeLists.txt file:

--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -16,15 +16,13 @@ include(CheckHwTimestamp)
 include(Pod2Man)
 
 add_definitions(
-  -O3
+  -O2
   -fstack-protector
   -fpie
   -std=gnu99
   -fno-strict-aliasing
   -D_FORTIFY_SOURCE=2
   -D_REENTRANT
-  -march=native
-  -mtune=native
   -Wall
   -Wundef
   -Wstrict-prototypes

If you are a developer and would like to add unit tests, forget CMake's
'make test', it's seriously broken! CMake developers obviously thought that
the output of a CTest program is something noone should care about. This is
why they not only print nothing on default, but they also did not think of
adding an option for lets say 'power-users' to enable output. This is why we
recommend to leave this brain damage aside and use a small helper script by
Emmanuel Roullit that is able to show you libtap's output:

#!/bin/sh
# ctest --verbose prints all output from tests programs, something that CMake's
# 'make test' heavily fails; 'sed' removes the heading test number ("5:" for
# instance); 'grep' removes all lines which does not contains TAP output lines
# starting with 'ok','nok','1..*' and '#' are considered TAP output
ctest --verbose | sed -e 's/^[0-9]*: //g' | grep -E '^nok|^ok|^#|^[0-9]+\.\.'

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