INSTALL

   1 Currently only operating systems running on Linux kernels with
   2 CONFIG_PACKET_MMAP enabled. This feature can be found even back to the days of
   3 2.4 kernels. Most operating systems ship pre-compiled kernels that have this
   4 config option enabled and even the latest kernel versions got rid of this
   5 option and have this functionality already built-in. However, we recommend a
   6 kernel >= 2.6.31, because the TX_RING is officially integrated since then. In
   7 any case, if you have the possibility, consider getting the latest kernel from
   8 Linus' Git repository, tweak and compile it and run this one!
   9
  10 netsniff-ng has been successfully tested on x86 and x86_64. It should also run
  11 on most other major architectures. However, since we don't have a possibility
  12 to test it, please drop us a short mail, if it runs successfully on hardware
  13 other than x86/x86_64.
  14
  15 What libraries / tools are required?
  16
  17  - glibc (all)
  18  - cmake (all)
  19  - libpthread (curvetun, netsniff-ng, flowtop)
  20  - libncurses (ifpps, flowtop)
  21  - libGeoIP and its database (ashunt, flowtop)
  22  - flex, bison (bpfc, trafgen)
  23  - libnacl (curvetun)
  24  - libnetfilter-conntrack (flowtop)
  25  - liburcu (flowtop)
  26  - libcli (gremlin)
  27  - libnl (netsniff-ng, trafgen)
  28
  29 What additional tools are recommended?
  30
  31  - ntpd, tlsdate or equivalent (curvetun)
  32
  33 It is common, that these libraries are shipped as distribution packages
  34 for an easy installation. We try to keep this as minimal as possible.
  35
  36 For downloading the latest GeoIP database, you can use the script that
  37 is located at scripts/geoip-database-update.
  38
  39 The installation process done by cmake is fairly simple:
  40
  41   $ cd netsniff-ng/src/
  42   $ mkdir build
  43   $ cd build
  44   $ cmake ..
  45   $ make
  46   # make install
  47
  48 Man pages are generated out of the corresponding source files by cmake.
  49 They are written in POD format as a C header comment within those files.
  50 For this, you need the tool pod2man which is distributed with Perl and
  51 should therefore be available on most systems.
  52
  53 To uninstall, simply remove all files refered in install_manifest.txt
  54
  55 For bpfc, we also have a Vim syntax highlighting file. Have a look at
  56 scripts/bpf.vim for installation instructions.
  57
  58 In order to build curvetun, libnacl must be built first. A helper script
  59 called build_nacl.sh is there to facilitate this process. If you want to
  60 build NaCl in the directory ~/nacl, the script should be called this way:
  61
  62   $ cd src/curvetun
  63   $ ./build_nacl.sh ~/nacl
  64
  65 This gives an initial output such as "Building NaCl for arch amd64 on host
  66 fuuubar (grab a coffee, this takes a while) ...". If the automatically
  67 detected architecture (such as amd64) is not the one you intend to compile
  68 for, then edit the (cc="gcc") variable within the build_nacl.sh script to
  69 your cross compiler. Yes, we know, the build system of NaCl is a bit of a
  70 pain, so you might check for a pre-built package from your distribution in
  71 case you are not cross compiling.
  72
  73 If NaCl already has been built on the target, it is quicker to use
  74 nacl_path.sh this way:
  75
  76   $ cd src/curvetun
  77   $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
  78
  79 When done, netsniff-ng build infrastructure will read nacl_path.cmake to get
  80 the needed paths to NaCl.
  81
  82 For using TUN/TAP devices as a user, e.g. create a file called
  83 src/50-tuntap.rules in /etc/udev/rules.d/ with ...
  84
  85 KERNEL=="tun",NAME="net/%k",GROUP="netdev",MODE="0660",OPTIONS+="ignore_remove"
  86
  87 ... and restart the udev daemon. Add yourself to the "netdev" group.
  88
  89 Further notes:
  90
  91 Add the flag -D__WITH_HARDWARE_TIMESTAMPING=1 into src/CMakeLists.txt for
  92 hardware timestamping support. Note that your kernel must be configured for
  93 this (e.g. to ship the linux/net_tstamp.h header file).
  94
  95 If you are a package distribution maintainer, have a look at the patch set
  96 under contrib/patches which makes packaging a little easier for you.
  97
  98 If you are a developer and would like to add unit tests, forget CMake's
  99 'make test', it's seriously broken! CMake developers obviously thought that
 100 the output of a CTest program is something noone should care about. This is
 101 why they not only print nothing on default, but they also did not think of
 102 adding an option for lets say 'power-users' to enable output. This is why we
 103 recommend to leave this brain damage aside and use a small helper script that
 104 is able to show you libtap's output:
 105
 106 #!/bin/sh
 107 # ctest --verbose prints all output from tests programs, something that CMake's
 108 # 'make test' heavily fails; 'sed' removes the heading test number ("5:" for
 109 # instance); 'grep' removes all lines which does not contains TAP output lines
 110 # starting with 'ok','nok','1..*' and '#' are considered TAP output
 111 ctest --verbose | sed -e 's/^[0-9]*: //g' | grep -E '^nok|^ok|^#|^[0-9]+\.\.'
 112
 113 The following warnings can be seen when compiling bpfc with flex 2.5.35 and
 114 bison 2.4.1:
 115  - redundant redeclaration of ‘isatty’
 116  - cannot optimize loop, the loop counter may overflow
 117
 118 Those two warnings occur on generated C code produced by flex and bison and
 119 there is no possibility on our side to fix them while staying with both tools.
 120
 121 Similar to that, gcc will throw a warning on strchr(3) which is a false
 122 positive (http://gcc.gnu.org/bugzilla/show_bug.cgi?id=36513) from glibc:
 123  - warning: logical ‘&&’ with non-zero constant will always evaluate as true