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