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