c6ea98eb6f
Add cooked mode capturing information to network documentation. Signed-off-by: Jukka Rissanen <jukka.rissanen@nordicsemi.no>
110 lines
4.2 KiB
ReStructuredText
110 lines
4.2 KiB
ReStructuredText
.. _net_capture_interface:
|
|
|
|
Network Packet Capture
|
|
######################
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
Overview
|
|
********
|
|
|
|
The ``net_capture`` API allows user to monitor the network
|
|
traffic in one of the Zephyr network interfaces and send that traffic to
|
|
external system for analysis. The monitoring can be setup either manually
|
|
using ``net-shell`` or automatically by using the ``net_capture`` API.
|
|
|
|
Cooked Mode Capture
|
|
*******************
|
|
|
|
If capturing is enabled and configured, the system will automatically capture
|
|
network traffic for a given network interface. If you would like to capture
|
|
network data when there is no network interface involved, then you need to use
|
|
the cooked mode capture API.
|
|
|
|
In cooked mode capture, arbitrary network packets can be captured and there
|
|
does not need to be network interface involved. For example low level HDLC
|
|
packets in PPP can be captured, as the HDLC L2 layer data is stripped away when
|
|
using the normal network interface based capture. Also CANBUS or Bluetooth
|
|
network data could be captured although currently there is no support in the
|
|
network stack to capture those.
|
|
|
|
The cooked mode capture works like this:
|
|
|
|
* An ``any`` network interface is created. It acts as a sink where the cooked
|
|
mode captured packets are written by the cooked mode capture API.
|
|
* A ``cooked`` virtual network interface is attached on top of this ``any``
|
|
interface.
|
|
* The ``cooked`` interface must be configured to capture certain L2 packet types
|
|
using the network interface configuration API.
|
|
* When cooked mode capture API is used, the caller must specify what is the
|
|
layer 2 protocol type of the captured data. The cooked mode capture API is then
|
|
able to determine what to capture when receiving such a L2 packet.
|
|
* The network packet capturing infrastructure is then setup so that the ``cooked``
|
|
interface is marked as captured network interface.
|
|
The packets received by the ``cooked`` interface via the ``any`` interface are
|
|
then automatically placed to the capture IP tunnel and sent to remote host
|
|
for analysis.
|
|
|
|
For example, in the sample capture application, these network interfaces
|
|
are created:
|
|
|
|
.. code-block:: c
|
|
|
|
Interface any (0x808ab3c) (Dummy) [1]
|
|
================================
|
|
Virtual interfaces attached to this : 2
|
|
Device : NET_ANY (0x80849a4)
|
|
|
|
Interface cooked (0x808ac94) (Virtual) [2]
|
|
==================================
|
|
Virtual name : Cooked mode capture
|
|
Attached : 1 (Dummy / 0x808ab3c)
|
|
Device : NET_COOKED (0x808497c)
|
|
|
|
Interface eth0 (0x808adec) (Ethernet) [3]
|
|
===================================
|
|
Virtual interfaces attached to this : 4
|
|
Device : zeth0 (0x80849b8)
|
|
IPv6 unicast addresses (max 4):
|
|
fe80::5eff:fe00:53e6 autoconf preferred infinite
|
|
2001:db8::1 manual preferred infinite
|
|
IPv4 unicast addresses (max 2):
|
|
192.0.2.1/255.255.255.0 overridable preferred infinite
|
|
|
|
Interface net0 (0x808af44) (Virtual) [4]
|
|
==================================
|
|
Virtual name : Capture tunnel
|
|
Attached : 3 (Ethernet / 0x808adec)
|
|
Device : IP_TUNNEL0 (0x8084990)
|
|
IPv6 unicast addresses (max 4):
|
|
2001:db8:200::1 manual preferred infinite
|
|
fe80::efed:6dff:fef2:b1df autoconf preferred infinite
|
|
fe80::56da:1eff:fe5e:bc02 autoconf preferred infinite
|
|
|
|
In this example, the ``192.0.2.2`` is the address of the outer end point of the
|
|
host that terminates the tunnel. Zephyr uses this address to select the
|
|
internal interface to use for the tunnel. In this example it is interface 3.
|
|
|
|
The interface 2 is a virtual interface that runs on top of interface 1. The
|
|
cooked capture packets are written by the capture API to sink interface 1.
|
|
The packets propagate to interface 2 because it is linked to the first interface.
|
|
The ``net capture enable 2`` net-shell command will cause the packets sent to
|
|
interface 2 to be written to capture interface 4, which in turn then capsulates
|
|
the packets and tunnels them to peer via the Ethernet interface 3.
|
|
|
|
The above IP addresses might change if you change the addresses in the
|
|
sample :zephyr_file:`samples/net/capture/overlay-tunnel.conf` file.
|
|
|
|
Sample usage
|
|
************
|
|
|
|
See :zephyr:code-sample:`net-capture` sample application and
|
|
:ref:`network_monitoring` for details.
|
|
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: net_capture
|