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