| 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 |
- pkg-config: all |
| 15 |
- flex, bison: bpfc, trafgen |
| 16 |
|
| 17 |
- ccache (optional) |
| 18 |
- gpg (optional) |
| 19 |
- sparse (optional) |
| 20 |
|
| 21 |
What libraries are required? |
| 22 |
|
| 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 |
| 31 |
|
| 32 |
The following libraries can optionally be used to provide additional |
| 33 |
functionality for certain tools: |
| 34 |
|
| 35 |
- libGeoIP >=1.4.8: astraceroute, flowtop, netsniff-ng |
| 36 |
- libz: astraceroute, flowtop, netsniff-ng |
| 37 |
|
| 38 |
What additional tools are recommended, but not mandatory after the build? |
| 39 |
|
| 40 |
- cpp: trafgen |
| 41 |
- ntpd: curvetun |
| 42 |
- gnuplot: ifpps |
| 43 |
- setcap: all |
| 44 |
|
| 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. |
| 47 |
|
| 48 |
One-liner installation for *all* dependencies on Debian: |
| 49 |
|
| 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 |
| 54 |
|
| 55 |
One-liner installation for *all* dependencies on Fedora: |
| 56 |
|
| 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 |
| 61 |
|
| 62 |
After downloading the netsniff-ng toolkit, you should change to the |
| 63 |
repository root directory: |
| 64 |
|
| 65 |
$ cd netsniff-ng/ |
| 66 |
|
| 67 |
The installation (deinstallation) process is fairly simple: |
| 68 |
|
| 69 |
$ ./configure |
| 70 |
$ make |
| 71 |
# make install |
| 72 |
|
| 73 |
(# make uninstall) |
| 74 |
|
| 75 |
The configure script can be influenced by setting certain command line |
| 76 |
options and environment variables (e.g. CC or CROSS_COMPILE). To get a list |
| 77 |
of all supported options and variables use: |
| 78 |
|
| 79 |
$ ./configure --help |
| 80 |
|
| 81 |
The use of the optional libGeoIP and libz libraries can be explicitely |
| 82 |
disabled by using the corresponding command line option for the configure |
| 83 |
script: |
| 84 |
|
| 85 |
$ ./configure --disable-geoip |
| 86 |
$ ./configure --disable-zlib |
| 87 |
|
| 88 |
In order to remove all build files from the source tree: |
| 89 |
|
| 90 |
$ make clean |
| 91 |
|
| 92 |
In any case "make help" will give you some pointers of what can be done. |
| 93 |
|
| 94 |
To bring the source tree into a pristine state, there are two options. |
| 95 |
The first one will remove all build and build config file, the latter will |
| 96 |
also remove any manually added files: |
| 97 |
|
| 98 |
$ make distclean |
| 99 |
($ make mrproper) |
| 100 |
|
| 101 |
You can also build/install/uninstall only a particular tool, e.g.: |
| 102 |
|
| 103 |
$ make trafgen |
| 104 |
# make trafgen_install |
| 105 |
|
| 106 |
(# make trafgen_uninstall) |
| 107 |
|
| 108 |
If you want to build all tools, but {curvetun,mausezahn} (i.e. because you |
| 109 |
don't need the tunneling software and the NaCl build process lasts quite long): |
| 110 |
|
| 111 |
$ make allbutcurvetun (allbutmausezahn) |
| 112 |
# make install_allbutcurvetun (install_allbutmausezahn) |
| 113 |
|
| 114 |
(# make uninstall) |
| 115 |
|
| 116 |
In order to build curvetun, libnacl must be built first. A helper script |
| 117 |
called nacl_build.sh is there to facilitate this process. If you want to |
| 118 |
build NaCl in the directory ~/nacl, the script should be called this way: |
| 119 |
|
| 120 |
$ cd curvetun |
| 121 |
$ ./nacl_build.sh ~/nacl |
| 122 |
|
| 123 |
There's also an abbreviation for this by simply typing: |
| 124 |
|
| 125 |
$ make nacl |
| 126 |
|
| 127 |
This gives an initial output such as "Building NaCl for arch amd64 on host |
| 128 |
fuuubar (grab a coffee, this takes a while) ...". If the automatically |
| 129 |
detected architecture (such as amd64) is not the one you intend to compile |
| 130 |
for, then edit the (cc="gcc") variable within the nacl_build.sh script to |
| 131 |
your cross compiler. Yes, we know, the build system of NaCl is a bit of a |
| 132 |
pain, so you might check for a pre-built package from your distribution in |
| 133 |
case you are not cross compiling. |
| 134 |
|
| 135 |
If NaCl already has been built on the target, it is quicker to use |
| 136 |
nacl_path.sh this way: |
| 137 |
|
| 138 |
$ cd curvetun |
| 139 |
$ ./nacl_path.sh ~/nacl/build/include/x86 ~/nacl/build/lib/x86 |
| 140 |
|
| 141 |
Instead of libnacl you can also use libsodium which itself is a portable, |
| 142 |
cross-compilable, API compatible drop-in replacement for libnacl. |
| 143 |
|
| 144 |
In order to use libsodium you need to provide some little help when running |
| 145 |
the configure script, so it will be able to detect the needed header files. |
| 146 |
Additionally you need to configure the build to not link against libnacl |
| 147 |
but against libsodium. |
| 148 |
|
| 149 |
In the case libsodium was installed into /usr/local you run the netsniff-ng |
| 150 |
configure script this way: |
| 151 |
|
| 152 |
$ NACL_INC_DIR=/usr/local/include/sodium NACL_LIB=sodium ./configure |
| 153 |
|
| 154 |
Alternatively you can use pkg-config for determining the include dir by |
| 155 |
setting the NACL_INC_DIR variable for the configure script like this: |
| 156 |
|
| 157 |
$ NACL_INC_DIR=$(pkg-config --variable=includedir libsodium )/sodium |
| 158 |
|
| 159 |
When done, netsniff-ng's build infrastructure will read those evironment |
| 160 |
variables in order to get the needed paths to NaCl. |
| 161 |
|
| 162 |
If you're unsure with any make targets, check out: make help |
| 163 |
|
| 164 |
In order to run the toolkit as a normal user, set the following privilege |
| 165 |
separation after the build/installation: |
| 166 |
|
| 167 |
$ sudo setcap cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_net_admin=eip {toolname} |
| 168 |
|
| 169 |
For cross-compiling netsniff-ng, the process is fairly simple. Assuming you |
| 170 |
want to build netsniff-ng for the Microblaze architecture, update the PATH |
| 171 |
variable first, e.g.: |
| 172 |
|
| 173 |
$ export PATH=<cc-tools-path>/microblazeel-unknown-linux-gnu/bin:$PATH |
| 174 |
|
| 175 |
And then, build the toolkit like this: |
| 176 |
|
| 177 |
$ CROSS_COMPILE=microblazeel-unknown-linux-gnu- \ |
| 178 |
SYSROOT=<sysroot-path> ./configure |
| 179 |
$ make |
| 180 |
|
| 181 |
SYSROOT should be set to the path where your cross-compiled libraries are |
| 182 |
stored, i.e. the path you specify as prefix when configuring the library using |
| 183 |
`./configure --prefix=<prefix>'. |
| 184 |
|
| 185 |
Note that some adaptations might be necessary regarding the CFLAGS, since not |
| 186 |
all might be supported by a different architecture. Probably the most simple |
| 187 |
way would be to run make CFLAGS="-O2 -Wall". |
| 188 |
|
| 189 |
For power users we have a set of zsh auto completion files, have a look at all |
| 190 |
file with ending *.zsh. There's also a BPF vim syntax highlighting file in the |
| 191 |
tree called bpf.vim. |
| 192 |
|
| 193 |
For doing a debug build of the toolkit with less optimizations and non-stripped |
| 194 |
symbols, do: |
| 195 |
|
| 196 |
$ make DEBUG=1 |
| 197 |
|
| 198 |
For debugging the build system, actual commands are verbosly shown if every |
| 199 |
make target is executed with: |
| 200 |
|
| 201 |
$ make Q= |
| 202 |
|
| 203 |
A hardening option is also available via HARDENING=1 if needed. You can then |
| 204 |
build and install the toolkit into prefixed path like: |
| 205 |
|
| 206 |
$ make PREFIX=<path-prefix-for-package> |
| 207 |
$ make PREFIX=<path-prefix-for-package> install |
| 208 |
|
| 209 |
Additionally to setting the PREFIX you can set DESTDIR if you want to install |
| 210 |
the toolkit outside of your current root filesystem but into an alternative |
| 211 |
path. This is particularly useful when cross-compiling because most likely |
| 212 |
you want to install into a dedicated sandbox or into a mounted root filesystem |
| 213 |
for the target architecture and not into the build hosts root filesystem. |
| 214 |
|
| 215 |
$ make PREFIX=<path-prefix-for-package> DESTDIR=<alternative-rootfs> install |
| 216 |
|
| 217 |
Thanks for maintaining netsniff-ng in your distribution. Further questions will |
| 218 |
be answered on the public mailing list. |
| 219 |
|
| 220 |
Last but not least, there is one small utility for advanced users that we have |
| 221 |
not integrated into the main build process. This is a minimal BPF JIT image |
| 222 |
disassembler for the Linux kernel. You can also find this tool in the Linux |
| 223 |
kernel Git tree under 'tools/net/bpf_jit_disasm.c' or within the netsniff-ng |
| 224 |
Git tree simply under 'bpf_jit_disasm.c'. To build it, execute: |
| 225 |
|
| 226 |
$ gcc -Wall -O2 bpf_jit_disasm.c -o bpf_jit_disasm -lopcodes -lbfd -ldl |
| 227 |
|
| 228 |
The rest is described in the file header comment itself, i.e. how to get to the |
| 229 |
BPF JIT code. |