.. zephyr:code-sample:: net-capture
:name: Network packet capture
:relevant-api: net_capture
Capture network packets and send them to a remote host via IPIP tunnel.
Overview
********
This application will setup the device so that net-shell can be used
to enable network packet capture.
The captured packets are sent to
remote host via IPIP tunnel. The tunnel can be configured to be in the
same connection as what we are capturing packets or it can be a separate
bearer. For example if you are capturing network traffic for interface 1,
then the remote host where the captured packets are sent can also be reached
via interface 1 or via some other network interface if the device has
multiple network interfaces connected.
Requirements
************
- :ref:`networking_with_host`
Building and Running
********************
Build the sample application like this:
.. zephyr-app-commands::
:zephyr-app: samples/net/capture
:board: <board to use>
:conf: <config file to use>
:goals: build
:compact:
Network Configuration
*********************
The ``net-tools`` project contains ``net-setup.sh`` script that can be used to setup
the tunneling.
In terminal #1, type:
.. code-block:: console
./net-setup.sh -c zeth-tunnel.conf
The script will create following network interfaces:
.. code-block:: console
zeth: flags=4099<UP,BROADCAST,MULTICAST> mtu 1500
inet 192.0.2.2 netmask 255.255.255.255 broadcast 0.0.0.0
inet6 2001:db8::2 prefixlen 128 scopeid 0x0<global>
ether 00:00:5e:00:53:ff txqueuelen 1000 (Ethernet)
RX packets 0 bytes 0 (0.0 B)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 0 bytes 0 (0.0 B)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
zeth-ip6ip: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1480
inet6 2001:db8:200::2 prefixlen 64 scopeid 0x0<global>
inet6 fe80::c000:202 prefixlen 64 scopeid 0x20<link>
sit txqueuelen 1000 (IPv6-in-IPv4)
RX packets 0 bytes 0 (0.0 B)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 0 bytes 0 (0.0 B)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
zeth-ip6ip6: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1452
inet6 fe80::486c:eeff:fead:5d11 prefixlen 64 scopeid 0x20<link>
inet6 2001:db8:100::2 prefixlen 64 scopeid 0x0<global>
unspec 20-01-0D-B8-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 1000 (UNSPEC)
RX packets 0 bytes 0 (0.0 B)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 0 bytes 0 (0.0 B)
TX errors 8 dropped 8 overruns 0 carrier 8 collisions 0
zeth-ipip: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1480
inet 198.51.100.2 netmask 255.255.255.0 destination 198.51.100.2
inet6 fe80::5efe:c000:202 prefixlen 64 scopeid 0x20<link>
tunnel txqueuelen 1000 (IPIP Tunnel)
RX packets 0 bytes 0 (0.0 B)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 0 bytes 0 (0.0 B)
TX errors 7 dropped 0 overruns 0 carrier 0 collisions 0
zeth-ipip6: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1452
inet 203.0.113.2 netmask 255.255.255.0 destination 203.0.113.2
inet6 fe80::387b:a6ff:fe56:6cac prefixlen 64 scopeid 0x20<link>
unspec 20-01-0D-B8-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 1000 (UNSPEC)
RX packets 0 bytes 0 (0.0 B)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 0 bytes 0 (0.0 B)
TX errors 7 dropped 7 overruns 0 carrier 0 collisions 0
The ``zeth`` is the outer tunnel interface, all the packets go via it.
The other interfaces receive packets depending on the configuration you have
in the Zephyr side.
Network Capture Configuration
=============================
In Zephyr console, type:
.. code-block:: console
uart:~$ net iface
Interface 0x807df74 (Virtual) [1]
=================================
Interface is down.
Interface 0x807e040 (Ethernet) [2]
==================================
Link addr : 02:00:5E:00:53:3B
MTU : 1452
Flags : AUTO_START,IPv4,IPv6
Ethernet capabilities supported:
IPv6 unicast addresses (max 4):
fe80::5eff:fe00:533b autoconf preferred infinite
2001:db8::1 manual preferred infinite
IPv6 multicast addresses (max 4):
ff02::1
ff02::1:ff00:533b
ff02::1:ff00:1
IPv6 prefixes (max 2):
<none>
IPv6 hop limit : 64
IPv6 base reachable time : 30000
IPv6 reachable time : 43300
IPv6 retransmit timer : 0
IPv4 unicast addresses (max 2):
192.0.2.1 manual preferred infinite
IPv4 multicast addresses (max 1):
<none>
IPv4 gateway : 0.0.0.0
IPv4 netmask : 255.255.255.0
Next the monitoring is setup so that captured packets are sent as a payload
in IPv6/UDP packets.
.. code-block:: console
uart:~$ net capture setup 192.0.2.2 2001:db8:200::1 2001:db8:200::2
Capture setup done, next enable it by "net capture enable <idx>"
The ``net capture`` command will show current configuration. As we have not
yet enabled capturing, the interface is not yet set.
.. code-block:: console
uart:~$ net capture
Network packet capture disabled
Capture Tunnel
Device iface iface Local Peer
NET_CAPTURE0 - 1 [2001:db8:200::1]:4242 [2001:db8:200::2]:4242
Next enable network packet capturing for interface 2.
.. code-block:: console
uart:~$ net capture enable 2
The tunneling interface will be UP and the captured packets will be sent to
peer host.
.. code-block:: console
uart:~$ net iface 1
Interface 0x807df74 (Virtual) [1]
=================================
Name : IPv4 tunnel
Attached : 2 (Ethernet / 0x807e040)
Link addr : 8E:F9:94:6D:B9:E6
MTU : 1452
Flags : POINTOPOINT,NO_AUTO_START,IPv6
IPv6 unicast addresses (max 4):
fe80::aee6:fbff:fe50:28c0 autoconf preferred infinite
2001:db8:200::1 manual preferred infinite
IPv6 multicast addresses (max 4):
<none>
IPv6 prefixes (max 2):
<none>
IPv6 hop limit : 64
IPv6 base reachable time : 30000
IPv6 reachable time : 22624
IPv6 retransmit timer : 0
IPv4 not enabled for this interface.
If you now do this:
.. code-block:: console
uart:~$ net ping -c 1 192.0.2.2
You should see a ICMPv4 message sent to ``192.0.2.2`` and also the captured
packet will be sent to ``192.0.2.2`` in tunnel to ``2001:db8:200::2``
address. The UDP port is by default ``4242`` but that can be changed when
setting the tunnel endpoint address.
The actual captured network packets received at the end of the tunnel will look
like this:
.. code-block:: console
No. Time Source Destination Protocol Length Info
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)
Frame 34: 94 bytes on wire (752 bits), 94 bytes captured (752 bits) on interface zeth-ip6ip, id 0
Raw packet data
Internet Protocol Version 6, Src: 2001:db8:200::1, Dst: 2001:db8:200::2
User Datagram Protocol, Src Port: 4242, Dst Port: 4242
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)
Internet Protocol Version 4, Src: 192.0.2.1, Dst: 192.0.2.2
Internet Control Message Protocol
No. Time Source Destination Protocol Length Info
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)
Frame 35: 94 bytes on wire (752 bits), 94 bytes captured (752 bits) on interface zeth-ip6ip, id 0
Raw packet data
Internet Protocol Version 6, Src: 2001:db8:200::1, Dst: 2001:db8:200::2
User Datagram Protocol, Src Port: 4242, Dst Port: 4242
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)
Internet Protocol Version 4, Src: 192.0.2.2, Dst: 192.0.2.1
Internet Control Message Protocol
994558ef8e