Promiscuous Mode

.. _promiscuous_interface:

Promiscuous Mode ################

.. contents:: :local: :depth: 2

Overview

Promiscuous mode is a mode for a network interface controller that causes it to pass all traffic it receives to the application rather than passing only the frames that the controller is specifically programmed to receive. This mode is normally used for packet sniffing as used to diagnose network connectivity issues by showing an application all the data being transferred over the network. (See the Wikipedia article on promiscuous mode <https://en.wikipedia.org/wiki/Promiscuous_mode>_ for more information.)

The network promiscuous APIs are used to enable and disable this mode, and to wait for and receive a network data to arrive. Not all network technologies or network device drivers support promiscuous mode.

Sample usage

First the promiscuous mode needs to be turned ON by the application like this:

.. code-block:: c

ret = net_promisc_mode_on(iface);
if (ret < 0) {
	if (ret == -EALREADY) {
		printf("Promiscuous mode already enabled\n");
	} else {
		printf("Cannot enable promiscuous mode for "
		       "interface %p (%d)\n", iface, ret);
	}
}

If there is no error, then the application can start to wait for network data:

.. code-block:: c

while (true) {
	pkt = net_promisc_mode_wait_data(K_FOREVER);
	if (pkt) {
		print_info(pkt);
	}

	net_pkt_unref(pkt);
}

Finally the promiscuous mode can be turned OFF by the application like this:

.. code-block:: c

ret = net_promisc_mode_off(iface);
if (ret < 0) {
	if (ret == -EALREADY) {
		printf("Promiscuous mode already disabled\n");
	} else {
		printf("Cannot disable promiscuous mode for "
		       "interface %p (%d)\n", iface, ret);
	}
}

See :zephyr:code-sample:net-promiscuous-mode for a more comprehensive example.

API Reference

.. doxygengroup:: promiscuous