diff --git a/doc/guides/networking/index.rst b/doc/guides/networking/index.rst index be3d2c0b135..68a66b0b16c 100644 --- a/doc/guides/networking/index.rst +++ b/doc/guides/networking/index.rst @@ -14,3 +14,4 @@ operation of the stacks and how they were implemented. net-stack-architecture.rst networking-api-usage.rst networking_with_host.rst + network_monitoring.rst diff --git a/doc/guides/networking/network_monitoring.rst b/doc/guides/networking/network_monitoring.rst new file mode 100644 index 00000000000..a40eee3833f --- /dev/null +++ b/doc/guides/networking/network_monitoring.rst @@ -0,0 +1,208 @@ +.. _network_monitoring: + +Monitor Network Traffic +####################### + +.. contents:: + :local: + :depth: 2 + +It is useful to be able to monitor the network traffic especially when +debugging a connectivity issues or when developing new protocol support in +Zephyr. This page describes how to set up a way to capture network traffic so +that user is able to use Wireshark or similar tool in remote host to see the +network packets sent or received by a Zephyr device. + +See also the :ref:`net-capture-sample` sample application from the Zephyr +source distribution for configuration options that need to be enabled. + +Host Configuration +****************** + +The instructions here describe how to setup a Linux host to capture Zephyr +network RX and TX traffic. Similar instructions should work also in other +operating systems. +On the Linux Host, fetch the Zephyr ``net-tools`` project, which is located +in a separate Git repository: + +.. code-block:: console + + git clone https://github.com/zephyrproject-rtos/net-tools + +The ``net-tools`` project provides a configure file to setup IP-to-IP tunnel +interface so that we can transfer monitoring data from Zephyr to host. + +In terminal #1, type: + +.. code-block:: console + + ./net-setup.sh -c zeth-tunnel.conf + +This script will create following IPIP tunnel interfaces: + +.. csv-table:: + :header: "Interface name", "Description" + :widths: auto + + "``zeth-ip6ip``", "IPv6-over-IPv4 tunnel" + "``zeth-ipip``", "IPv4-over-IPv4 tunnel" + "``zeth-ipip6``", "IPv4-over-IPv6 tunnel" + "``zeth-ip6ip6``", "IPv6-over-IPv6 tunnel" + +Zephyr will send captured network packets to one of these interfaces. +The actual interface will depend on how the capturing is configured. +You can then use Wireshark to monitor the proper network interface. + +After the tunneling interfaces have been created, you can use for example +``netcat`` to provide an UDP listener like this in terminal #2, so that the +host will not send port unreachable message to Zephyr: + +.. code-block:: console + + nc -l -u 2001:db8:200::2 4242 > /dev/null + +The IP address above is the inner tunnel endpoint, and can be changed and +it depends on how the Zephyr is configured. Zephyr will send UDP packets +containing the captured network packets to the configured IP tunnel, so we +need to terminate the network connection like this. + +Zephyr Configuration +******************** + +In this example, we use ``native_posix`` board. You can also use any other board +that supports networking. + +In terminal #3, type: + +.. zephyr-app-commands:: + :zephyr-app: samples/net/capture + :host-os: unix + :board: native_posix + :gen-args: -DCONFIG_NATIVE_UART_AUTOATTACH_DEFAULT_CMD=\""gnome-terminal -- screen %s"\" + :goals: build + :compact: + +To see the Zephyr console and shell, start Zephyr instance like this: + +.. code-block:: console + + build/zephyr/zephyr.exe -attach_uart + +Any other application can be used too, just make sure that suitable +configuration options are enabled (see ``samples/net/capture/prj.conf`` file +for examples). + +The network capture can be configured automatically if needed, but +currently the ``capture`` sample application does not do that. User has to use +``net-shell`` to setup and enable the monitoring. + +The network packet monitoring needs to be setup first. The ``net-shell`` has +``net capture setup`` command for doing that. The command syntax is + +.. code-block:: console + + net capture setup + is the (outer) endpoint IP address + is the (inner) local IP address + is the (inner) peer IP address + Local and Peer IP addresses can have UDP port number in them (optional) + like 198.0.51.2:9000 or [2001:db8:100::2]:4242 + +In Zephyr console, type: + +.. code-block:: console + + net capture setup 192.0.2.2 2001:db8:200::1 2001:db8:200::2 + +This command will create the tunneling interface. The ``192.0.2.2`` is the +remote host where the tunnel is terminated. The address is used to select +the local network interface where the tunneling interface is attached to. +The ``2001:db8:200::1`` tells the local IP address for the tunnel, +the ``2001:db8:200::2`` is the peer IP address where the captured network +packets are sent. The port numbers for UDP packet can be given in the +setup command like this for IPv6-over-IPv4 tunnel + +.. code-block:: console + + net capture setup 192.0.2.2 [2001:db8:200::1]:9999 [2001:db8:200::2]:9998 + +and like this for IPv4-over-IPv4 tunnel + +.. code-block:: console + + net capture setup 192.0.2.2 198.51.100.1:9999 198.51.100.2:9998 + +If the port number is omitted, then ``4242`` UDP port is used as a default. + +The current monitoring configuration can be checked like this: + +.. 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 + +which will print the current configuration. As we have not yet enabled +monitoring, the ``Capture iface`` is not set. + +Then we need to enable the network packet monitoring like this: + +.. code-block:: console + + net capture enable 2 + +The ``2`` tells the network interface which traffic we want to capture. In +this example, the ``2`` is the ``native_posix`` board Ethernet interface. +Note that we send the network traffic to the same interface that we are +monitoring in this example. The monitoring system avoids to capture already +captured network traffic as that would lead to recursion. +You can use ``net iface`` command to see what network interfaces are available. +Note that you cannot capture traffic from the tunnel interface as that would +cause recursion loop. +The captured network traffic can be sent to some other network interface +if configured so. Just set the ```` option properly in +``net capture setup`` so that the IP tunnel is attached to desired network +interface. +The capture status can be checked again like this: + +.. code-block:: console + + uart:~$ net capture + Network packet capture enabled + Capture Tunnel + Device iface iface Local Peer + NET_CAPTURE0 2 1 [2001:db8:200::1]:4242 [2001:db8:200::2]:4242 + +After enabling the monitoring, the system will send captured (either received +or sent) network packets to the tunnel interface for further processing. + +The monitoring can be disabled like this: + +.. code-block:: console + + net capture disable + +which will turn currently running monitoring off. The monitoring setup can +be cleared like this: + +.. code-block:: console + + net capture cleanup + +It is not necessary to use ``net-shell`` for configuring the monitoring. +The network capture API functions can be called by the application if needed. + +Wireshark Configuration +*********************** + +The `Wireshark `_ tool can be used to monitor the +captured network traffic in a useful way. + +You can monitor either the tunnel interfaces or the ``zeth`` interface. +In order to see the actual captured data inside an UDP packet, +see `Wireshark decapsulate UDP`_ document for instructions. + +.. _Wireshark decapsulate UDP: + https://osqa-ask.wireshark.org/questions/28138/decoding-ethernet-encapsulated-in-tcp-or-udp/ diff --git a/doc/reference/networking/net_shell.rst b/doc/reference/networking/net_shell.rst index a11d464fa04..19a11305da1 100644 --- a/doc/reference/networking/net_shell.rst +++ b/doc/reference/networking/net_shell.rst @@ -19,6 +19,8 @@ The following net-shell commands are implemented: :option:`CONFIG_NET_DEBUG_NET_PKT_ALLOC` is set." "net arp", "Print information about IPv4 ARP cache. Only available if :option:`CONFIG_NET_ARP` is set in IPv4 enabled networks." + "net capture", "Monitor network traffic See :ref:`network_monitoring` + for details." "net conn", "Print information about network connections." "net dns", "Show how DNS is configured. The command can also be used to resolve a DNS name. Only available if :option:`CONFIG_DNS_RESOLVER` is set."