1.. _net_capture_interface:
2
3Network Packet Capture
4######################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13The ``net_capture`` API allows user to monitor the network
14traffic in one of the Zephyr network interfaces and send that traffic to
15external system for analysis. The monitoring can be setup either manually
16using ``net-shell`` or automatically by using the ``net_capture`` API.
17
18Cooked Mode Capture
19*******************
20
21If capturing is enabled and configured, the system will automatically capture
22network traffic for a given network interface. If you would like to capture
23network data when there is no network interface involved, then you need to use
24the cooked mode capture API.
25
26In cooked mode capture, arbitrary network packets can be captured and there
27does not need to be network interface involved. For example low level HDLC
28packets in PPP can be captured, as the HDLC L2 layer data is stripped away when
29using the normal network interface based capture. Also CANBUS or Bluetooth
30network data could be captured although currently there is no support in the
31network stack to capture those.
32
33The cooked mode capture works like this:
34
35* An ``any`` network interface is created. It acts as a sink where the cooked
36  mode captured packets are written by the cooked mode capture API.
37* A ``cooked`` virtual network interface is attached on top of this ``any``
38  interface.
39* The ``cooked`` interface must be configured to capture certain L2 packet types
40  using the network interface configuration API.
41* When cooked mode capture API is used, the caller must specify what is the
42  layer 2 protocol type of the captured data. The cooked mode capture API is then
43  able to determine what to capture when receiving such a L2 packet.
44* The network packet capturing infrastructure is then setup so that the ``cooked``
45  interface is marked as captured network interface.
46  The packets received by the ``cooked`` interface via the ``any`` interface are
47  then automatically placed to the capture IP tunnel and sent to remote host
48  for analysis.
49
50For example, in the sample capture application, these network interfaces
51are created:
52
53.. code-block:: c
54
55	Interface any (0x808ab3c) (Dummy) [1]
56	================================
57	Virtual interfaces attached to this : 2
58	Device    : NET_ANY (0x80849a4)
59
60	Interface cooked (0x808ac94) (Virtual) [2]
61	==================================
62	Virtual name : Cooked mode capture
63	Attached  : 1 (Dummy / 0x808ab3c)
64	Device    : NET_COOKED (0x808497c)
65
66	Interface eth0 (0x808adec) (Ethernet) [3]
67	===================================
68	Virtual interfaces attached to this : 4
69	Device    : zeth0 (0x80849b8)
70	IPv6 unicast addresses (max 4):
71	     fe80::5eff:fe00:53e6 autoconf preferred infinite
72	     2001:db8::1 manual preferred infinite
73	IPv4 unicast addresses (max 2):
74	     192.0.2.1/255.255.255.0 overridable preferred infinite
75
76	Interface net0 (0x808af44) (Virtual) [4]
77	==================================
78	Virtual name : Capture tunnel
79	Attached  : 3 (Ethernet / 0x808adec)
80	Device    : IP_TUNNEL0 (0x8084990)
81	IPv6 unicast addresses (max 4):
82	     2001:db8:200::1 manual preferred infinite
83	     fe80::efed:6dff:fef2:b1df autoconf preferred infinite
84	     fe80::56da:1eff:fe5e:bc02 autoconf preferred infinite
85
86In this example, the ``192.0.2.2`` is the address of the outer end point of the
87host that terminates the tunnel. Zephyr uses this address to select the
88internal interface to use for the tunnel. In this example it is interface 3.
89
90The interface 2 is a virtual interface that runs on top of interface 1. The
91cooked capture packets are written by the capture API to sink interface 1.
92The packets propagate to interface 2 because it is linked to the first interface.
93The ``net capture enable 2`` net-shell command will cause the packets sent to
94interface 2 to be written to capture interface 4, which in turn then capsulates
95the packets and tunnels them to peer via the Ethernet interface 3.
96
97The above IP addresses might change if you change the addresses in the
98sample :zephyr_file:`samples/net/capture/overlay-tunnel.conf` file.
99
100Sample usage
101************
102
103See :zephyr:code-sample:`net-capture` sample application and
104:ref:`network_monitoring` for details.
105
106
107API Reference
108*************
109
110.. doxygengroup:: net_capture
111