+grml-sniff(8)
+============
+
+NAME
+----
+grml-sniff - script for configuring a network sniffing setup
+
+SYNOPSIS
+--------
+*grml-sniff* [OPTIONS]
+
+DESCRIPTION
+-----------
+This manual page documents briefly the *grml-sniff* command.
+*grml-sniff* is a script for configuring a network sniffing setup.
+It does NOT sniff on a hub/switch but instead sets up a man-in-the-middle (MITM)
+configuration using a bridge device with two network devices.
+
+OPTIONS
+-------
+
+ *start*::
+
+Start sniffing setup.
+
+ *stop*::
+
+Stop sniffing setup (set interfaces down and remove bridge device).
+
+ *restart*::
+
+Restart grml-sniff.
+
+ *status*::
+
+Display status of configuration.
+
+ *info*|*-h*|*--help*::
+
+Show usage information.
+
+Usage example
+-------------
+
+This section describes the setup and configuration for capturing network traffic
+on a setup like follows (assuming the 'Sniffing Computer' is the box where
+you are using Grml with grml-sniff):
+
+ Hub/Switch/Router
+ ^
+ |
+ | Interface known as 'eth0' in the documentation
+ |
+ |
+ v Interface known as 'eth2'
+ Sniffing Computer <---------------------------> Control Computer (optional,
+ ^ providing GUI, Wireshark,
+ | Backup of dumpfiles, etc)
+ |
+ | Interface known as 'eth1' in the documentation
+ |
+ v
+ Client System
+
+Disable DHCP
+~~~~~~~~~~~~
+
+Start with booting Grml using the 'nodhcp' bootoption. This makes sure that no
+network configuration is being executed automatically while booting. If you
+booted your Grml system without the nodhcp option by accident, just execute
+'killall pump; killall dhclient' after booting finished to make sure there
+aren’t any running DHCP clients anymore.
+
+After booting finished check out the available network interfaces:
+
+ ifconfig -a
+
+At least two interfaces should be present (usually named eth0 and eth1, that’s
+what we are using in this documentation as well). Make sure the network cards
+are connected with the hub/switch/router and the client accordingly! The third
+interface (known as eth2 in this documentation) is just optional and not
+necessary for sniffing itself.
+
+Simple (but not necessarily 100% reliable) check for network connnection using a
+software command:
+
+ ethtool eth0
+ ethtool eth1
+ ethtool eth2
+
+Look for 'Advertised auto-negotiation: Yes' and 'Link detected: yes'.
+
+Configuration
+~~~~~~~~~~~~~
+
+Make sure the according network interfaces are configured as BRIDGE_DEVICES in
+/etc/grml/router-setup. If you are using eth0 and eth1 you don't have to do
+anything (the default is just fine)! Otherwise adjust BRIDGE_DEVICES in
+/etc/grml/router-setup accordingly. For example if the devices you would like to
+use within the sniffing bridge are named eth2 and eth4 use:
+
+ BRIDGE_DEVICES='eth2 eth4'
+
+Start sniffing setup
+~~~~~~~~~~~~~~~~~~~~
+
+Assuming you configured /etc/grml/router-setup as documented in the previous
+section, finally invoke grml-sniff:
+
+ grml-sniff start
+
+That's it. Now your system should be set up accordingly for capturing network
+traffic.
+
+Capturing traffic
+~~~~~~~~~~~~~~~~~
+
+Execute:
+
+ tcpdump -s -C 50 -vvvv -w pcap -i br0
+
+to generate files named pcap, pcap1, pcap2,... each with a file size of ~50MB.
+Press CTRL-C to stop capturing traffic. You can analyse the generated pcap files
+for example using wireshark(1).
+
+See also
+--------
+grml-ap(8), grml-bridge(8), grml-router(8)
+
+AUTHOR
+------
+grml-sniff was written by Michael Prokop <mika@grml.org>.