Promiscuous Mode

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

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:

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:

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 Promiscuous Mode Sample Application for a more comprehensive example.

API Reference

group promiscuous

Promiscuous mode support.

Functions

struct net_pkt *net_promisc_mode_wait_data(k_timeout_t timeout)

Start to wait received network packets.

Return

Received net_pkt, NULL if not received any packet.

Parameters

• timeout: How long to wait before returning.

int net_promisc_mode_on(struct net_if *iface)

Enable promiscuous mode for a given network interface.

Return

0 if ok, <0 if error

Parameters

• iface: Network interface

int net_promisc_mode_off(struct net_if *iface)

Disable promiscuous mode for a given network interface.

Return

0 if ok, <0 if error

Parameters

• iface: Network interface