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 additional tools next to your build-chain are required?
  13
  14  - ccache, pkg-config, gpg (optional)
  15  - flex, bison (bpfc, trafgen)
  16
  17 What libraries are required?
  18
  19  - libncurses (ifpps, flowtop)
  20  - libGeoIP >=1.4.8 (astraceroute, flowtop, netsniff-ng)
  21  - libz (astraceroute, flowtop, netsniff-ng)
  22  - libnacl (curvetun)
  23  - libnetfilter-conntrack (flowtop)
  24  - libpcap (netsniff-ng [for tcpdump-like filters], mausezahn)
  25  - liburcu (flowtop)
  26  - libnl3 (netsniff-ng, trafgen)
  27  - libcli (mausezahn)
  28  - libnet (mausezahn)
  29
  30 What additional tools are recommended after the build?
  31
  32  - cpp (trafgen)
  33  - ntpd (curvetun)
  34  - setcap (all)
  35
  36 It is common, that these libraries are shipped as distribution packages
  37 for an easy installation. We try to keep this as minimal as possible.
  38
  39 One-liner installation for *all* dependencies on Debian:
  40
  41   $ sudo apt-get install ccache flex bison libnl-3-dev \
  42   libnl-genl-3-dev libgeoip-dev libnetfilter-conntrack-dev \
  43   libncurses5-dev liburcu-dev libnacl-dev libpcap-dev \
  44   zlib1g-dev libcli-dev libnet1-dev
  45
  46 One-liner installation for *all* dependencies on Fedora:
  47
  48   $ sudo yum install ccache flex bison ccache libnl3-devel \
  49   GeoIP-devel libnetfilter_conntrack-devel ncurses-devel \
  50   userspace-rcu-devel nacl-devel libpcap-devel zlib-devel \
  51   libcli-devel libnet-devel
  52
  53 After downloading the netsniff-ng toolkit, you should change to the
  54 repository root directory:
  55
  56   $ cd netsniff-ng/
  57
  58 The installation (deinstallation) process done by make is fairly simple:
  59
  60   $ make
  61   # make install
  62
  63   (# make distclean)
  64   ($ make clean)
  65   (or for both at once: # make mrproper)
  66
  67 You can also build only a particular tool, e.g.:
  68
  69   $ make trafgen
  70   # make trafgen_install
  71
  72   (# make trafgen_distclean)
  73   ($ make trafgen_clean)
  74
  75 If you want to build all tools, but {curvetun,mausezahn} (i.e. because you
  76 don't need the tunneling software and the NaCl build process lasts quite long):
  77
  78   $ make allbutcurvetun               (allbutmausezahn)
  79   # make install_allbutcurvetun       (install_allbutmausezahn)
  80
  81   (# make mrproper)
  82
  83 In order to build curvetun, libnacl must be built first. A helper script
  84 called nacl_build.sh is there to facilitate this process. If you want to
  85 build NaCl in the directory ~/nacl, the script should be called this way:
  86
  87   $ cd curvetun
  88   $ ./nacl_build.sh ~/nacl
  89
  90 There's also an abbreviation for this by simply typing:
  91
  92   $ make nacl
  93
  94 This gives an initial output such as "Building NaCl for arch amd64 on host
  95 fuuubar (grab a coffee, this takes a while) ...". If the automatically
  96 detected architecture (such as amd64) is not the one you intend to compile
  97 for, then edit the (cc="gcc") variable within the nacl_build.sh script to
  98 your cross compiler. Yes, we know, the build system of NaCl is a bit of a
  99 pain, so you might check for a pre-built package from your distribution in
 100 case you are not cross compiling.
 101
 102 If NaCl already has been built on the target, it is quicker to use
 103 nacl_path.sh this way:
 104
 105   $ cd curvetun
 106   $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
 107
 108 When done, netsniff-ng's build infrastructure will read those evironment
 109 variables in order to get the needed paths to NaCl.
 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 For cross-compiling netsniff-ng, the process is faily simple. Assuming you
 119 want to build netsniff-ng for the Microblaze architecture, update the PATH
 120 variable first, e.g.:
 121
 122   $ export PATH=<cc-tools-path>/microblazeel-unknown-linux-gnu/bin:$PATH
 123
 124 And then, build the toolkit like this:
 125
 126   $ make CROSS_COMPILE=microblazeel-unknown-linux-gnu- \
 127          CROSS_LD_LIBRARY_PATH=<cc-lib-search-path>
 128
 129 Note that some adaptations might be necessary regarding the CFLAGS, since not
 130 all might be supported by a different architecture. Probably the most simple
 131 way would be to run make CFLAGS="-O2 -Wall".
 132
 133 For power users we have a set of zsh auto completion files, have a look at all
 134 file with ending *.zsh. There's also a BPF vim syntax highlighting file in the
 135 tree called bpf.vim.
 136
 137 For doing a debug build of the toolkit with less optimizations and non-stripped
 138 symbols, do:
 139
 140   $ make DEBUG=1
 141
 142 For debugging the build system, full commands are shown if every make target is
 143 executed with:
 144
 145   $ make Q=
 146
 147 Concerning packaging the toolkit for a Linux distribution, by default,
 148 netsniff-ng has some architecture-specific tuning options enabled that don't
 149 belong into a package binary of a distribution. Hence, you might want to adapt
 150 some build-related things before starting to package the toolkit. All
 151 necessary things (e.g., CFLAGS,WFLAGS) can be found in Makefile. Hence,
 152 you need to adapt it there. You can then build and install the toolkit into
 153 a prefixed path like:
 154
 155   $ make PREFIX=<path-prefix-for-package>
 156   $ make PREFIX=<path-prefix-for-package> install
 157
 158 Thanks for maintaining netsniff-ng in your distribution. Further questions
 159 will be answered on the public mainling list.