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  - gcc, make, sed, perl, coreutils (all)
  14  - ccache (optional)
  15  - flex, bison (bpfc, trafgen)
  16  - asciidoc (man-pages)
  17
  18 What libraries are required?
  19
  20  - glibc (all)
  21  - libncurses (ifpps, flowtop)
  22  - libGeoIP >=1.4.8 (astraceroute, flowtop)
  23  - libnacl (curvetun)
  24  - libnetfilter-conntrack (flowtop)
  25  - liburcu (flowtop)
  26  - libnl3 (netsniff-ng, trafgen)
  27  - libnet (mausezahn)
  28  - libcli (mausezahn)
  29
  30 What additional tools are recommended after the build?
  31
  32  - ntpd (curvetun)
  33  - setcap (all)
  34
  35 It is common, that these libraries are shipped as distribution packages
  36 for an easy installation. We try to keep this as minimal as possible.
  37
  38 For downloading the latest GeoIP database, you should use the script that
  39 is located at scripts/geoip-database-update.
  40
  41 The installation process done by make is fairly simple:
  42
  43   $ cd netsniff-ng/src/
  44   $ make
  45   # make install
  46
  47 In order to build curvetun, libnacl must be built first. A helper script
  48 called build_nacl.sh is there to facilitate this process. If you want to
  49 build NaCl in the directory ~/nacl, the script should be called this way:
  50
  51   $ cd src/curvetun
  52   $ ./build_nacl.sh ~/nacl
  53
  54 This gives an initial output such as "Building NaCl for arch amd64 on host
  55 fuuubar (grab a coffee, this takes a while) ...". If the automatically
  56 detected architecture (such as amd64) is not the one you intend to compile
  57 for, then edit the (cc="gcc") variable within the build_nacl.sh script to
  58 your cross compiler. Yes, we know, the build system of NaCl is a bit of a
  59 pain, so you might check for a pre-built package from your distribution in
  60 case you are not cross compiling.
  61
  62 If NaCl already has been built on the target, it is quicker to use
  63 nacl_path.sh this way:
  64
  65   $ cd src/curvetun
  66   $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
  67
  68 When done, netsniff-ng's build infrastructure will read those evironment
  69 variables in order to get the needed paths to NaCl.
  70
  71 In case you have to manually install libgeoip in version 1.4.8 or higher, you
  72 can also use the provided helper script called build_geoip.sh from the
  73 src/astraceroute directory (depending on your distribution, you might want to
  74 adapt paths within the script):
  75
  76   $ cd src/astraceroute
  77   # ./build_geoip.sh
  78
  79 In order to run the toolkit as a normal user, set the following privilege
  80 separation after the build/installation:
  81
  82   $ sudo setcap cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_net_admin=eip {toolname}
  83
  84 Man pages are generated out of the files from Documentation/Manpages dir.
  85 They are written in asciidoc format. For this, you need the tool asciidoc which
  86 is distributed with on most Linux systems.
  87
  88 For bpfc, we also have a Vim syntax highlighting file. Have a look at
  89 scripts/bpf.vim for installation instructions.
  90
  91 To uninstall the toolkit from your system, simply execute:
  92
  93   # make distclean
  94
  95 netsniff-ng has been successfully tested on x86 and x86_64. It should also run
  96 on most other major architectures. However, since we don't have a possibility
  97 to test it, please drop us a short mail, if it runs successfully on hardware
  98 other than x86/x86_64.
  99
 100 For using TUN/TAP devices as a user, e.g. create a file called
 101 src/50-tuntap.rules in /etc/udev/rules.d/ with ...
 102
 103 KERNEL=="tun",NAME="net/%k",GROUP="netdev",MODE="0660",OPTIONS+="ignore_remove"
 104
 105 ... and restart the udev daemon. Add yourself to the "netdev" group.
 106
 107 Add the flag -D__WITH_HARDWARE_TIMESTAMPING=1 into src/Makefile for
 108 hardware timestamping support. Note that your kernel must be configured for
 109 this (e.g. to ship the linux/net_tstamp.h header file).
 110
 111 The following warnings can be seen when compiling bpfc with flex 2.5.35 and
 112 bison 2.4.1:
 113  - redundant redeclaration of ‘isatty’
 114  - cannot optimize loop, the loop counter may overflow
 115
 116 Those two warnings occur on generated C code produced by flex and bison and
 117 there is no possibility on our side to fix them while staying with both tools.
 118
 119 Similar to that, gcc will throw a warning on strchr(3) which is a false
 120 positive (http://gcc.gnu.org/bugzilla/show_bug.cgi?id=36513) from glibc:
 121  - warning: logical ‘&&’ with non-zero constant will always evaluate as true