1.. zephyr:code-sample:: net-capture
2   :name: Network packet capture
3   :relevant-api: net_capture
4
5   Capture network packets and send them to a remote host via IPIP tunnel.
6
7Overview
8********
9
10This application will setup the device so that net-shell can be used
11to enable network packet capture.
12
13The captured packets are sent to
14remote host via IPIP tunnel. The tunnel can be configured to be in the
15same connection as what we are capturing packets or it can be a separate
16bearer. For example if you are capturing network traffic for interface 1,
17then the remote host where the captured packets are sent can also be reached
18via interface 1 or via some other network interface if the device has
19multiple network interfaces connected.
20
21Requirements
22************
23
24- :ref:`networking_with_host`
25
26Building and Running
27********************
28
29Build the sample application like this:
30
31.. zephyr-app-commands::
32   :zephyr-app: samples/net/capture
33   :board: <board to use>
34   :conf: <config file to use>
35   :goals: build
36   :compact:
37
38
39Network Configuration
40*********************
41
42The ``net-tools`` project contains ``net-setup.sh`` script that can be used to setup
43the tunneling.
44
45In terminal #1, type:
46
47.. code-block:: console
48
49   ./net-setup.sh -c zeth-tunnel.conf
50
51The script will create following network interfaces:
52
53.. code-block:: console
54
55   zeth: flags=4099<UP,BROADCAST,MULTICAST>  mtu 1500
56        inet 192.0.2.2  netmask 255.255.255.255  broadcast 0.0.0.0
57        inet6 2001:db8::2  prefixlen 128  scopeid 0x0<global>
58        ether 00:00:5e:00:53:ff  txqueuelen 1000  (Ethernet)
59        RX packets 0  bytes 0 (0.0 B)
60        RX errors 0  dropped 0  overruns 0  frame 0
61        TX packets 0  bytes 0 (0.0 B)
62        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
63
64   zeth-ip6ip: flags=209<UP,POINTOPOINT,RUNNING,NOARP>  mtu 1480
65        inet6 2001:db8:200::2  prefixlen 64  scopeid 0x0<global>
66        inet6 fe80::c000:202  prefixlen 64  scopeid 0x20<link>
67        sit  txqueuelen 1000  (IPv6-in-IPv4)
68        RX packets 0  bytes 0 (0.0 B)
69        RX errors 0  dropped 0  overruns 0  frame 0
70        TX packets 0  bytes 0 (0.0 B)
71        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
72
73   zeth-ip6ip6: flags=209<UP,POINTOPOINT,RUNNING,NOARP>  mtu 1452
74        inet6 fe80::486c:eeff:fead:5d11  prefixlen 64  scopeid 0x20<link>
75        inet6 2001:db8:100::2  prefixlen 64  scopeid 0x0<global>
76        unspec 20-01-0D-B8-00-00-00-00-00-00-00-00-00-00-00-00  txqueuelen 1000  (UNSPEC)
77        RX packets 0  bytes 0 (0.0 B)
78        RX errors 0  dropped 0  overruns 0  frame 0
79        TX packets 0  bytes 0 (0.0 B)
80        TX errors 8  dropped 8 overruns 0  carrier 8  collisions 0
81
82   zeth-ipip: flags=209<UP,POINTOPOINT,RUNNING,NOARP>  mtu 1480
83        inet 198.51.100.2  netmask 255.255.255.0  destination 198.51.100.2
84        inet6 fe80::5efe:c000:202  prefixlen 64  scopeid 0x20<link>
85        tunnel   txqueuelen 1000  (IPIP Tunnel)
86        RX packets 0  bytes 0 (0.0 B)
87        RX errors 0  dropped 0  overruns 0  frame 0
88        TX packets 0  bytes 0 (0.0 B)
89        TX errors 7  dropped 0 overruns 0  carrier 0  collisions 0
90
91   zeth-ipip6: flags=209<UP,POINTOPOINT,RUNNING,NOARP>  mtu 1452
92        inet 203.0.113.2  netmask 255.255.255.0  destination 203.0.113.2
93        inet6 fe80::387b:a6ff:fe56:6cac  prefixlen 64  scopeid 0x20<link>
94        unspec 20-01-0D-B8-00-00-00-00-00-00-00-00-00-00-00-00  txqueuelen 1000  (UNSPEC)
95        RX packets 0  bytes 0 (0.0 B)
96        RX errors 0  dropped 0  overruns 0  frame 0
97        TX packets 0  bytes 0 (0.0 B)
98        TX errors 7  dropped 7 overruns 0  carrier 0  collisions 0
99
100The ``zeth`` is the outer tunnel interface, all the packets go via it.
101The other interfaces receive packets depending on the configuration you have
102in the Zephyr side.
103
104Network Capture Configuration
105=============================
106
107In Zephyr console, type:
108
109.. code-block:: console
110
111   uart:~$ net iface
112
113   Interface 0x807df74 (Virtual) [1]
114   =================================
115   Interface is down.
116
117   Interface 0x807e040 (Ethernet) [2]
118   ==================================
119   Link addr : 02:00:5E:00:53:3B
120   MTU       : 1452
121   Flags     : AUTO_START,IPv4,IPv6
122   Ethernet capabilities supported:
123   IPv6 unicast addresses (max 4):
124        fe80::5eff:fe00:533b autoconf preferred infinite
125        2001:db8::1 manual preferred infinite
126   IPv6 multicast addresses (max 4):
127        ff02::1
128        ff02::1:ff00:533b
129        ff02::1:ff00:1
130   IPv6 prefixes (max 2):
131        <none>
132   IPv6 hop limit           : 64
133   IPv6 base reachable time : 30000
134   IPv6 reachable time      : 43300
135   IPv6 retransmit timer    : 0
136   IPv4 unicast addresses (max 2):
137        192.0.2.1 manual preferred infinite
138   IPv4 multicast addresses (max 1):
139        <none>
140   IPv4 gateway : 0.0.0.0
141   IPv4 netmask : 255.255.255.0
142
143Next the monitoring is setup so that captured packets are sent as a payload
144in IPv6/UDP packets.
145
146.. code-block:: console
147
148   uart:~$ net capture setup 192.0.2.2 2001:db8:200::1 2001:db8:200::2
149   Capture setup done, next enable it by "net capture enable <idx>"
150
151The ``net capture`` command will show current configuration. As we have not
152yet enabled capturing, the interface is not yet set.
153
154.. code-block:: console
155
156   uart:~$ net capture
157   Network packet capture disabled
158                   Capture  Tunnel
159   Device          iface    iface   Local                  Peer
160   NET_CAPTURE0    -        1      [2001:db8:200::1]:4242  [2001:db8:200::2]:4242
161
162Next enable network packet capturing for interface 2.
163
164.. code-block:: console
165
166   uart:~$ net capture enable 2
167
168The tunneling interface will be UP and the captured packets will be sent to
169peer host.
170
171.. code-block:: console
172
173   uart:~$ net iface 1
174
175   Interface 0x807df74 (Virtual) [1]
176   =================================
177   Name      : IPv4 tunnel
178   Attached  : 2 (Ethernet / 0x807e040)
179   Link addr : 8E:F9:94:6D:B9:E6
180   MTU       : 1452
181   Flags     : POINTOPOINT,NO_AUTO_START,IPv6
182   IPv6 unicast addresses (max 4):
183        fe80::aee6:fbff:fe50:28c0 autoconf preferred infinite
184        2001:db8:200::1 manual preferred infinite
185   IPv6 multicast addresses (max 4):
186        <none>
187   IPv6 prefixes (max 2):
188        <none>
189   IPv6 hop limit           : 64
190   IPv6 base reachable time : 30000
191   IPv6 reachable time      : 22624
192   IPv6 retransmit timer    : 0
193   IPv4 not enabled for this interface.
194
195If you now do this:
196
197.. code-block:: console
198
199   uart:~$ net ping -c 1 192.0.2.2
200
201You should see a ICMPv4 message sent to ``192.0.2.2`` and also the captured
202packet will be sent to ``192.0.2.2`` in tunnel to ``2001:db8:200::2``
203address. The UDP port is by default ``4242`` but that can be changed when
204setting the tunnel endpoint address.
205
206The actual captured network packets received at the end of the tunnel will look
207like this:
208
209.. code-block:: console
210
211   No.     Time           Source                Destination           Protocol Length Info
212        34 106.078538049  192.0.2.1             192.0.2.2             ICMP     94     Echo (ping) request  id=0xdc36, seq=0/0, ttl=64 (reply in 35)
213
214   Frame 34: 94 bytes on wire (752 bits), 94 bytes captured (752 bits) on interface zeth-ip6ip, id 0
215   Raw packet data
216   Internet Protocol Version 6, Src: 2001:db8:200::1, Dst: 2001:db8:200::2
217   User Datagram Protocol, Src Port: 4242, Dst Port: 4242
218   Ethernet II, Src: 02:00:5e:00:53:3b (02:00:5e:00:53:3b), Dst: ICANNIAN_00:53:ff (00:00:5e:00:53:ff)
219   Internet Protocol Version 4, Src: 192.0.2.1, Dst: 192.0.2.2
220   Internet Control Message Protocol
221
222   No.     Time           Source                Destination           Protocol Length Info
223        35 106.098850599  192.0.2.2             192.0.2.1             ICMP     94     Echo (ping) reply    id=0xdc36, seq=0/0, ttl=64 (request in 34)
224
225   Frame 35: 94 bytes on wire (752 bits), 94 bytes captured (752 bits) on interface zeth-ip6ip, id 0
226   Raw packet data
227   Internet Protocol Version 6, Src: 2001:db8:200::1, Dst: 2001:db8:200::2
228   User Datagram Protocol, Src Port: 4242, Dst Port: 4242
229   Ethernet II, Src: ICANNIAN_00:53:ff (00:00:5e:00:53:ff), Dst: 02:00:5e:00:53:3b (02:00:5e:00:53:3b)
230   Internet Protocol Version 4, Src: 192.0.2.2, Dst: 192.0.2.1
231   Internet Control Message Protocol
232