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 (optional)
  15  - gpg (optional)
  16
  17  - pkg-config:             all
  18  - flex, bison:            bpfc, trafgen
  19
  20 What libraries are required?
  21
  22  - libncurses:             ifpps, flowtop
  23  - libGeoIP >=1.4.8:       astraceroute, flowtop, netsniff-ng
  24  - libz:                   astraceroute, flowtop, netsniff-ng
  25  - libnacl:                curvetun
  26  - libnetfilter-conntrack: flowtop
  27  - libpcap:                mausezahn, netsniff-ng (tcpdump-like filters)
  28  - liburcu:                flowtop
  29  - libnl3:                 netsniff-ng, trafgen
  30  - libcli:                 mausezahn
  31  - libnet:                 mausezahn
  32
  33 What additional tools are recommended, but not mandatory after the build?
  34
  35  - cpp:                    trafgen
  36  - ntpd:                   curvetun
  37  - gnuplot:                ifpps
  38  - setcap:                 all
  39
  40 It is common, that these libraries are shipped as distribution packages
  41 for an easy installation. We try to keep this as minimal as possible.
  42
  43 One-liner installation for *all* dependencies on Debian:
  44
  45   $ sudo apt-get install ccache flex bison libnl-3-dev \
  46   libnl-genl-3-dev libgeoip-dev libnetfilter-conntrack-dev \
  47   libncurses5-dev liburcu-dev libnacl-dev libpcap-dev \
  48   zlib1g-dev libcli-dev libnet1-dev
  49
  50 One-liner installation for *all* dependencies on Fedora:
  51
  52   $ sudo yum install ccache flex bison ccache libnl3-devel \
  53   GeoIP-devel libnetfilter_conntrack-devel ncurses-devel \
  54   userspace-rcu-devel nacl-devel libpcap-devel zlib-devel \
  55   libcli-devel libnet-devel
  56
  57 After downloading the netsniff-ng toolkit, you should change to the
  58 repository root directory:
  59
  60   $ cd netsniff-ng/
  61
  62 The installation (deinstallation) process is fairly simple:
  63
  64   $ ./configure
  65   $ make
  66   # make install
  67
  68   (# make uninstall)
  69
  70 In order to remove all build files from the source tree:
  71
  72   $ make clean
  73
  74 In any case "make help" will give you some pointers of what can be done.
  75 To bring the source tree into a pristine state, there are two options.
  76 The first one will remove all build and build config file, the latter will
  77 also remove any manually added files:
  78
  79   $ make distclean
  80   ($ make mrproper)
  81
  82 You can also build/install/uninstall only a particular tool, e.g.:
  83
  84   $ make trafgen
  85   # make trafgen_install
  86
  87   (# make trafgen_uninstall)
  88
  89 If you want to build all tools, but {curvetun,mausezahn} (i.e. because you
  90 don't need the tunneling software and the NaCl build process lasts quite long):
  91
  92   $ make allbutcurvetun               (allbutmausezahn)
  93   # make install_allbutcurvetun       (install_allbutmausezahn)
  94
  95   (# make uninstall)
  96
  97 In order to build curvetun, libnacl must be built first. A helper script
  98 called nacl_build.sh is there to facilitate this process. If you want to
  99 build NaCl in the directory ~/nacl, the script should be called this way:
 100
 101   $ cd curvetun
 102   $ ./nacl_build.sh ~/nacl
 103
 104 There's also an abbreviation for this by simply typing:
 105
 106   $ make nacl
 107
 108 This gives an initial output such as "Building NaCl for arch amd64 on host
 109 fuuubar (grab a coffee, this takes a while) ...". If the automatically
 110 detected architecture (such as amd64) is not the one you intend to compile
 111 for, then edit the (cc="gcc") variable within the nacl_build.sh script to
 112 your cross compiler. Yes, we know, the build system of NaCl is a bit of a
 113 pain, so you might check for a pre-built package from your distribution in
 114 case you are not cross compiling.
 115
 116 If NaCl already has been built on the target, it is quicker to use
 117 nacl_path.sh this way:
 118
 119   $ cd curvetun
 120   $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
 121
 122 When done, netsniff-ng's build infrastructure will read those evironment
 123 variables in order to get the needed paths to NaCl.
 124
 125 If you're unsure with any make targets, check out: make help
 126
 127 In order to run the toolkit as a normal user, set the following privilege
 128 separation after the build/installation:
 129
 130   $ sudo setcap cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_net_admin=eip {toolname}
 131
 132 For cross-compiling netsniff-ng, the process is faily simple. Assuming you
 133 want to build netsniff-ng for the Microblaze architecture, update the PATH
 134 variable first, e.g.:
 135
 136   $ export PATH=<cc-tools-path>/microblazeel-unknown-linux-gnu/bin:$PATH
 137
 138 And then, build the toolkit like this:
 139
 140   $ make CROSS_COMPILE=microblazeel-unknown-linux-gnu- \
 141          CROSS_LD_LIBRARY_PATH=<cc-lib-search-path>
 142
 143 Note that some adaptations might be necessary regarding the CFLAGS, since not
 144 all might be supported by a different architecture. Probably the most simple
 145 way would be to run make CFLAGS="-O2 -Wall".
 146
 147 For power users we have a set of zsh auto completion files, have a look at all
 148 file with ending *.zsh. There's also a BPF vim syntax highlighting file in the
 149 tree called bpf.vim.
 150
 151 For doing a debug build of the toolkit with less optimizations and non-stripped
 152 symbols, do:
 153
 154   $ make DEBUG=1
 155
 156 For debugging the build system, actual commands are verbosly shown if every
 157 make target is executed with:
 158
 159   $ make Q=
 160
 161 Concerning packaging the toolkit for a Linux distribution, by default,
 162 netsniff-ng has some architecture-specific tuning options enabled that don't
 163 belong into a package binary of a distribution. Hence, you might want to build
 164 the toolkit with:
 165
 166   $ make DISTRO=1
 167
 168 A hardening option is also available via HARDENING=1 if needed. You can then
 169 build and install the toolkit into prefixed path like:
 170
 171   $ make PREFIX=<path-prefix-for-package>
 172   $ make PREFIX=<path-prefix-for-package> install
 173
 174 Thanks for maintaining netsniff-ng in your distribution. Further questions will
 175 be answered on the public mailing list.
 176
 177 Last but not least, there is one small utility for advanced users that we have
 178 not integrated into the main build process. This is a minimal BPF JIT image
 179 disassembler for the Linux kernel. You can also find this tool in the Linux
 180 kernel Git tree under 'tools/net/bpf_jit_disasm.c' or within the netsniff-ng
 181 Git tree simply under 'bpf_jit_disasm.c'. To build it, execute:
 182
 183     $ gcc -Wall -O2 bpf_jit_disasm.c -o bpf_jit_disasm -lopcodes -lbfd -ldl
 184
 185 The rest is described in the file header comment itself, i.e. how to get to the
 186 BPF JIT code.