INSTALL

   1 Currently only operating systems running on Linux kernels with the option
   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! A note for
   9 distribution package maintainers is at the end of this document.
  10
  11 What tools are required to build netsniff-ng?
  12
  13  - cmake (all)
  14  - flex, bison (bpfc, trafgen)
  15  - pod2man (all, only for manpages)
  16
  17 What libraries are required?
  18
  19  - libc, inc. libm, librt, libpthread (all)
  20  - libncurses (ifpps, flowtop)
  21  - libGeoIP >=1.4.8 (astraceroute, flowtop)
  22  - libnacl (curvetun)
  23  - libnetfilter-conntrack (flowtop)
  24  - liburcu (flowtop)
  25  - libnl (netsniff-ng, trafgen)
  26  - libnet (mausezahn)
  27  - libcli (mausezahn)
  28
  29 What additional tools are recommended after the build?
  30
  31  - ntpd, tlsdate or equivalent (curvetun)
  32  - setcap (all)
  33
  34 It is common, that these libraries are shipped as distribution packages
  35 for an easy installation. We try to keep this as minimal as possible.
  36
  37 For downloading the latest GeoIP database, you should use the script that
  38 is located at scripts/geoip-database-update.
  39
  40 The installation process done by cmake is fairly simple:
  41
  42   $ cd netsniff-ng/src/
  43   $ mkdir build
  44   $ cd build
  45   $ cmake ..
  46   $ make
  47   # make install
  48
  49 In order to build curvetun, libnacl must be built first. A helper script
  50 called build_nacl.sh is there to facilitate this process. If you want to
  51 build NaCl in the directory ~/nacl, the script should be called this way:
  52
  53   $ cd src/curvetun
  54   $ ./build_nacl.sh ~/nacl
  55
  56 This gives an initial output such as "Building NaCl for arch amd64 on host
  57 fuuubar (grab a coffee, this takes a while) ...". If the automatically
  58 detected architecture (such as amd64) is not the one you intend to compile
  59 for, then edit the (cc="gcc") variable within the build_nacl.sh script to
  60 your cross compiler. Yes, we know, the build system of NaCl is a bit of a
  61 pain, so you might check for a pre-built package from your distribution in
  62 case you are not cross compiling.
  63
  64 If NaCl already has been built on the target, it is quicker to use
  65 nacl_path.sh this way:
  66
  67   $ cd src/curvetun
  68   $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
  69
  70 When done, netsniff-ng build infrastructure will read nacl_path.cmake to get
  71 the needed paths to NaCl.
  72
  73 In case you have to manually install libgeoip in version 1.4.8 or higher, you
  74 can also use the provided helper script called build_geoip.sh from the
  75 src/astraceroute directory (depending on your distribution, you might want to
  76 adapt paths within the script):
  77
  78   $ cd src/astraceroute
  79   # ./build_geoip.sh
  80
  81 In order to run the toolkit as a normal user, set the following privilege
  82 separation after the build/installation:
  83
  84   $ sudo setcap cap_net_raw=ep astraceroute
  85   $ sudo setcap cap_net_admin=ep flowtop
  86   $ sudo setcap cap_net_raw=ep mausezahn
  87   $ sudo setcap "cap_net_raw=ep cap_ipc_lock=ep" netsniff-ng
  88   $ sudo setcap "cap_net_raw=ep cap_ipc_lock=ep" trafgen
  89
  90 Man pages are generated out of the files from Documentation/Manpages dir.
  91 They are written in POD format. For this, you need the tool pod2man which
  92 is distributed with Perl and should therefore be available on most systems.
  93
  94 For bpfc, we also have a Vim syntax highlighting file. Have a look at
  95 scripts/bpf.vim for installation instructions.
  96
  97 To uninstall, simply remove all files referred in install_manifest.txt, e.g.
  98 by running 'xargs rm < install_manifest.txt'.
  99
 100 Further notes:
 101 //////////////
 102
 103 netsniff-ng has been successfully tested on x86 and x86_64. It should also run
 104 on most other major architectures. However, since we don't have a possibility
 105 to test it, please drop us a short mail, if it runs successfully on hardware
 106 other than x86/x86_64.
 107
 108 For using TUN/TAP devices as a user, e.g. create a file called
 109 src/50-tuntap.rules in /etc/udev/rules.d/ with ...
 110
 111 KERNEL=="tun",NAME="net/%k",GROUP="netdev",MODE="0660",OPTIONS+="ignore_remove"
 112
 113 ... and restart the udev daemon. Add yourself to the "netdev" group.
 114
 115 Add the flag -D__WITH_HARDWARE_TIMESTAMPING=1 into src/CMakeLists.txt for
 116 hardware timestamping support. Note that your kernel must be configured for
 117 this (e.g. to ship the linux/net_tstamp.h header file). However, it is likely
 118 that our cmake module will detect this automatically for you.
 119
 120 If you are a package distribution maintainer, have a look at the patch set
 121 under contrib/patches which makes packaging a little easier for you. In case
 122 you want cmake to install manpages under /usr/share/man/, apply the following
 123 patch from Emmanuel Roullit:
 124
 125 --- a/src/cmake/modules/Pod2Man.cmake
 126 +++ b/src/cmake/modules/Pod2Man.cmake
 127 @@ -47,7 +47,7 @@
 128
 129         INSTALL(
 130                 FILES ${CMAKE_CURRENT_BINARY_DIR}/${MANFILE}.${SECTION}.gz
 131 -               DESTINATION share/man/man${SECTION}
 132 +               DESTINATION /usr/share/man/man${SECTION}
 133         )
 134  ENDMACRO(POD2MAN PODFILE MANFILE SECTION)
 135
 136 The same thing counts for installing relevant files from the documentation:
 137
 138 --- a/src/CMakeLists.txt
 139 +++ b/src/CMakeLists.txt
 140 @@ -5,7 +5,7 @@ cmake_minimum_required(VERSION 2.6)
 141  set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/modules)
 142  set(EXECUTABLE_INSTALL_PATH /usr/sbin)
 143  set(CONFIG_INSTALL_PATH /etc/netsniff-ng)
 144 -set(DOC_INSTALL_PATH share/doc/netsniff-ng)
 145 +set(DOC_INSTALL_PATH /usr/share/doc/netsniff-ng)
 146
 147  set(VERSION "0.5.8")
 148
 149 In case there is already a NaCl library version shipped with your distribution
 150 so that you only need to tell cmake pointers to the library and include path,
 151 you can add a new cmake file into src/curvetun and apply the patch from Kartik
 152 Mistry with perhaps changed paths:
 153
 154 --- /dev/null
 155 +++ b/src/curvetun/nacl_path.cmake
 156 @@ -0,0 +1,2 @@
 157 +SET(NACL_INCLUDE_DIR /usr/include/nacl)
 158 +SET(NACL_LIB_DIR /usr/lib)
 159
 160 Last but not least, if you package a binary distribution, make sure that
 161 architecture specific tuning has been turned off. You can do this by changing
 162 the following flags in the src/CMakeLists.txt file:
 163
 164 --- a/src/CMakeLists.txt
 165 +++ b/src/CMakeLists.txt
 166 @@ -16,15 +16,13 @@ include(CheckHwTimestamp)
 167  include(Pod2Man)
 168
 169  add_definitions(
 170 -  -O3
 171 +  -O2
 172    -fstack-protector
 173    -fpie
 174    -std=gnu99
 175    -fno-strict-aliasing
 176    -D_FORTIFY_SOURCE=2
 177    -D_REENTRANT
 178 -  -march=native
 179 -  -mtune=native
 180    -Wall
 181    -Wundef
 182    -Wstrict-prototypes
 183
 184 If you are a developer and would like to add unit tests, forget CMake's
 185 'make test', it's seriously broken! CMake developers obviously thought that
 186 the output of a CTest program is something noone should care about. This is
 187 why they not only print nothing on default, but they also did not think of
 188 adding an option for lets say 'power-users' to enable output. This is why we
 189 recommend to leave this brain damage aside and use a small helper script by
 190 Emmanuel Roullit that is able to show you libtap's output:
 191
 192 #!/bin/sh
 193 # ctest --verbose prints all output from tests programs, something that CMake's
 194 # 'make test' heavily fails; 'sed' removes the heading test number ("5:" for
 195 # instance); 'grep' removes all lines which does not contains TAP output lines
 196 # starting with 'ok','nok','1..*' and '#' are considered TAP output
 197 ctest --verbose | sed -e 's/^[0-9]*: //g' | grep -E '^nok|^ok|^#|^[0-9]+\.\.'
 198
 199 The following warnings can be seen when compiling bpfc with flex 2.5.35 and
 200 bison 2.4.1:
 201  - redundant redeclaration of ‘isatty’
 202  - cannot optimize loop, the loop counter may overflow
 203
 204 Those two warnings occur on generated C code produced by flex and bison and
 205 there is no possibility on our side to fix them while staying with both tools.
 206
 207 Similar to that, gcc will throw a warning on strchr(3) which is a false
 208 positive (http://gcc.gnu.org/bugzilla/show_bug.cgi?id=36513) from glibc:
 209  - warning: logical ‘&&’ with non-zero constant will always evaluate as true