From 7536378d44b70235cba211681cbf36e093c069aa Mon Sep 17 00:00:00 2001 From: Daniel Borkmann Date: Mon, 8 Apr 2013 17:43:26 +0200 Subject: [PATCH] man: finish netsniff-ng man page Fill in the rest of the gaps for this man page. Signed-off-by: Daniel Borkmann --- man/netsniff-ng.8 | 192 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 163 insertions(+), 29 deletions(-) diff --git a/man/netsniff-ng.8 b/man/netsniff-ng.8 index 9e7fe0be..8bc67403 100644 --- a/man/netsniff-ng.8 +++ b/man/netsniff-ng.8 @@ -56,35 +56,146 @@ pcap files as well. .SH OPTIONS -.\" -i|-d|--dev|--in Input source as netdev, pcap or pcap stdin -.\" -o|--out Output sink as netdev, pcap, directory, trafgen, or stdout -.\" -f|--filter Use BPF filter file from bpfc or tcpdump-like expression -.\" -t|--type Filter for: host|broadcast|multicast|others|outgoing -.\" -F|--interval Dump interval if -o is a dir: KiB/MiB/GiB/s/sec/min/hrs -.\" -J|--jumbo-support Support for 64KB Super Jumbo Frames (def: 2048B) -.\" -R|--rfraw Capture or inject raw 802.11 frames -.\" -n|--num <0|uint> Number of packets until exit (def: 0) -.\" -P|--prefix Prefix for pcaps stored in directory -.\" -T|--magic Pcap magic number/pcap format to store, see -D -.\" -D|--dump-pcap-types Dump pcap types and magic numbers and quit -.\" -B|--dump-bpf Dump generated BPF assembly -.\" -r|--rand Randomize packet forwarding order (dev->dev) -.\" -M|--no-promisc No promiscuous mode for netdev -.\" -A|--no-sock-mem Don't tune core socket memory -.\" -m|--mmap Mmap(2) pcap file i.e., for replaying pcaps -.\" -G|--sg Scatter/gather pcap file I/O -.\" -c|--clrw Use slower read(2)/write(2) I/O -.\" -S|--ring-size Specify ring size to: KiB/MiB/GiB -.\" -k|--kernel-pull Kernel pull from user interval in us (def: 10us) -.\" -b|--bind-cpu Bind to specific CPU -.\" -u|--user Drop privileges and change to userid -.\" -g|--group Drop privileges and change to groupid -.\" -H|--prio-high Make this high priority process -.\" -Q|--notouch-irq Do not touch IRQ CPU affinity of NIC -.\" -s|--silent Do not print captured packets -.\" -q|--less Print less-verbose packet information -.\" -X|--hex Print packet data in hex format -.\" -l|--ascii Print human-readable packet data +.SS -i , -d , --in , --dev +Defines an input device, that can either be a networking device, a pcap file +or stdin (``-''). In case of a pcap file, the pcap type (``-D'' option) is +determined automatically by the pcap file magic. In case of stdin, it is +assumed that the input stream is a pcap file. + +.SS -o , --out +Defines the output device, that can either be a networking device, a pcap file, +a folder, a trafgen(8) configuration file or stdout (``-''). In case of a pcap +file, that should not have the default pcap type (0xa1b2c3d4), the additional +option ``-T'' must be provided. If a directory is given, then, instead of a +single pcap file, multiple pcap files are generated with rotation based on +maximum file size or a given interval (``-F'' option). A trafgen configuration +file can currently only be specified if the input device is a pcap file. If +stdout is given as a device, then a trafgen configuration will be written to +stdout if the input device is a pcap file, or a pcap file if the input device +is a networking device. + +.SS -f, --filter +Specifies to not dump all traffic, but to filter the network packet haystack. +As a filter, either a bpfc(8) compiled file can be passed as a parameter or +a tcpdump(1)-like filter expression in quotes. For details regarding the +bpf-file have a look at bpfc(8), for details regarding a tcpdump(1)-like filter +have a look at section ``filter example'' or at pcap-filter(7). A filter +expression may also be passed to netsniff-ng without option ``-f'' in case +there is no subsequent option following after the command-line filter expression. + +.SS -t, --type +This defines some sort of filtering mechanisms in terms of addressing. Possible +values for type are ``host'' (to us), ``broadcast'' (to all), ``multicast'' (to +group), ``others'' (promiscuous mode) or ``outgoing'' (from us). + +.SS -F, --interval +If the output device is a folder, with ``-F'' it is possible to define the pcap +file rotation interval either in terms of size or time. Thus, when the interval +limit has been reached, a new pcap file will be started. As size parameter, the +following values are possible ``KiB/MiB/GiB'' while as a time parameter +it can be ``s/sec/min/hrs''. + +.SS -J, --jumbo-support +On default netsniff-ng's ring buffer frames are of a fixed size of 2048 bytes. +This means that if you're expecting jumbo frames or even super jumbo frames to +pass your line, then you need to enable support for that with the help of this +option. However, this has the disadvantage of a performance regression and a +bigger memory footprint for the ring buffer. + +.SS -R, --rfraw +In case the input or output networking device is a wireless device, it is +possible with netsniff-ng to turn this into monitor mode and create a mon +device that netsniff-ng will be listening on instead of wlan, for instance. +This enables netsniff-ng to analyze, dump, or even replay raw 802.11 frames. + +.SS -n <0|uint>, --num <0|uint> +Process a number of packets and then exit. If the number of packets is 0, then +this is equivalent to infinite packets resp. processing until interrupted. +Otherwise, a number given as an unsigned integer will limit processing. + +.SS -P , --prefix +When dumping pcap files into a folder, a file name prefix can be defined with +this option. If not otherwise specified, the default prefix is ``dump-'' followed +by a unix timestamp. + +.SS -T , --magic +Specify a pcap type for storage. Different pcap types with their various meta +data capabilities are shown with option ``-D''. If not otherwise specified, the +pcap-magic 0xa1b2c3d4, also known as a standard tcpdump-capable pcap format, is +used. Pcap files with swapped endianess are also supported. + +.SS -D, --dump-pcap-types +Dump all available pcap types with their capabilities and magic numbers that +can be used with option ``-T'' and exit. + +.SS -B, --dump-bpf +If a Berkeley Packet Filter is given, e.g. via option ``-f'', then dump the BPF +disassembly to stdout during ring setup. This only serves for informative or +verification purposes. + +.SS -r, --rand +If the input and output device are both networking devices, then this option will +randomize packet order in the output ring buffer. + +.SS -M, --no-promisc +The networking interface will not be put into promiscuous mode. On default, +promiscuous mode is turned on. + +.SS -A, --no-sock-mem +On startup (and shutdown), netsniff-ng is trying to increase socket read and +write buffers if appropriate. This option will prevent netsniff-ng from doing +that. + +.SS -m, --mmap +Use mmap(2) as pcap file I/O. This is default in case of replaying pcap files. + +.SS -G, --sg +Use scatter-gather as pcap file I/O. This is default in case when capturing +pcap files. + +.SS -c, --clrw +Use slower read(2)/write(2) I/O. This is not the default case anywhere, but in +some situations it could be preferred as it has a lower latency on write-back +to disc. + +.SS -S , --ring-size +Manually define the RX_RING resp. TX_RING size in ``KiB/MiB/GiB''. On +default the size is being determined based on the network connectivity rate. + +.SS -k , --kernel-pull +Manually define + +.SS -b , --bind-cpu +Pin netsniff-ng to a specific CPU and also pin resp. migrate the NIC's IRQ +CPU affinity to this CPU. This option should be preferred in combination with +``-s'' in case a middle till high packet rate is expected. + +.SS -u , --user resp. -g , --group +After ring setup drop priviledges to a non-root user/group combination. + +.SS -H, --prio-high +Set this process as a high priority process in order to achieve a higher +scheduling rate resp. CPU time. This is however not default setting, since +it could lead to starvation of other processes, e.g. low priority kernel +threads. + +.SS -Q, --notouch-irq +Do not reassign the NIC's IRQ CPU affinity settings. + +.SS -s, --silent +Do not enter the packet dissector at all and do not print any packet information +to the terminal. Just shut up and be silent. This option should be preferred in +combination with pcap recording or replay, since it will not flood your terminal +which causes a significant performance regression. + +.SS -q, --less +Print a less verbose one-line information for each packet to the terminal. + +.SS -X, --hex +Only dump packets in hex format to the terminal. + +.SS -l, --ascii +Only display ASCII prinable characters. .SS -U, --update If geographical IP locationing should be used, the built-in database update @@ -174,6 +285,16 @@ are not available. Read a pcap file from stdin and convert it into a trafgen(8) configuration file to stdout. +.SH CONFIG FILES + +Under /etc/netsniff-ng/ there are the following files stored that are used +by netsniff-ng and can be extended if wished: + + * oui.conf - OUI/MAC vendor database + * ether.conf - Ethernet type descriptions + * tcp.conf - TCP port/services map + * udp.conf - UDP port/services map + .SH FILTER EXAMPLE netsniff-ng supports both, low-level and high-level filters that are @@ -261,6 +382,19 @@ and how it interacts with the Linux kernel, the kernel documentation under Documentation/networking/{packet_mmap.txt, filter.txt, multiqueue.txt} might be of interest. +How do you sniff in a switched environment? I rudely refer to dSniff's +documentation that says: + +The easiest route is simply to impersonate the local gateway, stealing +client traffic en route to some remote destination. Of course, the traffic +must be forwarded by your attacking machine, either by enabling kernel IP +forwarding or with a userland program that acccomplishes the same +(fragrouter -B1). + +Several people have reportedly destroyed connectivity on their LAN to the +outside world by arpspoof'ing the gateway, and forgetting to enable IP +forwarding on the attacking machine. Don't do this. You have been warned. + If you do not need to dump all possible traffic, you have to consider running netsniff-ng with a BPF filter for the ingress path. For that purpose, read the bpfc(8) man page. -- 2.11.4.GIT