New script grml-sniff; fix typo in grml-bridge; drop Latest change header

[grml-network.git] / docs / grml-sniff.8.txt

diff --git a/docs/grml-sniff.8.txt b/docs/grml-sniff.8.txt
new file mode 100644 (file)
index 0000000..1d501d6
--- /dev/null
+++ b/docs/grml-sniff.8.txt
@@ -0,0 +1,132 @@
+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>.