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