zephyr/samples/net/capture

.. 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