man: flowtop: Add notes about enabling traffic accounting
[netsniff-ng.git] / INSTALL
blob9c000de38208606b0996e7561ea8692202b8502b
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!
10 A note for distribution package maintainers can be found at the end of the file.
12 What additional tools next to your build-chain are required?
14  - pkg-config:             all
15  - flex, bison:            bpfc, trafgen
17  - ccache (optional)
18  - gpg (optional)
19  - sparse (optional)
21 What libraries are required?
23  - libncurses:             ifpps, flowtop
24  - libnacl or libsodium:   curvetun
25  - libnetfilter-conntrack: flowtop
26  - libnl3:                 netsniff-ng, trafgen
27  - libpcap:                mausezahn, netsniff-ng (tcpdump-like filters)
28  - liburcu:                flowtop
29  - libcli:                 mausezahn
30  - libnet:                 mausezahn
32 The following libraries can optionally be used to provide additional
33 functionality for certain tools:
35  - libGeoIP >=1.4.8:       astraceroute, flowtop, netsniff-ng
36  - libz:                   astraceroute, flowtop, netsniff-ng
38 What additional tools are recommended, but not mandatory after the build?
40  - cpp:                    trafgen
41  - ntpd:                   curvetun
42  - gnuplot:                ifpps
43  - setcap:                 all
45 It is common that these libraries are shipped as distribution packages
46 for an easy installation. We try to keep this as minimal as possible.
48 One-liner installation for *all* dependencies on Debian:
50   $ sudo apt-get install ccache flex bison libnl-3-dev \
51   libnl-genl-3-dev libnl-route-3-dev libgeoip-dev \
52   libnetfilter-conntrack-dev libncurses5-dev liburcu-dev \
53   libnacl-dev libpcap-dev zlib1g-dev libcli-dev libnet1-dev
55 One-liner installation for *all* dependencies on Fedora:
57   $ sudo yum install ccache flex bison ccache libnl3-devel \
58   GeoIP-devel libnetfilter_conntrack-devel ncurses-devel \
59   userspace-rcu-devel nacl-devel libpcap-devel zlib-devel \
60   libcli-devel libnet-devel
62 After downloading the netsniff-ng toolkit, you should change to the
63 repository root directory:
65   $ cd netsniff-ng/
67 The installation (deinstallation) process is fairly simple:
69   $ ./configure
70   $ make
71   # make install
73   (# make uninstall)
75 In order to remove all build files from the source tree:
77   $ make clean
79 In any case "make help" will give you some pointers of what can be done.
80 To bring the source tree into a pristine state, there are two options.
81 The first one will remove all build and build config file, the latter will
82 also remove any manually added files:
84   $ make distclean
85   ($ make mrproper)
87 You can also build/install/uninstall only a particular tool, e.g.:
89   $ make trafgen
90   # make trafgen_install
92   (# make trafgen_uninstall)
94 If you want to build all tools, but {curvetun,mausezahn} (i.e. because you
95 don't need the tunneling software and the NaCl build process lasts quite long):
97   $ make allbutcurvetun               (allbutmausezahn)
98   # make install_allbutcurvetun       (install_allbutmausezahn)
100   (# make uninstall)
102 In order to build curvetun, libnacl must be built first. A helper script
103 called nacl_build.sh is there to facilitate this process. If you want to
104 build NaCl in the directory ~/nacl, the script should be called this way:
106   $ cd curvetun
107   $ ./nacl_build.sh ~/nacl
109 There's also an abbreviation for this by simply typing:
111   $ make nacl
113 This gives an initial output such as "Building NaCl for arch amd64 on host
114 fuuubar (grab a coffee, this takes a while) ...". If the automatically
115 detected architecture (such as amd64) is not the one you intend to compile
116 for, then edit the (cc="gcc") variable within the nacl_build.sh script to
117 your cross compiler. Yes, we know, the build system of NaCl is a bit of a
118 pain, so you might check for a pre-built package from your distribution in
119 case you are not cross compiling.
121 If NaCl already has been built on the target, it is quicker to use
122 nacl_path.sh this way:
124   $ cd curvetun
125   $ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86
127 Instead of libnacl you can also use libsodium which itself is a portable,
128 cross-compilable, API compatible drop-in replacement for libnacl.
130 In order to use libsodium you need to provide some little help when running
131 the configure script, so it will be able to detect the needed header files.
132 Additionally you need to configure the build to not link against libnacl
133 but against libsodium.
135 In the case libsodium was installed into /usr/local you run the netsniff-ng
136 configure script this way:
138   $ NACL_INC_DIR=/usr/local/include/sodium NACL_LIB=sodium ./configure
140 Alternatively you can use pkg-config for determining the include dir by
141 setting the NACL_INC_DIR variable for the configure script like this:
143   $ NACL_INC_DIR=$(pkg-config --variable=includedir libsodium )/sodium
145 When done, netsniff-ng's build infrastructure will read those evironment
146 variables in order to get the needed paths to NaCl.
148 If you're unsure with any make targets, check out: make help
150 In order to run the toolkit as a normal user, set the following privilege
151 separation after the build/installation:
153   $ sudo setcap cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_net_admin=eip {toolname}
155 For cross-compiling netsniff-ng, the process is fairly simple. Assuming you
156 want to build netsniff-ng for the Microblaze architecture, update the PATH
157 variable first, e.g.:
159   $ export PATH=<cc-tools-path>/microblazeel-unknown-linux-gnu/bin:$PATH
161 And then, build the toolkit like this:
163   $ CROSS_COMPILE=microblazeel-unknown-linux-gnu- \
164     SYSROOT=<sysroot-path> ./configure
165   $ make
167 SYSROOT should be set to the path where your cross-compiled libraries are
168 stored, i.e. the path you specify as prefix when configuring the library using
169 `./configure --prefix=<prefix>'.
171 Note that some adaptations might be necessary regarding the CFLAGS, since not
172 all might be supported by a different architecture. Probably the most simple
173 way would be to run make CFLAGS="-O2 -Wall".
175 For power users we have a set of zsh auto completion files, have a look at all
176 file with ending *.zsh. There's also a BPF vim syntax highlighting file in the
177 tree called bpf.vim.
179 For doing a debug build of the toolkit with less optimizations and non-stripped
180 symbols, do:
182   $ make DEBUG=1
184 For debugging the build system, actual commands are verbosly shown if every
185 make target is executed with:
187   $ make Q=
189 A hardening option is also available via HARDENING=1 if needed. You can then
190 build and install the toolkit into prefixed path like:
192   $ make PREFIX=<path-prefix-for-package>
193   $ make PREFIX=<path-prefix-for-package> install
195 Additionally to setting the PREFIX you can set DESTDIR if you want to install
196 the toolkit outside of your current root filesystem but into an alternative
197 path. This is particularly useful when cross-compiling because most likely
198 you want to install into a dedicated sandbox or into a mounted root filesystem
199 for the target architecture and not into the build hosts root filesystem.
201   $ make PREFIX=<path-prefix-for-package> DESTDIR=<alternative-rootfs> install
203 Thanks for maintaining netsniff-ng in your distribution. Further questions will
204 be answered on the public mailing list.
206 Last but not least, there is one small utility for advanced users that we have
207 not integrated into the main build process. This is a minimal BPF JIT image
208 disassembler for the Linux kernel. You can also find this tool in the Linux
209 kernel Git tree under 'tools/net/bpf_jit_disasm.c' or within the netsniff-ng
210 Git tree simply under 'bpf_jit_disasm.c'. To build it, execute:
212     $ gcc -Wall -O2 bpf_jit_disasm.c -o bpf_jit_disasm -lopcodes -lbfd -ldl
214 The rest is described in the file header comment itself, i.e. how to get to the
215 BPF JIT code.